Re: visually describing command syntax ?

["Peter Neilson" <neilson -at- windstream -dot- net>]

It's always difficult to document complex syntax. One would naively expect  
to provide a strict format that is possible for mortals to comprehend.  
That, unfortunately, can be a tall order.

If you examine the Unix (or Linux) "man" command's results for the various  
Unix commands you will discover that neither the command structures  
(options and arguments) nor the descriptions are fully uniform. (The 'dd'  
command is notoriously strange, but the syntax of 'find' is hardly  
trivial.) In some situations it is necessary to take certain combinations  
of options and arguments as special cases.

A failure of much traditional Unix documentation is the lack of examples.  
Certain complicated commands have one or two common uses, but these are  
submerged in documentation that covers all possibilities, including the  
most esoteric. To my eye, it makes sense to call out those particular uses  
and give examples of their use, both the simpler cases and the more hairy.  
One should not be required to parse and entire structure of possibilities  
before learning that 24 out of 27 options apply only to extremely rare  
cases.

See the Wikipedia entry on the description of the Unix dd command:  
http://en.wikipedia.org/wiki/Dd_(Unix)

On Thu, 17 Nov 2011 17:06:50 -0500, Dossy Shiobara <dossy -at- panoptic -dot- com>  
wrote: