>Number:         2721
>Category:       bin
>Synopsis:       sh.1 is obscure in places
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    bin-bug-people (Utility Bug People)
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Thu Aug 29 22:05:06 1996
>Last-Modified:
>Originator:     VaX#n8
>Organization:
Random
>Release:        1.2_BETA
>Environment:
	
System: NetBSD linkdead.paranoia.com 1.2_BETA NetBSD 1.2_BETA (LINKDEAD) #1: Tue Aug 13 01:08:43 CDT 1996 bashroot@linkdead.paranoia.com:/usr/src/sys/arch/i386/compile/LINKDEAD i386


>Description:
	
>How-To-Repeat:
	
>Fix:
	

Apply this patch to manpage

--- sh.1.orig	Sat Aug 24 07:20:16 1996
+++ sh.1	Sat Aug 24 10:55:22 1996
@@ -191,11 +191,11 @@
 running (i.e. with set(1)).
 .TP
 -V    vi
-Enable the builtin vi(1) command line editor (disables
+Enable the built-in vi(1) command line editor (disables
 -E if it has been set).
 .TP
 -E    emacs
-Enable the builtin emacs(1) command line editor (disables
+Enable the built-in emacs(1) command line editor (disables
 -V if it has been set).
 .TP
 -b    notify
@@ -241,7 +241,8 @@
 .sp
 .LP
 Enclosing characters in single quotes preserves the literal
-meaning of all the characters.
+meaning of all the characters (except single quotes, making
+it impossible to put single-quotes in a single-quoted string).
 .sp 2
 .B Double Quotes
 .sp
@@ -397,11 +398,13 @@
 .B Search and Execution
 .sp
 .LP
-There are three types of commands: shell functions, builtin commands, and normal programs -- and the
+There are three types of commands: shell functions,
+builtin commands, and normal programs -- and the
 command is searched for (by name) in that order.  They
 each are executed in a different way.
 .LP
-When a shell function is executed, all of the shell positional parameters (except $0, which remains unchanged) are
+When a shell function is executed, all of the shell positional
+parameters (except $0, which remains unchanged) are
 set to the arguments of the shell function.
 The variables which are explicitly placed in the environment of
 the command (by placing assignments to them before the
@@ -409,37 +412,49 @@
 to the values given. Then the command given in the function
 definition is executed.   The positional parameters are
 restored to their original values when the command completes.
+This all occurs within the current shell.
 .LP
-Shell builtins are executed internally to the shell, without spawning a new process.
+Shell builtins are executed internally to the shell, without
+spawning a new process.
 .LP
 Otherwise, if the command name doesn't match a function
 or builtin, the command is searched for as a normal
 program in the filesystem (as described in the next section).
 When a normal program is executed, the shell runs the program,
 passing the arguments and the environment to the
-program. If the program is a shell procedure, the shell
-will interpret the program in a subshell.  The shell will
+program. If the program is not a normal executable file
+(i.e., if it does not begin with the "magic number"
+whose ASCII representation is "#!", so execve(2) returns
+ENOEXEC then) the shell
+will interpret the program in a subshell.  The child shell will
 reinitialize itself in this case, so that the effect will
-be as if a new shell had been invoked to handle the shell
-procedure, except that the location of commands located in
+be as if a new shell had been invoked to handle the ad-hoc shell
+script, except that the location of hashed commands located in
 the parent shell will be remembered by the child.
+.LP
+Note that previous versions of this document
+and the source code itself misleadingly and sporadically
+refer to a shell script without a magic number
+as a "shell procedure".
 .sp 2
 .B Path Search
 .sp
 .LP
 When locating a command, the shell first looks to see if
 it has a shell function by that name.  Then it looks for a
-builtin command by that name.
-Finally, it searches each
-entry in PATH in turn for the command.
-.LP
+builtin command by that name.  If a builtin command is not found,
+one of two things happen:
+.sp
+1) Command names containing a slash are simply executed without
+performing any searches.
+.sp
+2) The shell searches each entry in PATH in turn for the command.
 The value of the PATH variable should be a series of
 entries separated by colons.  Each entry consists of a
 directory name.
 The current directory
-may be indicated by an empty directory name.
-.LP
-Command names containing a slash are simply executed without performing any of the above searches.
+may be indicated implicitly by an empty directory name,
+or explicitly by a single period.
 .sp 2
 .B Command Exit Status
 .sp
@@ -450,7 +465,7 @@
 error, or a false indication.  The man page for each command
 should indicate the various exit codes and what they mean.
 Additionally, the builtin commands return exit codes, as does
-an executed function.
+an executed shell function.
 .sp 2
 .B Complex Commands
 .sp
@@ -475,13 +490,14 @@
 Unless otherwise stated, the exit status of a command is
 that of the last simple command executed by the command.
 .sp 2
-.B Pipeline
+.B Pipelines
 .sp
 .LP
 A pipeline is a sequence of one or more commands separated
 by the control operator |.  The standard output of all but
 the last command is connected to the standard input
-of the next command.
+of the next command.  The standard output of the last
+command is inherited from the shell, as usual.
 .LP
 The format for a pipeline is:
 .nf
@@ -521,6 +537,12 @@
 A ; or <newline> terminator causes the preceding
 AND-OR-list (described next) to be executed sequentially; a & causes
 asynchronous execution of the preceding AND-OR-list.
+.LP
+Note that unlike some other shells, each process in the
+pipeline is a child of the invoking shell (unless it
+is a shell builtin, in which case it executes in the
+current shell -- but any effect it has on the
+environment is wiped).
 .sp 2
 .B Background Commands -- &
 .sp
@@ -551,6 +573,9 @@
 command and immediately proceed onto the next command;
 otherwise it waits for the command to terminate before
 proceeding to the next one.
+.sp 2
+.B Short-Circuit List Operators
+.sp
 .LP
 ``&&'' and ``||'' are AND-OR list operators.  ``&&'' executes
 the first command, and then executes the second command
@@ -558,6 +583,9 @@
 is similar, but executes the second command iff the exit
 status of the first command is nonzero.  ``&&'' and ``||''
 both have the same priority.
+.sp 2
+.B Flow-Control Constructs -- if, while, for, case
+.sp
 .LP
 The syntax of the if command is
 .nf
@@ -578,7 +606,9 @@
     done
 
 .fi
-The two lists are executed repeatedly while the exit status of the first list is zero.  The until command is similar, but has the word until in place of while
+The two lists are executed repeatedly while the exit status of the
+first list is zero.  The until command is similar, but has the word
+until in place of while, which causes it to
 repeat until the exit status of the first list is zero.
 .LP
 The syntax of the for command is
@@ -601,7 +631,8 @@
 
 .fi
 Break terminates the num innermost for or while loops.
-Continue continues with the next iteration of the innermost loop.  These are implemented as builtin commands.
+Continue continues with the next iteration of the innermost loop.
+These are implemented as builtin commands.
 .LP
 The syntax of the case command is
 .nf
@@ -615,7 +646,9 @@
 .LP
 The pattern can actually be one or more patterns (see Shell
 Patterns described later), separated by ``|'' characters.
-
+.sp 2
+.B Grouping Commands Together
+.sp
 .LP
 Commands may be grouped by writing either
 .nf
@@ -630,6 +663,17 @@
 
 .fi
 The first of these executes the commands in a subshell.
+Builtin commands grouped into a (list) will not affect
+the current shell.
+The second form does not fork another shell so is
+slightly more efficient.
+Grouping commands together this way allows you to
+redirect their output as though they were one program:
+.nf
+
+    { echo -n "hello"; echo " world" } > greeting
+
+.fi
 .sp 2
 .B Functions
 .sp
@@ -661,7 +705,8 @@
 with the same name in the surrounding scope, if there is
 one.  Otherwise, the variable is initially unset.   The shell
 uses dynamic scoping, so that if you make the variable x
-local to function f, which then calls function g, references to the variable x made inside g will refer to the
+local to function f, which then calls function g, references
+to the variable x made inside g will refer to the
 variable x declared inside f, not to the global variable
 named x.
 .LP
@@ -879,7 +924,8 @@
 the value of parameter.
 .LP
 The following four varieties of parameter expansion provide for substring
-processing.  In each case, pattern matching notation (see Shell Patterns), rather
+processing.  In each case, pattern matching notation (see Shell Patterns),
+rather
 than regular expression notation, is used to evaluate the patterns.
 If parameter is * or @, the result of the expansion is unspecified.
 Enclosing the full parameter expansion string in double-quotes does not
@@ -980,12 +1026,14 @@
 .B Pathname Expansion (File Name Generation)
 .sp
 .LP
-Unless the -f flag is set, file name generation is performed after word splitting is complete.  Each word is
+Unless the -f flag is set, file name generation is performed
+after word splitting is complete.  Each word is
 viewed as a series of patterns, separated by slashes.  The
 process of expansion replaces the word with the names of
 all existing files whose names can be formed by replacing
 each pattern with a string that matches the specified pattern.
-There are two restrictions on this: first, a pattern cannot match a string containing a slash, and second,
+There are two restrictions on this: first, a pattern cannot match
+a string containing a slash, and second,
 a pattern cannot match a string starting with a period
 unless the first character of the pattern is a period.
 The next section describes the patterns used for both
@@ -995,7 +1043,8 @@
 .B Shell Patterns
 .sp
 .LP
-A pattern consists of normal characters, which match themselves, and meta-characters.   The meta-characters are
+A pattern consists of normal characters, which match themselves,
+and meta-characters.   The meta-characters are
 ``!'', ``*'', ``?'', and ``[''.  These  characters lose
 there special meanings if they are quoted.  When command
 or variable substitution is performed and the dollar sign
@@ -1025,7 +1074,8 @@
 .LP
 This section lists the builtin commands which
 are builtin because they need to perform some  operation
-that can't be performed by a separate process. In addition to these, there are several other commands that may
+that can't be performed by a separate process. In addition to
+these, there are several other commands that may
 be builtin for efficiency (e.g. printf(1), echo(1), test(1),
 etc).
 .TP
@@ -1047,7 +1097,8 @@
 jobs are given) in the background.
 .TP
 command command arg...
-Execute the specified builtin command.  (This is useful when you have a shell function with the same name
+Execute the specified builtin command.  (This is useful when you
+have a shell function with the same name
 as a builtin command.)
 .TP
 cd [ directory ]
@@ -1057,7 +1108,8 @@
 and the directory name does not begin with a slash,
 then the directories listed in CDPATH will be
 searched for the specified directory.  The format of
-CDPATH is the same as that of PATH. In an interactive shell, the cd command will print out the name of
+CDPATH is the same as that of PATH. In an interactive shell,
+the cd command will print out the name of
 the directory that it actually switched to if this is
 different from the name that the user gave.  These
 may be different either because the CDPATH mechanism
@@ -1071,7 +1123,8 @@
 Unless command is omitted, the shell process is
 replaced with the specified program (which must be a
 real program, not a shell builtin or function).   Any
-redirections on the exec command are marked as permanent, so that they are not undone when the exec command finishes.
+redirections on the exec command are marked as permanent,
+so that they are not undone when the exec command finishes.
 .TP
 exit [ exitstatus ]
 Terminate the shell process.  If exitstatus is given
@@ -1178,7 +1231,8 @@
 the last cd command are marked with an asterisk; it
 is possible for these entries to be invalid.
 .sp
-With arguments, the hash command removes the specified commands from the hash table (unless they are
+With arguments, the hash command removes the specified
+commands from the hash table (unless they are
 functions) and then locates them.   With the -v
 option, hash prints the locations of the commands as
 it finds them.  The -r option causes the hash command
@@ -1209,15 +1263,18 @@
 is deleted from the line and the line is split as
 described in the section on word splitting above, and
 the pieces are assigned to the variables in order.
-If there are more pieces than variables, the remaining pieces (along with the characters in IFS that
+If there are more pieces than variables, the remaining
+pieces (along with the characters in IFS that
 separated them) are assigned to the last variable.
-If there are more variables than pieces, the remaining variables are assigned the null string.
+If there are more variables than pieces, the remaining
+variables are assigned the null string.
 .sp
 The -e option causes any backslashes in the input to
 be treated specially.  If a backslash is followed by
 a newline, the backslash and the newline will be
 deleted.   If a backslash is followed by any other
-character, the backslash will be deleted and the following character will be treated as though it were
+character, the backslash will be deleted and the following
+character will be treated as though it were
 not in IFS, even if it is.
 .TP
 readonly name...
@@ -1243,7 +1300,8 @@
 The third use of the set command is to set the values
 of the shell's positional parameters to the specified
 args.   To change the positional parameters without
-changing any options, use ``--'' as the first argument to set.  If no args are present, the set command
+changing any options, use ``--'' as the first argument
+to set.  If no args are present, the set command
 will clear all the positional parameters (equivalent
 to executing ``shift $#''.
 .TP
>Audit-Trail:
>Unformatted: