[src/trunk]: src/bin/sh Man page enhancements.

[kre <kre%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/79e470b1b476
branches:  trunk
changeset: 942857:79e470b1b476
user:      kre <kre%NetBSD.org@localhost>
date:      Thu Aug 20 23:19:34 2020 +0000

description:
Man page enhancements.

Better describe the command search procedure.
Document "trap -P"
Describe what works as a function name.
More accurate description of reserved word recognition.
Be more accurate about when field splittng happens after
expansions (and in particular note that tilde expansions are
not subject to field splitting).   Be clear that "$@" is
not field split, it simply produces multiple fields as part
of its expansion (hence IFS is irrelevant to this), but if
used as $@ (unquoted) each field produced is potentially subject
to field splitting.   Other minor wording changes.

diffstat:

 bin/sh/sh.1 |  98 ++++++++++++++++++++++++++++++++++++++++++++++--------------
 1 files changed, 75 insertions(+), 23 deletions(-)

diffs (172 lines):

diff -r fc9eea499177 -r 79e470b1b476 bin/sh/sh.1
--- a/bin/sh/sh.1       Thu Aug 20 23:09:56 2020 +0000
+++ b/bin/sh/sh.1       Thu Aug 20 23:19:34 2020 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: sh.1,v 1.224 2020/02/20 18:24:20 pgoyette Exp $
+.\"    $NetBSD: sh.1,v 1.225 2020/08/20 23:19:34 kre Exp $
 .\" Copyright (c) 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
 .\"
@@ -31,7 +31,7 @@
 .\"
 .\"    @(#)sh.1        8.6 (Berkeley) 5/4/95
 .\"
-.Dd February 20, 2020
+.Dd August 20, 2020
 .Dt SH 1
 .\" everything except c o and s (keep them ordered)
 .ds flags abCEeFfhIiLmnpquVvXx
@@ -815,8 +815,11 @@
 .Ss Reserved Words
 .\"
 Reserved words are words that have special meaning to the
-shell and are recognized at the beginning of a line and
-after a control operator.
+shell and are recognized,
+if completely unquoted,
+at the beginning of a line,
+after a control operator,
+and where the syntax of a command specifically requires a reserved word.
 The following are reserved words:
 .Bl -column while while while while -offset indent
 .It Ic \&! Ta Ic \&{ Ta Ic \&} Ta Ic case
@@ -1108,16 +1111,17 @@
 .\"
 .Ss Path Search
 .\"
-When locating a command, the shell first looks to see if it has a shell
-function by that name.
-Then it looks for a built-in command by that name.
-If a built-in command is not found, one of two things happen:
-.Bl -enum
-.It
-Command names containing a slash are simply executed without performing
-any searches.
-.It
-Otherwise, the shell searches each entry in
+When locating a command,
+command names containing a slash
+.Pq Sq \&/
+are simply executed without performing any searches.
+.Pp
+If there is no slash in the name,
+the shell first looks to see if it is a special built-in command,
+if not it looks to see if there is a shell function by that name.
+If that fails it looks for an ordinary built-in command.
+If a none of these searches located the command
+the shell searches each entry in
 .Ev PATH
 in turn for the command.
 The value of the
@@ -1541,7 +1545,34 @@
 .Dl Ar name Ns Ic \&() Ar command Op Ar redirect No ...
 .Pp
 A function definition is an executable statement; when executed it
-installs a function named name and returns an exit status of zero.
+installs a function named
+.Ar name
+and returns an exit status of zero.
+To be portable, and standards compliant, the name must use the same
+syntax as a variable name, (see
+.Sx "Variables and Parameters"
+below).
+As an extension, this shell allows almost all characters in
+.Ar name
+.Po
+the exception is slash
+.Pq Sq \&/
+as there is no way to invoke a function with a name containing
+a slash
+.Pc .
+Including quoting, whitespace, and operator characters requires
+that the word be quoted.
+The
+.Ar name
+is subject to quote removal, but no other expansions.
+Because of implementation issues,
+unquoted dollar signs
+.Pq Sq \&$
+and backquotes
+.Pq Sq \&`
+are prohibited,
+but can be included in a function name by use of quoting.
+.Pp
 The command is normally a list enclosed between
 .Dq {
 and
@@ -1748,12 +1779,15 @@
 .Bl -enum
 .It
 Tilde Expansion, Parameter Expansion, Command Substitution,
-Arithmetic Expansion (these all occur at the same time).
+Arithmetic Expansion (these all occur at the same time, and the
+result of any of these expansions is not rescanned for further
+instances of the expansion, or any of the others).
 .It
+Unless the
+.Ev IFS
+variable has an empty value,
 Field Splitting is performed on fields
-generated by step (1) unless the
-.Ev IFS
-variable is null.
+generated by step (1) except for Tilde Expansion.
 .It
 Pathname Expansion (unless set
 .Fl f
@@ -1821,8 +1855,15 @@
 pathname expansion is not performed on the results of the expansion;
 .It
 field splitting is not performed on the results of the
-expansion, with the exception of the special rules for
-.Dv @ . \" $@
+expansion.
+Note that the special rules for
+.Dv @  \" $@
+can result in multiple fields being produced, but this is
+not because of field-splitting.
+If unquoted, each
+field produced by
+.Dv $ \" $@
+is subject to field splitting.
 .El
 .Pp
 In addition, a parameter expansion where braces are used,
@@ -3441,7 +3482,8 @@
 .It Ic trap Ar action signal ...
 .It Ic trap \-
 .It Ic trap Op Fl l
-.It Ic trap Oo Fl p Oc Ar signal ...
+.It Ic trap Fl p Oo Ar signal ... Oc
+.It Ic trap Fl P Ar signal ...
 .It Ic trap Ar N signal ...
 .Pp
 Cause the shell to parse and execute action when any of the specified
@@ -3502,9 +3544,15 @@
 flag, trap prints the same information for the signals specified,
 or if none are given, for all signals, including those where the
 action is the default.
+The
+.Fl P
+flag is similar, but prints only the action(s) associated with the
+named signals, at least (and usually only) one of which must be given.
+Nothing is printed if the action is the default,
+an empty line is printed for ignored signals.
 These variants of the trap command may be executed in a sub-shell
 .Pq "such as in a command substitution" ,
-provided they appear as the sole, or first, command in that sub-shell,
+provided they appear as the initial sequence of commands in that sub-shell,
 in which case the state of traps from the parent of that
 sub-shell is reported.
 .Pp
@@ -3534,6 +3582,10 @@
 .Dq HUP
 command, or function, upon receiving signal INT.
 .Pp
+.Dl Ic eval Qo \&$( trap -P QUIT \&) Qc
+.Pp
+Parse and execute the action that would be invoked were a SIGQUIT received.
+.Pp
 .Dl trap 1 2
 .Pp
 Reset the actions for signals 1 (HUP) and 2 (INT) to their defaults.