Proposal: Better wording for "Glossary notation"

Author

Ruv

Change Log

• 2021-09-24 Initial version

Problem

The section 2.2.4 Glossary notation says:

Each glossary entry specifies a Forth word and consists of two parts: an index line and the semantic description of the definition.

The section 2.2.4.2 Glossary semantic description says:

The first paragraph of the semantic description contains a stack notation for each stack affected 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:

1. 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).

2. 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:

3. 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".

4. Different terms are used to refer a same notion in the quoted lines. Use either "word" or "definition".

Solution

Possible solutions per each item

Item 1

Possible variants

• Say that a glossary entry contains the 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, the label is omitted" in 3.4.3.1 Execution semantics.

Item 2

Use another wording "by performing the semantics" instead of "by execution of the word".

Item 3

Use the phrase "stack diagram" instead of "stack notation".

Item 4

Use the normative term "Forth definition".

Deletions and insertions

Each glossary entry specifies a Forth word definition and consists of two parts: an the index line part and the one ore more semantic description parts of for the definition.

The first paragraph of the a semantic description contains an optional label for the semantics and a stack notation stack diagram for each stack affected by execution of the word performing these semantics (if they are defined).

Proposal

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 2.2.4.2 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).