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

          Issue ID: 24571
           Summary: Grammar spec should not use "opt"
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: dlang.org
          Assignee: nobody@puremagic.com
          Reporter: qs.il.paperinik@gmail.com

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 ,
```

--