Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

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?

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

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

0 comment threads

Post
+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.

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

1 comment thread

General comments (2 comments)
General comments
Monica Cellio‭ wrote over 3 years ago

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

Mark Baker‭ wrote over 3 years 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.