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

[Brendan O'Dea]

On Thu, Apr 07, 2005 at 06:59:28AM -0600, Eric Blake wrote:
>[forwarding to the bug-help2man list (where is it archived?) and Brendan]

It's not a list, merely an alias to my address.

[USAGE_BUILTIN_WARNING macro]
>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:
>> 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.

I'm not sure if "WARNING" is really justified here, since the usage of
the binaries in coreutils is generally a sub-set of the bultin
behaviour, so the documentation may be incomplete rather than incorrect.

As such, "NOTE" (or perhaps "NOTES", which is a fairly common man
subsection name) is probably more appropriate thsn "WARNING".

I haven't currently given "NOTES" an explicit ordering in @pre or @post,
although if I were to do so I'd probably place it as the first element
of @post.

One thing I did note about the USAGE_BUILTIN_WARNING macro is that for
at least the case of test/[ in CVS it produces lines in excess of 80
chars.

--bod