Take the 2-minute tour ×
Unix & Linux Stack Exchange is a question and answer site for users of Linux, FreeBSD and other Un*x-like operating systems.. It's 100% free, no registration required.

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?

share|improve this question
    
Pick one and stick with it. –  Kevin Jul 3 at 18:26
    
For some reason I don't think that would help. Every person would have there own standard, and then nothing would ever get done about it. –  Tormyst Jul 3 at 18:35
4  
Is this the sort of standard you mean? pubs.opengroup.org/onlinepubs/009695399/basedefs/… –  Mark Plotnick Jul 3 at 18:43
    
Yes, this is exactly what I was looking for. Thank you. –  Tormyst Jul 3 at 18:46
1  
@MarkPlotnick - I'd make that an A so the OP can accept it. That's the standard if ever there was one. Reference the link that illuminÉ referenced. –  slm Jul 3 at 20:55

1 Answer 1

up vote 5 down vote accepted

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.