[getopt-sig] my vote is for automatic usage message generation

[Russ Cox]

I'm torn about this.

I agree in principle -- it would be wonderful if we could arrange
things so that the code and the documentation automatically agree.

Even if I concede that full documentation belongs in the usage message
(which I'm not sure about), the price appears to be that you can't
customize the documentation as much as might be most helpful for the
users.  For example, below is output of GNU grep --help.  Perhaps the
getopt parser that GNU grep is using generated the message
automatically, but I doubt it.  I think that humans formatting the
usage messages still holds the best hope for very good usage messages.

As another example, consider sed's property that the presence of some
options (-e, -f) changes the interpretation of the remaining
arguments.  It's going to be hard to work that into an automatic usage
message-generation framework.

Finally, just because the parser knows about the option doesn't mean
that the program consults it.  I've seen far too many getopt format
strings that specify old arguments that have fallen out of use and
simply weren't removed from the string.  Automatic parser-generated
documentation doesn't help here.

I'm just not convinced that keeping the parser and the documentation
consistent completely solves the documentation problem; while it often
generates reasonable documentation, it makes it hard to write very
good documentation, and there's still no guarantee that the
documentation is correct (although I admit it's likely closer).  If
you write very good documentation by overriding the usage string,
you've lost the benefit and paid the price in (lack of) code clarity.

Russ

=====

Usage: grep [OPTION]... PATTERN [FILE] ...
Search for PATTERN in each FILE or standard input.
Example: grep -i 'hello world' menu.h main.c

Regexp selection and interpretation:
  -E, --extended-regexp     PATTERN is an extended regular expression
  -F, --fixed-strings       PATTERN is a set of newline-separated strings
  -G, --basic-regexp        PATTERN is a basic regular expression
  -e, --regexp=PATTERN      use PATTERN as a regular expression
  -f, --file=FILE           obtain PATTERN from FILE
  -i, --ignore-case         ignore case distinctions
  -w, --word-regexp         force PATTERN to match only whole words
  -x, --line-regexp         force PATTERN to match only whole lines
  -z, --null-data           a data line ends in 0 byte, not newline

Miscellaneous:
  -s, --no-messages         suppress error messages
  -v, --invert-match        select non-matching lines
  -V, --version             print version information and exit
      --help                display this help and exit
      --mmap                use memory-mapped input if possible

Output control:
  -b, --byte-offset         print the byte offset with output lines
  -n, --line-number         print line number with output lines
  -H, --with-filename       print the filename for each match
  -h, --no-filename         suppress the prefixing filename on output
  -q, --quiet, --silent     suppress all normal output
      --binary-files=TYPE   assume that binary files are TYPE
                            TYPE is 'binary', 'text', or 'without-match'.
  -a, --text                equivalent to --binary-files=text
  -I                        equivalent to --binary-files=without-match
  -d, --directories=ACTION  how to handle directories
                            ACTION is 'read', 'recurse', or 'skip'.
  -r, --recursive           equivalent to --directories=recurse.
  -L, --files-without-match only print FILE names containing no match
  -l, --files-with-matches  only print FILE names containing matches
  -c, --count               only print a count of matching lines per FILE
  -Z, --null                print 0 byte after FILE name

Context control:
  -B, --before-context=NUM  print NUM lines of leading context
  -A, --after-context=NUM   print NUM lines of trailing context
  -C, --context[=NUM]       print NUM (default 2) lines of output context
                            unless overridden by -A or -B
  -NUM                      same as --context=NUM
  -U, --binary              do not strip CR characters at EOL (MSDOS)
  -u, --unix-byte-offsets   report offsets as if CRs were not there (MSDOS)

=====

Usage: sed [OPTION]... {script-only-if-no-other-script} [input-file]...

  -n, --quiet, --silent
                 suppress automatic printing of pattern space
  -e script, --expression=script
                 add the script to the commands to be executed
  -f script-file, --file=script-file
                 add the contents of script-file to the commands to be executed
      --help     display this help and exit
  -V, --version  output version information and exit

If no -e, --expression, -f, or --file option is given, then the first
non-option argument is taken as the sed script to interpret.  All
remaining arguments are names of input files; if no input files are
specified, then the standard input is read.