flurry of updates:

- be more consistent w.r.t. variables in macros with `.Ic'
  instead of `.Va'
- document changes in IFS parsing
- minimize diffs between ksh.1tbl and sh.1tbl w.r.t. `.Nm'
  macros and in other places
- sort recognized keywords and remove dependency on tbl(1)
- indent example displays
- kill `bind'
- collapse `test' display, it has two entries for `str',
  and use different args for file time tests
- grammar, punctuation, and mdoc fixes
- tidy display of `alias' and `kill'

ok and bits from jmc

1 files changed, 109 insertions, 98 deletions

diff --git a/bin/ksh/sh.1 b/bin/ksh/sh.1
index 4e64b389119..7ff5db13fe3 100644
--- a/bin/ksh/sh.1
+++ b/bin/ksh/sh.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: sh.1,v 1.52 2004/11/09 21:56:54 jmc Exp $
+.\"	$OpenBSD: sh.1,v 1.53 2004/12/10 01:56:56 jaredy Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1993
 .\"     The Regents of the University of California.  All rights reserved.
@@ -56,7 +56,7 @@ interactive and script use.
 The following options can be specified only on the command line:
 .Bl -tag -width Ds
 .It Fl c Ar command-string
-.Nm sh
+.Nm
 will execute the command(s) contained in
 .Ar command-string .
 .It Fl i
@@ -84,7 +84,7 @@ If there are no non-option
 arguments, the shell reads commands from the standard input.
 The name of
 the shell (i.e., the contents of
-.Va $0 )
+.Ic $0 )
 is determined as follows: if the
 .Fl c
 option is used and there is a non-option argument, it is used as the name;
@@ -98,7 +98,8 @@ A shell is
 if the
 .Fl i
 option is used or if both standard input and standard error are attached
-to a tty.
+to a
+.Xr tty 4 .
 An interactive shell has job control enabled (if available), ignores the
 .Dv SIGINT ,
 .Dv SIGQUIT ,
@@ -222,7 +223,7 @@ In the absence of fatal errors,
 the exit status is that of the last command executed, or zero, if no
 command is executed.
 .Ss Command syntax
-The shells begins parsing its input by breaking it into
+The shell begins parsing its input by breaking it into
 .Em words .
 Words, which are sequences of characters, are delimited by unquoted whitespace
 characters (space, tab, and newline) or meta-characters
@@ -291,7 +292,7 @@ The first three of these are the above mentioned quoting characters (see
 .Sx Quoting
 below);
 .Ql # ,
