Mdoc cleanup, with a few grammar cleanups on the side.

Reviewed by:	mpp

1 files changed, 922 insertions, 498 deletions

diff --git a/bin/sh/sh.1 b/bin/sh/sh.1
index c33eae3..4fdce9a 100644
--- a/bin/sh/sh.1
+++ b/bin/sh/sh.1
@@ -58,19 +58,21 @@ conform with the
 specification for the shell.  This version has many features which make
 it appear
 similar in some respects to the Korn shell, but it is not a Korn
-shell clone (run GNU's bash if you want that).  Only features
+shell clone like GNU
+.Xr bash 1 .
+Only features
 designated by POSIX, plus a few Berkeley extensions, are being
 incorporated into this shell.
-This man page is not intended to be a tutorial or a complete
+This man page is not intended to be a tutorial nor a complete
 specification of the shell.
 .Ss Overview
 The shell is a command that reads lines from
 either a file or the terminal, interprets them, and
 generally executes other commands.
-It is the program that is running when a user logs into the system
-(although a user can select a different shell with the
+It is the program that is started when a user logs into the system,
+although a user can select a different shell with the
 .Xr chsh 1
-command).
+command.
 The shell
 implements a language that has flow control constructs,
 a macro facility that provides a variety of features in
@@ -79,27 +81,35 @@ editing capabilities.  It incorporates many features to
 aid interactive use and has the advantage that the interpretative
 language is common to both interactive and non-interactive
 use (shell scripts).  That is, commands 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.
+to the running shell or can be put into a file,
+which can be executed directly by the shell.
 .Ss Invocation
-If no args are present and if the standard input of the shell
-is connected to a terminal (or if the -i flag is set), the shell
-is considered an interactive shell.  An interactive shell
+.\"
+.\" XXX This next sentence is incredibly confusing.
+.\"
+If no arguments are present and if the standard input of the shell
+is connected to a terminal
+(or if the
+.Fl i
+option is set),
+the shell is considered an interactive shell.  An interactive shell
 generally prompts before each command and handles programming
 and command errors differently (as described below).
 When first starting, the shell inspects argument 0, and
-if it begins with a dash '-', the shell is also considered
-a login shell.  This is normally done automatically by the system
+if it begins with a dash
+.Pq Li - ,
+the shell is also considered a login shell.
+This is normally done automatically by the system
 when the user first logs in.  A login shell first reads commands
 from the files
 .Pa /etc/profile
-and
+and then
 .Pa .profile
 if they exist.  If the environment variable
 .Ev ENV
 is set on entry to a shell, or is set in the
 .Pa .profile
-of a login shell, the shell next reads commands from the file named in
+of a login shell, the shell then reads commands from the file named in
 .Ev ENV .
 Therefore, a user should place commands that are to be executed only
 at login time in the
@@ -107,19 +117,19 @@ at login time in the
 file, and commands that are executed for every shell inside the
 .Ev ENV
 file.
-To set the
+The user can set the
 .Ev ENV
-variable to some file, place the following line in your
+variable to some file by placing the following line in the file
 .Pa .profile
-of your home directory
-.sp
-.Dl ENV=$HOME/.shinit; export ENV
-.sp
+in the home directory,
 substituting for
 .Pa .shinit
-any filename you wish.
-If command line arguments besides the options have been
-specified, then the shell treats the first argument as the
+the filename desired:
+.Pp
+.Dl ENV=$HOME/.shinit; export ENV
+.Pp
+The first non-option argument specified on the command line
+will be treated as the
 name of a file from which to read commands (a shell script), and
 the remaining arguments are set as the positional parameters
 of the shell ($1, $2, etc).  Otherwise, the shell reads commands
@@ -137,51 +147,76 @@ scripts.
 .Ss Argument List Processing
 All of the single letter options to
 .Nm
-have a corresponding name that can be used as an argument to the
+have a corresponding long name,
+with the exception of
+.Fl c
+and
+.Fl /+o .
+These long names are provided next to the single letter options
+in the descriptions below.
+The long name for an option may be specified as an argument to the
+.Fl /+o
+option of
+.Xr sh 1 .
+Once the shell is running,
+the long name for an option may be specified as an argument to the
+.Fl /+o
+option of the
 .Ic set
-builtin command (described later).  These names are provided next to the
-single letter option in the descriptions below.  Specifying a dash
-.Dq -
-enables the option, while using a plus
-.Dq +
-disables the option.  A
-.Dq --
+builtin command
+(described later in the section called
+.Sx Builtin Commands ) .
+Introducing an option with a dash
+.Pq Li -
+enables the option,
+while using a plus
+.Pq Li +
+disables the option.
+A
+.Dq Li --
 or plain
-.Dq -
+.Dq Li -
 will stop option processing and will force the remaining
 words on the command line to be treated as arguments.
+The
+.Fl /+o
+and
+.Fl c
+options do not have long names.
+They take arguments and are described after the single letter options.
 .Bl -tag -width Ds
 .It Fl a Li allexport
-Export all variables assigned to.
+Flag variables for export when assignments are made to them.
 .It Fl b Li notify
 Enable asynchronous notification of background job
 completion.
 .Pq UNIMPLEMENTED
 .It Fl C Li noclobber
 Do not overwrite existing files with
-.Dq > .
+.Dq Li > .
 .Pq UNIMPLEMENTED
 .It Fl E Li emacs
 Enable the builtin
 .Xr emacs 1
-command line editor (disables
+command line editor (disables the
 .Fl V
-if it has been set).
+option if it has been set).
 .It Fl e Li errexit
-If not interactive, exit immediately if any
-untested command fails.
+Exit immediately if any untested command fails in non-interactive mode.
 The exit status of a command is considered to be
 explicitly tested if the command is used to control
 an if, elif, while, or until; or if the command is the left
 hand operand of an
-.Dq &&
+.Dq Li &&
 or
-.Dq ||
+.Dq Li ||
 operator.
 .It Fl f Li noglob
 Disable pathname expansion.
 .It Fl I Li ignoreeof
-Ignore EOF's from input when interactive.
+Ignore
+.Dv EOF Ns ' Ns s
+from input when in interactive mode.
 .It Fl i Li interactive
 Force the shell to behave interactively.
 .It Fl m Li monitor
@@ -195,15 +230,15 @@ Turn on privileged mode.  This mode is enabled on startup
 if either the effective user or group id is not equal to the
 real user or group id.  Turning this mode off sets the
 effective user and group ids to the real user and group ids.
-Also on interactive shells and when enabled, this mode sources
+When this mode is enabled for interactive shells, the file
 .Pa /etc/suid_profile
-(instead of
-.Pa ~/.profile Ns )
+is sourced instead of
+.Pa ~/.profile
 after
 .Pa /etc/profile
-and ignores the contents of the
+is sourced, and the contents of the
 .Ev ENV
-variable.
+variable are ignored.
 .It Fl s Li stdin
 Read commands from standard input (set automatically
 if no file arguments are present).  This option has
@@ -240,14 +275,33 @@ if it has been set).
 The shell writes its input to standard error
 as it is read.  Useful for debugging.
 .It Fl x Li xtrace
