Re: FYI: --help now warns about built-in conflicts

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

[forwarding to the bug-help2man list (where is it archived?) and Brendan]

For reference on the help2man side of things, CVS coreutils is currently
using the following text in the USAGE_BUILTIN_WARNING macro to document
when a coreutils program may be shadowed by a shell builtin:

NOTE: your shell may have its own version of <program>, which usually
supersedes the version described here.  Please refer to your shell's
documentation for details about the options it supports.

According to Jim Meyering on 4/5/2005 8:19 AM:
>>>Initially, I added those three lines at the very top (between the Usage 
>>>line(s)
>>>and the short description), since mistaking the man-page as a reference
>>>for the built-in is such a common problem.  But I didn't like that.
>>>Now it's at the end, e.g.:
>>
>>Is there any way to get the --help output to put the warning at the end, but
>>the man page to list it at the front?  With --help, the last thing printed is 
>>most
>>important, but in man pages, the first screenful is most important.  What does
>>help2man offer to help us acheive this?  Do we need a new section name?
> 
> 
> That sounds worthwhile.
> I didn't see anything in help2man that looked like it'd be appropriate.
> Maybe Brendan O'Dea (help2man author) can suggest something -- or even
> add the feature.
> 
> In case anyone is interested, here's a patch that would add a new
> section name, `WARNING' to help2man.  But calling it `WARNING' is
> probably too extreme.  Besides, I suppose adding a new section is
> not something to do lightly.

The man page reference at http://www.schweikhardt.net/man_page_howto.html
recommends inventing other sections as needed (and even `man man' on my
system has invented the CAT PAGES and TIPS sections, for example).  I
don't think WARNING is too extreme, since we really are trying to warn the
user that this man page documents the coreutils program, and not the shell
builtin.

Also, is it worth updating USAGE_BUILTIN_WARNING in system.h to give the
hint that calling $(bindir)/program always gets the coreutils version of
program that the man page is documenting?  But I don't see an easy way to
refer to the configure variable %bindir% from the system.h macro.

> 
> Index: help2man
> ===================================================================
> RCS file: /fetish/cu/man/help2man,v
> retrieving revision 1.28
> diff -u -p -r1.28 help2man
> --- help2man  25 Nov 2004 22:17:55 -0000      1.28
> +++ help2man  5 Apr 2005 13:28:59 -0000
> @@ -373,6 +373,7 @@ my $PAT_BUGS              = _('Report +bugs|Email +b
>  my $PAT_AUTHOR               = _('Written +by');
>  my $PAT_OPTIONS              = _('Options');
>  my $PAT_EXAMPLES     = _('Examples');
> +my $PAT_WARNING              = _('WARNING');
>  my $PAT_FREE_SOFTWARE        = _('This +is +free +software');
>  
>  # Start a new paragraph (if required) for these.
> @@ -393,6 +394,11 @@ while (length)
>       $sect = _('EXAMPLES');
>       next;
>      }
> +    elsif (s/^($PAT_WARNING): *\n//o)
> +    {
> +     $sect = _('WARNING');
> +     next;
> +    }
>  
>      # Copyright section
>      if (/^Copyright +[(\xa9]/)
> @@ -581,8 +587,8 @@ print <<EOT;
>  EOT
>  
>  # Section ordering.
> -my @pre = (_('NAME'), _('SYNOPSIS'), _('DESCRIPTION'), _('OPTIONS'),
> -    _('EXAMPLES'));
> +my @pre = (_('NAME'), _('SYNOPSIS'), _('WARNING'), _('DESCRIPTION'),
> +        _('OPTIONS'), _('EXAMPLES'));
>  
>  my @post = (_('AUTHOR'), _('REPORTING BUGS'), _('COPYRIGHT'), _('SEE ALSO'));
>  my $filter = join '|', @pre, @post;
> 

- --
Life is short - so eat dessert first!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.0 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFCVS6w84KuGfSFAYARAhdMAJ9Fx3DF5UGKqKWdtIVwipRpTUWFDwCgzw02
NmbVYLvwhGZinJhhyCDfv1M=
=2Nds
-----END PGP SIGNATURE-----