Standard for writing a command synopsis

command lineman

It appears to me that everyone has their own idea on how to write a synopsis describing command usage for the end user.

For example, this is the format from man grep:

grep [OPTIONS] PATTERN [FILE...]
grep [OPTIONS] [-e PATTERN | -f FILE] [FILE...]

Now this has some syntax that appears in other manpages. [] is recognized as optional, and ... makes sense as multiple of the same input.

But people use | or / for OR and there are others that will reverse what [] means. Or they do not give any indication as to where [OPTIONS] goes.

I would like to follow a standard for what I write, but every website I look at tells me something different.

Is there an actual standard way of writing synopses, or is the convention just what people have been doing over time?

Best Answer

The classic standard for this is from POSIX, Utility Argument Syntax (thanks to @illuminÉ for the updated link). It describes the syntax to be used in man pages, for example

utility_name[-a][-b][-c option_argument]
    [-d|-e][-f[option_argument]][operand...]

Being classic, it recommends using single-character options, with -W recommended for use by vendors, and that is how multi-character options are accommodated (see, for example, gcc Option Summary).

GNU software introduced multi-character options that start with --. Some guidelines from GNU for formatting man pages with those options can be found in the help2man reference.

Related Solutions

Man Pages – Understand Synopsis in Manpage

The synopsis section usually gives some example use-cases. Sometimes sub-commands have different options, so several examples might be shown.
Brackets [] always denote optional switches, arguments, options, etc.
Yes, the pipe | means or, particularly when inside brackets or parenthesis.
Brackets in brackets just means that the second part is dependent on the first, and also itself optional. Some switches you can use on their own or add a value to them. Commas at the start of a bracket would indicate there can be multiple comma separated values.
They lean on Regex concepts, but are meant to be human readable so don't follow all the escaping rules etc.

Standard Unix Command to Check English Verb Conjugation – Is There One?

Seems the easiest way is to write it yourself. At the first look I found pretty good website, that can give us all information we need. Thus all we need to do is to write a function that will parse it. So five minutes with bash and voila:

 $ function verbteacher() { 
    wget -qO - http://conjugator.reverso.net/conjugation-english-verb-$1.html | \
    sed -n "/>Preterite\|>Past</{s@<[^>]*>@ @g;s/\s\+/ /g;/e I/s/.* I \([^ ]*\) you .*/Simple past: \1/;/ Past/s/ Past /Past participle: /;p}" ; 
 }
 $ verbteacher go
Simple past: went
Past participle: gone 
 $ verbteacher throw
Simple past: threw
Past participle: thrown

So you can put this function to your ~/.bashrc and use it until the site will change its structure. Hope it will never do it.

Obviously it won't work without the internet connection. Hope this is not critical for you.

Best Answer

Related Solutions

Man Pages – Understand Synopsis in Manpage

Standard Unix Command to Check English Verb Conjugation – Is There One?

Related Question