-Write each command to standard error (preceded
-by a '+ ') before it is executed.  Useful for
-debugging.
-.It Fl c Ar string
-Pass the string argument to the shell to be interpreted as input.
+Write each command
+(preceded by
+.Dq Li +\  )
+to standard error before it is executed.
+Useful for debugging.
+.El
+.Pp
+The
+.Fl c
+option may be used to pass its string argument to the shell
+to be interpreted as input.
 Keep in mind that this option only accepts a single string as its
 argument, hence multi-word strings must be quoted.
-.El
+.Pp
+The
+.Fl /+o
+option takes as its only argument the long name of an option
+to be enabled or disabled.
+For example, the following two invocations of
+.Nm
+both enable the builtin
+.Xr emacs 1
+command line editor:
+.Bd -literal -offset indent
+set -E
+set -o emacs
+.Ed
 .Ss Lexical Structure
 The shell reads input in terms of lines from a file and breaks
 it up into words at whitespace (blanks and tabs), and at
@@ -259,11 +313,37 @@ There are two types of operators: control operators and
 redirection operators (their meaning is discussed later).
 The following is a list of valid operators:
 .Bl -tag -width Ds
-.It No Control operators:
-&  &&  (  )  ;  ;; | ||
-.No \en
-.It No Redirection operators:
-<  >  >|  <<  >>  <&  >&  <<-
+.It Control operators:
+.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
+.It Xo
+.Li & Ta Xo
+.Li && Ta Xo
+.Li ( Ta Xo
+.Li ) Ta Xo
+.Li \en
+.Xc Xc Xc Xc Xc
+.It Xo
+.Li ;; Ta Xo
+.Li ; Ta Xo
+.Li | Ta Xo
+.Li ||
+.Xc Xc Xc Xc
+.El
+.It Redirection operators:
+.Bl -column "XXX" "XXX" "XXX" "XXX" -offset center -compact
+.It Xo
+.Li < Ta Xo
+.Li > Ta Xo
+.Li << Ta Xo
+.Li >>
+.Xc Xc Xc Xc
+.It Xo
+.Li <& Ta Xo
+.Li >& Ta Xo
+.Li <<- Ta Xo
+.Li >|
+.Xc Xc Xc Xc
+.El
 .El
 .Ss Quoting
 Quoting is used to remove the special meaning of certain characters
@@ -277,29 +357,58 @@ meaning of all the characters (except single quotes, making
 it impossible to put single-quotes in a single-quoted string).
 .It Double Quotes
 Enclosing characters within double quotes preserves the literal
-meaning of all characters except dollarsign ($), backquote (`),
-and backslash (\\).  The backslash inside double quotes is
-historically weird, and serves to quote only the following
-characters: $  `  "  \\
-.No \en .
-Otherwise it remains literal.
+meaning of all characters except dollarsign
+.Pq Li $ ,
+backquote
+.Pq Li ` ,
+and backslash
+.Po Li \e\"
+.Pc .
+The backslash inside double quotes is historically weird.
+It remains literal unless it precedes the following characters,
+which it serves to quote:
+.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
+.It Xo
+.Li $ Ta Xo
+.Li ` Ta Xo
+.Li \&" Ta Xo
+.Li \e\  Ta Xo
+.Li \en
+.Xc Xc Xc Xc Xc
+.El
 .It Backslash
 A backslash preserves the literal meaning of the following
-character, with the exception of
-.No \en.
-A backslash preceding a
-.No \en
-is treated as a line continuation.
+character, with the exception of the newline character
+.Pq Li \en .
+A backslash preceding a newline is treated as a line continuation.
 .El
 .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:
-.Bd -literal -offset indent
-!       {       }       case    do
-done    elif    else    esac    fi
-for     if      then    until   while
-.Ed
+.Bl -column "doneXX" "elifXX" "elseXX" "untilXX" "whileX" -offset center
+.It Xo
+.Li ! Ta Xo
+.Li { Ta Xo
+.Li } Ta Xo
+.Ic case Ta Xo
+.Ic do
+.Xc Xc Xc Xc Xc
+.It Xo
+.Ic done Ta Xo
+.Ic elif Ta Xo
+.Ic else Ta Xo
+.Ic esac Ta Xo
+.Ic fi
+.Xc Xc Xc Xc Xc
+.It Xo
+.Ic for Ta Xo
+.Ic if Ta Xo
+.Ic then Ta Xo
+.Ic until Ta Xo
+.Ic while
+.Xc Xc Xc Xc Xc
+.El
 .Ss Aliases
 An alias is a name and corresponding value set using the
 .Ic alias
@@ -308,17 +417,17 @@ 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.
 For example, if there is an alias called
-.Dq lf
+.Dq Li lf
 with the value
-.Dq ls -F ,
+.Dq Li ls -F ,
 then the input
 .Bd -literal -offset indent
-lf foobar <return>
+lf foobar
 .Ed
 .Pp
 would become
 .Bd -literal -offset indent
-ls -F foobar <return>
+ls -F foobar
 .Ed
 .Pp
 Aliases provide a convenient way for naive users to
@@ -341,7 +450,7 @@ the following actions:
 .Bl -enum
 .It
 Leading words of the form
-.Dq name=value
+.Dq Li name=value
 are stripped off and assigned to the environment of
 the simple command.  Redirection operators and
 their arguments (as described below) are stripped
@@ -354,7 +463,7 @@ and the first remaining word is considered the command
 name and the command is located.  The remaining
 words are considered the arguments of the command.
 If no command name resulted, then the
-.Dq name=value
+.Dq Li name=value
 variable assignments recognized in 1) affect the
 current shell.
 .It
@@ -366,38 +475,43 @@ Redirections are used to change where a command reads its input
 or sends its output.  In general, redirections open, close, or
 duplicate an existing reference to a file.  The overall format
 used for redirection is:
-.sp
+.Pp
 .Dl [n] redir-op file
-.sp
-where redir-op is one of the redirection operators mentioned
+.Pp
+The
+.Ql redir-op
+is one of the redirection operators mentioned
 previously.  The following gives some examples of how these
-operators can be used.  NOTE: stdin and stdout are commonly
-used abbreviations for standard input and standard output,
-respectively.
-.Bl -tag -width "1234567890" -offset indent
-.It [n]> file
-redirect stdout (or n) to file
-.It [n]>| file
-same as above, but override the -C option
-.It [n]>> file
-append stdout (or n) to file
-.It [n]< file
-redirect stdin (or n) from file
-.It [n1]<&n2
-duplicate stdin (or n1) from file descriptor n2
-.It [n]<&-
-close stdin (or n)
-.It [n1]>&n2
-duplicate stdout (or n1) to n2.
-.It [n]>&-
-close stdout (or n)
+operators can be used.
+Note that stdin and stdout are commonly used abbreviations
+for standard input and standard output respectively.
+.Bl -tag -width "1234567890XX" -offset indent
+.It Li [n]> file
+redirect stdout (or file descriptor n) to file
+.It Li [n]>| file
+same as above, but override the
+.Fl C
+option
+.It Li [n]>> file
+append stdout (or file descriptor n) to file
+.It Li [n]< file
+redirect stdin (or file descriptor n) from file
+.It Li [n1]<&n2
+duplicate stdin (or file descriptor n1) from file descriptor n2
+.It Li [n]<&-
+close stdin (or file descriptor n)
+.It Li [n1]>&n2
+duplicate stdout (or file descriptor n1) to file descriptor n2
+.It Li [n]>&-
+close stdout (or file descriptor n)
 .El
 .Pp
 The following redirection is often called a
 .Dq here-document .
 .Bd -literal -offset indent
 [n]<< delimiter
-	here-doc-text...
+	here-doc-text
+	...
 delimiter
 .Ed
 .Pp
@@ -410,16 +524,16 @@ parameter expansion, command substitution, and arithmetic
 expansion (as described in the section on
 .Sx Word Expansions ) .
 If the operator is
-.Dq <<-
+.Dq Li <<-
 instead of
-.Dq << ,
+.Dq Li << ,
 then leading tabs
 in the here-doc-text are stripped.
 .Ss Search and Execution
 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.
+builtin commands, and normal programs.
+The command is searched for (by name) in that order.
+The three types of commands are all executed in a different way.
 .Pp
 When a shell function is executed, all of the shell positional
 parameters (except $0, which remains unchanged) are
@@ -448,8 +562,10 @@ whose
 .Tn ASCII
 representation is
 .Qq #! ,
-resulting in an ENOEXEC return value from
-.Fn execve )
+resulting in an
+.Dv ENOEXEC
+return value from
+.Xr execve 2 )
 the shell will interpret the program in a subshell.
 The child shell will reinitialize itself in this case,
 so that the effect will be
@@ -522,9 +638,8 @@ of the next command.  The standard output of the last
 command is inherited from the shell, as usual.
 .Pp
 The format for a pipeline is:
-.Bd -literal -offset indent
-[!] command1 [ | command2 ...]
-.Ed
+.Pp
+.Dl [!] command1 [ | command2 ...]
 .Pp
 The standard output of command1 is connected to the standard
 input of command2.  The standard input, standard output, or
@@ -546,27 +661,34 @@ is zero.
 Because pipeline assignment of standard input or standard
 output or both takes place before redirection, it can be
 modified by redirection.  For example:
-.Bd -literal -offset indent
-$ command1 2>&1 | command2
-.Ed
 .Pp
-sends both the standard output and standard error of command1
-to the standard input of command2.
+.Dl $ command1 2>&1 | command2
+.Pp
+sends both the standard output and standard error of
+.Ql command1
+to the standard input of
+.Ql command2 .
 .Pp
-A ; or <newline> terminator causes the preceding
+A
+.Dq Li ;
+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.
 .Pp
-Note that unlike some other shells, each process in the
-pipeline is a child of the invoking shell (unless it
-is a shell builtin command, in which case it executes in the
-current shell -- but any effect it has on the
-environment is wiped).
-.Ss Background Commands -- &
+Note that unlike some other shells,
+.Nm
+executes each process in the pipeline as a child of the
+.Nm
+process.
+Shell builtin commands are the exception to this rule.
+They are executed in the current shell, although they do not affect its
+environment when used in pipelines.
+.Ss Background Commands (&)
 If a command is terminated by the control operator ampersand
-(&), the shell executes the command asynchronously -- that is,
-the shell does not wait for
-the command to finish before executing the next command.
+.Pq Li & ,
+the shell executes the command asynchronously;
+the shell does not wait for the command to finish
+before executing the next command.
 .Pp
 The format for running a command in background is:
 .Bd -literal -offset indent
@@ -575,7 +697,7 @@ command1 & [command2 & ...]
 .Pp
 If the shell is not interactive, the standard input of an
 asynchronous command is set to /dev/null.
-.Ss Lists -- Generally Speaking
+.Ss Lists (Generally Speaking)
 A list is a sequence of zero or more commands separated by
 newlines, semicolons, or ampersands,
 and optionally terminated by one of these three characters.
@@ -586,78 +708,106 @@ command and immediately proceed onto the next command;
 otherwise it waits for the command to terminate before
 proceeding to the next one.
 .Ss Short-Circuit List Operators
-.Dq &&
+.Dq Li &&
 and
-.Dq ||
+.Dq Li ||
 are AND-OR list operators.
-.Dq &&
+.Dq Li &&
 executes the first command, and then executes the second command
 if the exit status of the first command is zero.
-.Dq ||
+.Dq Li ||
 is similar, but executes the second command if the exit
 status of the first command is nonzero.
-.Dq &&
+.Dq Li &&
 and
-.Dq ||
+.Dq Li ||
 both have the same priority.
-.Ss Flow-Control Constructs -- if, while, for, case
-The syntax of the if command is
-.Bd -literal -offset indent
-if list
-then list
-[ elif list
-then    list ] ...
-[ else list ]
-fi
-.Ed
-.Pp
-The syntax of the while command is
-.Bd -literal -offset indent
-while list
-do   list
-done
-.Ed
+.Ss Flow-Control Constructs (if, while, for, case)
+The syntax of the
+.Ic if
+command is:
+.\"
+.\" XXX Use .Dl to work around broken handling of .Ic inside .Bd and .Ed .
+.\"
+.Dl Ic if Ar list
+.Dl Ic then Ar list
+.Dl [ Ic elif Ar list
+.Dl Ic then Ar list ] ...
+.Dl [ Ic else Ar list ]
+.Dl Ic fi
+.Pp
+The syntax of the
+.Ic while
+command is:
+.Dl Ic while Ar list
+.Dl Ic do Ar list
+.Dl Ic done
 .Pp
 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
+first list is zero.
+The
+.Ic until
+command is similar, but has the word
+.Ic until
+in place of
+.Ic while ,
+which causes it to
 repeat until the exit status of the first list is zero.
 .Pp
-The syntax of the for command is
-.Bd -literal -offset indent
-for variable in word...
-do   list
-done
-.Ed
+The syntax of the
+.Ic for
+command is:
+.Dl Ic for Ar variable Ic in Ar word ...
+.Dl Ic do Ar list
+.Dl Ic done
 .Pp
 The words are expanded, and then the list is executed
-repeatedly with the variable set to each word in turn.  do
-and done may be replaced with
-.Dq {
+repeatedly with the variable set to each word in turn.
+The
+.Ic do
 and
-.Dq } .
-.Pp
-The syntax of the break and continue command is
-.Bd -literal -offset indent
-break [ num ]
-continue [ num ]
-.Ed
+.Ic done
+commands may be replaced with
+.Dq Li {
+and
+.Dq Li } .
 .Pp
