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

[Jim Meyering]

address@hidden (Eric Blake) wrote:
...
>> If anyone knows of any
>> other coreutils commands that are built-in, please let me know.
>
> tcsh provides nice, nohup, and printenv.  Not that csh-variants are
> POSIX-compliant, but they are often a user's default shell, so these three
> should also get the warning.

Thanks.  I've done that.

>> 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.

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;