-if used at the beginning of a word, introduces a comment -- everything after
+if used at the beginning of a word, introduces a comment \(em everything after
 the
 .Ql #
 up to the nearest newline is ignored;
@@ -395,7 +396,7 @@ only if the exit status of
 .Ar cmd1
 is zero;
 .Ql ||
-is the opposite --
+is the opposite \(em
 .Ar cmd2
 is executed only if the exit status of
 .Ar cmd1
@@ -454,16 +455,14 @@ These words
 are only recognized if they are unquoted and if they are used as the first
 word of a command (i.e., they can't be preceded by parameter assignments or
 redirections):
-.Pp
-.TS
-center;
-lfB lfB lfB lfB lfB .
+.Bd -unfilled -offset center
+.Bf Sy
 case    else    function        !
-do      esac    if      until   [[
-done    fi      in      while   {
-elif    for     time    then    }
-.TE
-.Pp
+do      esac    if      time    [[
+done    fi      in      until   {
+elif    for     then    while   }
+.Ef
+.Ed
 .Sy Note:
 Some shells (but not this one) execute control structure commands in a
 subshell when one or more of their file descriptors are redirected, so any
@@ -478,14 +477,14 @@ In the following compound command descriptions, command lists (denoted as
 that are followed by reserved words must end with a semicolon, a newline, or
 a (syntactically correct) reserved word.
 For example,
-.Bd -unfilled -offset -indent
+.Bd -unfilled -offset indent
 .Ic { echo foo; echo bar; }
 .Ic { echo foo; echo bar<newline> }
 .Ic { { echo foo; echo bar; } }
 .Ed
 .Pp
 are all valid, but
-.Bd -unfilled -offset -indent
+.Bd -unfilled -offset indent
 .Ic { echo foo; echo bar }
 .Ed
 .Pp
@@ -563,7 +562,7 @@ If
 .Ic in
 is not used to specify a word list, the positional parameters
 .Po
-.Va $1 , $2 ,
+.Ic $1 , $2 ,
 etc.\&
 .Pc
 are used instead.
@@ -790,7 +789,7 @@ characters, delimit a field.
 As a special case, leading and trailing
 .Ev IFS
 whitespace is stripped (i.e., no leading or trailing empty field is created by
-it); leading or trailing
+it); leading
 .Pf non- Ev IFS
 whitespace does create an empty field.
 .Pp
@@ -896,8 +895,8 @@ or
 where
 .Ar name
 is a parameter name.
-If substitution is performed on a parameter that is not set, a
-null string is substituted unless the
+If substitution is performed on a parameter
+that is not set, a null string is substituted unless the
 .Ic nounset
 option
 .Po
@@ -1087,7 +1086,7 @@ Process ID of the last background process started.
 If no background processes have been started, the parameter is not set.
 .It Ev \&#
 The number of positional parameters (i.e.,
-.Va $1 , $2 ,
+.Ic $1 , $2 ,
 etc.).
 .It Ev \&$
 The process ID of the shell, or the
@@ -1105,7 +1104,7 @@ command below for a list of options).
 .It Ev \&?
 The exit status of the last non-asynchronous command executed.
 If the last command was killed by a signal,
-.Va \&$?\&
+.Ic \&$?\&
 is set to 128 plus the signal number.
 .It Ev 0
 The name the shell was invoked with (i.e.,
@@ -1131,7 +1130,7 @@ Further positional parameters may be accessed using
 .Ic ${ Ns Ar number Ns Ic \&} .
 .It Ev \&*
 All positional parameters (except parameter 0); i.e.,
-.Va $1 , $2 , $3 ,
+.Ic $1 , $2 , $3 ,
 \&...
 If used
 outside of double quotes, parameters are separate words (which are subjected
@@ -1486,7 +1485,7 @@ and
 but the original
 .Xr ksh ,
 Bourne
-.Xr sh
+.Xr sh ,
 and
 .Xr bash
 do, so this may have to change (too bad).
@@ -1619,7 +1618,7 @@ Parameter, command, and arithmetic
 substitutions, tilde substitutions, and (if the shell is interactive)
 file name generation are all performed on the
 .Ar file ,
-.Ar marker
+.Ar marker ,
 and
 .Ar fd
 arguments of redirections.
@@ -1639,7 +1638,7 @@ any redirections must appear at the end.
 Redirections are processed after
 pipelines are created and in the order they are given, so
 .Pp
-.Ic cat /foo/bar 2\&>&1 \&> /dev/null \&| cat -n
+.Dl Ic cat /foo/bar 2\*(Gt&1 \*(Gt /dev/null \&| cat -n
 .Pp
 will print an error with a line number prepended to it.
 .Ss Arithmetic expressions
@@ -1820,7 +1819,7 @@ in that they are executed in the current environment.
 However, unlike
 .Li .-scripts ,
 shell arguments (i.e., positional parameters
-.Va $1 , $2 ,
+.Ic $1 , $2 ,
 etc.) are never visible
 inside them.
 When the shell is determining the location of a command, functions
@@ -1879,7 +1878,9 @@ assignments made inside functions are visible after the function completes.
 If this is not the desired effect, the
 .Ic typeset
 command can be used inside a function to create a local parameter.
-Note that special parameters (e.g., $$, $\&!) can't be scoped in this way.
+Note that special parameters (e.g.,
+.Ic \&$$ , $\&! )
+can't be scoped in this way.
 .Pp
 The exit status of a function is that of the last command executed in the
 function.
@@ -1895,8 +1896,12 @@ defined with the
 notation:
 .Bl -bullet
 .It
-The $0 parameter is set to the name of the function (Bourne-style functions
-leave $0 untouched).
+The
+.Ic $0
+parameter is set to the name of the function (Bourne-style functions
+leave
+.Ic $0
+untouched).
 .It
 Parameter assignments preceding function calls are not kept in the shell
 environment (executing Bourne-style functions will keep assignments).
@@ -1997,7 +2002,7 @@ mode, signal names are listed one per line; in
 .Pf non- Tn POSIX
 mode,
 signal numbers, names, and descriptions are printed in columns.
-In future, a new option
+In the future, a new option
 .Po Fl v
 \ perhaps
 .Pc
@@ -2139,7 +2144,9 @@ mode, the expression
 .Sq Ic \&!
 arguments) is always true as it is a non-zero length string; in
 .Pf non- Tn POSIX
-mode, it tests if file descriptor 1 is a tty (i.e., the
+mode, it tests if file descriptor 1 is a
+.Xr tty 4
+(i.e., the
 .Ar fd
 argument to the
 .Fl t
@@ -2183,7 +2190,9 @@ special commands
 .Ic readonly , return , set , shift ,
 .Ic trap , unset
 .Pp
-Additional ksh special commands
+Additional
+.Nm
+special commands
 .Pp
 .Ic builtin , times , typeset
 .Pp
@@ -2200,12 +2209,16 @@ regular commands
 .Ic jobs , kill , read , true ,
 .Ic umask , unalias , wait
 .Pp
-Additional ksh regular commands
+Additional
+.Nm
+regular commands
 .Pp
 .Ic \&[ , echo , let , print ,
 .Ic pwd , test , ulimit , whence
 .Pp
-In the future, the additional ksh special and regular commands may be treated
+In the future, the additional
+.Nm
+special and regular commands may be treated
 differently from the
 .Tn POSIX
 special and regular commands.
@@ -2236,8 +2249,7 @@ Exit status is set to zero.
 .Op Ic +-
 .Oo Ar name
 .Op Ns = Ns Ar value
-.Ar ...
-.Oc
+.Ar ... Oc
 .Xc
 Without arguments,
 .Ic alias
@@ -2296,15 +2308,6 @@ is assumed.
 This command is only available on systems which support job control (see
 .Sx Job control
 below for more information).
-.It Xo
-.Ic bind Op Fl m
-.Oo Ar key
-.Op Ns = Ns Ar editing-command
-.Ar ... Oc
-.Xc
-Set or view the current emacs command editing key bindings/macros (see
-.Sx Emacs interactive input line editing
-below for a complete description).
 .It Ic break Op Ar level
 Exit the
 .Ar level Ns th
@@ -2456,7 +2459,7 @@ The shell exits with the specified exit status.
 If
 .Ar status
 is not specified, the exit status is the current value of the
-.Ic ?\&
+.Ic $?\&
 parameter.
 .It Xo Ic export Op Fl p
 .Op Ar parameter Ns Op \&= Ns Ar value
@@ -2599,10 +2602,10 @@ below for the format of
 .Ar job
 and the displayed job.
 .It Xo Ic kill
-.Oo Fl s Ar signame No \&|
-.Fl signum No \&| Fl signame Oc {
-.Ar job No \&|
-.Ar pid No \&|
+.Oo Fl s Ar signame \*(Ba
+.Fl Ar signum | Fl Ar signame Oc {
+.Ar job |
+.Ar pid |
 .Ar pgrp No } Ar ...
 .Xc
 Send the specified signal to the specified jobs, process IDs, or process
@@ -2622,7 +2625,7 @@ specified
 If no arguments are specified, a list of all the signals, their numbers and
 a short description of them are printed.
 .It Xo Ic print
-.Oo Fl nprsu Ns Ar n No \&|
+.Oo Fl nprsu Ns Ar n \*(Ba
 .Fl R Op Fl en Oc
 .Op Ar argument ...
 .Xc
@@ -2674,7 +2677,7 @@ The
 .Fl R
 option is used to emulate, to some degree, the
 .Bx
-.Xr echo
+.Xr echo 1
 command, which does not process
 .Ql \e
 sequences unless the
@@ -2727,7 +2730,9 @@ exits with a non-zero status.
 .Pp
 The first parameter may have a question mark and a string appended to it, in
 which case the string is used as a prompt (printed to standard error before
-any input is read) if the input is a tty (e.g.,
+any input is read) if the input is a
+.Xr tty 4
+(e.g.,
 .Ic read nfoo?'number of foos: ' ) .
 .Pp
 The
@@ -2971,7 +2976,9 @@ Enable vi-like command-line editing (interactive shells only).
 No effect.
 In the original Korn shell, unless
 .Ic viraw
-was set, the vi command-line mode would let the tty driver do the work until
+was set, the vi command-line mode would let the
+.Xr tty 4
+driver do the work until
 .Tn ESC
 (^[) was entered.
 .Nm pdksh
@@ -3000,7 +3007,7 @@ will print the long names of all options that are currently on.
 .Pp
 Remaining arguments, if any, are positional parameters and are assigned, in
 order, to the positional parameters (i.e.,
-.Va $1 , $2 ,
+.Ic $1 , $2 ,
 etc.).
 If options end with
 .Ql --
@@ -3008,7 +3015,7 @@ and there are no remaining arguments, all positional parameters are cleared.
 If no options or arguments are given, the values of all names are printed.
 For unknown historical reasons, a lone
 .Ql -
-option is treated specially -- it clears both the
+option is treated specially \(em it clears both the
 .Fl x
 and
 .Fl v
@@ -3037,20 +3044,6 @@ and
 statements.
 The following basic expressions are available:
 .Bl -tag -width 17n
-.It Ar str
-.Ar str
-has non-zero length.
-Note that there is the potential for problems if
-.Ar str
-turns out to be an operator (e.g.,
-.Fl r ) .
-It is generally better to use a test like
-.Sm off
-.Ic \&[\ X\&" Ar str Ic \&" Ic \ \&]
-.Sm on
-instead (double quotes are used in case
-.Ar str
-contains spaces or file globbing characters).
 .It Fl r Ar file
 .Ar file
 exists and is readable.
@@ -3127,25 +3120,24 @@ doesn't exist (thus
 returns true if and only if option
 .Ar foo
 exists).
-.It Ar file Fl nt Ar file
-first
-.Ar file
-is newer than second
-.Ar file .
-.It Ar file Fl ot Ar file
-first
-.Ar file
-is older than second
-.Ar file .
-.It Ar file Fl ef Ar file
-first
-.Ar file
-is the same file as second
-.Ar file .
+.It Ar file1 Fl nt Ar file2
+.Ar file1
+is newer than
+.Ar file2 .
+.It Ar file1 Fl ot Ar file2
+.Ar file1
+is older than
+.Ar file2 .
+.It Ar file1 Fl ef Ar file2
+.Ar file1
+is the same file as
+.Ar file2 .
 .It Fl t Op Ar fd
 File descriptor
 .Ar fd
-is a tty device.
+is a
+.Xr tty 4
+device.
 If the
 .Ic posix
 option is not set,
@@ -3156,7 +3148,18 @@ to the special
 rules described below).
 .It Ar string
 .Ar string
-is not empty.
+has non-zero length.
+Note that there is the potential for problems if
+.Ar string
+turns out to be an operator (e.g.,
+.Fl r ) .
+It is generally better to use a test like
+.Sm off
+.Ic \&[\ X\&" Ar string Ic \&" Ic \ \&]
+.Sm on
+instead (double quotes are used in case
+.Ar string
+contains spaces or file globbing characters).
 .It Fl z Ar string
 .Ar string
 is empty.
@@ -3250,7 +3253,7 @@ instead.
 Print the accumulated user and system times used by the shell and by processes
 which have exited that the shell started.
 .It Ic trap Op Ar handler signal ...
-Sets trap handler that is to be executed when any of the specified signals are
+Sets a trap handler that is to be executed when any of the specified signals are
 received.
 .Ar handler
 is either a
@@ -3296,6 +3299,10 @@ lists, as a series of
 .Ic trap
 commands, the current state of the traps that have been set since the shell
 started.
+Note that the output of
+.Ic trap
+cannot be usefully piped to another process (an artifact of the fact that
+traps are cleared when subprocesses are created).
 .Pp
 The original Korn shell's
 .Dv DEBUG
@@ -3419,7 +3426,7 @@ This is the default action (option exists for ksh93 compatibility).
 .It Fl r
 Read-only attribute.
 Parameters with this attribute may not be assigned to or unset.
-Once this attribute is set, it can not be turned off.
+Once this attribute is set, it cannot be turned off.
 .It Fl t
 Tag attribute.
 Has no meaning to the shell; provided for application use.
@@ -3471,7 +3478,7 @@ limit is imposed.
 Note that some systems may not allow limits to be increased
 once they are set.
 Also note that the types of limits available are system
-dependent -- some systems have only the
+dependent \(em some systems have only the
 .Fl f
 limit.
 .Bl -tag -width 5n
@@ -3682,7 +3689,9 @@ A job may be referred to in the
 and
 .Ic wait
 commands either by the process ID of the last process in the command pipeline
-(as stored in the $! parameter) or by prefixing the job number with a percent
+(as stored in the
+.Ic $!\&
+parameter) or by prefixing the job number with a percent
 sign
 .Pq Sq % .
 Other percent sequences can also be used to refer to jobs:
@@ -3712,8 +3721,9 @@ The job starting with string
 .Pp
 When a job changes state (e.g., a background job finishes or foreground job is
 stopped), the shell prints the following status information:
-.Pp
+.Bd -unfilled -offset indent
 .Ic \&[ Ar number Ic \&] Ar flag status command
+.Ed
 .Pp
 where
 .Bl -tag -width "status"
@@ -3735,7 +3745,7 @@ indicates the current state of the job and can be:
 The job has neither stopped nor exited (note that running does not necessarily
 mean consuming
 .Tn CPU
-time -- the process could be blocked waiting for some
+time \(em the process could be blocked waiting for some
 event).
 .It Cm Done Op Ar number
 The job exited.
@@ -3805,6 +3815,7 @@ signal and the shell exits.
 .Xr rand 3 ,
 .Xr signal 3 ,
 .Xr system 3 ,
+.Xr tty 4 ,
 .Xr environ 7
 .Pp
 .Rs
@@ -3831,11 +3842,11 @@ signal and the shell exits.
 is implemented as a run-time option of
 .Nm pdksh ,
 with only those
-.Nm ksh
+.Nm
 features whose syntax or semantics are incompatible with a traditional Bourne
 shell disabled.
 Since this leaves some
-.Nm ksh
+.Nm
 extensions exposed, caution should be used where backwards compatibility with
 traditional Bourne or
 .Tn POSIX