-Break terminates the num innermost for or while loops.
-Continue continues with the next iteration of the innermost loop.
+The syntax of the
+.Ic break
+and
+.Ic continue
+commands is:
+.Dl Ic break Op Ar num
+.Dl Ic continue Op Ar num
+.Pp
+The
+.Ic break
+command terminates the
+.Ar num
+innermost
+.Ic for
+or
+.Ic while
+loops.
+The
+.Ic continue
+command continues with the next iteration of the innermost loop.
 These are implemented as builtin commands.
 .Pp
-The syntax of the case command is
-.Bd -literal -offset indent
-case word in
-pattern) list ;;
-...
-esac
-.Ed
-.Pp
-The pattern can actually be one or more patterns (see Shell
-Patterns described later), separated by
-.Dq |
+The syntax of the
+.Ic case
+command is
+.Dl Ic case Ar word Ic in
+.Dl pattern) list ;;
+.Dl ...
+.Dl Ic esac
+.Pp
+The pattern can actually be one or more patterns
+(see
+.Sx Shell Patterns
+described later),
+separated by
+.Dq Li |
 characters.
 .Ss Grouping Commands Together
 Commands may be grouped by writing either
@@ -670,12 +820,11 @@ or
 { list; }
 .Ed
 .Pp
-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
+The first form executes the commands in a subshell.
+Note that builtin commands thus executed do not affect the current shell.
+The second form does not fork another shell,
+so it is slightly more efficient.
+Grouping commands together this way allows the user to
 redirect their output as though they were one program:
 .Bd -literal -offset indent
 { echo -n "hello"; echo " world"; } > greeting
@@ -690,45 +839,57 @@ A function definition is an executable statement; when
 executed it installs a function named name and returns an
 exit status of zero.  The command is normally a list
 enclosed between
-.Dq {
+.Dq Li {
 and
-.Dq } .
+.Dq Li } .
 .Pp
 Variables may be declared to be local to a function by
-using a local command.  This should appear as the first
-statement of a function, and the syntax is
-.Bd -literal -offset indent
-local [ variable | - ] ...
+using the
+.Ic local
+command.
+This should appear as the first statement of a function,
+and the syntax is:
+.Bd -ragged -offset indent
+.Ic local
+.Op Ar variable ...
+.Op Ar -
 .Ed
 .Pp
-Local is implemented as a builtin command.
+The
+.Ic local
+command is implemented as a builtin command.
 .Pp
 When a variable is made local, it inherits the initial
 value and exported and readonly flags from the variable
 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
+uses dynamic scoping, so that if the variable x is made
 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.
 .Pp
 The only special parameter than can be made local is
-.Dq - .
+.Dq Li - .
 Making
-.Dq -
+.Dq Li -
 local causes any shell options that are
 changed via the set command inside the function to be
 restored to their original values when the function
 returns.
 .Pp
-The syntax of the return command is
-.Bd -literal -offset indent
-return [ exitstatus ]
+The syntax of the
+.Ic return
+command is
+.Bd -ragged -offset indent
+.Ic return
+.Op Ar exitstatus
 .Ed
 .Pp
-It terminates the currently executing function.  Return is
-implemented as a builtin command.
+It terminates the currently executing function.
+The
+.Ic return
+command is implemented as a builtin command.
 .Ss Variables and Parameters
 The shell maintains a set of parameters.  A parameter
 denoted by a name is called a variable.  When starting up,
@@ -739,11 +900,12 @@ name=value
 .Ed
 .Pp
 Variables set by the user must have a name consisting solely
-of alphabetics, numerics, and underscores - the first of which
-must not be numeric.  A parameter can also be denoted by a number
+of alphabetics, numerics, and underscores.
+The first letter of a variable name must not be numeric.
+A parameter can also be denoted by a number
 or a special character as explained below.
 .Ss Positional Parameters
-A positional parameter is a parameter denoted by a number (n > 0).
+A positional parameter is a parameter denoted by a number greater than zero.
 The shell sets these initially to the values of its command line
 arguments that follow the name of the shell script.  The
 .Ic set
@@ -753,13 +915,19 @@ A special parameter is a parameter denoted by one of the following
 special characters.  The value of the parameter is listed
 next to its character.
 .Bl -hang
-.It *
+.It Li *
 Expands to the positional parameters, starting from one.  When
 the expansion occurs within a double-quoted string
 it expands to a single field with the value of each parameter
-separated by the first character of the IFS variable, or by a
-<space> if IFS is unset.
-.It @
+separated by the first character of the
+.Ev IFS
+variable,
+or by a
+.Aq space
+if
+.Ev IFS
+is unset.
+.It Li @
 Expands to the positional parameters, starting from one.  When
 the expansion occurs within double-quotes, each positional
 parameter expands as a separate argument.
@@ -777,24 +945,24 @@ the two arguments:
 .Bd -literal -offset indent
 "abc"   "def ghi"
 .Ed
-.It #
+.It Li #
 Expands to the number of positional parameters.
-.It ?
+.It Li ?
 Expands to the exit status of the most recent pipeline.
-.It -
+.It Li -
 (hyphen) Expands to the current option flags (the single-letter
 option names concatenated into a string) as specified on
 invocation, by the set builtin command, or implicitly
 by the shell.
-.It $
+.It Li $
 Expands to the process ID of the invoked shell.  A subshell
 retains the same value of $ as its parent.
-.It !
+.It Li !
 Expands to the process ID of the most recent background
 command executed from the current shell.  For a
 pipeline, the process ID is that of the last command in the
 pipeline.
-.It 0
+.It Li 0
 (zero) Expands to the name of the shell or shell script.
 .El
 .Ss Word Expansions
@@ -817,20 +985,30 @@ The order of word expansion is:
 Tilde Expansion, Parameter Expansion, Command Substitution,
 Arithmetic Expansion (these all occur at the same time).
 .It
-Field Splitting is performed on fields
-generated by step (1) unless the IFS variable is null.
+Field Splitting is performed on fields generated by step (1)
+unless the
+.Ev IFS
+variable is null.
 .It
-Pathname Expansion (unless set -f is in effect).
+Pathname Expansion (unless the
+.Fl f
+option is in effect).
 .It
 Quote Removal.
 .El
 .Pp
-The $ character is used to introduce parameter expansion, command
+The
+.Dq Li $
+character is used to introduce parameter expansion, command
 substitution, or arithmetic evaluation.
 .Ss Tilde Expansion (substituting a user's home directory)
-A word beginning with an unquoted tilde character (~) is
-subjected to tilde expansion.  All the characters up to
-a slash (/) or the end of the word are treated as a username
+A word beginning with an unquoted tilde character
+.Pq Li ~
+is
+subjected to tilde expansion.
+All the characters up to a slash
+.Pq Li /
+or the end of the word are treated as a username
 and are replaced with the user's home directory.  If the
 username is missing (as in ~/foobar), the tilde is replaced
 with the value of the HOME variable (the current user's
@@ -841,10 +1019,14 @@ The format for parameter expansion is as follows:
 ${expression}
 .Ed
 .Pp
-where expression consists of all characters until the matching }.  Any }
+where expression consists of all characters until the matching
+.Dq Li } .
+Any
+.Dq Li }
 escaped by a backslash or within a quoted string, and characters in
 embedded arithmetic expansions, command substitutions, and variable
