[src/trunk]: src/bin/sh Start adding more gaudy markup. Use .Li or .Dv when ...

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

details:   https://anonhg.NetBSD.org/src/rev/16883491f6a5
branches:  trunk
changeset: 831174:16883491f6a5
user:      uwe <uwe%NetBSD.org@localhost>
date:      Thu Mar 15 01:20:43 2018 +0000

description:
Start adding more gaudy markup.  Use .Li or .Dv when referring to
parameters.  Use more .Ic and .Ar when defining syntax.

The manual is still rather inconsistent e.g. when referring to
parameters where it randomly uses both $0 and 0 or $@ and @ - but I'm
not shaving that yak at least for now.

diffstat:

 bin/sh/sh.1 |  379 +++++++++++++++++++++++++++++++++++++++--------------------
 1 files changed, 248 insertions(+), 131 deletions(-)

diffs (truncated from 924 to 300 lines):

diff -r 378f8594b289 -r 16883491f6a5 bin/sh/sh.1
--- a/bin/sh/sh.1       Thu Mar 15 00:48:13 2018 +0000
+++ b/bin/sh/sh.1       Thu Mar 15 01:20:43 2018 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: sh.1,v 1.192 2018/03/14 10:38:52 uwe Exp $
+.\"    $NetBSD: sh.1,v 1.193 2018/03/15 01:20:43 uwe Exp $
 .\" Copyright (c) 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
 .\"
@@ -196,8 +196,12 @@
 .Fl s
 was given, then the shell treats the first argument
 as the name of a file from which to read commands (a shell script).
-This also becomes $0 and the remaining arguments are set as the
-positional parameters of the shell ($1, $2, etc).
+This also becomes
+.Li $0
+and the remaining arguments are set as the
+positional parameters of the shell
+.Li ( $1 , $2 ,
+etc).
 Otherwise, if
 .Fl c
 was given, then the first argument, which must exist,
@@ -205,14 +209,22 @@
 .Nm
 commands to execute.
 Then if any additional arguments follow the command string,
-those arguments become $0, $1, ...
+those arguments become
+.Li $0 , $1 ,
+\&...
 Otherwise, if additional arguments were given
 (which implies that
 .Fl s
 was set)
-those arguments become $1, $2, ...
-If $0 has not been set by the preceding processing, it
-will be set to argv[0] as passed to the shell, which will
+those arguments become
+.Li $1 , $2 ,
+\&...
+If
+.Li $0
+has not been set by the preceding processing, it
+will be set to
+.Va argv\^ Ns [ 0 ]
+as passed to the shell, which will
 usually be the name of the shell itself.
 If
 .Fl s
@@ -273,15 +285,19 @@
 Read commands from the
 .Ar command_string
 operand instead of, or in addition to, from the standard input.
-Special parameter 0 will be set from the
+Special parameter
+.Dv 0 \" $0
+will be set from the
 .Ar command_name
-operand if given, and the positional parameters ($1, $2, etc.)
+operand if given, and the positional parameters
+.Li ( $1 , $2 ,
+etc.)
 set from the remaining argument operands, if any.
 .Fl c
 is only available at invocation, it cannot be
 .Ic set ,
 and there is no form using
