Comments on Syntax summaries use brackets for optional elements; how do I represent literal brackets in a way readers will understand?
Parent
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.
Post
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.
0 comment threads