WASM text format improved integration #32917

hamishwillee · 2024-04-02T04:17:46Z

The WASM text format is partially documented in WebAssembly instruction reference but you wouldn't know that if you didn't already know about it. The content incomplete, but IMO it is still very useful and we are foolish not to include it.

This attempts to work on some better cross linking, and serve for discussion on how we might expand this out in future, based on our learnings from other parts of MDN.

Specifically:

URLs named after actual method name, not functional description - add not "Addition".
Discuss addition of sidebar (comment below).
Agree titles - currently not enough context - see https://github.com/mdn/content/pull/32917/files#r1547118926
Agree starting text format - see https://github.com/mdn/content/pull/32917/files#r1547130242
Cross linking

This is a precursor to work I am doing for #32777 because without understanding the text format it is hard to use or understand when you might use the new multi memory features.

ON HOLD. I have done some of this in #32919. Plan to come back to this. It's in the queue.

github-actions · 2024-04-02T04:18:52Z

Preview URLs (61 pages)

Flaws (5)

Note! 58 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/WebAssembly/Reference/Control_flow
Title: WebAssembly control flow instructions
Flaw count: 1

broken_links:
- Can't resolve /en-US/docs/WebAssembly/Reference/Control_flow/Select

URL: /en-US/docs/WebAssembly/Reference/Variables
Title: WebAssembly variable instructions
Flaw count: 1

broken_links:
- Can't resolve /en-US/docs/WebAssembly/Reference/Variables/Global_set

URL: /en-US/docs/WebAssembly/Reference/Numeric
Title: WebAssembly numeric instructions
Flaw count: 3

broken_links:
- Can't resolve /en-US/docs/WebAssembly/Reference/Numeric/Extend
- Can't resolve /en-US/docs/WebAssembly/Reference/Numeric/OR
- Can't resolve /en-US/docs/WebAssembly/Reference/Numeric/XOR

External URLs (2)

URL: /en-US/docs/WebAssembly/Understanding_the_text_format
Title: Understanding WebAssembly text format

https://webassembly.github.io/spec/core/exec/index.html (3 times) (Note! This may be a new URL 👀)

URL: /en-US/docs/WebAssembly/Reference/Control_flow/select
Title: select

https://en.wikipedia.org/wiki/Short-circuit_evaluation (1 time) (Note! This may be a new URL 👀)

hamishwillee · 2024-04-02T04:18:56Z

files/en-us/webassembly/reference/index.md

@@ -6,12 +6,18 @@ page-type: landing-page

 {{WebAssemblySidebar}}

+This page lists all the documented WebAssembly text-format instructions.
+
+{{ListSubPages("","3")}}


As there is no sidebar there is no other way to get a complete listing of what is documented. I'd suggest maybe reverting to the old way list or a macro if we can get the sidebar.

hamishwillee · 2024-04-02T04:27:23Z

files/en-us/webassembly/reference/memory/copy/index.md

@@ -1,14 +1,14 @@
 ---
-title: Copy
-slug: WebAssembly/Reference/Memory/Copy
+title: memory.copy


So my original thinking here was that the actual instruction is memory.copy - not copy - so having the full instruction is useful.

