UNIX for Dummies Questions & Answers

In different online sources, I found bits and pieces of information about those square and angular brackets and pipes. From what I have read, I can conclude it looks like this:

1. Options outside any brackets are mandatory
2. Options inside these < .. > are mandatory too
3. Options inside [ .. ] are optional
4. | works like an "exclusive or", separating options inside the brackets they are placed (or outside in case they are not inside any brackets).
5. Options listed with no separators with '-' in front (ex: -abcd) can be used in any combination with each other (i.e. "inclusive or")

First problem is that I'm not even sure I am correct here. Second, I cannot convince developers (I am a tester) to be compliant with any standard in user's manual and in help, since I cannot find any standard. Our project has several dozens of command line utilities each with elaborate parameter strings. The developers make them even more confusing by using '|' both as exclusive and inclusive or. In our latest release I realized that those confuse even me, so I'm concerned about our clients. Is there any standard to which man synopsis with those brackets and pipes is compliant? Is there any convincing source online, where that standard is carefully described?

Interesting, GNU coding standards are very lean on this topic.

I've had a look at a Solaris example...

Code:

     man [-] [-adFlrt] [-M path] [-T macro-package]  [-s section]
     name...

Notice that there is not an option "-adFlrt", they are all different flags, but with no inclusive OR between them. I would tend towards the exclusive OR however I would make the documentation concise and remove ambiguity.

Yes, good point about Solaris. Is seems that my research has failed It is very strange that such a fundamental thing in all UNIXes and UNIX-like operating systems is not standardized in any way.

Not really, UNIX is about mechanism, not policy.

Hi.

Is this convincing?
I agree that consistency is to be valued - especially for a set of commands in a specific project -- however, {GNU/Linux, Solaris, other *nix}-universe consistency and consensus is unlikely in my opinion. It may even be undesirable -- too many rules have a chilling effect on innovation.

Your particular situation may be saying more about your developers than about the *nix universe.

Best wishes ... cheers, drl