[src/trunk]: src/bin/sh Corrected some typos, added some (hopefully improving...

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

details:   https://anonhg.NetBSD.org/src/rev/b5a1c37f436a
branches:  trunk
changeset: 823873:b5a1c37f436a
user:      kre <kre%NetBSD.org@localhost>
date:      Fri May 12 08:39:47 2017 +0000

description:
Corrected some typos, added some (hopefully improving) extra text,
sorted stuff that needed sorting, and added some (probably incorrect)
markup...

diffstat:

 bin/sh/sh.1 |  465 ++++++++++++++++++++++++++++++++++++++---------------------
 1 files changed, 301 insertions(+), 164 deletions(-)

diffs (truncated from 1031 to 300 lines):

diff -r 773889670750 -r b5a1c37f436a bin/sh/sh.1
--- a/bin/sh/sh.1       Fri May 12 08:03:26 2017 +0000
+++ b/bin/sh/sh.1       Fri May 12 08:39:47 2017 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: sh.1,v 1.136 2017/05/07 15:01:18 kre Exp $
+.\"    $NetBSD: sh.1,v 1.137 2017/05/12 08:39:47 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 May 7, 2017
+.Dd May 12, 2017
 .Dt SH 1
 .ds flags abCEeFfhnuvxIimpqV
 .Os
@@ -90,12 +90,6 @@
 features which make it appear similar in some respects to the Korn shell,
 but it is not a Korn shell clone (see
 .Xr ksh 1 ) .
-Only features designated by
-.Tn POSIX ,
-plus a few Berkeley extensions, are being incorporated into this shell.
-.\" We expect
-.\" .Tn POSIX
-.\" conformance by the time 4.4 BSD is released.
 This man page is not intended
 to be a tutorial or a complete specification of the shell.
 .Ss Overview
@@ -116,8 +110,9 @@
 can be typed directly to the running shell or can be put into a file and
 the file can be executed directly by the shell.
 .Ss Invocation
-If no arguments are present and if the standard input of the shell
-is connected to a terminal (or if the
+If no arguments are present and if the standard input,
+and output, of the shell
+are connected to a terminal (or if the
 .Fl i
 flag is set),
 and the
@@ -140,9 +135,14 @@
 if they exist.
 If the environment variable
 .Ev ENV
-is set on entry to a shell, or is set in the
+is set on entry to a shell,
+or is set in the
 .Pa .profile
-of a login shell, the shell next reads
+of a login shell,
+and either the shell is interactive, or the
+.Cm posix
+option is not set,
+the shell next reads
 commands from the file named in
 .Ev ENV .
 Therefore, a user should place commands that are to be executed only at
@@ -164,7 +164,7 @@
 any filename you wish.
 Since the
 .Ev ENV
-file is read for every invocation of the shell, including shell scripts
+file can be read for every invocation of the shell, including shell scripts
 and non-interactive shells, the following paradigm is useful for
 restricting commands in the
 .Ev ENV
@@ -215,6 +215,9 @@
 .Bl -tag -width aaaallexportfoo -offset indent
 .It Fl a Em allexport
 Export all variables assigned to.
+.It Fl b Em notify
+Enable asynchronous notification of background job completion.
+(Not implemented.)
 .It Fl c
 Read commands from the
 .Ar command_string
@@ -253,55 +256,6 @@
 is tested when
 .Fl e
 is set to determine if the shell should exit.
-.It Fl f Em noglob
-Disable pathname expansion.
-.It Fl n Em noexec
-If not interactive, read commands but do not execute them.
-This is useful for checking the syntax of shell scripts.
-.It Fl u Em nounset
-Write a message to standard error when attempting to expand a variable
-that is not set, and if the shell is not interactive, exit immediately.
-.It Fl v Em verbose
-The shell writes its input to standard error as it is read.
-Useful for debugging.
-.It Fl x Em xtrace
-Write each command to standard error (preceded by a
-.Sq +\  )
-before it is executed.
-Useful for debugging.
-.It Fl q Em quietprofile
-If the
-.Fl v
-or
-.Fl x
-options have been set, do not apply them when reading
-initialization files, these being
-.Pa /etc/profile ,
-.Pa .profile ,
-and the file specified by the
-.Ev ENV
-environment variable.
-.It Fl I Em ignoreeof
-Ignore EOFs from input when interactive.
-.It Fl i Em interactive
-Force the shell to behave interactively.
-.It Fl m Em monitor
-Turn on job control (set automatically when interactive).
-.It Fl s Em stdin
-Read commands from standard input (set automatically if no file arguments
-are present).
-This option has no effect when set or reset after the shell has
-already started running (i.e. with
-.Ic set ) .
-.It Fl V Em vi
-Enable the built-in
-.Xr vi 1
-command line editor (disables
-.Fl E
-if it has been set).
-(See the
-.Sx Command Line Editing
-section below.)
 .It Fl E Em emacs
 Enable the built-in emacs style
 command line editor (disables
@@ -310,9 +264,8 @@
 (See the
 .Sx Command Line Editing
 section below.)
-.It Fl b Em notify
-Enable asynchronous notification of background job completion.
-(Not implemented.)
+.It Fl f Em noglob
+Disable pathname expansion.
 .It Fl F Em fork
 Cause the shell to always use
 .Xr fork 2
@@ -333,6 +286,15 @@
 When off,
 the file system is searched for commands each time the function is invoked.
 (Not implemented.)
+.It Fl i Em interactive
+Force the shell to behave interactively.
+.It Fl I Em ignoreeof
+Ignore EOFs from input when interactive.
+.It Fl m Em monitor
+Turn on job control (set automatically when interactive).
+.It Fl n Em noexec
+If not interactive, read commands but do not execute them.
+This is useful for checking the syntax of shell scripts.
 .It Fl p Em nopriv
 Do not attempt to reset effective UID if it does not match UID.
 This is not set by default to help avoid incorrect usage by setuid
@@ -340,6 +302,44 @@
 .Xr system 3
 or
 .Xr popen 3 .
+.It Fl q Em quietprofile
+If the
+.Fl v
+or
+.Fl x
+options have been set, do not apply them when reading
+initialization files, these being
+.Pa /etc/profile ,
+.Pa .profile ,
+and the file specified by the
+.Ev ENV
+environment variable.
+.It Fl s Em stdin
+Read commands from standard input (set automatically if no file arguments
+are present).
+This option has no effect when set or reset after the shell has
+already started running (i.e. with
+.Ic set ) .
+.It Fl u Em nounset
+Write a message to standard error when attempting to expand a variable
+that is not set, and if the shell is not interactive, exit immediately.
+.It Fl v Em verbose
+The shell writes its input to standard error as it is read.
+Useful for debugging.
+.It Fl x Em xtrace
+Write each command to standard error (preceded by a
+.Sq +\  )
+before it is executed.
+Useful for debugging.
+.It Fl V Em vi
+Enable the built-in
+.Xr vi 1
+command line editor (disables
+.Fl E
+if it has been set).
+(See the
+.Sx Command Line Editing
+section below.)
 .It "\ \ " Em cdprint
 Make an interactive shell always print the new directory name when
 changed by the
@@ -365,9 +365,12 @@
 the file given by the
 .Ev ENV
 variable is read at startup by a non-interactive shell.
-Consequently, while it can be manipulated by the
-.Ic set
-command, doing so has no current purpose.
+It also controls whether the shell treats
+an empty compound statement as a syntax error (required
+by posix) or permits it.
+Empty compound statements
+.Dq "{ }"
+can be useful when defining dummy functions.
 .It "\ \ " Em tabcomplete
 Enables filename completion in the command line editor.
 Typing a tab character will extend the current input word to match a
@@ -387,7 +390,7 @@
 .Dq operators .
 There are two types of operators: control operators and redirection
 operators (their meaning is discussed later).
-Following is a list of operators:
+The following is a list of operators:
 .Bl -ohang -offset indent
 .It "Control operators:"
 .Dl \*[Am]  \*[Am]\*[Am]  \&(  \&)  \&;  ;; | || \*[Lt]newline\*[Gt]
@@ -400,12 +403,12 @@
 There are three types of quoting: matched single quotes,
 matched double quotes, and backslash.
 .Ss Backslash
-A backslash preserves the literal meaning of the following
+An unquoted backslash preserves the literal meaning of the following
 character, with the exception of
 .Aq newline .
-A backslash preceding a
+An unquoted backslash preceding a
 .Aq newline
-is treated as a line continuation.
+is treated as a line continuation, the two characters are simply removed.
 .Ss Single Quotes
 Enclosing characters in single quotes preserves the literal meaning of all
 the characters (except single quotes, making it impossible to put
@@ -419,26 +422,28 @@
 and backslash
 .Pq \e .
 The backslash inside double quotes is historically weird, and serves to
-quote only the following characters:
-.Dl $  `  \*q  \e  \*[Lt]newline\*[Gt] .
+quote only the following characters (and these not in all contexts):
+.Dl $  `  \*q  \e  \*[Lt]newline\*[Gt] ,
+where a backslash newline is a line continuation as above.
 Otherwise it remains literal.
 .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.
 The following are reserved words:
-.Bl -column while while while while while -offset indent
-.It ! Ta elif Ta fi Ta while Ta case
-.It else Ta for Ta then Ta { Ta }
-.It do Ta done Ta until Ta if Ta esac
+.Bl -column while while while while -offset indent
+.It ! Ta { Ta } Ta case
+.It do Ta done Ta elif Ta else
+.It esac Ta fi Ta for Ta if
+.It in Ta then Ta until Ta while
 .El
 .Pp
-Their meaning is discussed later.
+Their meanings are discussed later.
 .Ss Aliases
 An alias is a name and corresponding value set using the
 .Ic alias
 built-in command.
-Whenever a reserved word may occur (see above),
+Whenever a reserved word (see above) may occur,
 and after checking for reserved words, the shell
 checks the word to see if it matches an alias.
 If it does, it replaces it in the input stream with its value.
@@ -457,7 +462,7 @@
 Aliases provide a convenient way for naive users to create shorthands for
 commands without having to learn how to create functions with arguments.
 They can also be used to create lexically obscure code.
-This use is discouraged.
+This use is strongly discouraged.
 .Ss Commands
 The shell interprets the words it reads according to a language, the
 specification of which is outside the scope of this man page (refer to the
@@ -476,21 +481,23 @@
 .It
 Leading words of the form
 .Dq name=value
-are stripped off and assigned to the environment of the simple command.