-expansions, are not examined in determining the matching }.
+expansions, are not examined in determining the matching
+.Dq Li } .
 .Pp
 The simplest form for parameter expansion is:
 .Bd -literal -offset indent
@@ -864,7 +1046,8 @@ 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 @.
+expansion, with the exception of
+.Dq Li @ .
 .El
 .Pp
 In addition, a parameter expansion can be modified by using one of the
@@ -907,10 +1090,17 @@ String Length.  The length in characters of
 the value of parameter.
 .Pp
 The following four varieties of parameter expansion provide for substring
-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.
+processing.
+In each case, pattern matching notation
+(see
+.Sx Shell Patterns ) ,
+rather than regular expression notation,
+is used to evaluate the patterns.
+If parameter is
+.Dq Li *
+or
+.Dq Li @ ,
+the result of the expansion is unspecified.
 Enclosing the full parameter expansion string in double-quotes does not
 cause the following four varieties of pattern characters to be quoted,
 whereas quoting characters within the braces has this effect.
@@ -947,21 +1137,20 @@ the command is enclosed as follows:
 $(command)
 .Ed
 .Pp
-or (
-.Dq backquoted
-version):
+or the backquoted version:
 .Bd -literal -offset indent
 `command`
 .Ed
 .Pp
 The shell expands the command substitution by executing command in a
 subshell environment and replacing the command substitution
-with the
-standard output of the command, removing sequences of one or more
-<newline>s at the end of the substitution.  (Embedded <newline>s before
-the end of the output are not removed; however, during field
-splitting, they may be translated into <space>s, depending on the value
-of IFS and quoting that is in effect.)
+with the standard output of the command,
+removing sequences of one or more newlines at the end of the substitution.
+Embedded newlines before the end of the output are not removed;
+however, during field splitting, they may be translated into spaces
+depending on the value of
+.Ev IFS
+and the quoting that is in effect.
 .Ss Arithmetic Expansion
 Arithmetic expansion provides a mechanism for evaluating an arithmetic
 expression and substituting its value.
@@ -983,11 +1172,16 @@ arithmetic expansion the shell scans the results of
 expansions and substitutions that did not occur in double-quotes for
 field splitting and multiple fields can result.
 .Pp
-The shell treats each character of the IFS as a delimiter and use
+The shell treats each character of the
+.Ev IFS
+as a delimiter and uses
 the delimiters to split the results of parameter expansion and command
 substitution into fields.
 .Ss Pathname Expansion (File Name Generation)
-Unless the -f flag is set, file name generation is performed
+Unless the
+.Fl f
+option 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
@@ -1003,12 +1197,13 @@ Pathname Expansion and the
 command.
 .Ss Shell Patterns
 A pattern consists of normal characters, which match themselves,
-and meta-characters.   The meta-characters are
-.Dq ! ,
-.Dq * ,
-.Dq ? ,
+and meta-characters.
+The meta-characters are
+.Dq Li ! ,
+.Dq Li * ,
+.Dq Li ? ,
 and
-.Dq [ .
+.Dq Li [ .
 These characters lose their special meanings if they are quoted.
 When command or variable substitution is performed and the dollar sign
 or back quotes are not double-quoted, the value of the
@@ -1016,20 +1211,20 @@ variable or the output of the command is scanned for these
 characters and they are turned into meta-characters.
 .Pp
 An asterisk
-.Dq *
+.Pq Li *
 matches any string of characters.  A
 question mark matches any single character.
 A left bracket
-.Dq [
+.Pq Li [
 introduces a character class.
 The end of the character class is indicated by a
-.Dq ] ;
+.Dq Li \&] ;
 if the
-.Dq ]
+.Dq Li \&]
 is missing then the
