Syntax summaries use brackets for optional elements; how do I represent literal brackets in a way readers will understand?
In our documentation of SQL functions and statements, we include a BNF-style syntax summary. As is conventional, we indicate optional elements in square brackets, like this:
CREATE [IF NOT EXISTS] TABLE [schema.]table-name (column-definition[,...]) ...
There's more to it, but that's the idea. To unpack this a bit: "IF NOT EXISTS" is optional, including a schema is optional, and you must include at least one column definition and may include more. (A column definition is further expanded as a name and a data type.)
This has worked fine for us for years... until now, when I need to show syntax summaries that have literal square brackets. An array declaration must include a data type and may include a maximum number of elements, like this:
ARRAY[INT,10]
Or just:
ARRAY[INT]
Is there a way, that won't confuse readers, to indicate that the second item in the first example, the element count, is optional?
Even though we had the square-bracket problem as soon as we had to document arrays, I think readers understood that ARRAY[data-type] wasn't saying you could omit the data type; people understand that arrays use square brackets. But ARRAY[data-type[, count]] feels confusing, because I'm using the same symbols in two different ways in the same statement.
Am I going to need to escape the literal square brackets somehow, to disambiguate? Or is there a better way to approach this problem? Currently I'm punting on a single syntax summary in favor of separate descriptions of the three different ways to declare arrays (there's another dimension of optionality that I have not shown here). That might be the best approach, but I'd like to know if there are other options.
4 answers
Official ISO programming standards that describe programming language syntax etc often use opt to mark an argument as optional (with "OPT" in italics). So I would propose to write
ARRAY[data-type, countopt]
This has the advantage that the abbreviation "OPT" is kind of self-explanatory and you don't have to write an explicit note about count being optional.
The disadvantage is that you need some manner of formatted text or HTML (<sub>) to support this, so it won't work in raw source code comments/raw Doxygen etc.
I wouldn't use italics for the optional parameter itself (count), because that's very ambiguous. Italics can be used for a lot of diverse things: emphasis, place-holders, formal definition of technical terms, source code identifiers and so on.
0 comment threads
The most obvious approach, depending one where the help is to be displayed, is to use italics for optional items. That is a well established convention in command-line documentation.
ARRAY[data-type , count ]
One problem with italics is that the italic form of the comma is indistinguishable from the regular. You could do bold:
ARRAY[data-type , count ]
Which helps a little. Or you could rely on a general knowledge of what commas are for, which is probably a reasonable solution for most people.
If, for some reason, you can't use italics (such as displaying help in a terminal window) then I suppose you can see if there is a parenthesis/bracket set that is not used in SQL. (Though that can be somewhat problematic if the user is not familiar with what is an is not a valid SQL character.)
Failing that there does not seem to be much for it but actual BNF or some form of BNF-like notation that can be simplified sufficiently for your purpose. BNF, after all, exists to get around the problem a doing a syntax diagram with no free characters available.
But frankly any use of a general syntax summary works only for those users who are pretty well versed in these conventions and most of those could probably handle BNF without much bother. For any less technically immersed user, reading any form of general syntax diagram is problematic. I always preferred the solution you mention, of showing examples of all the variations of the syntax. This is unambiguous and works for all readers. I would keep doing this regardless of what solutions you come up with for general syntax.
To cover readers from both ends of the spectrum, you might consider including both BNF, which can be absolutely precise and general, and individual examples of all the common forms. In addition to communicating clearly to both audiences, it would give your less technical users a quick course in the interpretation of BNF which would then enable them to decipher the BNF for any obscure cases for which you don't provide and example.
A fairly common solution I've seen to issues like this is to use different font faces for literal text and meta-notation. Often it will be a monospace "teletype" or sans-serif font for literal text and a contrasting (usually lighter) variable width font for meta-notation.
For your example, you'd get:
ARRAY[ data-type[ , count] ]
In case that doesn't render well, here are compromise mimics using code:
ARRAY[data-type[, count]]
or bold:
ARRAY[ data-type[ , count] ]
(Indeed, the static renderer strips the style attributes making the first example pointless. If you edit the answer, you will see the intended effect in the preview.)
Other text decorations such as underlining could be used to make it clear what is literal text. I've mostly seen this in older hand-typed documents.
As you can tell from the examples, it is easy to distinguish the literal brackets from the meta-brackets.
Whatever the approach, it would be explicitly documented in the early part of the documentation but is often intuitive enough even if someone skips that explanation.
0 comment threads
Assuming you're not limited to US-ASCII in notation, I think the best approach would be to find bracket characters or some other notation that won't conflict with any characters that will need to be literally in the command. There are a lot of bracket characters in Unicode, so something like this could work:
ARRAY[data-type ⌞, count⌟]
Though that of course requires defining your notation in a clear way in each place someone might stumble upon it.
The other option is to just be overly verbose in each example, calling out the optional parts:
ARRAY[data-type, count]
└──┬──┘
The count is optional, but if included must be preceded by a comma.
If the count is not included, the comma must also be omitted.
But that's probably a bit much. As you say, not calling out parts as "optional" explicitly and just showing all the possible cases may be the clearest approach for what you're trying to do.
0 comment threads
0 comment threads