However in other cases, such as store the instruction depends on the type of data you want to store - so you would have i32.store or f64.store (note, we documtened store but actually there are effectively variants..
So the questions are:

Do we prefix none of them - i.e. copy and store have no prefix in the name

In this case we might have to move the variables under global and local so we can document them with an inferred type.

Do we prefix all of them with the affected type, such as memory - even though this is not how they are called. So memory.copy, memory.store

Do we prefix them but with some "proxy" for the type. So we'd use memory.copy but number.store?

I wouldn't do 2.
Between the others I'm not sure, both seem good to me.

hamishwillee · 2024-04-02T04:31:02Z

files/en-us/webassembly/reference/memory/copy/index.md

@@ -1,14 +1,14 @@
 ---
-title: Copy
-slug: WebAssembly/Reference/Memory/Copy
+title: memory.copy


At the moment title is just a name of the function, but should we have better naming to give context here - such as we do in API refer. For example instead of

Suggested change

title: memory.copy

title: memory.copy: WASM text instruction

And if not that, what would be good?

Yes, great idea!

hamishwillee · 2024-04-02T04:31:53Z

files/en-us/webassembly/reference/memory/store/index.md

 page-type: webassembly-instruction
 ---

 {{WebAssemblySidebar}}

-The **`store`** instructions, are used to store a number in memory.
+The **`store`** [memory](/en-US/docs/WebAssembly/Reference/Memory) instruction is used to store a number in memory.


So I was also thinking of this pattern with a link to the parent type of instruction in the body - again, mostly for better cross linking. Thoughts?

hamishwillee · 2024-04-02T04:32:44Z

files/en-us/webassembly/reference/memory/store/index.md


-For the integer numbers, you can also store a wide typed number as a narrower number in memory, e.g. store a 32-bit number in an 8-bit slot (**`i32.store8`**). If the number doesn't fit in the narrower number type it will wrap.
+There are variants of the instruction, such as `i32.store8`, `i32.store16`, and so on (see below), for storing a wide typed integer number as a narrower number in memory.


The variants are all listed below in the syntax section, for all cases that take a number type. Should we list the supported number types in the description as done here for ALL items?

Why would you list all types here but not in other pages? E.g. add

hamishwillee · 2024-04-02T04:37:30Z

files/en-us/webassembly/reference/numeric/abs/index.md

 page-type: webassembly-instruction
 ---

 {{WebAssemblySidebar}}

-The **`abs`** instructions, short for _absolute_, are used to get the absolute value of a number. That is, it returns x if x is positive, and the negation of x if x is negative.
+The **`abs`** [numeric](/en-US/docs/WebAssembly/Reference/Numeric) WebAssembly text-format instruction, short for _absolute_, is used to get the absolute value of an `f32` or `f64` number on the stack. That is, it returns x if x is positive, and the negation of x if x is negative.


Similarly

should it be text-format instructions, or Web Assembly text-format instructions, or just instructions?

Should we simplify the "short for" to a bracketed expansion.

My preference is that we use a pattern like this:

Suggested change

The **`abs`** [numeric](/en-US/docs/WebAssembly/Reference/Numeric) WebAssembly text-format instruction, short for _absolute_, is used to get the absolute value of an `f32` or `f64` number on the stack. That is, it returns x if x is positive, and the negation of x if x is negative.

The **`abs`** (absolute) [numeric instruction](/en-US/docs/WebAssembly/Reference/Numeric), is used to get the absolute value of an `f32` or `f64` number on the stack. That is, it returns x if x is positive, and the negation of x if x is negative.

hamishwillee · 2024-04-02T04:52:04Z

@wbamberg Can you offer advice on adding the WebAssembly instruction reference to the WebAssemblySidebar.

The simplest approach would be to just append a link to above doc (and perhaps the ones below):

  <li class="toggle">
    <details open>
      <summary><%=text['WebAssembly Text Instruction Reference']%></summary>
      <ol>
        <li><a href="<%=baseURL%>/Reference"><code>Overview</code></a></li>
      </ol>
    </details>
  </li>

But what I'd like to do is expand out the sub tree and include that . Is something like this using ListSubpagesForSidebar likely to work (note, I'd call this several times to get the full listing, for each class of instruction):

  <li class="toggle">
    <details open>
      <summary><%=text['WebAssembly Text Instruction Reference']%></summary>
      <ol>
        <li><a href="<%=baseURL%>/Reference"><code>Overview</code></a></li>
        {{ListSubpagesForSidebar("/en-US/docs/WebAssembly/Reference")}}
      </ol>
    </details>
  </li>

Or would be be better listing all of them with no sorting, and somehow matching on the page type? If so, can you point me to the sidebar you would copy?

wbamberg · 2024-04-02T16:59:06Z

Is something like this using ListSubpagesForSidebar likely to work

Something like this: https://github.com/mdn/yari/blob/1ffb0261196752308a48b9f87d32101427d82430/kumascript/macros/HTMLSidebar.ejs#L363-L375 should work, if I understand your use case. It would probably be good to have a section for each instruction type, using ListSubpagesForSidebar to list all the instructions for each type, like:

Instruction reference
  - Numeric instructions
    - Addition
    - Const
    - Equal
    - etc
  - Variable instructions
    - Local
    - Local_get
    - etc
  - etc

MendyBerger

Thanks @hamishwillee for showing some love for these pages! I think the changes you made will make them much more readable!

MendyBerger · 2024-04-03T19:50:37Z

files/en-us/webassembly/reference/memory/load/index.md

 page-type: webassembly-instruction
 ---

 {{WebAssemblySidebar}}

-The **`load`** instructions, are used to load a number from memory onto the stack.
+The **`load`** [memory](/en-US/docs/WebAssembly/Reference/Memory) instruction is used to load a number from memory onto the stack.


Why the change to singular? Since there are multiple load instructions (see table below)

MendyBerger · 2024-04-03T19:50:51Z

files/en-us/webassembly/reference/memory/copy/index.md

@@ -1,14 +1,14 @@
 ---
-title: Copy
-slug: WebAssembly/Reference/Memory/Copy
+title: memory.copy


Yes, great idea!

MendyBerger · 2024-04-03T19:50:55Z

files/en-us/webassembly/reference/memory/copy/index.md

@@ -1,14 +1,14 @@
 ---
-title: Copy
-slug: WebAssembly/Reference/Memory/Copy
+title: memory.copy


I wouldn't do 2.
Between the others I'm not sure, both seem good to me.

MendyBerger · 2024-04-03T19:52:21Z

