Command line parameter formatting conventions

[Childs]

So, I was in a meeting today going over some docs with one of our writers, and she had a table with parameters and arguments, with a column for a description. So I say you need to use square brackets for optional parameters, curly braces for required, angles, pipes, etc. Then she asked why....my answer was it was the convention. Then she asked for a reference. Its one of those things where I don't know why I know something, I just do. I was googling, but I must be getting old because I do not see any docs where these conventions are explicitly listed. Every so often I can get a page like so:

http://docs.oracle.com/cd/E19859-01/820-3252-11/using_cli.html#50397243_21898

Cisco has a similar doc. And Stack Overflow has a post that just uses squares. But every link is just a little different. I probably read this in a book that I have long since forgot. Any help?

 

[Ken g6]

Looks like you're looking for a convention on what, in Linux, is called the man page synopsis. Searching that I found a Stack Overflow question and a possible formal answer as well as less-formal answers.

 

[Childs]

You know, a long time ago I made man pages for stuff I was working on, so before I posted this I was looking at groff and man page formatting, the first couple of pages I looked at for the synopsis section just used square brackets for everything, sometimes angles, so I moved on thinking I must have referenced something "official" that covered everything. It might be just something you pick up using UNIX, or cli in general. Some of the reference manuals I linked are more specific. Maybe I didn't actually read some spec, just lots of manuals over the years, so its just the way it is.

Anyways, thanks for the reply!