[rust-dev] doc format error? rust.html

[John McKown]

Starting at line 607 in doc/rust.html

<pre><code class="language-{.ebnf">num_lit : nonzero_dec [ dec_digit |
&#39;_&#39; ] * num_suffix ?
        | &#39;0&#39; [       [ dec_digit | &#39;_&#39; ] * num_suffix ?
              | &#39;b&#39;   [ &#39;1&#39; | &#39;0&#39; |
&#39;_&#39; ] + int_suffix ?
              | &#39;o&#39;   [ oct_digit | &#39;_&#39; ] + int_suffix ?
              | &#39;x&#39;   [ hex_digit | &#39;_&#39; ] + int_suffix ? ] ;

The line:
       | &#39;0&#39; [       [ dec_digit | &#39;_&#39; ] * num_suffix ?
the very first [ seems to be inserted in error. I.e the line should read
       | &#39;0&#39;         [ dec_digit | &#39;_&#39; ] * num_suffix ?
This backtracks to line 401 of file src/doc/rust.md. This appears true
to me because I modified that line to remove the extraneous [, then
did a "make docs".

detail:

$git diff
diff --git a/src/doc/rust.md b/src/doc/rust.md
index 69bef81..06bdc87 100644
--- a/src/doc/rust.md
+++ b/src/doc/rust.md
@@ -398,7 +398,7 @@ b"\\x52"; br"\x52";                  // \x52

 ~~~~ {.ebnf .gram}
 num_lit : nonzero_dec [ dec_digit | '_' ] * num_suffix ?
-        | '0' [       [ dec_digit | '_' ] * num_suffix ?
+        | '0'         [ dec_digit | '_' ] * num_suffix ?
               | 'b'   [ '1' | '0' | '_' ] + int_suffix ?
               | 'o'   [ oct_digit | '_' ] + int_suffix ?
               | 'x'   [ hex_digit | '_' ] + int_suffix ? ] ;

The above is relative to commit
20c0ba1279efb5d40fcd4a739a50d09e48e0b37f . I cloned from the repo at
https://github.com/rust-lang/rust.git

===

One question about the above definition of a num_lit. Can any body
explain why the first two lines are not simply:

num_lit: dec_digit [ dec_digit|'_']* num_suffix ?

Why have two lines, which are identical other than the starting
character either a 0 or a nonzero_dec? I am not claiming to be an
expert on EBNF but it seems unnecessary.

===
As an aside:

One possible enhancement to the documentation would be if it
_explicitly_ stated that block comments can be nested. I have worked
with other languages which also use /* ... */ to delimit block
comments, but they do not allow a block comment within a block
comment. This is not really an error, but might be helpful to others
who have encounter this restriction in other languages.

-- 
There is nothing more pleasant than traveling and meeting new people!
Genghis Khan

Maranatha! <><
John McKown
_______________________________________________
Rust-dev mailing list
Rust-dev@mozilla.org
https://mail.mozilla.org/listinfo/rust-dev