Alan Madden wrote: explain it fully in the description. I am sure many users will not
understand why an argument is bracketed, but they will understand itI can understand that entirely, and I do see where you're coming from. However, I don't think that it is necessary to... 'disadvantage' people who are familiar with traditional syntax. It doesn't *harm* understanding to have italics or brackets, and anyone who actually needs to learn about it can just read on to the description (which they really should be doing anyway; someone who is technical and just wants to remember the format might just glance at the first part and move on, rather than having to read the text to see what is optional) and they can very quickly see (and work out after a couple of examples) that the italic parts are the bits they should be changing, and the square bracketed parts are the bits that are optional. I also only chose to implement the bracketing system because one of the examples was already using brackets, and it gave me the idea to continue to use this format, since to the initiated it makes readability a lot easier. In fact, the brackets are one thing, but the italics are far more generic and important, because they indicate that there is simply something special or worthy of note about the text. In many respects, this is a better thing, since it helps to develop good understanding of exactly what it is they're reading, and when they apply that to more technical things, they won't have a steep learning curve to get up to speed on things that aren't as verbose with the documentation as we are.
when they read the description.
Alan
What is the standard? I have not noted one yet, but, that just might mean that I have not read the right stuff. :+}
Long time ago in a shop far away certain marks had been defined for certain uses, that is,
parentheses ( ) meant something, usually for a formula
brackets [ ] usually meant had to make a choice of one or to insert a number
braces { } something else, and finally,
carets < > something else again.
Similar to slash / was for division while stroke \ was something else. Etc etc.
Chris
