[PATCH] doc: mention which commands may be built-in functions

[Jim Meyering]

This started when I noticed that in Solaris 11's /bin/sh
sleep is a built-in function.  That broke one of coreutils' tests.
(fixed, patch coming up)

        doc: mention which commands may be built-in functions
        * doc/coreutils.texi (mayConflictWithShellBuiltIn): New macro.
        (mknod invocation, stat invocation, echo invocation)
        (printf invocation, test invocation, pwd invocation)
        (nice invocation, kill invocation, sleep invocation): Use it.
        (printf invocation): Invoke via "env" rather than using a
        literal /usr/local/bin/ prefix in examples.

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 7b7e47a..804f60f 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -596,6 +596,16 @@ Common options
 @xref{Trailing slashes}.
 @end macro

address@hidden mayConflictWithShellBuiltIn{cmd}
address@hidden conflicts with shell built-ins
address@hidden built-in shell commands, conflicts with
+Due to shell aliases and built-in @command{\cmd\} command, using an
+unadorned @command{\cmd\} interactively or in a script may get you
+different functionality than that described here.  Invoke it via
address@hidden (i.e., @code{env \cmd\ @dots{}}) to avoid interference
+from the shell.
+
address@hidden macro
 @cindex common options

 Certain options are available in all of these programs.  Rather than
@@ -8808,6 +8818,9 @@ mknod invocation
 time or a ``block'' (many characters) at a time, hence we say there are
 @dfn{block special} files and @dfn{character special} files.

address@hidden mknod is a shell built-in at least with OpenBSD's /bin/sh
address@hidden
+
 The arguments after @var{name} specify the type of file to make:

 @table @samp
@@ -10147,6 +10160,7 @@ stat invocation
 given files are located on.  If the files are links, @command{stat} can
 also give information about the files the links point to.

address@hidden

 @table @samp

@@ -10396,6 +10410,8 @@ echo invocation
 echo address@hidden@dots{} address@hidden@dots{}
 @end example

address@hidden
+
 The program accepts the following options.  Also see @ref{Common options}.
 Options must precede operands, and the normally-special argument
 @samp{--} has no special meaning and is treated like any other
@@ -10483,7 +10499,9 @@ printf invocation
 in a way that is mostly similar to the C @samp{printf} function.
 @xref{Output Conversion Syntax,, @command{printf} format directives,
 libc, The GNU C Library Reference Manual}, for details.
-The differences are as follows:
+The differences are listed below.
+
address@hidden

 @itemize @bullet

@@ -10579,7 +10597,7 @@ printf invocation
 independent way.  For example, a string containing the Euro currency symbol

 @example
-$ /usr/local/bin/printf '\u20AC 14.95'
+$ env printf '\u20AC 14.95'
 @end example

 @noindent
@@ -10587,15 +10605,15 @@ printf invocation
 (@acronym{ISO}-8859-15, UTF-8, and others).  Similarly, a Chinese string

 @example
-$ /usr/local/bin/printf '\u4e2d\u6587'
+$ env printf '\u4e2d\u6587'
 @end example

 @noindent
 will be output correctly in all Chinese locales (GB2312, BIG5, UTF-8, etc).

-Note that in these examples, the full name of @command{printf} has been
-given, to distinguish it from the GNU @code{bash} built-in function
address@hidden
+Note that in these examples, the @command{printf} command has been
+invoked via @command{env} to ensure that we run the program found via
+your shell's search @code{PATH}, and not a shell alias or a built-in function.

 For larger strings, you don't need to look up the hexadecimal code
 values of each character one by one.  @acronym{ASCII} characters mixed with \u
@@ -10752,11 +10770,7 @@ est invocation
 [ @var{option}
 @end example

address@hidden conflicts with shell built-ins
address@hidden built-in shell commands, conflicts with
-Because most shells have a built-in @command{test} command, using an
-unadorned @command{test} in a script or interactively may get you
-different functionality than that described here.
address@hidden

 If @var{expression} is omitted, @command{test} returns false.
 If @var{expression} is a single argument,
@@ -11711,15 +11725,11 @@ pwd invocation
 That is, all components of the printed name will be actual directory
 names---none will be symbolic links.

address@hidden conflicts with shell built-ins
address@hidden built-in shell commands, conflicts with
-Because most shells have a built-in @command{pwd} command, using an
-unadorned @command{pwd} in a script or interactively may get you
-different functionality than that described here.
-
 The only options are a lone @option{--help} or
 @option{--version}.  @xref{Common options}.

address@hidden
+
 @exitstatus


@@ -13897,11 +13907,7 @@ nice invocation
 @var{command} must not be a special built-in utility (@pxref{Special
 built-in utilities}).

address@hidden conflicts with shell built-ins
address@hidden built-in shell commands, conflicts with
-Because many shells have a built-in @command{nice} command, using an
-unadorned @command{nice} in a script or interactively may get you
-different functionality than that described here.
address@hidden

 The program accepts the following option.  Also see @ref{Common options}.
 Options must precede operands.
@@ -14292,6 +14298,8 @@ kill invocation
 kill [-l | --list | -t | --table] address@hidden@dots{}
 @end example

address@hidden
+
 The first form of the @command{kill} command sends a signal to all
 @var{pid} arguments.  The default signal to send if none is specified
 is @samp{TERM}.  The special signal number @samp{0} does not denote a
@@ -14398,6 +14406,9 @@ sleep invocation
 The only options are @option{--help} and @option{--version}.  @xref{Common
 options}.

address@hidden sleep is a shell built-in at least with Solaris 11's /bin/sh
address@hidden
+
 @exitstatus


--
1.6.0.1.285.g1070