Am 04.10.2018 um 13:09 schrieb Jim Holsenback:

> done: http://wiki.povray.org/content/Reference:Array

Thanks.

As usual, I keep finding nits to pick.

New nits:

- The syntax isn't clean with respect to which square brackets (`[`,
`]`) are literal characters and which indicate optional items. Most
notably, `[ mixed ]` (an optional keyword) is currently written in just
the same style as `[ INT ]` (an integer surrounded by brackets).

To the best of my understanding, the convention is that an opening
square bracket followed by a blank or a closing square bracket preceded
by a blank is meant to indicate a literal square bracket, while an
opening (closing) square bracket followed (preceded) by anything else is
meant to indicate an optional item.

Thus, it should be `array[mixed][ INT ][[ INT ]]..` (or, maybe even
clearer yet, `array [mixed] [ INT ] [[ INT ]]..`).

- The sentence "Any attempt to reference an uninitialized element
results in an error." may be misunderstood to apply only when the
`mixed` keyword is used.

Old nits:

- The syntax of `DICTIONARY_ITEM` is broken w/r/t the first variant:
Besides the aforementioned bracket issue (here being just the other way
round), the syntax implies that the string must be a literal, while in
fact it can be an arbitrary string expression. So it should be something
along the lines of `[ STRING ] :` or `[ STRING_EXPRESSION ] :`.

- The syntax of ARRAY_DECLARATION does not yet reflect that the
dimensions may be omitted altogether (creating a 1-dimensional
dynamically-sized array), so it should actually be `array [mixed] [[ INT
]]..`.


While I'm at it, maybe we should overhaul the way we present the syntax
altogether; I've written up a few ideas in
http://wiki.povray.org/content/User:Clipka/Syntax, some of which should
be reasonably easy to write.

(Of course if we go that route, I wouldn't expect you to do the boring
part of the work, just to set up the necessary framework.)

BTW, is there no easy shortcut to writing `<code>` tags? It's being used
a lot in our docs and is tedious to write. In Markdown, one would simply
use backticks (`) around the code, for instance.

Post a reply to this message