Discussion:
[rust-dev] doc format error? rust.html
John McKown
2014-09-06 22:49:18 UTC
Permalink
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
Loading...