Notifications
Mark all as read
Q&A

Syntax summaries use brackets for optional elements; how do I represent literal brackets in a way readers will understand?

+3
−0

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.

Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

0 comments

3 answers

+3
−0

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.

Why does this post require moderator attention?
You might want to add some details to your flag.

2 comments

We use italics for variables. In my first example, schema and table-name are variables and would be italicized, but "if not exists" is literal text that is optional. (We do try to include examples on all our reference pages too. We're trying to support both the "just show me the formal syntax" readers and the learn-by-example readers. Examples won't be exhaustive, though I did that for my array case because I needed something.) Monica Cellio‭ about 1 month ago

At a certain point one simply runs out of available characters and typographic alternatives, at which point formal notation like BNF is all that is left. Which is why BNF exists. And even then, BNF can become cumbersome for some syntaxes in which BNF's own syntax overlaps, which is why we have several varieties of BNF as well. Mark Baker‭ about 1 month ago

+3
−0

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.

Why does this post require moderator attention?
You might want to add some details to your flag.

0 comments

+1
−0

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.

Why does this post require moderator attention?
You might want to add some details to your flag.

0 comments

Sign up to answer this question »

This community is part of the Codidact network. We have other communities too — take a look!

You can also join us in chat!

Want to advertise this community? Use our templates!