Re: (man|info) pages and --help

[Jim Meyering]

C de-Avillez wrote:

> On Thu, 2009-09-17 at 11:59 -0700, Micah Cowan wrote:
>> -----BEGIN PGP SIGNED MESSAGE-----
>> Hash: SHA1
>>
>> C de-Avillez wrote:
>> > So. Would it be an acceptable idea to add, to the '--help', a warning
>> > that this is *not* the full documentation?
>> >
>> > Say, like:
>> >
>> > "This is an abridged documentation. The full documentation for blahblah
>> > is maintained as a Texinfo manual. If the info and date programs are
>> > properly installed at your site, the command
>> >
>> >               info coreutils 'blahblah invocation'
>> >
>> >        should give you access to the complete manual."
>>
>> Is there anyone who's unaware that --help doesn't provide complete
>> documentation?
>
> I would not expect anyone to *not* know that help output is abridged.
> But I would rather have them go straight into 'info' than wasting time
> on 'man', only to be redirected to 'info'.
>
> Usually one looks at the '--help' output first. If we redirect on 'man',
> why not there?

I'm tempted to say add a one-liner, but there are already *four*
lines at the end of even the smallest --help output message, e.g.,

    $ sync --help
    Usage: sync [OPTION]
    Force changed blocks to disk, update the super block.

          --help     display this help and exit
          --version  output version information and exit

    Report sync bugs to address@hidden
    GNU coreutils home page: <http://www.gnu.org/software/coreutils/>
    General help using GNU software: <http://www.gnu.org/gethelp/>
    Report sync translation bugs to <http://translationproject.org/team/>

I guess you'd like to see this added:

  For complete documentation, run "info coreutils 'sync invocation'"

Maybe.
Though I'm tempted to remove the "Report ... translation bugs..."
line when using the C (or maybe all of en_*, too) locale.

Other opinions?