• d-bugmail puremagic.com (56/56) May 28 https://issues.dlang.org/show_bug.cgi?id=24571

d-bugmail puremagic.com writes:

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

--