files/en-us/webassembly/reference/memory/size/index.md

 page-type: webassembly-instruction
 ---

 {{WebAssemblySidebar}}

-The **`size`** instruction, returns the amount of pages the memory instance currently has, each page is sized 64KiB.
+The **`memory.size`** instruction, returns the size of the memory instance, in 64KiB pages.


I believe that there are active discussions about other memory sizes, might be worth keeping the "currently"

MendyBerger · 2024-04-03T19:52:45Z

files/en-us/webassembly/reference/memory/store/index.md

 page-type: webassembly-instruction
 ---

 {{WebAssemblySidebar}}

-The **`store`** instructions, are used to store a number in memory.
+The **`store`** [memory](/en-US/docs/WebAssembly/Reference/Memory) instruction is used to store a number in memory.


MendyBerger · 2024-04-03T19:56:02Z

files/en-us/webassembly/reference/memory/store/index.md


-For the integer numbers, you can also store a wide typed number as a narrower number in memory, e.g. store a 32-bit number in an 8-bit slot (**`i32.store8`**). If the number doesn't fit in the narrower number type it will wrap.
+There are variants of the instruction, such as `i32.store8`, `i32.store16`, and so on (see below), for storing a wide typed integer number as a narrower number in memory.


Why would you list all types here but not in other pages? E.g. add

github-actions · 2024-04-16T00:31:39Z

This pull request has merge conflicts that must be resolved before it can be merged.

hamishwillee added 2 commits April 2, 2024 14:59

WAT Reference - rename to match instructions

f16b99e

Cross linking from understanding the text format

b586bf7

hamishwillee requested a review from a team as a code owner April 2, 2024 04:17

hamishwillee requested review from chrisdavidmills and removed request for a team April 2, 2024 04:17

github-actions bot added Content:wasm WebAssembly docs size/m [PR only] 51-500 LoC changed labels Apr 2, 2024

hamishwillee commented Apr 2, 2024

View reviewed changes

hamishwillee requested a review from MendyBerger April 2, 2024 05:02

hamishwillee mentioned this pull request Apr 2, 2024

FF125 WAS multi memory ff125 #32919

Merged

10 tasks

MendyBerger reviewed Apr 3, 2024

View reviewed changes

hamishwillee mentioned this pull request Apr 9, 2024

[WASM] Ship multi-memory #32777

Closed

10 tasks

hamishwillee marked this pull request as draft April 15, 2024 05:49

github-actions bot added the merge conflicts 🚧 [PR only] label Apr 16, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WASM text format improved integration #32917

WASM text format improved integration #32917

hamishwillee commented Apr 2, 2024 •

edited

Loading

github-actions bot commented Apr 2, 2024

hamishwillee Apr 2, 2024

hamishwillee Apr 2, 2024

MendyBerger Apr 3, 2024

hamishwillee Apr 2, 2024

MendyBerger Apr 3, 2024

hamishwillee Apr 2, 2024

MendyBerger Apr 3, 2024

hamishwillee Apr 2, 2024

MendyBerger Apr 3, 2024

hamishwillee Apr 2, 2024

hamishwillee commented Apr 2, 2024

wbamberg commented Apr 2, 2024 •

edited

Loading

MendyBerger left a comment •

edited

Loading

MendyBerger Apr 3, 2024

MendyBerger Apr 3, 2024

MendyBerger Apr 3, 2024

MendyBerger Apr 3, 2024

MendyBerger Apr 3, 2024

MendyBerger Apr 3, 2024

github-actions bot commented Apr 16, 2024


		For the integer numbers, you can also store a wide typed number as a narrower number in memory, e.g. store a 32-bit number in an 8-bit slot (`i32.store8`). If the number doesn't fit in the narrower number type it will wrap.
		There are variants of the instruction, such as `i32.store8`, `i32.store16`, and so on (see below), for storing a wide typed integer number as a narrower number in memory.

	The `abs` [numeric](/en-US/docs/WebAssembly/Reference/Numeric) WebAssembly text-format instruction, short for _absolute_, is used to get the absolute value of an `f32` or `f64` number on the stack. That is, it returns x if x is positive, and the negation of x if x is negative.
	The `abs` (absolute) [numeric instruction](/en-US/docs/WebAssembly/Reference/Numeric), is used to get the absolute value of an `f32` or `f64` number on the stack. That is, it returns x if x is positive, and the negation of x if x is negative.

WASM text format improved integration #32917

Are you sure you want to change the base?

WASM text format improved integration #32917

Conversation

hamishwillee commented Apr 2, 2024 • edited Loading

github-actions bot commented Apr 2, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hamishwillee commented Apr 2, 2024

wbamberg commented Apr 2, 2024 • edited Loading

MendyBerger left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Apr 16, 2024

hamishwillee commented Apr 2, 2024 •

edited

Loading

wbamberg commented Apr 2, 2024 •

edited

Loading

MendyBerger left a comment •

edited

Loading