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

[Eric Blake]

> FYI,
> Before, 3 man pages (echo, printf, pwd) included a warning like this:
> 
>   NOTE: your shell may have its own version of printf, which usually 
> supersedes
>   the version described here.  Please refer to your shell's documentation
>   for details about the options it supports.
> 
> I've put that warning in the --help output of 7 commands (actually,
> it's 8.5 if you count `[' and `false'), so it will now appear
> automatically in the generated man/*.1 files.  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.

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

--
Eric Blake