Post History

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 [OR REPLACE] TABLE [schema.]table-name (column-definition[,...]) ...

There's more to it, but that's the idea.  To unpack this a bit: "OR REPLACE" 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.