[src/trunk]: src/bin/sh Try to improve markup in the Built-ins section.

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

details:   https://anonhg.NetBSD.org/src/rev/735ed7ae8c3d
branches:  trunk
changeset: 321381:735ed7ae8c3d
user:      uwe <uwe%NetBSD.org@localhost>
date:      Tue Mar 13 23:03:21 2018 +0000

description:
Try to improve markup in the Built-ins section.
Mostly sprinkle missing .Ic and .Ar

diffstat:

 bin/sh/sh.1 |  364 +++++++++++++++++++++++++++++++++++------------------------
 1 files changed, 216 insertions(+), 148 deletions(-)

diffs (truncated from 856 to 300 lines):

diff -r 89f11920f66d -r 735ed7ae8c3d bin/sh/sh.1
--- a/bin/sh/sh.1       Tue Mar 13 21:49:15 2018 +0000
+++ b/bin/sh/sh.1       Tue Mar 13 23:03:21 2018 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: sh.1,v 1.186 2018/03/13 21:49:15 uwe Exp $
+.\"    $NetBSD: sh.1,v 1.187 2018/03/13 23:03:21 uwe Exp $
 .\" Copyright (c) 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
 .\"
@@ -2038,7 +2038,10 @@
 and the
 .Dq \(mi
 last, in the character class.
+.\"
+.\"
 .Ss Built-ins
+.\"
 This section lists the built-in commands which are built-in because they
 need to perform some operation that can't be performed by a separate
 process.
@@ -2050,10 +2053,10 @@
 .Xr test 1 ,
 etc).
 .Bl -tag -width 5n
-.It : [ Ar arg ... ]
+.It Ic : Oo Ar arg ... Oc
 A null command that returns a 0 (true) exit value.
 Any arguments or redirects are evaluated, then ignored.
-.It \&. file
+.It Ic \&. Ar file
 The dot command reads and executes the commands from the specified
 .Ar file
 in the current shell environment.
@@ -2062,10 +2065,9 @@
 .Ev PATH
 variable if its name does not contain a directory separator
 .Pq Sq / .
