Re: duplicate documentation

[Ingo Schwarze]

Hi Jan,

Jan Stary wrote on Sun, Nov 15, 2020 at 04:55:08PM +0100:
> On Nov 15 16:23:38, schwarze@usta.de wrote:

>>     Some people argue for a third level of conciseness vs.
>>     completeness, e.g. the --help option.  I consider that detrimental
>>     because it adds a larger amount of text than the SYNOPSIS for
>>     a lesser gain (because you already have both very concise and
>>     very complete docs even without --help.)  So personally, i think
>>     documentation is better without --help.

> Implementing the -h or --help option mostly becomes calling usage(),

Not usually.

The usage() output ideally corresponds to the synopsis:

   $ man -h groff
  groff [-abcegijklpstzCEGNRSUVXZ] [-d cs] [-D arg] [-f fam] [-F dir]
        [-I dir] [-K arg] [-L arg] [-m name] [-M dir] [-n num] [-o list]
        [-P arg] [-r cn] [-T dev] [-w name] [-W name] [file ...]

  groff -h
  groff --help

  groff -v [option ...]
  groff --version [option ...]

   $ groff --usage
  groff: unrecognized option '--usage'
  usage: groff [-abceghijklpstvzCEGNRSUVXZ] [-dcs] [-ffam] [-mname] [-nnum]
         [-olist] [-rcn] [-wname] [-Darg] [-Fdir] [-Idir] [-Karg] [-Larg]
         [-Mdir] [-Parg] [-Tdev] [-Wname] [files...]
  groff -h gives more help

The --help output typically also contains one-line descriptions
of the options:

   $ groff --help
  usage: groff [-abceghijklpstvzCEGNRSUVXZ] [-dcs] [-ffam] [-mname] [-nnum]
         [-olist] [-rcn] [-wname] [-Darg] [-Fdir] [-Idir] [-Karg] [-Larg]
         [-Mdir] [-Parg] [-Tdev] [-Wname] [files...]

  -h      print this message
  -v      print version number
  -e      preprocess with eqn
  -g      preprocess with grn
  -j      preprocess with chem
  -k      preprocess with preconv
  -p      preprocess with pic
  -s      preprocess with soelim
  -t      preprocess with tbl
  -G      preprocess with grap
  -J      preprocess with gideal
  -R      preprocess with refer
  -a      produce ASCII description of output
  -b      print backtraces with errors or warnings
  -c      disable color output
  -dcs    define a string c as s
  -ffam   use fam as the default font family
  -i      read standard input after named input files
  -l      spool the output
  -mname  read macros tmac.name
  -nnum   number first page n
  -olist  output only pages in list
  -rcn    define a number register c as n
  -wname  enable warning name
  -z      suppress formatted output
  -C      enable compatibility mode
  -Darg   use arg as default input encoding.  Implies -k
  -E      inhibit all errors
  -Fdir   search dir for device directories
  -Idir   search dir for soelim, troff, and grops.  Implies -s
  -Karg   use arg as input encoding.  Implies -k
  -Larg   pass arg to the spooler
  -Mdir   search dir for macro files
  -N      don't allow newlines within eqn delimiters
  -Parg   pass arg to the postprocessor
  -S      enable safer mode (the default)
  -Tdev   use device dev
  -U      enable unsafe mode
  -V      print commands on stdout instead of running them
  -Wname  inhibit warning name
  -X      use X11 previewer rather than usual postprocessor
  -Z      don't postprocess

> which will gradually slide out of sync with the description of
> options in DESCRIPTION, the list of options in SYNOPSIS,
> and the actual options string in getopt().

 ... but you are right that if all those exist, they rarely remain
fully in sync over time.  For example, in the groff(1) example
above, --help describes -J, but usage() and SYNOPSIS do not.

Anyway, this was just intended as an example that documentation goals
usually conflict with each other and even when agreeing on the general
goals, that doesn't necessarily lead all documentation authors to
exactly the same conclusions about the best strategies, and even
less so about their application to specific situations.

Allowing outright duplication of major chunks of text, interspersed
with minor differences, still doesn't seem like a very good strategy,
though.

Yours,
  Ingo