man-pages and usage() howto

[Karel Zak <kzak@redhat.com>]

 Hi,

Sami is already working on some howtos, what we need is some
consensus about a way how describe options.

My suggestion:

 * argument required:

   -o, --option FILE    # usage()
   -o, --option file    # man page

 * optional argument:

   -o, --option[=FILE]  # usage()
   -o, --option[=file]  # man page


 * synopsis

   - without individual options, bad example:
   
        command [-o offset] [--sizelimit size] [-p pfd] [-r] file

   - [options] is better:

        command [options] file

   - use more synopsis lines if the command supports more separated modes.

       command --add file
       command --del file

     (use common sense! ... if there is too many modes, then use [options])

     The options specific to the mode are allowed in the synopsis or
     in the man page should be per-mode section with description about
     the options.


 * common options:

   -V, --version
   -h, --help

 * suggestions:

   -a, --all
   -o, --output <list>
   -r, --raw
   -f, --force
   -b, --bytes   (don't print SIZE in human readable format)


 * We also need any consensus about groff formatting, the ideal
   solution would be add any Documentation/example.man

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com