-The return command
-(see
-.Sx Built-ins
-below)
+The
+.Ic return
+command (see below)
 can be used for a premature return from the sourced file.
 .Pp
 The POSIX standard has been unclear on how loop control keywords (break
@@ -2073,9 +2075,9 @@
 This implementation allows them to control loops surrounding the dot command,
 but obviously such behavior should not be relied on.
 It is now permitted by the standard, but not required.
-.It alias Op Ar name Ns Op Ar "=string ..."
+.It Ic alias Op Ar name Ns Op Li = Ns Ar string ...
 If
-.Ar name=string
+.Ar name Ns Li = Ns Ar string
 is specified, the shell defines the alias
 .Ar name
 with value
@@ -2090,10 +2092,10 @@
 built-in prints the
 names and values of all defined aliases (see
 .Ic unalias ) .
-.It bg [ Ar job ] ...
+.It Ic bg Op Ar job ...
 Continue the specified jobs (or the current job if no
 jobs are given) in the background.
-.It command Oo Fl p Oc Oo Fl v Oc Oo Fl V Oc Ar command Oo Ar arg ... Oc
+.It Ic command Oo Fl pVv Oc Ar command Op Ar arg ...
 Execute the specified command but ignore shell functions when searching
 for it.
 (This is useful when you
@@ -2115,7 +2117,7 @@
 search for the command and print the absolute pathname
 of utilities, the name for built-ins or the expansion of aliases.
 .El
-.It cd Oo Fl P Oc Op Ar directory Op Ar replace
+.It Ic cd Oo Fl P Oc Op Ar directory Op Ar replace
 Switch to the specified directory (default
 .Ev $HOME ) .
 If
@@ -2128,7 +2130,7 @@
 Otherwise if
 .Ar directory
 is
-.Sq - ,
+.Sq Li - ,
 then the current working directory is changed to the previous current
 working directory as set in
 .Ev OLDPWD .
@@ -2173,7 +2175,7 @@
 directory that it actually switched to if this is different from the name
 that the user gave,
 or always if the
-.Ic cdprint
+.Cm cdprint
 option is set.
 The destination may be different either because the
 .Ev CDPATH
@@ -2182,11 +2184,13 @@
 or if the
 .Ar replace
 argument was used.
-.It eval Ar string ...
+.It Ic eval Ar string ...
 Concatenate all the arguments with spaces.
 Then re-parse and execute the command.
-.It exec Op Ar command arg ...
-Unless command is omitted, the shell process is replaced with the
+.It Ic exec Op Ar command Op Ar arg ...
+Unless
+.Ar command
+is omitted, the shell process is replaced with the
 specified program (which must be a real program, not a shell built-in or
 function).
 Any redirections on the
@@ -2195,7 +2199,7 @@
 .Ic exec
 command finishes.
 When the
-.Ic posix
+.Cm posix
 option is not set,
 file descriptors created via such redirections are marked close-on-exec
 (see
@@ -2212,7 +2216,7 @@
 .Xr ksh 1 ) ,
 made those file descriptors available to exec'ed processes.
 This behavior is required by the POSIX standard, so when the
-.Ic posix
+.Cm posix
 option is set, this shell also acts that way.
 To be assured the close-on-exec setting is off,
 redirect the descriptor to (or from) itself,
@@ -2228,14 +2232,14 @@
 .Ic fdflags
 command below, which can set, or clear, this, and other,
 file descriptor flags.
-.It exit Op Ar exitstatus
+.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 (the current value of $?) is used.
-.It export Oo Fl npx Oc Ar name ...
-.It export Fl p Oo Fl x Oc
+.It Ic export Oo Fl npx Oc Ar name ...
+.It Ic export Fl p Oo Fl x Oc
 With no options,
 but one or more names,
 the specified names are exported so that they will appear in the
@@ -2243,7 +2247,9 @@
 With
 .Fl n
 the specified names are un-exported.
-Variables can also be un-exported using the unset built in command.
+Variables can also be un-exported using the
+.Ic unset
+built in command.
 With
 .Fl x
 (exclude) the specified names are marked not to be exported,
@@ -2259,8 +2265,10 @@
 FOO=some_value my_command
 .Ed
 .Pp
-still passes the value (FOO=some_value) to
-.Ic my_command
+still passes the value
+.Pq Li FOO=some_value
+to
+.Li my_command
 through the environment.
 .Pp
 The shell allows the value of a variable to be set at the
@@ -2288,17 +2296,21 @@
 or un-exporting, read-only variables.
 The no-export flag can be reset by unsetting the variable
 and creating it again \(en provided it is not also read-only.
-.It fc Oo Fl e Ar editor Oc Oo Ar first Oo Ar last Oc Oc
-.It fc Fl l Oo Fl nr Oc Oo Ar first Oo Ar last Oc Oc
-.It fc Fl s Oo Ar old=new Oc Oo Ar first Oc
+.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last
+.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last
+.It Ic fc Fl s Oo Ar old=new Oc Op Ar first
 The
 .Ic fc
 built-in lists, or edits and re-executes, commands previously entered
 to an interactive shell.
 .Bl -tag -width 5n
-.It Fl e No editor
-Use the editor named by editor to edit the commands.
-The editor string is a command name, subject to search via the
+.It Fl e Ar editor
+Use the editor named by
+.Ar editor
+to edit the commands.
+The
+.Ar editor
+string is a command name, subject to search via the
 .Ev PATH
 variable.
 The value in the
@@ -2323,7 +2335,8 @@
 .Fl r ,
 with each command preceded by the command number.
 .It Fl n
-Suppress command numbers when listing with -l.
+Suppress command numbers when listing with
+.Fl l .
 .It Fl r
 Reverse the order of the commands listed (with
 .Fl l )
@@ -2333,14 +2346,18 @@
 .Fl s ) .
 .It Fl s
 Re-execute the command without invoking an editor.
-.It first
-.It last
+.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 first or last or both are one of the following:
+The value of
+.Ar first
+or
+.Ar last
+or both are one of the following:
 .Bl -tag -width 5n
 .It Oo Cm + Oc Ns Ar number
 A positive number representing a command number; command numbers can be
@@ -2352,27 +2369,30 @@
 number of commands previously.
 For example, \-1 is the immediately previous command.
 .El
-.It string
+.It Ar string
 A string indicating the most recently entered command that begins with
 that string.
-If the old=new operand is not also specified with
+If the
+.Ar old Ns Li = Ns Ar 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:
+The following environment variables affect the execution of
+.Ic fc :
 .Bl -tag -width HISTSIZE
 .It Ev FCEDIT
 Name of the editor to use.
 .It Ev HISTSIZE
 The number of previous commands that are accessible.
 .El
-.It fg Op Ar job
+.It Ic fg Op Ar job
 Move the specified job or the current job to the foreground.
 A foreground job can interact with the user via standard input,
 and receive signals from the terminal.
-.It fdflags Oo Fl v Oc Oo fd ... Oc
-.It fdflags Oo Fl v Oc Fl s Ar flags fd Oo ... Oc
+.It Ic fdflags Oo Fl v Oc Op Ar fd ...
+.It Ic fdflags Oo Fl v Oc Fl s Ar flags fd Op ...
 Get or set file descriptor flags.
 The
 .Fl v
@@ -2407,12 +2427,11 @@
 and
 .Xr open 2
 for more information.
-.It getopts Ar optstring var
+.It Ic getopts Ar optstring var
 The POSIX
 .Ic getopts
 command, not to be confused with the
-.Em Bell Labs
--derived
+Bell Labs\[en]derived
 .Xr getopt 1 .
 .Pp
 The first argument should be a series of letters, each of which may be
@@ -2434,7 +2453,7 @@
 .Ic getopts
 places the value of the next option from the option string in the list in
 the shell variable specified by
-.Va var
+.Ar var
 and its index in the shell variable
 .Ev OPTIND .
 When the shell is invoked,
@@ -2445,12 +2464,12 @@
 built-in will place it in the shell variable
 .Ev OPTARG .