Grammar spec should not use "opt"

[dlangBugzillaToGithub]

Bolpat reported this on 2024-05-28T11:15:19Z

Transferred from https://issues.dlang.org/show_bug.cgi?id=24571

CC List

• Bolpat

Description

The grammar spec websites should not use subscript `opt` to indicate optional stuff. While okay to read on the HTML page, the subscript is in general lost when copy-pasting grammar to the Issue Tracker, a Forum post, or a DIP draft so that the `opt` becomes looking like part of the name. DIPs that specify grammar changes usually do so using a `diff` syntax-highlight code-block, where subscript cannot be used. Another minor nuisance is that subscript goes against the style of a monospace font.

Instead of rendering `$(OPT)` as `<sub>opt</sub>`, I suggest using `<abbr title="optional">?</abbr>`

Appending a question mark to indicate an entity is optional is well-known from Regular Expressions, and also used in Parsing Expression Grammar. The dlang.org website does not even specify what kind of grammar specification it uses and lets the reader make a well-educated guess, which does not seem to bother anyone, as the grammar spec is fairly simple.

---

Potential issues

The fact that the question mark is not part of the literal grammar can be readily guessed by the fact that it appends to a grammar entity name directly without any space (contrary to literal tokens) and is not a letter. Because almost all entities are linked they’re underlined and colored, whereas the question mark isn’t, so visually, it stands out.

The question mark is potentially confusing only in the case when optionality is expressed for a literal token. While most, if not all, browsers render `<abbr>` with a dotted underline, that can be missed, and following one or more symbol characters representing a token, a question mark is not obviously not part of the token.
However, the only symbol token `opt` is applied to in the current grammar is `,` for indicating an optional trailing comma. If the question mark on those is deemed too confusing, I suggest to just rephrase the grammar rules without `opt`. There are only three instances of optional `,`, one in `SliceOperation` and two in `AssertArguments`, which would become:
```
SliceOperation:
    [ ]
    [ Slice ]
    [ Slice , ]
AssertArguments:
    AssignExpression
    AssignExpression ,
    AssignExpression , AssignExpression
    AssignExpression , AssignExpression ,
```

[dlangBugzillaToGithub]

qs.il.paperinik commented on 2024-05-28T11:16:12Z

Even a subscript or superscript question mark is better than `opt` as it copy-pastes well.

[dlangBugzillaToGithub]

dlang-bot commented on 2024-05-28T11:45:30Z

@Bolpat updated dlang/dlang.org pull request #3838 "Fix Issue 24571 - Grammar spec should not use "opt"" fixing this issue:

- Fix Bugzilla Issue 24571 - Grammar spec should not use "opt"
  
  Address optional trailing comma

https://github.com/dlang/dlang.org/pull/3838

[dlangBugzillaToGithub]

dlang-bot commented on 2024-06-25T11:18:14Z

@Bolpat created dlang/dlang.org pull request #3855 "Rename FunctionLiteralBody2 to FunctionLiteralBody" fixing this issue:

- Fix Bugzilla Issue 24571 - Grammar spec should not use "opt"
  
  Address optional trailing comma

https://github.com/dlang/dlang.org/pull/3855

[dlangBugzillaToGithub]

dlang-bot commented on 2024-06-25T11:46:01Z

@Bolpat created dlang/dlang.org pull request #3857 "Grammar spec should not use "opt"" fixing this issue:

- Fix Bugzilla Issue 24571 - Grammar spec should not use "opt"

https://github.com/dlang/dlang.org/pull/3857