35034: improve manual format up to Chapter18

1 files changed, 50 insertions, 44 deletions

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index c4acf7672..5b25290b0 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -5,7 +5,8 @@ sect(Shell Builtin Commands)
 )\
 def(prefix)(1)(\
 item(tt(ARG1) var(simple command))(
-See noderef(Precommand Modifiers).
+See ifzman(the section `Precommand Modifiers' in zmanref(zshmisc))\
+ifnzman(noderef(Precommand Modifiers)).
 )\
 )\
 def(alias)(2)(\
@@ -95,7 +96,7 @@ which may have effects on shell parameters.  A zero exit status is returned.
 findex(alias)
 cindex(aliases, defining)
 cindex(aliases, listing)
-item(tt(alias) [ {tt(PLUS()|tt(-))}tt(gmrsL) ] [ var(name)[tt(=)var(value)] ... ])(
+item(tt(alias) [ {tt(PLUS())|tt(-)}tt(gmrsL) ] [ var(name)[tt(=)var(value)] ... ])(
 For each var(name) with a corresponding var(value), define an alias
 with that value.  A trailing space in var(value) causes the next word
 to be checked for alias expansion.  If the tt(-g) flag is present,
@@ -135,8 +136,8 @@ alias in a manner suitable for putting in a startup script.  The exit
 status is nonzero if a var(name) (with no var(value)) is given for
 which no alias has been defined.
 
-For more on aliases, include common problems,
-ifzman(see the section ALIASING in zmanref(zshmisc))\
+For more on aliases, include common problems, see
+ifzman(the section ALIASING in zmanref(zshmisc))\
 ifnzman(noderef(Aliasing)).
 )
 findex(autoload)
@@ -273,7 +274,8 @@ searched instead of that in tt($path). With the tt(-v) flag, tt(command)
 is similar to tt(whence) and with tt(-V), it is equivalent to tt(whence
 -v).
 
-See also noderef(Precommand Modifiers).
+See also ifzman(the section `Precommand Modifiers' in zmanref(zshmisc))\
+ifnzman(noderef(Precommand Modifiers)).
 )
 module(comparguments)(zsh/computil)
 module(compcall)(zsh/compctl)
@@ -353,7 +355,7 @@ setting here.  For example, if tt(EXTENDED_GLOB) is not active,
 the pattern tt(^) is ineffective even if `tt(disable -p "^")' has
 not been issued.  The list below indicates any option settings
 that restrict the use of the pattern.  It should be noted that
-setting tt(SH_GLOB) has a wider effect then merely disabling patterns
+setting tt(SH_GLOB) has a wider effect than merely disabling patterns
 as certain expressions, in particular those involving parentheses,
 are parsed differently.
 
@@ -361,6 +363,7 @@ The following patterns may be disabled; all
 the strings need quoting on the command line to prevent them from
 being interpreted immediately as patterns and the patterns are
 shown below in single quotes as a reminder.
+
 startitem()
 item(tt('?'))(
 The pattern character tt(?) wherever it occurs, including when preceding
@@ -370,7 +373,7 @@ item(tt('*'))(
 The pattern character tt(*) wherever it occurs, including recursive
 globbing and when preceding a parenthesis with tt(KSH_GLOB).
 )
-item('LSQUARE()')(
+item(tt('LSQUARE()'))(
 Character classes.
 )
 item(tt('<') (tt(NO_SH_GLOB)))(
@@ -615,12 +618,14 @@ the same as if the commands had been executed directly by the shell;
 if there are no var(args) or they contain no commands (i.e. are
 an empty string or whitespace) the return status is zero.
 )
-item(tt(exec) [ tt(-cl) ] [ tt(-a) var(argv0) ] [ var(command) [ var(arg) ... ]])(
+item(tt(exec) [ tt(-cl) ] [ tt(-a) var(argv0) ] [ var(command) [ var(arg) ... ] ])(
 Replace the current shell with an external var(command) rather than forking.
 With tt(-c) clear the environment; with tt(-l) prepend tt(-) to the
 tt(argv[0]) string of the command executed (to simulate a login shell);
 with tt(-a) var(argv0) set the tt(argv[0]) string of the command
-executed.  See noderef(Precommand Modifiers).
+executed.
+See ifzman(the section `Precommand Modifiers' in zmanref(zshmisc))\
+ifnzman(noderef(Precommand Modifiers)).
 
 cindex(redirection, current shell's I/O)
 If var(command) is omitted but any redirections are specified,
@@ -775,13 +780,13 @@ Bring each specified var(job) in turn to the foreground.
 If no var(job) is specified, resume the current job.
 )
 findex(float)
-item(tt(float) [ {tt(PLUS())|tt(-)}tt(EFHghlprtux) ] [ tt(-LRZ) [ var(n) ]] \
-[ var(name)[tt(=)var(value)] ... ])(
+item(tt(float) [ {tt(PLUS())|tt(-)}tt(Hghlprtux) ] \
+[ {tt(PLUS())|tt(-)}tt(EFLRZ) [ var(n) ] ] [ var(name)[tt(=)var(value)] ... ])(
 Equivalent to tt(typeset -E), except that options irrelevant to floating
 point numbers are not permitted.
 )
 findex(functions)
-xitem(tt(functions) [ {tt(PLUS())|tt(-)}tt(UXkmtTuz) ] [ var(name) ... ])
+xitem(tt(functions) [ {tt(PLUS())|tt(-)}tt(UkmtTuz) ] [ var(name) ... ])
 xitem(tt(functions -M) var(mathfn) [ var(min) [ var(max) [ var(shellfn) ] ] ])
 xitem(tt(functions -M) [ tt(-m) var(pattern) ... ])
 item(tt(functions +M) [ tt(-m) ] var(mathfn) ... )(
@@ -834,7 +839,7 @@ cindex(line, reading)
 cindex(reading a line)
 item(tt(getln) [ tt(-AclneE) ] var(name) ...)(
 Read the top value from the buffer stack and put it in
-the shell parameter tt(name).  Equivalent to
+the shell parameter var(name).  Equivalent to
 tt(read -zr).
 )
 findex(getopts)
@@ -922,8 +927,8 @@ the form of a call to hash.
 )
 alias(history)(fc -l)
 findex(integer)
-item(tt(integer) [ {tt(PLUS())|tt(-)}tt(Hghilprtux) ] \
-[ tt(-LRZ) [ var(n) ]] [ var(name)[tt(=)var(value)] ... ])(
+item(tt(integer) [ {tt(PLUS())|tt(-)}tt(Hghlprtux) ] \
+[ {tt(PLUS())|tt(-)}tt(LRZi) [ var(n) ] ] [ var(name)[tt(=)var(value)] ... ])(
 Equivalent to tt(typeset -i), except that options irrelevant to
 integers are not permitted.
 )
@@ -1058,8 +1063,8 @@ shell starts in a mode emulating another shell.  It can be made available
 with the command `tt(zmodload -F zsh/rlimits b:limit)'.
 )
 findex(local)
-item(tt(local) [ {tt(PLUS())|tt(-)}tt(AEFHUahlprtux) ] \
-[ tt(-LRZi) [ var(n) ]] [ var(name)[tt(=)var(value)] ] ...)(
+item(tt(local) [ {tt(PLUS())|tt(-)}tt(AHUahlprtux) ] \
+[ {tt(PLUS())|tt(-)}tt(EFLRZi) [ var(n) ] ] [ var(name)[tt(=)var(value)] ... ])(
 Same as tt(typeset), except that the options tt(-g), and
 tt(-f) are not permitted.  In this case the tt(-x) option does not force
 the use of tt(-g), i.e. exported variables will be local to functions.
@@ -1078,12 +1083,12 @@ Same as tt(exit), except that it only works in a login shell.
 )
 prefix(noglob)
 findex(popd)
-item(tt(popd) [ [-q] {tt(PLUS())|tt(-)}var(n) ])(
+item(tt(popd) [ tt(-q) ] [ {tt(PLUS())|tt(-)}var(n) ])(
 Remove an entry from the directory stack, and perform a tt(cd) to
 the new top directory.  With no argument, the current top entry is
 removed.  An argument of the form `tt(PLUS())var(n)' identifies a stack
 entry by counting from the left of the list shown by the tt(dirs) command,
-starting with zero.  An argument of the form tt(-n) counts from the right.
+starting with zero.  An argument of the form tt(-)var(n) counts from the right.
 pindex(PUSHD_MINUS, use of)
 If the tt(PUSHD_MINUS) option is set, the meanings of `tt(PLUS())' and
 `tt(-)' in this context are swapped.
@@ -1117,7 +1122,7 @@ tt(-c) and tt(-C) options.
 item(tt(-b))(
 Recognize all the escape sequences defined for the tt(bindkey) command,
 see 
-ifzman(zmanref(zshzle))\
+ifzman(the section `Zle Builtins' in zmanref(zshzle))\
 ifnzman(noderef(Zle Builtins))\
 .
 )
@@ -1204,13 +1209,13 @@ item(tt(printf) var(format) [ var(arg) ... ])(
 Print the arguments according to the format specification. Formatting
 rules are the same as used in C. The same escape sequences as for tt(echo)
 are recognised in the format. All C conversion specifications ending in
-one of csdiouxXeEfgGn are handled. In addition to this, `tt(%b)' can be
+one of tt(csdiouxXeEfgGn) are handled. In addition to this, `tt(%b)' can be
 used instead of `tt(%s)' to cause escape sequences in the argument to be
 recognised and `tt(%q)' can be used to quote the argument in such a way
 that allows it to be reused as shell input. With the numeric format
 specifiers, if the corresponding argument starts with a quote character,
 the numeric value of the following character is used as the number to
-print otherwise the argument is evaluated as an arithmetic expression. See
+print; otherwise the argument is evaluated as an arithmetic expression. See
 ifzman(the section `Arithmetic Evaluation' in zmanref(zshmisc))\
 ifnzman(noderef(Arithmetic Evaluation))
 for a description of arithmetic
@@ -1487,7 +1492,7 @@ module(setcap)(zsh/cap)
 findex(setopt)
 cindex(options, setting)
 item(tt(setopt) [ {tt(PLUS())|tt(-)}var(options) | \
-{tt(PLUS())|tt(-)}tt(o) var(option_name) ] [ var(name) ... ])(
+{tt(PLUS())|tt(-)}tt(o) var(option_name) ] [ tt(-m) ] [ var(name) ... ])(
 Set the options for the shell.  All options specified either
 with flags or by name are set.
 
@@ -1653,7 +1658,7 @@ Do nothing and return an exit status of 0.
 )
 findex(ttyctl)
 cindex(tty, freezing)
-item(tt(ttyctl) tt(-fu))(
+item(tt(ttyctl) [ tt(-fu) ])(
 The tt(-f) option freezes the tty (i.e. terminal or terminal emulator), and
 tt(-u) unfreezes it.
 When the tty is frozen, no changes made to the tty settings by
@@ -1682,12 +1687,12 @@ Equivalent to tt(whence -v).
 findex(typeset)
 cindex(parameters, setting)
 cindex(parameters, declaring)
-xitem(tt(typeset) [ {tt(PLUS())|tt(-)}tt(AEFHUafghklprtuxmz) ] [ tt(-LRZi) \
-[ var(n) ]] [ \
-var(name)[tt(=)var(value)] ... ])
-item(tt(typeset) -T [ {tt(PLUS()|tt(-))}tt(Urux) ] \
- [ tt(-LRZ) [ var(n) ]] \
- var(SCALAR)[tt(=)var(value)] var(array) tt([) var(sep) tt(]))(
+xitem(tt(typeset) [ {tt(PLUS())|tt(-)}tt(AHUaghlmprtux) ] \
+[ {tt(PLUS())|tt(-)}tt(EFLRZi) [ var(n) ] ])
+xitem(        [ tt(+) | var(name)[tt(=)var(value)] ... ])
+xitem(tt(typeset) tt(-T) [ {tt(PLUS())|tt(-)}tt(Uglprux) ] [ {tt(PLUS())|tt(-)}tt(LRZ) [ var(n) ] ])
+xitem(           [ tt(+) | var(SCALAR)[tt(=)var(value)] var(array) [ var(sep) ] ])
+item(tt(typeset) tt(-f) [ {tt(PLUS())|tt(-)}tt(TUkmtuz) ] [ tt(+) | var(name) ... ])(
 Set or display attributes and values for shell parameters.
 
 A parameter is created for each var(name) that does not already refer
@@ -1811,7 +1816,7 @@ as before but the separator is changed.
 enditem()
 
 Attribute flags that transform the final value (tt(-L), tt(-R), tt(-Z),
-tt(-l), tt(u)) are only applied to the expanded value at the point
+tt(-l), tt(-u)) are only applied to the expanded value at the point
 of a parameter expansion expression using `tt($)'.  They are not applied
 when a parameter is retrieved internally by the shell for any purpose. 
 
@@ -1824,8 +1829,9 @@ ifzman(`Array Parameters' in zmanref(zshparam))\
 ifnzman(noderef(Array Parameters))\
 .
 )
-item(tt(-L))(
-Left justify and remove leading blanks from var(value).
+item(tt(-L) [ var(n) ])(
+Left justify and remove leading blanks from the value when the parameter
+is expanded.
 If var(n) is nonzero, it defines the width of the field.
 If var(n) is zero, the width is determined by the width of the value of
 the first assignment.  In the case of numeric parameters, the length of the
@@ -1845,7 +1851,7 @@ blanks or truncated if necessary to fit the field.
 Note truncation can lead to unexpected results with numeric parameters.
 Leading zeros are removed if the tt(-Z) flag is also set.
 )
-item(tt(-R))(
+item(tt(-R) [ var(n) ])(
 Similar to tt(-L), except that right justification is used;
 when the parameter is expanded, the field is left filled with
 blanks or truncated from the end.  May not be combined with the tt(-Z)
@@ -1857,7 +1863,7 @@ occurrence of each duplicated value.  This may also be set for
 colon-separated special parameters like tt(PATH) or tt(FIGNORE), etc.
 This flag has a different meaning when used with tt(-f); see below.
 )
-item(tt(-Z))(
+item(tt(-Z) [ var(n) ])(
 Specially handled if set along with the tt(-L) flag.
 Otherwise, similar to tt(-R), except that leading zeros are used for
 padding instead of blanks if the first non-blank character is a digit.
@@ -1884,7 +1890,7 @@ parameter will be searched to find the function definition when the
 function is first referenced; see noderef(Functions). The tt(-k) and
 tt(-z) flags make the function be loaded using ksh-style or zsh-style
 autoloading respectively. If neither is given, the setting of the
-KSH_AUTOLOAD option determines how the function is loaded.
+tt(KSH_AUTOLOAD) option determines how the function is loaded.
 )
 item(tt(-h))(
 Hide: only useful for special parameters (those marked `<S>' in the table in
@@ -1914,18 +1920,18 @@ default for the parameters in the tt(zsh/parameter) and tt(zsh/mapfile)
 modules.  Note, however, that unlike the tt(-h) flag this is also useful
 for non-special parameters.
 )
-item(tt(-i))(
+item(tt(-i) [ var(n) ])(
 Use an internal integer representation.  If var(n) is nonzero it
 defines the output arithmetic base, otherwise it is determined by the
 first assignment.  Bases from 2 to 36 inclusive are allowed.
 )
-item(tt(-E))(
+item(tt(-E) [ var(n) ])(
 Use an internal double-precision floating point representation.  On output
 the variable will be converted to scientific notation.  If var(n) is
 nonzero it defines the number of significant figures to display; the
 default is ten.
 )
-item(tt(-F))(
+item(tt(-F) [ var(n) ])(
 Use an internal double-precision floating point representation.  On output
 the variable will be converted to fixed-point decimal notation.  If var(n)
 is nonzero it defines the number of digits to display after the decimal
@@ -1968,7 +1974,7 @@ enditem()
 findex(ulimit)
 cindex(resource limits)
 cindex(limits, resource)
-item(tt(ulimit) [ [ tt(-SHacdfiklmnpqsTtvwx) | tt(-N) var(resource) [ var(limit) ] ... ])(
+item(tt(ulimit) [ tt(-HSa) ] [ { tt(-bcdfiklmnpqrsTtvwx) | tt(-N) var(resource) } [ var(limit) ] ... ])(
 Set or display resource limits of the shell and the processes started by
 the shell.  The value of var(limit) can be a number in the unit specified
 below or one of the values `tt(unlimited)', which removes the limit on the
@@ -2132,7 +2138,7 @@ to process IDs.
 )
 findex(whence)
 item(tt(whence) [ tt(-vcwfpamsS) ] var(name) ...)(
-For each name, indicate how it would be interpreted if used as a
+For each var(name), indicate how it would be interpreted if used as a
 command name.
 
 tt(whence) is most useful when var(name) is only the last path component
@@ -2334,7 +2340,7 @@ findex(zmodload)
 cindex(modules, loading)
 cindex(loading modules)
 xitem(tt(zmodload) [ tt(-dL) ] [ ... ])
-xitem(tt(zmodload -F) [ tt(-lLme) tt(-P) tt(param) ] var(module) [tt(PLUS()-)]var(feature...))
+xitem(tt(zmodload -F) [ tt(-alLme) tt(-P) var(param) ] var(module) [ [tt(PLUS()-)]var(feature) ... ])
 xitem(tt(zmodload -e) [ tt(-A) ] [ ... ])
 xitem(tt(zmodload) [ tt(-a) [ tt(-bcpf) [ tt(-I) ] ] ] [ tt(-iL) ] ...)
 xitem(tt(zmodload) tt(-u) [ tt(-abcdpf) [ tt(-I) ] ] [ tt(-iL) ] ...)
@@ -2385,7 +2391,7 @@ Each module has a boot and a cleanup function.  The module
 will not be loaded if its boot function fails.  Similarly a module
 can only be unloaded if its cleanup function runs successfully.
 )
-item(tt(zmodload -F) [ tt(-almLe) tt(-P) tt(param) ] var(module) [tt(PLUS()-)]var(feature...))(
+item(tt(zmodload -F) [ tt(-almLe) tt(-P) var(param) ] var(module) [ [tt(PLUS()-)]var(feature) ... ])(
 tt(zmodload -F) allows more selective control over the features provided
 by modules.  With no options apart from tt(-F), the module named
 var(module) is loaded, if it was not already loaded, and the list of
@@ -2416,7 +2422,7 @@ feature per line.  With tt(-L) alone, a tt(zmodload -F) command that would
 cause enabled features of the module to be turned on is shown.  With
 tt(-lL), a tt(zmodload -F) command that would cause all the features to be
 set to their current state is shown.  If one of these combinations is given
-the option tt(-P) var(param) then the parameter tt(param) is set to an
+with the option tt(-P) var(param) then the parameter var(param) is set to an
 array of features, either features together with their state or (if
 tt(-L) alone is given) enabled features.