Documentation Issues

["Peter Hill" <corwin@...>]

While on the topic of syntax & documentation (I just whipped up a Lua
lexical analyser in VB... now I'm working on the parser) I have a few more
queries & comments.


- DOCUMENTATION ISSUES -

Upon perusing the Lua manual...


(1) STRING ESCAPE CHARS
For literal strings, no mention is made of what happens when a non-valid C
escape character is used, such as "aaa\zbbb". Experiment shows it to be the
same as "aaazbbb" rather than generating an error but some specification
should be made. Perhaps it should instead generate an error to encourage
leaving the other values free for future expansion.


(2) [[ IN STRINGS
Single line literal strings should formally allow the escape sequences "\["
(equivalent to "[") and "\]" (equaivalent to "]"). The manual section should
also make a note that if the user wishes to embed "[[" in a literal string
then it is more robust to code it as "[\[", as this will give the string
protection against future code modifications that may wrap it in the "[[" /
"]]" block of a multiline-string or multiline-comment.

Eg, if I had:
    ...
    print("]]")
    ...

and I decided to temporarily comment out that section of code:
    --[[
    ...
    print("]]")
    ...
    ]]

the attempt would fail. However:
    --[[
    ...
    print("]\]")
    ...
    ]]

would work if "\]" was officially allowed in string literals.


(3) -- [[
No comment is made about whether "-- <white space> [[" works. Apparently it
doesn't.


(4) [[
No comment is made about whether "[[<white space><newline>" ignores the
<newline> like "[[<newline>" does. Apparently is doesn't.


(5) NUMBER SYNTAX
The official format for numbers should be specified. It appears to be:
    number ::= digit {digit} ['.' {digit}] [('e' | 'E') [-] digit {digit}]
where
    digit ::= '0' | '1' | ... | '9'


*cheers*
Peter Hill