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:
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.