digitalmars.D.bugs - [Issue 24571] New: Grammar spec should not use "opt"
- d-bugmail puremagic.com (56/56) May 28 https://issues.dlang.org/show_bug.cgi?id=24571
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 , ``` --
May 28