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

Post History

71%
+3 −0
Q&A Syntax summaries use brackets for optional elements; how do I represent literal brackets in a way readers will understand?

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

posted 3y ago by Mark Baker‭

Answer
#1: Initial revision by user avatar Mark Baker‭ · 2020-10-30T11:06:49Z (over 3 years ago)
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.