Proposal:  Better wording for "Glossary notation"
This page is dedicated to discussing this specific proposal
ruv  Better wording for "Glossary notation"Proposal2021-09-24 11:33:41
- 2021-09-24 Initial version
The section 2.2.4 Glossary notation says:
Each glossary entry specifies a Forth < u >word and consists of two parts: < u >an index line and < u >the semantic description of the < u >definition.
The section 18.104.22.168 Glossary semantic description says:
The first paragraph of the semantic description contains a < u >stack notation for each stack affected < u >by execution of the word.
(underlined by me)
The quoted lines are correct for the cases of ordinary words.
But for non ordinary words they are incorrect:
For non ordinary words the "semantic description" part actually contains a different section for each defined (or explicitly undefined) semantics, with an optional label for semantics and an optional stack diagrams in each section (see 3.4.3 Semantics).
The underlined part "by execution" is not correct for non ordinary words (when the section describes a behavior other than execution semantics). Since "execution of a word" means performing its execution semantics. But a section can describe compilation semantics, and the corresponding stack effects can be not equivalent to effects by "execution of the word".
Other problems in wording:
The underlined part "stack notation" is slightly confusing in its context. In the section 2 Terms, notation, and references, a notation means a convention. A semantic description in a glossary entry doesn't introduce a new notation, but uses the stack notation to describe the input and output stack parameters. Such description of the parameters is usually called "stack diagram".
Different terms are used to refer a same notion in the quoted lines. Use either "word" or "definition".
Possible solutions per each item
- Say that a glossary entry contains the < i >< u >behavior description part that contains one or more semantic description sections.
- Say that a glossary entry contains one or more semantic description parts.
The former variant better reflects the idea that semantics describe a behavior in some conditions. But, it seems, the latter variant is simpler without significant losses.
Note a label for semantics. Take into account the phrase "When a definition has only one specified behavior, < u >the label is omitted" in 22.214.171.124 Execution semantics.
Use another wording "by performing the semantics" instead of "by execution of the word".
Use the phrase "stack diagram" instead of "stack notation".
Use the normative term "Forth definition".
Deletions and insertions
Each glossary entry specifies a Forth < del >word < ins >definition and consists of < del >two parts: an < ins >the < i >index line < ins >part and < del >the < ins >one ore more semantic description < ins >parts < del >of < ins >for the definition.
The first paragraph of < del >the < ins >a semantic description contains < ins >an optional label for the semantics and a < del >stack notation < ins >stack diagram for each stack affected by < del >execution of the word < ins >performing these semantics (if they are defined).
In the section 2.2.4 Glossary notation
Replace the phrase:
Each glossary entry specifies a Forth word and consists of two parts: an index line and the semantic description of the definition.
with the phrase:
Each glossary entry specifies a Forth definition and consists of the index line part and one or more semantic description parts for the definition.
In the section 126.96.36.199 Glossary semantic description
Replace the phrase:
The first paragraph of the semantic description contains a stack notation for each stack affected by execution of the word.
with the phrase:
The first paragraph of a semantic description contains an optional label for the semantics and a stack diagram for each stack affected by preforming these semantics (if they are defined).