-----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 [EMAIL PROTECTED] -----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----- _______________________________________________ Bug-coreutils mailing list [email protected] http://lists.gnu.org/mailman/listinfo/bug-coreutils
