Nits in the core syntax spec documentation

[aathan]

I've noted some simple holes in the core syntax spec documentation, but I'm not sure exactly how to fix them and can therefore not submit a PR directly. Please guide me.

• the term "meta variable" is used but not defined, either in terms of its typography or meaning
• S[i] is defined but S_i is not (even though the latter is used a couple of bullet points further down

These are obviously nits, but could be cleaned up. There are others, but I'll spare you the details (vs PR). It's the "meta variable" that I'm not sure how to specify or write the markup for.

There is additionally no definition of what something like utf8(), which appears soon after the initial table, refers to.

[rossberg]

Saying "meta" variable is merely a common way to differentiate talking about a variable of the meta language (i.e., rules in the notation used to define a language) from syntactic variables of the language that's being defined.

Something like s_i is simply a name of a (meta) variable. The index has no meaning of its own, it's just like you would sometimes name things x_1, x_2, x_3 in math, or name variables x1, x2, x3 in a program when dealing with a group of similar things. It's just naming, there isn't anything to define.

S[i] on the other hand is an actual operation with a specific meaning, thus it needs a definition.

The utf8 function is defined here. I can't say which occurrence of utf8 you are referring to, but all uses of defined things should be hyper-linked to their definition.

Hope that answers your questions.

[aathan]

Thank you :)

What I meant by utf8() not being defined is not that the "function" utf8 is not specified somewhere or linked to, but that the notation is not defined (see end of this comment).

I understand regarding meta variables; and I agree it's likely many (most?) people (as I did) would understand what a meta variable is. That being said, the term is nevertheless used without being defined, and how such variables are denoted typographically is not illustrated.

Here, I'm speaking of the first bullet list in (https://webassembly.github.io/spec/core/syntax/conventions.html). Having read further into the doc, I'm still not sure exactly how or if they're differentiated from "non-terminal symbols"; and in fact, they may be practically equivalent and thus typographically congruent -- with meta-variables possibly deserving a bullet point that says something like "* meta variables are place holders for non-terminal symbols or for values in syntactic expressions, and are written in italic font. They are distinguishable by their context."

I also understand your point regarding how Si differs from S[i] but the discussion of concat(Si) requires a bit of extra parsing on behalf of a new reader, since the same indexing variable i is used. Here I'm speaking of the second bullet list on that page.

Something like these three additional bullet points immediately above concat(Si) may be inidcated:

• Si denotes the i'th sequence s in some sequence of sequences, such as S*.
• Si[j] is the j'th element of Si.
• name(...) refers to a parameterized production from meta-variables within the parenthesis, usually appearing as a link to its definition

If you like this suggestion, I'll submit a PR.

[aathan]

By the way, on the page https://webassembly.github.io/spec/core/syntax/instructions.html the meta variable or non-terminal "inn" is not defined. When I try searching for it, Chrome isn't able to even highlight occurences on the page (maybe a result of the mathjax or whatever formatting libary is interpreting the markup?). Is it intended to be inn := { ibunop | ibinp | ... } ?

btw ... I understand if these pages are not meant to be a strictly correct grammar specification. At the same time, I was left guessing whether inn may be any of those instructions mentioned below it.

[rossberg]

Ah, it's only the "nn" that is a non-terminal (the "i" is type-set differently, if you look closely). That nn is defined in the same figure.

Unfortunately, searching formulas does not work well with the current web technology. Hopefully, MathML will fix that one day.

• Si denotes the i'th sequence s in some sequence of sequences, such as S*.
• Si[j] is the j'th element of Si.
• name(...) refers to a parameterized production from meta-variables within the parenthesis, usually appearing as a link to its definition

You may be over-interpreting the notation. It is used in much more generic ways throughout the document than these explanations would suggest.

I'm generally fine with adding missing definitions, but we cannot hope to explain all of math's common notational conventions. We are assuming basic highschool math, which should include familiarity with basics like subscripts (a_i) and parameters (a(x)). If some reader does not know those, then I suspect notation will be their least problem with the spec. ;)

[aathan]

Thank you for your thoughtful responses. I appreciate your time.

Actually the "inn" (and "fnn") I'm referring to are the next one over. As in "inn.const inn" <--- that second inn is all italics and I am not sure what it's a non-terminal of. I'm guessing maybe that "inn" is supposed to be an actual literal of nn size? Maybe those second all-italics could say "int_literal" and "float_literal" instead of being exactly the same character string as preceding inn/fnn?

Coming into the language completely "clean" I must say, it would have been better to first look through an example program listing before reading these docs. Perhaps an example listing could be linked to up front somewhere, to help orient new readers.

As far as the rest of your comments: Understood/agreed. I was just making note of areas that caused me to re-read, even though I did finally understand upon doing so.

[rossberg]

Oh, I see. Yeah, those ones are a bit subtle to read. As the hyperlink suggests, these are integer/float values, that is, iN / fN with N = nn. I agree that might be non-obvious and could better be expressed by a side condition.

Right, the Wasm spec definitely is not the right place to start learning about Wasm. It is a formal specification, it's not useful as an introduction.