-.Dq [
+.Dq Li [
 matches a
-.Dq [
+.Dq Li [
 rather than introducing a character class.
 A character class matches any of the characters between the square brackets.
 A range of characters may be specified using a minus sign.
@@ -1037,10 +1232,10 @@ The character class may be complemented
 by making an exclamation point the first character of the character class.
 .Pp
 To include a
-.Dq ]
+.Dq Li \&]
 in a character class, make it the first character listed
 (after the
-.Dq ! ,
+.Dq Li ! ,
 if any).
 To include a minus sign, make it the first or last character listed.
 .Ss Builtin Commands
@@ -1053,348 +1248,563 @@ and
 .Xr echo 1
 commands are provided for efficiency.
 .Bl -tag -width Ds
-.It :
+.It Ic :
 A null command that returns a 0 (true) exit value.
-.It \&. file
+.It Ic . Ar file
 The commands in the specified file are read and executed by the shell.
 If
 .Ar file
 contains any
-.Ql /
+.Dq /
 characters, it is used as is.  Otherwise, the shell searches the
 .Ev PATH
 for the file.  If it is not found in the
 .Ev PATH ,
 it is sought in the current working directory.
-.It alias  [ name[=string] ...  ]
-If name=string is specified, the shell defines the
-alias
-.Dq name
+.It Ic alias Op Ar name ...
+.It Ic alias Op Ar name=string ...
+If
+.Ar name=string
+is specified, the shell defines the alias
+.Ar name
 with value
-.Dq string .
+.Ar string .
 If just
-.Dq name
+.Ar name
 is specified, the value of the alias
-.Dq name
+.Ar name
 is printed.
-With no arguments, the alias builtin command prints the
-names and values of all defined aliases (see unalias).
-.It bg [ job ] ...
-Continue the specified jobs (or the current job if no
-jobs are given) in the background.
-.It command command arg ...
-Execute the specified builtin command.  (This is useful when you
-have a shell function with the same name
-as a builtin command.)
-.It cd [ directory ]
-Switch to the specified directory (default $HOME).
-If an entry for CDPATH appears in the environment
-of the cd command or the shell variable CDPATH is set
-and the directory name does not begin with a slash (/),
-dot (.) or dot-dot (..),
-then the directories listed in CDPATH will be
-searched for the specified directory.  The format of
-CDPATH is the same as that of PATH.
+With no arguments, the
+.Ic alias
+builtin command prints the names and values of all defined aliases
+(see
+.Ic unalias ) .
+.It Ic bg Op Ar job ...
+Continue the specified jobs
+(or the current job if no jobs are given)
+in the background.
+.It Ic command Ar cmd Op Ar arg ...
+Execute the specified builtin command,
+.Ar cmd .
+This is useful when the user wishes to override a shell function
+with the same name as a builtin command.
+.It Ic cd Op Ar directory
+Switch to the specified
+.Ar directory ,
+or to the directory specified in the
+.Ev HOME
+environment variable if no
+.Ar directory
+is specified.
+If
+.Ar directory
+is not found as a subdirectory of the current directory
+(and does not begin with
+.Dq Li / ,
+.Dq Li ./ ,
+or
+.Dq Li ../ ) ,
+then the directories listed in the
+.Ev CDPATH
+variable will be
+searched for the specified
+.Ar directory .
+The format of
+.Ar CDPATH
+is the same as that of
+.Ev PATH .
 In an interactive shell,
-the cd command will print out the name of the directory
+the
+.Ic 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
-was used or because a symbolic link was crossed.
-.It eval string ...
+These may be different either because the
+.Ev CDPATH
+mechanism was used or because a symbolic link was crossed.
+.It Ic eval Ar string ...
 Concatenate all the arguments with spaces.
 Then re-parse and execute the command.
-.It exec [ command arg ...  ]
-Unless command is omitted, the shell process is
-replaced with the specified program (which must be a
-real program, not a shell builtin command or function).  Any
-redirections on the exec command are marked as permanent,
-so that they are not undone when the exec command finishes.
-.It exit [ exitstatus ]
-Terminate the shell process.  If exitstatus is given
-it is used as the exit status of the shell; otherwise
-the exit status of the preceding command is used.
-.It export name ...
+.It Ic exec Op Ar command Op arg ...
+Unless
+.Ar command
+is omitted,
+the shell process is replaced with the specified program
+(which must be a real program, not a shell builtin command or function).
+Any redirections on the
+.Ic exec
+command are marked as permanent,
+so that they are not undone when the
+.Ic exec
+command finishes.
+.It Ic exit Op Ar exitstatus
+Terminate the shell process.
+If
+.Ar exitstatus
+is given
+it is used as the exit status of the shell;
+otherwise the exit status of the preceding command is used.
+.It Ic export Ar name ...
 The specified names are exported so that they will
 appear in the environment of subsequent commands.
-The only way to un-export a variable is to unset it.
-The shell allows the value of a variable to be set at the
-same time it is exported by writing
+The only way to un-export a variable is to
+.Ic unset
+it.
+The shell allows the value of a variable to be set
+at the same time as it is exported by writing
 .Bd -literal -offset indent
 export name=value
 .Ed
 .Pp
 With no arguments the export command lists the names
 of all exported variables.
-.It fc [-e editor] [first [last]]
-.It fc -l [-nr] [first [last]]
-.It fc -s [old=new] [first]
-The fc builtin command lists, or edits and re-executes, commands
-previously entered to an interactive shell.
+.It Xo
+.Ic fc
+.Op Fl e Ar editor
+.Op Ar first Op Ar last
+.Xc
+.It Xo
+.Ic fc
+.Fl l
+.Op Fl nr
+.Op Ar first Op Ar last
+.Xc
+.It Xo
+.Ic fc
+.Fl s
+.Op Ar old=new
+.Op Ar first
+.Xc
+The
+.Ic fc
+builtin command lists, or edits and re-executes,
+commands previously entered to an interactive shell.
 .Bl -tag -width Ds
-.It -e editor
-Use the editor named by editor to edit the commands.  The
-editor string is a command name, subject to search via the
-PATH variable.  The value in the FCEDIT variable
-is used as a default when -e is not specified.  If
-FCEDIT is null or unset, the value of the EDITOR
-variable is used.  If EDITOR is null or unset,
+.It Fl e Ar editor
+Use the editor named by
+.Ar editor
+to edit the commands.
+The editor string is a command name,
+subject to search via the
+.Ev PATH
+variable.
+The value in the
+.Ev FCEDIT
+variable is used as a default when
+.Fl e
+is not specified.
+If
+.Ev FCEDIT
+is null or unset, the value of the
+.Ev EDITOR
+variable is used.
+If
+.Ev EDITOR
+is null or unset,
 .Xr ed 1
 is used as the editor.
-.It -l (ell)
+.It Fl l No (ell)
 List the commands rather than invoking
 an editor on them.  The commands are written in the
 sequence indicated by the first and last operands, as
-affected by -r, with each command preceded by the command
-number.
-.It -n
-Suppress command numbers when listing with -l.
-.It -r
-Reverse the order of the commands listed (with -l) or
-edited (with neither -l nor -s).
-.It -s
+affected by
+.Fl r ,
+with each command preceded by the command number.
+.It Fl n
+Suppress command numbers when listing with
+.Fl l .
+.It Fl r
+Reverse the order of the commands listed
+(with
+.Fl l )
+or edited
+(with neither
+.Fl l
+nor
+.Fl s ) .
+.It Fl s
 Re-execute the command without invoking an editor.
-.It first
-.It last
-Select the commands to list or edit.  The number of
-previous commands that can be accessed are determined
-by the value of the HISTSIZE variable.  The value of first
-or last or both are one of the following:
-.It [+]number
-A positive number representing a command
-number; command numbers can be displayed
-with the -l option.
-.It -number
+.It Ar first
+.It Ar last
+Select the commands to list or edit.
+The number of previous commands that can be accessed
+are determined by the value of the
+.Ev HISTSIZE variable.
+The value of
+.Ar first
+or
+.Ar last
+or both are one of the following:
+.Bl -tag -width Ds
+.It Ar [+]num
+A positive number representing a command number;
+command numbers can be displayed with the
+.Fl l
+option.
+.It Ar -num
 A negative decimal number representing the
-command that was executed number of
-commands previously.  For example, -1 is
-the immediately previous command.
-.It string
-A string indicating the most recently
-entered command that begins with that
-string.  If the old=new operand is not also
-specified with -s, the string form of the
-first operand cannot contain an embedded
-equal sign.
+command that was executed
+.Ar num
+of
+commands previously.
+For example, -1 is the immediately previous command.
+.It Ar string
+A string indicating the most recently entered command
+that begins with that string.
+If the
+.Ar old=new
+operand is not also specified with
+.Fl s ,
+the string form of the first operand cannot contain an embedded equal sign.
 .El
-.\".Pp
-The following environment variables affect the execution of fc:
+.El
+.Pp
+The following environment variables affect the execution of
+.Ic fc :
 .Bl -tag -width Ds
-.It Va FCEDIT
+.It Ev FCEDIT
 Name of the editor to use.
-.It Va HISTSIZE
+.It Ev HISTSIZE
 The number of previous commands that are accessible.
 .El
-.It fg [ job ]
-Move the specified job or the current job to the
-foreground.
-.It getopts optstring var
-The POSIX getopts command.
-The getopts command deprecates the older getopt command.
+.It Ic fg Op Ar job
+Move the specified
+.Ar job
+or the current job to the foreground.
+.It Ic getopts Ar optstring Ar var
+The POSIX
+.Ic getopts
+command.
+The
+.Ic getopts
+command deprecates the older
+.Xr getopt 1
+command.
 The first argument should be a series of letters, each possibly
 followed by a colon which indicates that the option takes an argument.
 The specified variable is set to the parsed option.  The index of
-the next argument is placed into the shell variable OPTIND.
+the next argument is placed into the shell variable
+.Ev OPTIND .
 If an option takes an argument, it is placed into the shell variable
-OPTARG.  If an invalid option is encountered, var is set to '?'.
+.Ev OPTARG .
+If an invalid option is encountered,
+.Ev var
+is set to
+.Dq Li ? .
 It returns a false value (1) when it encounters the end of the options.
-.It hash -rv command ...
-The shell maintains a hash table which remembers the
-locations of commands.  With no arguments whatsoever,
-the hash command prints out the contents of this
-table.  Entries which have not been looked at since
-the last cd command are marked with an asterisk; it
-is possible for these entries to be invalid.
-.Pp
-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
-to delete all the entries in the hash table except
-for functions.
-.It jobid [ job ]
-Print the process id's of the processes in the job.
-If the job argument is omitted, use the current job.
-.It jobs
+.It Xo
+.Ic hash
+.Op Fl rv
+.Op Ar command ...
+.Xc
+The shell maintains a hash table which remembers the locations of commands.
+With no arguments whatsoever, the
+.Ic hash
+command prints out the contents of this table.
+Entries which have not been looked at since the last
+.Ic cd
+command are marked with an asterisk;
+it is possible for these entries to be invalid.
+.Pp
+With arguments, the
+.Ic hash
+command removes each specified
+.Ar command
+from the hash table (unless they are functions) and then locates it.
+With the
+.Fl v
+option,
+.Ic hash
+prints the locations of the commands as it finds them.
+The
+.Fl r
+option causes the
+.Ic hash
+command to delete all the entries in the hash table except for functions.
+.It Ic jobid Op Ar job
+Print the process id's of the processes in the specified
+.Ar job .
+If the
+.Ar job
+argument is omitted, use the current job.
+.It Ic jobs
 This command lists out all the background processes
 which are children of the current shell process.
-.It pwd
-Print the current directory.  The builtin command may
+.It Ic pwd
+Print the path of the current directory.  The builtin command may
 differ from the program of the same name because the
 builtin command remembers what the current directory
 is rather than recomputing it each time.  This makes
 it faster.  However, if the current directory is
-renamed, the builtin version of pwd will continue to
-print the old name for the directory.
-.It Li "read [ -p prompt ] [ -t timeout ] [ -er ] variable ...
-The prompt is printed if the -p option is specified
+renamed,
+the builtin version of
+.Xr pwd 1
+will continue to print the old name for the directory.
+.It Xo
+.Ic read
+.Op Fl p Ar prompt
+.Op Fl t Ar timeout
+.Op Fl er
+.Ar variable ...
+.Xc
+The
+.Ar prompt
+is printed if the
+.Fl p
+option is specified
 and the standard input is a terminal.  Then a line is
 read from the standard input.  The trailing newline
 is deleted from the line and the line is split as
-described in the section on word splitting above, and
+described in the section on
+.Sx White Space Splitting (Field 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
-separated them) are assigned to the last variable.
+pieces (along with the characters in
+.Ev 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.
 .Pp
-Backslashes are treated specially, unless the -r option is
+Backslashes are treated specially, unless the
+.Fl r
+option is
 specified.  If a backslash is followed by
 a newline, the backslash and the newline will be
-deleted.   If a backslash is followed by any other
+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
-not in IFS, even if it is.
-.Pp
-If the -t option is specified the timeout elapses
-before any input is supplied, the read command will
-return without assigning any values.  The timeout value
-may optionally be followed by one of 's', 'm' or 'h' to
-explicitly specify seconds, minutes or or hours.  If none
-is supplied, 's' is assumed.
-.Pp
-The -e option exists only for backward compatibility with older scripts.
-.It readonly name ...
-The specified names are marked as read only, so that
-they cannot be subsequently modified or unset.  The shell
-allows the value of a variable to be set at the same
-time it is marked read only by writing
-using the following form
+character will be treated as though it were not in
+.Ev IFS ,
+even if it is.
+.Pp
+If the
+.Fl t
+option is specified and the
+.Ar timeout
+elapses before any input is supplied,
+the
+.Ic read
+command will return without assigning any values.
+The
+.Ar timeout
+value may optionally be followed by one of
+.Dq s ,
+.Dq m
+or
+.Dq h
+to explicitly specify seconds, minutes or or hours.
+If none is supplied,
+.Dq s
+is assumed.
+.Pp
+The
+.Fl e
+option exists only for backward compatibility with older scripts.
+.It Ic readonly Ar name ...
+Each specified
+.Ar name
+is marked as read only,
+so that it cannot be subsequently modified or unset.
+The shell allows the value of a variable to be set
+at the same time as it is marked read only
+by using the following form:
 .Bd -literal -offset indent
 readonly name=value
 .Ed
 .Pp
-With no arguments the readonly command lists the
-names of all read only variables.
-.It Li "set [ { -options | +options | -- } ] arg ...
-The set command performs three different functions.
+With no arguments the
+.Ic readonly
+command lists the names of all read only variables.
+.It Xo
+.Ic set
+.Op Fl /+abCEefIimnpTuVvx
+.Op Fl /+o Ar longname
+.Op Fl c Ar string
+.Op Fl - Ar arg ...
+.Xc
+The set command performs three different functions:
 .Bl -item
 .It
-With no arguments, it lists the values of all shell
-variables.
+With no arguments, it lists the values of all shell variables.
 .It
-If options are given, it sets the specified option
-flags, or clears them as described in the section
-called
+If options are given,
+either in short form or using the long
+.Dq Fl /+o Ar longname
+form,
+it sets or clears the specified options as described in the section called
 .Sx Argument List Processing .
 .It
-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
-.Dq --
-as the first argument
-to set.  If no args are present, the set command
-will clear all the positional parameters (equivalent
-to executing
-.Dq shift $# .
+If the
+.Dq Fl -
+option is specified,
+.Ic set
+will replace the shell's positional parameters with the subsequent
+arguments.
+If no arguments follow the
+.Dq Fl -
+option,
+all the positional parameters will be cleared,
+which is equivalent to executing the command
+.Dq Li shift $# .
+The
+.Dq Fl -
+flag may be ommitted when specifying arguments to be used
+as positional replacement parameters.
+This is not recommended,
+because the first argument may begin with a dash
+.Pq Li -
+or a plus
+.Pq Li + ,
+which the
+.Ic set
+command will interpret as a request to enable or disable options.
 .El
-.Pp
-.It setvar variable value
-Assigns value to variable.
-In general it is better to write variable=value rather than using setvar.
-Setvar is intended to be used in functions that
+.It Ic setvar Ar variable Ar value
+Assigns the specified
+.Ar value
+to the specified
+.Ar variable .
+.Ic Setvar
+is intended to be used in functions that
 assign values to variables whose names are passed as parameters.
-.It shift [ n ]
-Shift the positional parameters n times.  A shift
-sets the value of $1 to the value of $2, the value of
-$2 to the value of $3, and so on, decreasing the
-value of $# by one.  If there are zero positional
-parameters, shifting does not do anything.
-.It trap [ action ] signal ...
-Cause the shell to parse and execute action when any
-of the specified signals are received.  The signals
-are specified by signal number.  Action may be null
-or omitted; the former causes the specified signal to
-be ignored and the latter causes the default action
-to be taken.  When the shell forks off a subshell, it
-resets trapped (but not ignored) signals to the
-default action.  The trap command has no effect on
-signals that were ignored on entry to the shell.
-.It type [name] ...
-Interpret each name as a command and print the
-resolution of the command search.
+In general it is better to write
+.Bd -literal -offset indent
+variable=value
+.Ed
+rather than using
+.Ic setvar .
+.It Ic shift Op Ar n
+Shift the positional parameters
+.Ar n
+times, or one time if
+.Ar n
+is not specified.
+A shift sets the value of $1 to the value of $2,
+the value of $2 to the value of $3, and so on,
+decreasing the value of $# by one.
+If there are zero positional parameters, shifting does not do anything.
+.It Xo
+.Ic trap
+.Op Ar action
+.Ar signal ...
+.Xc
+Cause the shell to parse and execute
+.Ar action
+when any specified
+.Ar signal
+is received.
+The signals are specified by signal number.
+The
+.Ar action
+may be null or omitted;
+the former causes the specified signal to be ignored
+and the latter causes the default action to be taken.
+When the shell forks off a subshell,
+it resets trapped (but not ignored) signals to the default action.
+The
+.Ic trap
+command has no effect on signals that were ignored on entry to the shell.
+.It Ic type Op Ar name ...
+Interpret each
+.Ar name
+as a command and print the resolution of the command search.
 Possible resolutions are:
 shell keyword, alias, shell builtin command, command, tracked alias
-and not found.  For aliases the alias expansion is printed;
-for commands and tracked aliases the complete pathname of
-the command is printed.
-.It ulimit [ -HSacdflmnust ] [ limit ]
+and not found.
+For aliases the alias expansion is printed;
+for commands and tracked aliases
+the complete pathname of the command is printed.
+.It Xo
+.Ic ulimit
+.Op Fl HSacdflmnust
+.Op Ar limit
+.Xc
 Set or display resource limits (see
 .Xr getrlimit 2 ).
 If
-.Dq limit
+.Ar limit
 is specified, the named resource will be set;
 otherwise the current resource value will be displayed.
 .Pp
 If
-.Dq -H
-is specified, the hard limits will be
-set or displayed.  While everybody is allowed to reduce a
-hard limit, only the superuser can increase it.  Option
-.Dq -S
+.Fl H
+is specified, the hard limits will be set or displayed.
+While everybody is allowed to reduce a hard limit,
+only the superuser can increase it.
+The
+.Fl S
+option
 specifies the soft limits instead.  When displaying limits,
 only one of
-.Dq -S
+.Fl S
 or
-.Dq -H
-can be given.  The default is
-to display the soft limits, and to set both, the hard and
-the soft limits.
+.Fl H
+can be given.
+The default is to display the soft limits,
+and to set both the hard and the soft limits.
 .Pp
 Option
-.Dq -a
-requests to display all resources.  The parameter
-.Dq limit
+.Fl a
+causes the
+.Ic ulimit
+command to display all resources.
+The parameter
+.Ar limit
 is not acceptable in this mode.
 .Pp
 The remaining options specify which resource value is to be
-displayed or modified.  They are mutually exclusive.
+displayed or modified.
+They are mutually exclusive.
 .Bl -tag -width Ds
-.It -c coredumpsize
+.It Fl c Ar coredumpsize
 The maximal size of core dump files, in 512-byte blocks.
-.It -d datasize
+.It Fl d Ar datasize
 The maximal size of the data segment of a process, in kilobytes.
-.It -f filesize
-The maximal size of a file, in 512-byte blocks.  This is the
-default.
-.It -l lockedmem
+.It Fl f Ar filesize
+The maximal size of a file, in 512-byte blocks.
+.It Fl l Ar lockedmem
 The maximal size of memory that can be locked by a process, in
 kilobytes.
-.It -m memoryuse
+.It Fl m Ar memoryuse
 The maximal resident set size of a process, in kilobytes.
-.It -n nofiles
+.It Fl n Ar nofiles
 The maximal number of descriptors that could be opened by a process.
-.It -s stacksize
+.It Fl s Ar stacksize
 The maximal size of the stack segment, in kilobytes.
-.It -t time
+.It Fl t Ar time
 The maximal amount of CPU time to be used by each process, in seconds.
-.It -u userproc
+.It Fl u Ar userproc
 The maximal number of simultaneous processes for this user ID.
 .El
-.It umask [ mask ]
-Set the value of umask (see
+.It Ic umask Op Ar mask
+Set the file creation mask (see
 .Xr umask 2 )
-to the specified
-octal value.
-If the argument is omitted, the umask value is printed.
-.It unalias [-a] [name]
+to the octal value specified by
+.Ar mask
+If the argument is omitted, the current mask value is printed.
+.It Xo
+.Ic unalias
+.Op Fl a
+.Op Ar name
+.Xc
 If
-.Dq name
+.Ar name
 is specified, the shell removes that alias.
 If
-.Dq -a
+.Ar a
 is specified, all aliases are removed.
-.It unset name ...
-The specified variables and functions are unset and
-unexported.
-If a given name corresponds to both a variable and a function,
+.It Ic unset Ar name ...
+The specified variables and functions are unset and unexported.
+If a given
+.Ar name
+corresponds to both a variable and a function,
 both the variable and the function are unset.
-.It wait [ job ]
-Wait for the specified job to complete and return the
-exit status of the last process in the job.
+.It Ic wait Op Ar job
+Wait for the specified
+.Ar job
+to complete and return the exit status of the last process in the
+.Ar job .
 If the argument is omitted, wait for all jobs to complete
 and return an exit status of zero.
 .El
@@ -1402,19 +1812,33 @@ and return an exit status of zero.
 When
 .Nm
 is being used interactively from a terminal, the current command
-and the command history (see fc in
+and the command history
+(see
+.Ic fc
+in
 .Sx Builtin Commands )
-can be edited using vi-mode
-command line editing.  This mode uses commands similar
+can be edited using vi-mode command line editing.
+This mode uses commands similar
 to a subset of those described in the vi man page.
-The command 'set -o vi' enables vi-mode editing and places
+The command
+.Dq Li set -o vi
+(or
+.Dq Li set -E )
+enables vi-mode editing and places
 .Nm
 into vi insert mode.  With vi-mode enabled,
 .Nm
-can be switched between insert mode and command mode by typing <ESC>.
-Hitting <return> while in command mode will pass the line to the shell.
-.Pp
-Similarly, the 'set -o emacs' command can be used to enable a subset of
+can be switched between insert mode and command mode by typing
+.Aq ESC .
+Hitting
+.Aq return
+while in command mode will pass the line to the shell.
+.Pp
+Similarly, the
+.Dq Li set -o emacs
+(or
+.Dq Li set -V )
+command can be used to enable a subset of
 emacs-style command line editing features.
 .Sh SEE ALSO
 .Xr builtin 1 ,