[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: duplicate documentation

From: Jan Stary
Subject: Re: duplicate documentation
Date: Sun, 15 Nov 2020 16:55:08 +0100

On Nov 15 16:23:38, 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(),
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().

The reason I have most often seen for having --help
is that people want their software to also run on windows,
where there is nothing like a manpage or a place like /usr/share/man,
so prog --help is what they give their users, as if there is no -Tascii.

When reviewing a manpage of a software that does have --help,
there is _always_ some discrepancy between what --help says
and what the manpage says (and what the software actually has).


reply via email to

[Prev in Thread] Current Thread [Next in Thread]