-.Dq \&+ .
+.Dq Cm \&+ .
 .It Fl E Em emacs
 Enable the built-in emacs style
 command line editor (disables
@@ -577,17 +593,20 @@
 .Ss Double Quotes
 Enclosing characters within double quotes preserves the literal
 meaning of all characters except dollar sign
-.Pq $ ,
+.Pq Li \&$ ,
 backquote
-.Pq ` ,
+.Pq Li \&` ,
 and backslash
-.Pq \e .
+.Pq Li \e .
 The backslash inside double quotes is historically weird, and serves to
 quote only the following characters (and these not in all contexts):
 .Dl $  `  \*q  \e  <newline> ,
 where a backslash newline is a line continuation as above.
 Otherwise it remains literal.
-.Ss Dollar Single Quotes (\&$'...')
+.\"
+.\"
+.Ss Dollar Single Quotes ( Li \&$'...' )
+.\"
 .Bd -filled -offset indent
 .Bf Em
 Note: this form of quoting is still somewhat experimental,
@@ -600,10 +619,10 @@
 .Pp
 Enclosing characters in a matched pair of single quotes, with the
 first immediately preceded by an unquoted dollar sign
-.Pq \&$
+.Pq Li \&$
 provides a quoting mechanism similar to single quotes, except
 that within the sequence of characters, any backslash
-.Pq \e ,
+.Pq Li \e ,
 is an escape character, which causes the following character to
 be treated specially.
 Only a subset of the characters that can occur in the string
@@ -614,14 +633,14 @@
 .Pp
 The following characters are treated literally when following
 the escape character (backslash):
-.Dl \e \&' \&"
+.Dl \e \&' \(dq
 The sequence
-.Dq \e\e
+.Dq Li \e\e
 allows the escape character (backslash) to appear in the string literally.
-.Dq \e'
+.Dq Li \e'
 allows a single quote character into the string, such an
 escaped single quote does not terminate the quoted string.
-.Dq \e"
+.Dq Li \e\(dq
 is for compatibility with C strings, the double quote has
 no special meaning in a shell C-style string,
 and does not need to be escaped, but may be.
@@ -659,7 +678,7 @@
 In addition to those there are 5 forms that need additional
 data, which is obtained from the subsequent characters.
 An escape
-.Pq \e
+.Pq Li \e
 followed by one, two or three, octal digits
 .Po So 0 Sc Ns \&.. Ns So 7 Sc Ns Pc
 is processed to form an 8 bit character value.
@@ -687,7 +706,9 @@
 Consequently, users should ensure that the character
 following the hex escape sequence is something other than
 a hex digit.
-One way to achieve this is to end the $'...' string immediately
+One way to achieve this is to end the
+.Li $'...'
+string immediately
 after the final hex digit, and then, immediately start
 another, so
 .Dl \&$'\ex33'$'4...'
@@ -700,9 +721,9 @@
 in some other shells would be the hex value 0x334 (10, or more, bits).
 .Pp
 There are two escape sequences beginning with
-.Sq \eu
+.Sq Li \eu
 or
-.Sq \eU .
+.Sq Li \eU .
 The former is followed by from 1 to 4 hex digits, the latter by
 from 1 to 8 hex digits.
 Leading zeros can be used to pad the sequences to the maximum
@@ -728,30 +749,30 @@
 be an alphabetic character (a letter), or one of the following:
 .Dl \&@ \&[ \&\e \&] \&^ \&_ \&?
 Other than
-.Sq \ec?
+.Sq Li \ec?
 the value obtained is the least significant 5 bits of the
 ASCII value of the character following the
-.Sq \ec
+.Sq Li \ec
 escape sequence.
 That is what is commonly known as the
 .Dq control
 character obtained from the given character.
 The escape sequence
-.Sq \ec?
+.Sq Li \ec?
 yields the ASCII DEL character (0x7F).
 Note that to obtain the ASCII FS character (0x1C) this way,
 .Pq "that is control-\e"
 the trailing
-.Sq \e
+.Sq Li \e
 must be escaped itself, and so for this one case, the full
 escape sequence is
-.Dq \ec\e\e .
+.Dq Li \ec\e\e .
 The sequence
-.Dq \ec\eX
+.Dq Li \ec\e Ns Ar X\^
 where
-.Sq X
+.Sq Ar X\^
 is some character other than
-.Sq \e
+.Sq Li \e
 is reserved for future use, its meaning is unspecified.
 In this
 .Nm
@@ -759,12 +780,18 @@
 .Pp
 If any of the preceding escape sequences generate the value
 .Sq \e0
-(a NUL character) that character, and all that follow in the
-same $'...' string, are omitted from the resulting word.
+(a NUL character) that character, and all that follow in the same
+.Li $'...'
+string, are omitted from the resulting word.
 .Pp
-After the $'...' string has had any included escape sequences
+After the
+.Li $'...'
+string has had any included escape sequences
 converted, it is treated as if it had been a single quoted string.
+.\"
+.\"
 .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.
@@ -777,7 +804,10 @@
 .El
 .Pp
 Their meanings are discussed later.
+.\"
+.\"
 .Ss Aliases
+.\"
 An alias is a name and corresponding value set using the
 .Ic alias
 built-in command.
@@ -801,7 +831,9 @@
 commands without having to learn how to create functions with arguments.
 They can also be used to create lexically obscure code.
 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
 BNF in the POSIX 1003.2 document).
@@ -810,13 +842,16 @@
 then the shell has recognized a simple command.
 Otherwise, a complex
 command or some other special construct may have been recognized.
+.\"
+.\"
 .Ss Simple Commands
+.\"
 If a simple command has been recognized, the shell performs
 the following actions:
 .Bl -enum -offset indent
 .It
 Leading words of the form
-.Dq name=value
+.Dq Ar name Ns Li = Ns Ar value
 are stripped off, the value is expanded, as described below,
 and the results are assigned to the environment of the simple command.
 Redirection operators and their arguments (as described below) are
@@ -829,31 +864,34 @@
 command is located.
 Any remaining words are considered the arguments of the command.
 If no command name resulted, then the
-.Dq name=value
+.Dq Ar name Ns Li = Ns Ar value
 variable assignments recognized in item 1 affect the current shell.
 .It
 Redirections are performed, from first to last, in the order given,
 as described in the next section.
 .El
+.\"
+.\"
 .Ss Redirections
+.\"
 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:
 .Pp
-.Dl [n] Ns Va redir-op Ar file
+.Dl Oo Ar n Oc Ns Va redir-op Ar file
 .Pp
 where
 .Va redir-op
 is one of the redirection operators mentioned previously.
 The following is a list of the possible redirections.
 The
-.Bq n
+.Op Ar n
 is an optional number, as in
-.Sq 3
+.Sq Li 3
 (not
-.Sq Bq 3 ) ,
+.Li [3] ) ,