35075: improve manual format

also fixed a ChangeLog entry for 35034 (2015-05-06)

25 files changed, 420 insertions, 375 deletions

diff --git a/ChangeLog b/ChangeLog
index 5222027c2..ef2a6575e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2015-05-12  Jun-ichi Takimoto <takimoto-j@kba.biglobe.ne.jp>
+
+	* 35075: Doc/Zsh/builtins.yo, Doc/Zsh/calsys.yo,
+	Doc/Zsh/compctl.yo, Doc/Zsh/compsys.yo, Doc/Zsh/compwid.yo,
+	Doc/Zsh/contrib.yo, Doc/Zsh/expn.yo, Doc/Zsh/mod_clone.yo,
+	Doc/Zsh/mod_complist.yo, Doc/Zsh/mod_curses.yo,
+	Doc/Zsh/mod_parameter.yo, Doc/Zsh/mod_pcre.yo,
+	Doc/Zsh/mod_sched.yo, Doc/Zsh/mod_stat.yo, Doc/Zsh/mod_system.yo,
+	Doc/Zsh/mod_zftp.yo, Doc/Zsh/mod_zpty.yo, Doc/Zsh/mod_zselect.yo,
+	Doc/Zsh/mod_zutil.yo, Doc/Zsh/options.yo, Doc/Zsh/params.yo,
+	Doc/Zsh/tcpsys.yo, Doc/Zsh/zftpsys.yo, Doc/Zsh/zle.yo: improve
+	manual format
+
+	* unposted: ChangeLog: fixed entry for 35034 (2015-05-06)
+
 2015-05-11  Oliver Kiddle  <opk@zsh.org>
 
 	* 35049 (tweaked to make jname default): Completion/BSD/Type/_jails,
@@ -67,7 +82,10 @@
 
 2015-05-06  Jun-ichi Takimoto <takimoto-j@kba.biglobe.ne.jp>
 
-	* 35034: improve format in the manual (up to Chapter18)
+	* 35034: Doc/Zsh/arith.yo, Doc/Zsh/builtins.yo, Doc/Zsh/cond.yo,
+	Doc/Zsh/expn.yo, Doc/Zsh/grammar.yo, Doc/Zsh/options.yo,
+	Doc/Zsh/params.yo, Doc/Zsh/redirect.yo, Doc/Zsh/zle.yo: improve
+	format in the manual (up to Chapter18)
 
 2015-05-05  Peter Stephenson  <p.w.stephenson@ntlworld.com>
 
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 9699cf392..5327789cd 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -661,10 +661,11 @@ Do nothing and return an exit status of 1.
 findex(fc)
 cindex(history, editing)
 cindex(editing history)
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ ))ifnztexi(      )))
 xitem(tt(fc) [ tt(-e) var(ename) ] [ tt(-m) var(match) ] [ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ])
-xitem(tt(fc) tt(-l) [ tt(-nrdfEiD) ] [ tt(-t) var(timefmt) ] [ tt(-m) var(match) ])
-xitem(tt(      )[ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ])
-xitem(tt(fc) tt(-p) [ tt(-a) ] [ var(filename) [ var(histsize) [ var(savehistsize) ] ] ])
+xitem(tt(fc -l )[ tt(-nrdfEiD) ] [ tt(-t) var(timefmt) ] [ tt(-m) var(match) ])
+xitem(SPACES()[ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ])
+xitem(tt(fc -p )[ tt(-a) ] [ var(filename) [ var(histsize) [ var(savehistsize) ] ] ])
 xitem(tt(fc) tt(-P))
 item(tt(fc) tt(-ARWI) [ var(filename) ])(
 The tt(fc) command controls the interactive history mechanism.  Note
@@ -1099,8 +1100,8 @@ and the new directory stack is not printed.  This is useful for calls to
 tt(popd) that do not change the environment seen by an interactive user.
 )
 findex(print)
-xitem(tt(print) [ tt(-abcDilmnNoOpPrsSz) ] [ tt(-u) var(n) ] [ tt(-f) var(format) ] [ tt(-C) var(cols) ])
-item(  [ tt(-R) [ tt(-en) ]] [ var(arg) ... ])(
+xitem(tt(print )[ tt(-abcDilmnNoOpPrsSz) ] [ tt(-u) var(n) ] [ tt(-f) var(format) ] [ tt(-C) var(cols) ])
+item(SPACES()[ tt(-R) [ tt(-en) ]] [ var(arg) ... ])(
 With the `tt(-f)' option the arguments are printed as described by tt(printf).
 With no flags or with the flag `tt(-)', the arguments are printed on
 the standard output as described by tt(echo), with the following differences:
@@ -1288,8 +1289,9 @@ contain symbolic links.
 alias(r)(fc -e -)
 findex(read)
 vindex(IFS, use of)
-ifzman(xitem(tt(read) [ tt(-rszpqAclneE) ] [ tt(-t) [ var(num) ] ] [ tt(-k) [ var(num) ] ] [ tt(-d) var(delim) ]))
-item(ifnzman(tt(read) [ tt(-rszpqAclneE) ] [ tt(-t) [ var(num) ] ] [ tt(-k) [ var(num) ] ] [ tt(-d) var(delim) ]) [ tt(-u) var(n) ] [ var(name)[tt(?)var(prompt)] ] [ var(name) ...  ])(
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ ))ifnztexi(     )))
+xitem(tt(read )[ tt(-rszpqAclneE) ] [ tt(-t) [ var(num) ] ] [ tt(-k) [ var(num) ] ] [ tt(-d) var(delim) ])
+item(SPACES()[ tt(-u) var(n) ] [ var(name)[tt(?)var(prompt)] ] [ var(name) ...  ])(
 vindex(REPLY, use of)
 vindex(reply, use of)
 Read one line and break it into fields using the characters
@@ -1441,7 +1443,9 @@ cindex(parameters, positional)
 cindex(parameters, setting array)
 cindex(array parameters, setting)
 pindex(KSH_ARRAYS, use of)
-item(tt(set) [ {tt(PLUS())|tt(-)}var(options) | {tt(PLUS())|tt(-)}tt(o) [ var(option_name) ] ] ... [ {tt(PLUS())|tt(-)}tt(A) [ var(name) ] ] [ var(arg) ... ])(
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ ))ifnztexi(    )))
+xitem(tt(set )[ {tt(PLUS())|tt(-)}var(options) | {tt(PLUS())|tt(-)}tt(o) [ var(option_name) ] ] ... [ {tt(PLUS())|tt(-)}tt(A) [ var(name) ] ])
+item(SPACES()[ var(arg) ... ])(
 Set the options for the shell and/or set the positional parameters, or
 declare and set an array.  If the tt(-s) option is given, it causes the
 specified arguments to be sorted before assigning them to the positional
@@ -1687,11 +1691,12 @@ Equivalent to tt(whence -v).
 findex(typeset)
 cindex(parameters, setting)
 cindex(parameters, declaring)
-xitem(tt(typeset) [ {tt(PLUS())|tt(-)}tt(AHUaghlmprtux) ] \
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ ))ifnztexi(        )))
+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) ] ])
+xitem(SPACES()[ tt(+) | var(name)[tt(=)var(value)] ... ])
+xitem(tt(typeset )tt(-T) [ {tt(PLUS())|tt(-)}tt(Uglprux) ] [ {tt(PLUS())|tt(-)}tt(LRZ) [ var(n) ] ])
+xitem(SPACES()[ 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.
 
diff --git a/Doc/Zsh/calsys.yo b/Doc/Zsh/calsys.yo
index 6b5fe27fb..c20c87e61 100644
--- a/Doc/Zsh/calsys.yo
+++ b/Doc/Zsh/calsys.yo
@@ -272,7 +272,7 @@ When an anchor time is present, there is an extension to handle regular
 events in the form of the var(n)th var(some)day of the month.  Such a
 specification must occur immediately after any year and month
 specification, but before any time of day, and must be in the form
-var(n)tt(LPAR()th|st|rd+RPAR()) var(day), for example tt(1st Tuesday) or
+var(n)(tt(th)|tt(st)|tt(rd)) var(day), for example tt(1st Tuesday) or
 tt(3rd Monday).  As in other places, days are matched case insensitively,
 must be in English, and only the first three letters are significant except
 that a form beginning `month' does not match `Monday'.  No attempt is made
@@ -320,8 +320,11 @@ subsect(Calendar system functions)
 
 startitem()
 findex(calendar)
-xitem(tt(calendar) [ tt(-abdDsv) ] [ tt(-C) var(calfile) ] [ -n var(num) ] [ tt(-S) var(showprog) ] [ [ var(start) ] var(end) ])(
-item(tt(calendar -r) [ tt(-abdDrsv) ] [ tt(-C) var(calfile) ] [ -n var(num) ] [ tt(-S) var(showprog) ] [ var(start) ])(
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ ))ifnztexi(         )))
+xitem(tt(calendar )[ tt(-abdDsv) ] [ tt(-C) var(calfile) ] [ tt(-n) var(num) ] [ tt(-S) var(showprog) ])
+xitem(SPACES()[ [ var(start) ] var(end) ])
+xitem(tt(calendar -r) [ tt(-abdDrsv) ] [ tt(-C) var(calfile) ] [ tt(-n) var(num) ] [ tt(-S) var(showprog) ])
+item(SPACES()[ var(start) ])(
 Show events in the calendar.
 
 With no arguments, show events from the start of today until the end of
@@ -379,9 +382,9 @@ Show at least var(num) events, if present in the calendar file, regardless
 of the tt(start) and tt(end).
 )
 item(tt(-r))(
-Show all the remaining options in the calendar, ignoring the given tt(end)
-time.  The tt(start) time is respected; any argument given is treated
-as a tt(start) time.
+Show all the remaining options in the calendar, ignoring the given var(end)
+time.  The var(start) time is respected; any argument given is treated
+as a var(start) time.
 )
 item(tt(-s))(
 Use the shell's tt(sched) command to schedule a timed event that
@@ -471,7 +474,7 @@ the dates in the calendar file.
 enditem()
 )
 findex(calendar_add)
-item(tt(calendar_add) [ tt(-BL) ] var(event ...))(
+item(tt(calendar_add) [ tt(-BL) ] var(event) ...)(
 Adds a single event to the calendar in the appropriate location.
 The event can contain multiple lines, as described in
 ifnzman(noderef(Calendar File and Date Formats))\
@@ -578,7 +581,7 @@ keywords and values.)
 endsitem()
 
 findex(calendar_showdate)
-item(tt(calendar_showdate) [ tt(-r) ] [ tt(-f) var(fmt) ] var(date-spec ...))(
+item(tt(calendar_showdate) [ tt(-r) ] [ tt(-f) var(fmt) ] var(date-spec) ...)(
 The given var(date-spec) is interpreted and the corresponding date and
 time printed.  If the initial var(date-spec) begins with a tt(PLUS()) or
 tt(-) it is treated as relative to the current time; var(date-spec)s after
diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo
index fa13a747e..d06b31d25 100644
--- a/Doc/Zsh/compctl.yo
+++ b/Doc/Zsh/compctl.yo
@@ -23,11 +23,12 @@ the older tt(compctl) command.
 sect(Description)
 findex(compctl)
 )\
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ ))ifnztexi(        )))
 startlist()
 list(tt(compctl) [ tt(-CDT) ] var(options) [ var(command) ... ])
-list(tt(compctl) [ tt(-CDT) ] var(options) \
-  [ tt(-x) var(pattern) var(options) tt(-) ... tt(-)tt(-) ] \
-  [ tt(PLUS()) var(options) [ tt(-x) ... tt(-)tt(-) ] ... [tt(PLUS())] ] \
+list(tt(compctl )[ tt(-CDT) ] var(options) \
+  [ tt(-x) var(pattern) var(options) tt(-) ... tt(-)tt(-) ])
+list(SPACES()[ tt(PLUS()) var(options) [ tt(-x) ... tt(-)tt(-) ] ... [tt(PLUS())] ] \
   [ var(command) ... ])
 list(tt(compctl) tt(-M) var(match-specs) ...)
 list(tt(compctl) tt(-L) [ tt(-CDTM) ] [ var(command) ... ])
@@ -109,7 +110,8 @@ that completion after `tt(~)' is too slow to be usable), you can use
 example(compctl -T -x 's[~] C[0,[^/]#]' -k friends -S/ -tn)
 
 to complete the strings in the array tt(friends) after a `tt(~)'.
-The tt(C[...]) argument is necessary so that this form of ~-completion is
+The tt(C[)var(...)tt(]) argument is necessary so that this form of
+tt(~)-completion is
 not tried after the directory name is finished.
 )
 item(tt(-L))(
@@ -470,7 +472,7 @@ string.
 
 The sequences tt(%B), tt(%b), tt(%S), tt(%s), tt(%U), and tt(%u) specify
 output attributes (bold, standout, and underline), tt(%F), tt(%f), tt(%K),
-tt(%k) specify foreground and background colours, and tt(%{...%}) can
+tt(%k) specify foreground and background colours, and tt(%{)var(...)tt(%}) can
 be used to include literal escape sequences as in prompts.
 )
 item(tt(-Y) var(explanation))(
@@ -504,7 +506,7 @@ This gives the name of the group the matches should be placed in. Groups
 are listed and sorted separately; likewise, menu completion will offer
 the matches in the groups in the order in which the groups were
 defined. If no group name is explicitly given, the matches are stored in
-a group named var(default). The first time a group name is encountered,
+a group named tt(default). The first time a group name is encountered,
 a group with that name is created. After that all matches with the same
 group name are stored in that group.
 
@@ -565,13 +567,14 @@ Additional options are available that restrict completion to some part
 of the command line; this is referred to as `extended completion'.
 
 sect(Extended Completion)
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ ))ifnztexi(        )))
 startlist()
-list(tt(compctl) [ tt(-CDT) ] var(options) \
+list(tt(compctl )[ tt(-CDT) ] var(options) \
 tt(-x) var(pattern) var(options) tt(-) ... tt(-)tt(-))
-list(         [ var(command) ... ])
-list(tt(compctl) [ tt(-CDT) ] var(options) \
+list(SPACES()[ var(command) ... ])
+list(tt(compctl )[ tt(-CDT) ] var(options) \
 [ tt(-x) var(pattern) var(options) tt(-) ... tt(-)tt(-) ])
-list(         [ tt(PLUS()) var(options) [ tt(-x) ... tt(-)tt(-) ] ... \
+list(SPACES()[ tt(PLUS()) var(options) [ tt(-x) ... tt(-)tt(-) ] ... \
 [tt(PLUS())] ] [ var(command) ... ])
 endlist()
 
@@ -677,7 +680,7 @@ enditem()
 texinode(Example)()(Extended Completion)(Completion Using compctl)
 sect(Example)
 
-example(compctl -u -x 's[tt(PLUS())] c[-1,-f],s[-f+PLUS()]' \ 
+example(compctl -u -x 's[PLUS()] c[-1,-f],s[-f+PLUS()]' \ 
   -g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail)
 
 This is to be interpreted as follows:
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index b699502ca..a081ea32c 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -224,7 +224,7 @@ will try to find more by adding the directory tt(_compdir) to the search
 path.  If that directory has a subdirectory named tt(Base), all
 subdirectories will be added to the path.  Furthermore, if the subdirectory
 tt(Base) has a subdirectory named tt(Core), tt(compinit) will add all
-subdirectories of the subdirectories is to the path: this allows
+subdirectories of the subdirectories to the path: this allows
 the functions to be in the same format as in the tt(zsh) source
 distribution.
 
@@ -238,9 +238,9 @@ completion system and will not be treated specially.
 The tags are:
 
 startitem()
-item(tt(#compdef) var(names...) [ tt(-[pP]) var(patterns...) [ tt(-N) var(names...) ] ])(
+item(tt(#compdef) var(name) ... [ tt(-){tt(p)|tt(P)} var(pattern) ... [ tt(-N) var(name) ... ] ])(
 The file will be made autoloadable and the function defined 
-in it will be called when completing var(names), each of which is
+in it will be called when completing var(name)s, each of which is
 either the name of a command whose arguments are to be completed or one of
 a number of special contexts in the form tt(-)var(context)tt(-) described
 below.
@@ -265,9 +265,9 @@ The option tt(-N) is used after a list following tt(-p) or tt(-P); it
 specifies that remaining words no longer define patterns.  It is
 possible to toggle between the three options as many times as necessary.
 )
-item(tt(#compdef -k) var(style key-sequences...))(
+item(tt(#compdef -k) var(style key-sequence) ...)(
 This option creates a widget behaving like the
-builtin widget var(style) and binds it to the given var(key-sequences),
+builtin widget var(style) and binds it to the given var(key-sequence)s,
 if any.  The var(style) must be one of the builtin widgets that perform
 completion, namely tt(complete-word), tt(delete-char-or-list),
 tt(expand-or-complete), tt(expand-or-complete-prefix), tt(list-choices),
@@ -277,14 +277,14 @@ ifzman(zmanref(zshmodules))\
 ifnzman(noderef(The zsh/complist Module))\
 ) the widget tt(menu-select) is also available.
 
-When one of the var(key-sequences) is typed, the function in the file will
+When one of the var(key-sequence)s is typed, the function in the file will
 be invoked to generate the matches.  Note that a key will not be re-bound
 if it already was (that is, was bound to something other than
 tt(undefined-key)).  The widget created has the same name as the file and
 can be bound to any other keys using tt(bindkey) as usual.
 )
-item(tt(#compdef -K) var(widget-name) var(style) var(key-sequences) ...)(
-This is similar to tt(-k) except that only one var(key-sequences)
+item(tt(#compdef -K) var(widget-name) var(style) var(key-sequence) [ var(name) var(style) var(seq) ... ])(
+This is similar to tt(-k) except that only one var(key-sequence)
 argument may be given for each var(widget-name) var(style) pair.
 However, the entire set of three arguments may be repeated with a
 different set of arguments.  Note in particular that the
@@ -319,11 +319,11 @@ startitem()
 kindex(-array-value-, completion context)
 item(tt(-array-value-))(
 The right hand side of an array-assignment
-(`tt(foo=LPAR()...RPAR())')
+(`var(name)tt(=LPAR())var(...)tt(RPAR())')
 )
 kindex(-brace-parameter-, completion context)
 item(tt(-brace-parameter-))(
-The name of a parameter expansion within braces (`tt(${...})')
+The name of a parameter expansion within braces (`tt(${)var(...)tt(})')
 )
 kindex(-assign-parameter-, completion context)
 item(tt(-assign-parameter-))(
@@ -336,7 +336,7 @@ A word in command position
 )
 kindex(-condition-, completion context)
 item(tt(-condition-))(
-A word inside a condition (`tt([[...]])')
+A word inside a condition (`tt([[)var(...)tt(]])')
 )
 kindex(-default-, completion context)
 item(tt(-default-))(
@@ -359,11 +359,11 @@ functions defined for commands will be.
 kindex(-math-, completion context)
 item(tt(-math-))(
 Inside mathematical contexts, such as
-`tt(LPAR()LPAR())...tt(RPAR()RPAR())'
+`tt(LPAR()LPAR())var(...)tt(RPAR()RPAR())'
 )
 kindex(-parameter-, completion context)
 item(tt(-parameter-))(
-The name of a parameter expansion (`tt($...)')
+The name of a parameter expansion (`tt($)var(...)')
 )
 kindex(-redirect-, completion context)
 item(tt(-redirect-))(
@@ -402,7 +402,8 @@ field will be empty.
 
 For the tt(-value-) context, the form is
 `tt(-value-,)var(name)tt(,)var(command)', where var(name) is the name of
-the parameter.  In the case of elements of an associative array, for
+the parameter on the left hand side of the assignment.
+In the case of elements of an associative array, for
 example `tt(assoc=LPAR()key <TAB>)', var(name) is expanded to
 `var(name)tt(-)var(key)'.  In certain special contexts, such as
 completing after `tt(make CFLAGS=)', the var(command) part gives the
@@ -447,10 +448,11 @@ directly.
 findex(compdef)
 cindex(completion system, adding definitions)
 startitem()
-xitem(tt(compdef) [ tt(-ane) ] var(function names...) [ tt(-[pP]) var(patterns...) [ tt(-N) var(names...) ] ])
-xitem(tt(compdef -d) var(names...))
-xitem(tt(compdef -k) [ tt(-an) ] var(function style key-sequences...))
-item(tt(compdef -K) [ tt(-an) ] var(function name style key-sequences ...))(
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ ))ifnztexi(      )))
+xitem(tt(compdef) [ tt(-ane) ] var(function name) ... [ tt(-){tt(p)|tt(P)} var(pattern) ... [ tt(-N) var(name) ...]])
+xitem(tt(compdef -d) var(name) ...)
+xitem(tt(compdef -k) [ tt(-an) ] var(function style key-sequence) [ var(key-sequence) ... ])
+item(tt(compdef -K) [ tt(-an) ] var(function name style key-seq) [ var(name style seq) ... ])(
 The first form defines the var(function) to call for completion in the
 given contexts as described for the tt(#compdef) tag above.
 
@@ -477,7 +479,7 @@ command or context from being overwritten.
 The option tt(-d) deletes any completion defined for the command or
 contexts listed.
 
-The var(names) may also contain tt(-p), tt(-P) and tt(-N) options as
+The var(name)s may also contain tt(-p), tt(-P) and tt(-N) options as
 described for the tt(#compdef) tag.  The effect on the argument list is
 identical, switching between definitions of patterns tried initially,
 patterns tried finally, and normal commands and contexts.
@@ -489,7 +491,7 @@ set to a value containing the substring `tt(all)', no other function
 will be called.
 
 The form with tt(-k) defines a widget with the same name as the var(function)
-that will be called for each of the var(key-sequences); this is like the
+that will be called for each of the var(key-sequence)s; this is like the
 tt(#compdef -k) tag.  The function should generate the completions needed
 and will otherwise behave like the builtin widget whose name is given as
 the var(style) argument.  The widgets usable for this are:
@@ -502,7 +504,7 @@ than tt(undefined-key).
 
 The form with tt(-K) is similar and defines multiple widgets based on the
 same var(function), each of which requires the set of three arguments
-var(name), var(style) and var(key-sequences), where the latter two are as
+var(name), var(style) and var(key-seq)uence, where the latter two are as
 for tt(-k) and the first must be a unique widget name beginning with an
 underscore.
 
@@ -568,7 +570,7 @@ The context string always consists of a fixed set of fields, separated
 by colons and with a leading colon before the first.  Fields which are
 not yet known are left empty, but the surrounding colons appear anyway.
 The fields are always in the order
-tt(:completion:)var(function)tt(:)var(completer)tt(:)var(command)tt(:)var(argument)tt(:)tt(tag).  These have the following meaning:
+tt(:completion:)var(function)tt(:)var(completer)tt(:)var(command)tt(:)var(argument)tt(:)var(tag).  These have the following meaning:
 
 startitemize()
 itemiz(\
@@ -1100,7 +1102,7 @@ values.  Any of the strings `tt(true)', `tt(on)',
 any of the strings `tt(false)', `tt(off)', `tt(no)', and `tt(0)' for
 the value `false'.  The behavior for any other value is undefined 
 except where explicitly mentioned.  The default value may
-be either true or false if the style is not set.
+be either `true' or `false' if the style is not set.
 
 Some of these styles are tested first for every possible tag
 corresponding to a type of match, and if no style was found, for the
@@ -1134,7 +1136,7 @@ expanded.  For example, if there are parameters
 tt(foo) and tt(foobar), the string `tt($foo)' will only be expanded if 
 tt(accept-exact) is set to `true'; otherwise the completion system will
 be allowed to complete tt($foo) to tt($foobar). If the style is set to
-`continue', _expand will add the expansion as a match and the completion
+`tt(continue)', tt(_expand) will add the expansion as a match and the completion
 system will also be allowed to continue.
 )
 kindex(accept-exact-dirs, completion style)
@@ -1146,24 +1148,24 @@ the component matches an existing directory.  For example, when
 completion after tt(/usr/bin/), the function examines possible
 completions to tt(/usr).
 
-When this style is true, any prefix of a path that matches an existing
+When this style is `true', any prefix of a path that matches an existing
 directory is accepted without any attempt to complete it further.
 Hence, in the given example, the path tt(/usr/bin/) is accepted
 immediately and completion tried in that directory.
 
 If you wish to inhibit this behaviour entirely, set the tt(path-completion)
-style (see below) to tt(false).
+style (see below) to `false'.
 )
 kindex(add-space, completion style)
 item(tt(add-space))(
-This style is used by the tt(_expand) completer.  If it is true (the
+This style is used by the tt(_expand) completer.  If it is `true' (the
 default), a space will be inserted after all words resulting from the 
 expansion, or a slash in the case of directory names.  If the value
 is `tt(file)', the completer will only add a space
-to names of existing files.  Either a boolean true or the value
+to names of existing files.  Either a boolean `true' or the value
 `tt(file)' may be combined with `tt(subst)', in which case the completer
 will not add a space to words generated from the expansion of a
-substitution of the form `tt($LPAR()...RPAR())' or `tt(${...})'.
+substitution of the form `tt($LPAR())var(...)tt(RPAR())' or `tt(${)var(...)tt(})'.
 
 The tt(_prefix) completer uses this style as a simple boolean value
 to decide if a space should be inserted before the suffix.
@@ -1282,8 +1284,8 @@ item(tt(complete-options))(
 This is used by the completer for tt(cd), tt(chdir) and tt(pushd).
 For these commands a tt(-) is used to introduce a directory stack entry
 and completion of these is far more common than completing options.
-Hence unless the value of this style is true options will not be
-completed, even after an initial tt(-).  If it is true, options will
+Hence unless the value of this style is `true' options will not be
+completed, even after an initial tt(-).  If it is `true', options will
 be completed after an initial tt(-) unless there is a preceding
 tt(-)tt(-) on the command line.
 )
@@ -1341,7 +1343,7 @@ kindex(disabled, completion style)
 item(tt(disabled))(
 If this is set to `true', the tt(_expand_alias) completer and bindable 
 command will try to expand disabled aliases, too.  The default is
-`tt(false)'.
+`false'.
 )
 kindex(domains, completion style)
 item(tt(domains))(
@@ -1451,7 +1453,7 @@ this the following code can be included in an initialization file:
 example(zmodload -i zsh/stat
 disable stat)
 
-The style may either be set to a true value (or `tt(all)'), or
+The style may either be set to a `true' value (or `tt(all)'), or
 one of the values `tt(insert)' or `tt(list)', indicating that files
 are to be listed in long format in all circumstances, or when
 attempting to insert a file name, or when listing file names
@@ -1469,7 +1471,8 @@ or inserting a file with up to 10 matches (assuming a listing
 is to be shown at all, for example on an ambiguous completion), else short
 format will be used.
 
-example(zstyle -e ':completion:*' file-list '(( ${+NUMERIC} )) && reply=(true)')
+example(zstyle -e ':completion:*' file-list \ 
+       '(( ${+NUMERIC} )) && reply=(true)')
 
 specifies that long format will be used any time a numeric argument is
 supplied, else short format.
@@ -1580,14 +1583,14 @@ If this is set for the tt(descriptions) tag, its value is used as a
 string to display above matches in completion lists.  The sequence
 `tt(%d)' in this string will be replaced with a short description of
 what these matches are.  This string may also contain the following
-sequences to specify output attributes,
-ifnzman(noderef(Prompt Expansion))\
+sequences to specify output attributes
+ifnzman((see noderef(Prompt Expansion)))\
 ifzman(as described in the section EXPANSION OF PROMPT SEQUENCES in
 zmanref(zshmisc)):
 `tt(%B)', `tt(%S)', `tt(%U)', `tt(%F)', `tt(%K)' and their lower case
 counterparts, as well as `tt(%{)...tt(%})'.  `tt(%F)', `tt(%K)' and
 `tt(%{)...tt(%})' take arguments in the same form as prompt
-expansion.  Note that the tt(%G) sequence is not available; an argument
+expansion.  Note that the sequence `tt(%G)' is not available; an argument
 to `tt(%{)' should be used instead.
 
 The style is tested with each tag valid for the current completion
@@ -1637,8 +1640,10 @@ aliases, shell functions and parameters and reserved words as possible
 completions.  To have the external commands and shell functions listed
 separately:
 
-example(zstyle ':completion:*:*:-command-:*:commands' group-name commands
-zstyle ':completion:*:*:-command-:*:functions' group-name functions)
+example(zstyle ':completion:*:*:-command-:*:commands' \ 
+       group-name commands
+zstyle ':completion:*:*:-command-:*:functions' \ 
+       group-name functions)
 
 As a consequence, any match with the same tag will be displayed in the
 same group.
@@ -1674,7 +1679,7 @@ group names are taken from the YP database or the file `tt(/etc/group)'.
 )
 kindex(hidden, completion style)
 item(tt(hidden))(
-If this is set to true, matches for the given context
+If this is set to `true', matches for the given context
 will not be listed, although
 any description for the matches set with the tt(format) style will be
 shown.  If it is set to `tt(all)', not even the description will be
@@ -1700,7 +1705,7 @@ of hostnames; multiple ports for the same host may appear.
 kindex(ignore-line, completion style)
 item(tt(ignore-line))(
 This is tested for each tag valid for the current completion.  If
-it is set to `tt(true)', none of the words that are already on the line
+it is set to `true', none of the words that are already on the line
 will be considered as possible completions.  If it is set to
 `tt(current)', the word the cursor is on will not be considered as a
 possible completion.  The value `tt(current-shown)' is similar but only
@@ -1847,14 +1852,14 @@ there were other changes between the expanded words and the original
 word from the command line.  Any other value forces the prefix to be
 expanded unconditionally.
 
-The behaviour of expand when this style is true is to cause tt(_expand)
+The behaviour of tt(_expand) when this style is `true' is to cause tt(_expand)
 to give up when a single expansion with the restored prefix is the same
 as the original; hence any remaining completers may be called.
 )
 kindex(last-prompt, completion style)
 item(tt(last-prompt))(
 This is a more flexible form of the tt(ALWAYS_LAST_PROMPT) option.
-If it is true, the completion system will try to return the cursor to
+If it is `true', the completion system will try to return the cursor to
 the previous command line after displaying a completion list.  It is
 tested for all tags valid for the current completion, then the
 tt(default) tag.  The cursor will be moved back to the
@@ -1900,7 +1905,8 @@ tt(ZLS_COLOURS) parameters and simply using the tt(default) tag.
 It is possible to use any color specifications already set up for the GNU
 version of the tt(ls) command:
 
-example(zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS})
+example(zstyle ':completion:*:default' list-colors \ 
+       ${(s.:.)LS_COLORS})
 
 The default colors are the same as for the GNU tt(ls) command and can be
 obtained by setting the style to an empty string (i.e. tt('')).
@@ -1969,7 +1975,7 @@ if the tt(LIST_ROWS_FIRST) option were set.
 kindex(list-suffixes, completion style)
 item(tt(list-suffixes))(
 This style is used by the function that completes filenames.  If it is
-true, and completion is attempted on a string containing multiple partially
+`true', and completion is attempted on a string containing multiple partially
 typed pathname components, all ambiguous components will be shown.
 Otherwise, completion stops at the first ambiguous component.
 )
@@ -2040,7 +2046,8 @@ specification is prefixed with tt(+), it is added to the existing list.
 Hence it is possible to create increasingly general specifications
 without repetition:
 
-example(zstyle ':completion:*' matcher-list '' '+m:{a-z}={A-Z}' '+m:{A-Z}={a-z}')
+example(zstyle ':completion:*' matcher-list \ 
+       '' '+m:{a-z}={A-Z}' '+m:{A-Z}={a-z}')
 
 It is possible to create match specifications valid for particular
 completers by using the third field of the context.  This applies only
@@ -2060,7 +2067,8 @@ normal completion without a match specification, then normal completion
 with case-insensitive matching, then correction, and finally
 partial-word completion:
 
-example(zstyle ':completion:*' completer _complete _correct _complete:foo
+example(zstyle ':completion:*' completer \ 
+    _complete _correct _complete:foo
 zstyle ':completion:*:complete:*:*:*' matcher-list \ 
     '' 'm:{a-zA-Z}={A-Za-z}'
 zstyle ':completion:*:foo:*:*:*' matcher-list \ 
@@ -2128,20 +2136,20 @@ more of the description to be visible.
 )
 kindex(menu, completion style)
 item(tt(menu))(
-If this is true in the context of any of the tags defined
+If this is `true' in the context of any of the tags defined
 for the current completion menu completion will be used.  The value for
 a specific tag will take precedence over that for the `tt(default)' tag.
 
-If none of the values found in this way is true but at least
+If none of the values found in this way is `true' but at least
 one is set to `tt(auto)', the shell behaves as if the tt(AUTO_MENU)
 option is set.
 
-If one of the values is explicitly set to false, menu
+If one of the values is explicitly set to `false', menu
 completion will be explicitly turned off, overriding the
 tt(MENU_COMPLETE) option and other settings.
 
 In the form `tt(yes=)var(num)', where `tt(yes)' may be any of the
-true values (`tt(yes)', `tt(true)', `tt(on)' and `tt(1)'),
+`true' values (`tt(yes)', `tt(true)', `tt(on)' and `tt(1)'),
 menu completion will be turned on if there are at least var(num) matches.
 In the form `tt(yes=long)', menu completion will be turned on
 if the list does not fit on the screen.  This does not activate menu
@@ -2256,7 +2264,7 @@ the tt(_oldlist) completer.
 
 For example, suppose you type tt(^Xc) to generate a list of corrections,
 and menu completion is started in one of the usual ways.  Usually, or with
-this style set to tt(false), typing tt(TAB) at this point would start
+this style set to `false', typing tt(TAB) at this point would start
 trying to complete the line as it now appears.  With tt(_oldlist), it
 instead continues to cycle through the list of corrections.
 )
@@ -2296,11 +2304,11 @@ item(tt(path-completion))(
 This is used by filename completion.  By default, filename completion
 examines all components of a path to see if there are completions of
 that component.  For example, tt(/u/b/z) can be completed to
-tt(/usr/bin/zsh).  Explicitly setting this style to tt(false) inhibits this
+tt(/usr/bin/zsh).  Explicitly setting this style to `false' inhibits this
 behaviour for path components up to the tt(/) before the cursor; this
 overrides the setting of tt(accept-exact-dirs).
 
-Even with the style set to tt(false), it is still possible to complete
+Even with the style set to `false', it is still possible to complete
 multiple paths by setting the option tt(COMPLETE_IN_WORD) and moving the
 cursor back to the first component in the path to be completed.  For
 example, tt(/u/b/z) can be completed to tt(/usr/bin/zsh) if the cursor is
@@ -2373,7 +2381,7 @@ will be completed.
 If it is a range of the form `var(max)tt(:)var(slice)',
 the last var(slice) words will be completed; then if that
 yields no matches, the var(slice) words before those will be tried and 
-so on.  This process stops either when at least one match was been
+so on.  This process stops either when at least one match has been
 found, or var(max) words have been tried.
 
 The default is to complete all words from the history at once.
@@ -2403,8 +2411,8 @@ tt(zle_tr)em(TAB) can be completed to tt(Zle/zle_tricky.c).
 kindex(regular, completion style)
 item(tt(regular))(
 This style is used by the tt(_expand_alias) completer and bindable 
-command.  If set to `tt(true)' (the default), regular aliases will be
-expanded but only in command position.  If it is set to `tt(false)',
+command.  If set to `true' (the default), regular aliases will be
+expanded but only in command position.  If it is set to `false',
 regular aliases will never be expanded.   If it is set to `tt(always)',
 regular aliases will be expanded even if not in command position.
 )
@@ -2418,7 +2426,7 @@ slow file access.
 )
 kindex(remote-access, completion style)
 item(tt(remote-access))(
-If set to tt(false), certain commands will be prevented from making
+If set to `false', certain commands will be prevented from making
 Internet connections to retrieve remote information.  This includes the
 completion for the tt(CVS) command.
 
@@ -2468,13 +2476,13 @@ item(tt(show-ambiguity))(
 If the tt(zsh/complist) module is loaded, this style can be used to
 highlight the first ambiguous character in completion lists. The
 value is either a color indication such as those supported by the
-tt(list-colors) style or, with a value of tt(true), a default of
+tt(list-colors) style or, with a value of `true', a default of
 underlining is selected. The highlighting is only applied if the
 completion display strings correspond to the actual matches.
 )
 kindex(show-completer, completion style)
 item(tt(show-completer))(
-Tested whenever a new completer is tried.  If it is true, the completion
+Tested whenever a new completer is tried.  If it is `true', the completion
 system outputs a progress message in the listing area showing what
 completer is being tried.  The message will be overwritten by any output
 when completions are found and is removed after completion is finished.
@@ -2492,7 +2500,7 @@ item(tt(sort))(
 Many completion widgets call tt(_description) at some point which
 decides whether the matches are added sorted or unsorted (often
 indirectly via tt(_wanted) or tt(_requested)).  This style can be set
-explicitly to one of the usual true or false values as an override.
+explicitly to one of the usual `true' or `false' values as an override.
 If it is not set for the context, the standard behaviour of the
 calling widget is used.
 
@@ -2502,7 +2510,7 @@ if that fails to produce a value against the context without the tag.
 If the calling widget explicitly requests unsorted matches, this is usually
 honoured.  However, the default (unsorted) behaviour of completion
 for the command history may be overridden by setting the style to
-tt(true).
+`true'.
 
 In the tt(_expand) completer, if it is set to
 `true', the expansions generated will always be sorted.  If it is set
@@ -2561,7 +2569,7 @@ kindex(substitute, completion style)
 item(tt(substitute))(
 This boolean style controls whether the tt(_expand) completer will
 first try to expand all substitutions in the string (such as
-`tt($LPAR()...RPAR())' and `tt(${...})').
+`tt($LPAR())var(...)tt(RPAR())' and `tt(${)var(...)tt(})').
 
 The default is `true'.
 )
@@ -2647,7 +2655,8 @@ underscore the first time completion is tried:
 
 example(zstyle ':completion:*:*:-command-:*:*' tag-order \ 
     'functions:-non-comp *' functions
-zstyle ':completion:*:functions-non-comp' ignored-patterns '_*')
+zstyle ':completion:*:functions-non-comp' \ 
+    ignored-patterns '_*')
 
 On the first attempt, all tags will be offered but the tt(functions) tag
 will be replaced by tt(functions-non-comp).  The tt(ignored-patterns) style 
@@ -2662,10 +2671,12 @@ example(zstyle ':completion:*' tag-order \
     'options:-long:long\ options
      options:-short:short\ options
      options:-single-letter:single\ letter\ options'
-
-zstyle ':completion:*:options-long' ignored-patterns '[-+](|-|[^-]*)'
-zstyle ':completion:*:options-short' ignored-patterns '--*' '[-+]?'
-zstyle ':completion:*:options-single-letter' ignored-patterns '???*')
+zstyle ':completion:*:options-long' \ 
+     ignored-patterns '[-+](|-|[^-]*)'
+zstyle ':completion:*:options-short' \ 
+     ignored-patterns '--*' '[-+]?'
+zstyle ':completion:*:options-single-letter' \ 
+     ignored-patterns '???*')
 
 With the tt(group-names) style set, options beginning with
 `tt(-)tt(-)', options beginning with a single `tt(-)' or `tt(+)' but
@@ -2787,7 +2798,7 @@ kindex(use-ip, completion style)
 item(tt(use-ip))(
 By default, the function tt(_hosts) that completes host names strips
 IP addresses from entries read from host databases such as NIS and
-ssh files.  If this style is true, the corresponding IP addresses
+ssh files.  If this style is `true', the corresponding IP addresses
 can be completed as well.  This style is not use in any context
 where the tt(hosts) style is set; note also it must be set before
 the cache of host names is generated (typically the first completion
@@ -2834,7 +2845,7 @@ This is used by the tt(_list) completer, which prevents the insertion of
 completions until a second completion attempt when the line has not
 changed.  The normal way of finding out if the line has changed is to
 compare its entire contents between the two occasions.  If this style is
-true, the comparison is instead performed only on the current word.
+`true', the comparison is instead performed only on the current word.
 Hence if completion is performed on another word with the same contents,
 completion will not be delayed.
 )
@@ -2898,7 +2909,8 @@ then use tt(^Xa) to show all matches.  It is possible instead to
 add a standard completer to the list and request that the
 list of all matches should be directly inserted:
 
-example(zstyle ':completion:all-matches::::' completer _all_matches _complete
+example(zstyle ':completion:all-matches::::' completer \ 
+       _all_matches _complete
 zstyle ':completion:all-matches:*' insert true)
 
 In this case the tt(old-matches) style should not be set.
@@ -3009,7 +3021,8 @@ completer field in the context name is tt(correct).
 
 For example, with:
 
-example(zstyle ':completion:::::' completer _complete _correct _approximate
+example(zstyle ':completion:::::' completer \ 
+       _complete _correct _approximate
 zstyle ':completion:*:correct:::' max-errors 2 not-numeric
 zstyle ':completion:*:approximate:::' max-errors 3 numeric)
 
@@ -3261,21 +3274,21 @@ This includes the bindings for `tt(~)' in case they were already bound to
 something else; the completion code does not override user bindings.
 )
 findex(_correct_filename (^XC))
-item(tt(_correct_filename (^XC)))(
+item(tt(_correct_filename) (tt(^XC)))(
 Correct the filename path at the cursor position.  Allows up to six errors
 in the name.  Can also be called with an argument to correct
 a filename path, independently of zle; the correction is printed on
 standard output.
 )
 findex(_correct_word) (^Xc)
-item(tt(_correct_word) (^Xc))(
+item(tt(_correct_word) (tt(^Xc)))(
 Performs correction of the current argument using the usual contextual
 completions as possible choices. This stores the string
 `tt(correct-word)' in the var(function) field of the context name and
 then calls the tt(_correct) completer.
 )
 findex(_expand_alias (^Xa))
-item(tt(_expand_alias (^Xa)))(
+item(tt(_expand_alias) (tt(^Xa)))(
 This function can be used as a completer and as a bindable command.
 It expands the word the cursor is on if it is an alias.  The types of
 alias expanded can be controlled with the styles tt(regular), tt(global)
@@ -3289,7 +3302,7 @@ leaves the cursor directly after the completed word so that invoking
 tt(_expand_alias) once more will expand the now-complete alias name.
 )
 findex(_expand_word (^Xe))
-item(tt(_expand_word (^Xe)))(
+item(tt(_expand_word) (tt(^Xe)))(
 Performs expansion on the current word:  equivalent to the standard
 tt(expand-word) command, but using the tt(_expand) completer.  Before
 calling it, the var(function) field of the context is set to
@@ -3316,19 +3329,19 @@ tt(_main_complete) as the list of completers in place of those defined by
 the tt(completer) style.
 )
 findex(_history_complete_word (\e/))
-item(tt(_history_complete_word) (\e/))(
+item(tt(_history_complete_word) (tt(\e/)))(
 Complete words from the shell's command history. This uses the
 tt(list), tt(remove-all-dups), tt(sort), and tt(stop) styles.
 )
 findex(_most_recent_file (^Xm))
-item(tt(_most_recent_file (^Xm)))(
+item(tt(_most_recent_file) (tt(^Xm)))(
 Complete the name of the most recently modified file matching the pattern
 on the command line (which may be blank).  If given a numeric argument
 var(N), complete the var(N)th most recently modified file.  Note the
 completion, if any, is always unique.
 )
 findex(_next_tags (^Xn))
-item(tt(_next_tags) (^Xn))(
+item(tt(_next_tags) (tt(^Xn)))(
 This command alters the set of matches used to that for the next tag, or
 set of tags, either as given by the tt(tag-order) style or as set by
 default; these matches would otherwise not be available.
@@ -3336,7 +3349,7 @@ Successive invocations of the command cycle through all possible sets of
 tags.
 )
 findex(_read_comp (^X^R))
-item(tt(_read_comp (^X^R)))(
+item(tt(_read_comp) (tt(^X^R)))(
 Prompt the user for a string, and use that to perform completion on the
 current word.  There are two possibilities for the string.  First, it can
 be a set of words beginning `tt(_)', for example `tt(_files -/)', in which
@@ -3360,14 +3373,14 @@ existing string instead of reading a new one.  To force a new string to be
 read, call tt(_read_comp) with a numeric argument.
 )
 findex(_complete_debug (^X?))
-item(tt(_complete_debug (^X?)))(
+item(tt(_complete_debug) (tt(^X?)))(
 This widget performs ordinary completion, but captures in a temporary file
 a trace of the shell commands executed by the completion system.  Each
 completion attempt gets its own file.  A command to view each of these
 files is pushed onto the editor buffer stack.
 )
 findex(_complete_help (^Xh))
-item(tt(_complete_help (^Xh)))(
+item(tt(_complete_help) (tt(^Xh)))(
 This widget displays information about the context names, 
 the tags, and the completion functions used 
 when completing at the current cursor position. If given a numeric
@@ -3415,7 +3428,7 @@ typing `tt(C-x :)' followed by the key sequence for a generic widget
 will cause trace output for that widget to be saved to a file.
 )
 findex(_complete_tag (^Xt))
-item(tt(_complete_tag (^Xt)))(
+item(tt(_complete_tag) (tt(^Xt)))(
 This widget completes symbol tags created by the tt(etags) or tt(ctags)
 programmes (note there is no connection with the completion system's tags)
 stored in a file tt(TAGS), in the format used by tt(etags), or tt(tags), in the
@@ -3449,13 +3462,13 @@ it explicitly reinserts itself into the array.
 
 startitem()
 findex(_all_labels)
-item(tt(_all_labels) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(command) var(args) ... ])(
+item(tt(_all_labels) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(command) var(arg) ... ])(
 This is a convenient interface to the tt(_next_label) function below,
 implementing the loop shown in the tt(_next_label) example.  The
 var(command) and its arguments are called to generate the matches.  The
 options stored in the parameter var(name) will automatically be inserted
-into the var(args) passed to the var(command).  Normally, they are put
-directly after the var(command), but if one of the var(args) is a single
+into the var(arg)s passed to the var(command).  Normally, they are put
+directly after the var(command), but if one of the var(arg)s is a single
 hyphen, they are inserted directly before that.  If the hyphen is the last
 argument, it will be removed from the argument list before the
 var(command) is called.  This allows tt(_all_labels) to be used in almost all
@@ -3511,8 +3524,10 @@ Like tt(_tags) this function supports the tt(-C) option to give a
 different name for the argument context field.
 )
 findex(_arguments)
-xitem(tt(_arguments) [ tt(-nswWCRS) ] [ tt(-A) var(pat) ] [ tt(-O) var(name) ] [ tt(-M) var(matchspec) ] [ tt(:) ] var(spec)...)
-item(tt(_arguments) [ var(opts)... ] tt(-)tt(-) [ -i var(pats) ] [ tt(-s) var(pair) ] [ var(helpspec)... ])(
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ @ @ ))ifnztexi(           )))
+xitem(tt(_arguments )[ tt(-nswWCRS) ] [ tt(-A) var(pat) ] [ tt(-O) var(name) ] [ tt(-M) var(matchspec) ])
+xitem(SPACES()[ tt(:) ] var(spec) ...)
+item(tt(_arguments) [ var(opt) ... ] tt(-)tt(-) [ tt(-i) var(pats) ] [ tt(-s) var(pair) ] [ var(helpspec) ... ])(
 This function can be used to give a complete specification for completion
 for a command whose arguments follow standard UNIX option and argument
 conventions.  Options to tt(_arguments) itself must be in separate words,
@@ -3545,7 +3560,7 @@ completion option names and values.  The default var(matchspec) is:
 example(tt(r:|[_-]=* r:|=*))
 
 This allows partial word completion after `tt(_)' and `tt(-)', for example
-`-f-b' can be completed to `tt(-foo-bar)'.
+`tt(-f-b)' can be completed to `tt(-foo-bar)'.
 
 Each of the following forms is a var(spec) describing individual sets of
 options or arguments on the command line being analyzed.
@@ -3581,7 +3596,7 @@ three colons before the var(message) they are modified to refer only to
 the normal arguments covered by this description.
 )
 xitem(var(optspec))
-item(var(optspec):var(...))(
+item(var(optspec)tt(:)var(...))(
 This describes an option.  The colon indicates handling for one or more
 arguments to the option; if it is not present, the option is assumed to
 take no arguments.
@@ -3664,7 +3679,7 @@ that follows the var(optspec); see below.
 )
 enditem()
 
-It is possible for options with a literal `PLUS()' or `tt(=)' to
+It is possible for options with a literal `tt(PLUS())' or `tt(=)' to
 appear, but that character must be quoted, for example `tt(-\+)'.
 
 The options tt(-S) and tt(-A) are available to simplify the specifications
@@ -3727,7 +3742,7 @@ Each of the forms above may be preceded by a list in parentheses
 of option names and argument numbers.  If the given option is on
 the command line, the options and arguments indicated in parentheses
 will not be offered.  For example, 
-`tt((-two -three 1)-one:...)' completes the option `tt(-one)'; if this
+`tt((-two -three 1)-one:)var(...)' completes the option `tt(-one)'; if this
 appears on the command line, the options tt(-two) and tt(-three) and the
 first ordinary argument will not be completed after it.
 `tt((-foo):)var(...)' specifies an ordinary argument completion;
@@ -3736,7 +3751,7 @@ tt(-foo) will not be completed if that argument is already present.
 Other items may appear in the list of excluded options to indicate
 various other items that should not be applied when the current
 specification is matched: a single star (tt(*)) for the rest arguments
-(i.e. a specification of the form `tt(*:...)'); a colon (tt(:))
+(i.e. a specification of the form `tt(*:)var(...)'); a colon (tt(:))
 for all normal (non-option-) arguments; and a hyphen (tt(-)) for all
 options.  For example, if `tt((*))' appears before an option and the
 option appears on the command line, the list of remaining arguments
@@ -3765,7 +3780,8 @@ tt(compadd) builtin to all var(action)s.
 The forms for var(action) are as follows.
 
 startitem()
-item(tt( ) (single unquoted space))(
+def(SP)(0)(ifztexi(NOTRANS(@ ))ifnztexi( ))\
+item(tt(SP())(single unquoted space))(
 This is useful where an argument is required but it is not possible or
 desirable to generate matches for it.  The
 var(message) will be displayed but no completions listed.  Note
@@ -3848,7 +3864,7 @@ causes tt(_arguments) on a restricted range; it is necessary to use this
 trick to insert an appropriate command name into the range for the second
 call to tt(_arguments) to be able to parse the line.
 )
-xitem( var(word...))
+xitem(var(tt(SP())word...))
 item(var(word...))(
 This covers all forms other than those above.  If the var(action)
 starts with a space, the remaining list of words will be invoked unchanged.
@@ -3957,7 +3973,7 @@ the behaviour of the command is unspecified.
 
 In addition to options, `tt(_arguments -)tt(-)' will try to deduce the
 types of arguments available for options when the form
-`tt(-)tt(-)var(opt)=var(val)' is valid.  It is also possible to provide
+`tt(-)tt(-)var(opt)tt(=)var(val)' is valid.  It is also possible to provide
 hints by examining the help text of the command and adding var(helpspec) of
 the form `var(pattern)tt(:)var(message)tt(:)var(action)'; note that other
 tt(_arguments) var(spec) forms are not used.  The var(pattern) is matched
@@ -4002,7 +4018,7 @@ completed.  The patterns can be given as the name of an array parameter
 or as a literal list in parentheses.  For example,
 
 example(_arguments -- -i \ 
-    "LPAR()-tt(-(en|dis)able-FEATURE*RPAR()"))
+    "LPAR()--(en|dis)able-FEATURE*RPAR()")
 
 will cause completion to ignore the options
 `tt(-)tt(-enable-FEATURE)' and `tt(-)tt(-disable-FEATURE)' (this example is
@@ -4018,7 +4034,7 @@ For example, some tt(configure)-script help output describes options only
 as `tt(-)tt(-enable-foo)', but the script also accepts the negated form
 `tt(-)tt(-disable-foo)'.  To allow completion of the second form:
 
-example(tt(_arguments -- -s "LPAR()#-)tt(-enable- -)tt(-disable-RPAR()"))
+example(_arguments -- -s "LPAR()(#s)--enable- --disable-RPAR()")
 
 Finally, note that tt(_arguments) generally expects to be the primary
 function handling any completion for which it is used.  It may have side
@@ -4075,9 +4091,9 @@ example(_example_caching_policy () {
 })
 )
 findex(_call_function)
-item(tt(_call_function) var(return) var(name) [ var(args) ... ])(
+item(tt(_call_function) var(return) var(name) [ var(arg) ... ])(
 If a function var(name) exists, it is called with the arguments
-var(args).  The var(return) argument gives the name of a parameter in which
+var(arg)s.  The var(return) argument gives the name of a parameter in which
 the return status from the function var(name) should be stored; if var(return)
 is empty or a single hyphen it is ignored.
 
@@ -4140,10 +4156,12 @@ tt(compadd) when generating matches from the style value, or to
 the functions for the fields if they are called.
 )
 findex(_describe)
-item(tt(_describe) [tt(-12JVx)] [ tt(-oO) | tt(-t) var(tag) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)(
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ @ ))ifnztexi(          )))
+xitem(tt(_describe )[tt(-12JVx)] [ tt(-oO) | tt(-t) var(tag) ] var(descr) var(name1) [ var(name2) ] [ var(opt) ... ])
+item(SPACES()[ tt(-)tt(-) var(descr) var(name1) [ var(name2) ] [ var(opt) ... ] ... ])(
 This function associates completions with descriptions.
 Multiple groups separated by tt(-)tt(-) can be supplied, potentially with
-different completion options var(opts).
+different completion options var(opt)s.
 
 The var(descr) is taken as a string to display above the matches if the
 tt(format) style for the tt(descriptions) tag is set.  This is followed by
@@ -4239,11 +4257,11 @@ a similar format; this ensures that user-specified styles are correctly
 passed down to the builtins which implement the internals of completion.
 )
 findex(_dispatch)
-item(tt(_dispatch) var(context string ...))(
+item(tt(_dispatch) var(context string) ...)(
 This sets the current context to var(context) and looks for completion
 functions to handle this context by hunting through the list of command
 names or special contexts (as described above for tt(compdef))
-given as var(string ...).  The first completion function to be defined
+given as var(string)s.  The first completion function to be defined
 for one of the contexts in the list is used to generate matches.
 Typically, the last var(string) is tt(-default-) to cause the function
 for default completion to be used as a fallback.
@@ -4360,7 +4378,7 @@ Like other utility functions, this function accepts the `tt(-V)',
 them to the tt(compadd) builtin.
 )
 findex(_next_label)
-item(tt(_next_label) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(options) ... ])(
+item(tt(_next_label) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(option) ... ])(
 This function is used to implement the loop over different tag
 labels for a particular tag as described above for the tt(tag-order)
 style.  On each call it checks to see if there are any more tag labels; if
@@ -4374,7 +4392,7 @@ replaced by a tag label in this call.  Any description given in
 the tt(tag-order) style is preferred to the var(descr) passed to
 tt(_next_label).
 
-The var(options) given after the var(descr)
+The var(option)s given after the var(descr)
 are set in the parameter given by var(name), and hence are to be passed
 to tt(compadd) or whatever function is called to add the matches.
 
@@ -4397,7 +4415,7 @@ return ret)
 findex(_normal)
 item(tt(_normal))(
 This is the standard function called to handle completion outside
-any special var(-context-).  It is called both to complete the command
+any special tt(-)var(context)tt(-).  It is called both to complete the command
 word and also the arguments for a command.  In the second case,
 tt(_normal) looks for a special completion for that command, and if
 there is none it uses the completion for the tt(-default-) context.
@@ -4493,8 +4511,9 @@ tt(ambiguous), tt(special-dirs), tt(list-suffixes) and tt(file-sort)
 described above.
 )
 findex(_pick_variant)
-xitem(tt(_pick_variant) [ tt(-b) var(builtin-label) ] [ tt(-c) var(command) ] [ tt(-r) var(name) ])
-item(   var(label)tt(=)var(pattern) ... var(label) [ var(args) ... ])(
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ @ @ @ @ @ ))ifnztexi(              )))
+xitem(tt(_pick_variant )[ tt(-b) var(builtin-label) ] [ tt(-c) var(command) ] [ tt(-r) var(name) ])
+item(SPACES()var(label)tt(=)var(pattern) ... var(label) [ var(arg) ... ])(
 This function is used to resolve situations where a single command name
 requires more than one type of handling, either because it
 has more than one variant or because there is a name clash between two
@@ -4505,8 +4524,8 @@ tt(words) unless this is overridden by the option tt(-c).  This command
 is run and its output is compared with a series of patterns.  Arguments
 to be passed to the command can be specified at the end after all the
 other arguments.  The patterns to try in order are given by the arguments
-var(label)tt(=)var(pattern); if the output of `var(command) var(args)
-tt(...)' contains var(pattern), then tt(label) is selected as the label
+var(label)tt(=)var(pattern); if the output of `var(command) var(arg)
+...' contains var(pattern), then var(label) is selected as the label
 for the command variant.  If none of the patterns match, the final
 command label is selected and status 1 is returned.
 
@@ -4517,13 +4536,13 @@ the label var(builtin-label) is selected as the label for the variant.
 If the `tt(-r) var(name)' is given, the var(label) picked is stored in
 the parameter named var(name).
 
-The results are also cached in the var(_cmd_variant) associative array
+The results are also cached in the tt(_cmd_variant) associative array
 indexed by the name of the command run.
 )
 findex(_regex_arguments)
 item(tt(_regex_arguments) var(name) var(spec) ...)(
 This function generates a completion function var(name) which matches
-the specifications var(spec) tt(...), a set of regular expressions as
+the specifications var(spec)s, a set of regular expressions as
 described below.  After running tt(_regex_arguments), the function
 var(name) should be called as a normal completion function.
 The pattern to be matched is given by the contents of
@@ -4610,7 +4629,7 @@ their own arguments as a command line argument.
 Examples:
 
 example(_regex_arguments _tst /$'[^\0]#\0'/ \ 
-/$'[^\0]#\0'/ :'compadd aaa')
+    /$'[^\0]#\0'/ :'compadd aaa')
 
 This generates a function tt(_tst) that completes tt(aaa) as its only
 argument.  The var(tag) and var(description) for the action have been
@@ -4620,14 +4639,14 @@ second matches  any argument.  As the argument is also arbitrary, any
 following component would not depend on tt(aaa) being present.
 
 example(_regex_arguments _tst /$'[^\0]#\0'/ \ 
-/$'aaa\0'/ :'compadd aaa')
+    /$'aaa\0'/ :'compadd aaa')
 
 This is a more typical use; it is similar, but any following patterns
 would only match if tt(aaa) was present as the first argument.
 
 example(_regex_arguments _tst /$'[^\0]#\0'/ \( \ 
-/$'aaa\0'/ :'compadd aaa' \ 
-/$'bbb\0'/ :'compadd bbb' \) \#)
+    /$'aaa\0'/ :'compadd aaa' \ 
+    /$'bbb\0'/ :'compadd bbb' \) \#)
 
 In this example, an indefinite number of command arguments may be
 completed.  Odd arguments are completed as tt(aaa) and even arguments
@@ -4635,8 +4654,8 @@ as tt(bbb).  Completion fails unless the set of tt(aaa) and tt(bbb)
 arguments before the current one is matched correctly.
 
 example(_regex_arguments _tst /$'[^\0]#\0'/ \ 
-\( /$'aaa\0'/ :'compadd aaa' \| \ 
-/$'bbb\0'/ :'compadd bbb' \) \#)
+    \( /$'aaa\0'/ :'compadd aaa' \| \ 
+    /$'bbb\0'/ :'compadd bbb' \) \#)
 
 This is similar, but either tt(aaa) or tt(bbb) may be completed for
 any argument.  In this case tt(_regex_words) could be used to generate
@@ -4696,7 +4715,7 @@ array tt(mydb_add_cmds), quite possibly by a previous call to
 tt(_regex_words).
 )
 findex(_requested)
-item(tt(_requested) [ tt(-x) ] [ tt(-12VJ) ] var(tag) [ var(name) var(descr) [ var(command) var(args) ... ] ])(
+item(tt(_requested) [ tt(-x) ] [ tt(-12VJ) ] var(tag) [ var(name) var(descr) [ var(command) [ var(arg) ... ] ])(
 This function is called to decide whether a tag already registered by a
 call to tt(_tags) (see below) has been requested by the user and hence
 completion should be performed for it.  It returns status zero if the
@@ -4794,7 +4813,7 @@ This function is called automatically from tt(_description)
 and hence is not normally called explicitly.
 )
 findex(_store_cache)
-item(tt(_store_cache) var(cache_identifier) var(params) ...)(
+item(tt(_store_cache) var(cache_identifier) var(param) ...)(
 This function, together with tt(_retrieve_cache) and
 tt(_cache_invalid), implements a caching layer which can be used
 in any completion function.  Data obtained by
@@ -4806,7 +4825,7 @@ even in different instances of the shell.
 The var(cache_identifier) specifies the file which the data should be
 dumped to.  The file is stored in a directory specified by the
 tt(cache-path) style which defaults to tt(~/.zcompcache).  The remaining
-var(params) arguments are the parameters to dump to the file.
+var(param)s arguments are the parameters to dump to the file.
 
 The return status is zero if storage was successful.  The function will
 only attempt storage if the tt(use-cache) style is set, so you can
@@ -4823,7 +4842,7 @@ See the _perl_modules completion function for a simple example of
 the usage of the caching layer.
 )
 findex(_tags)
-item(tt(_tags) [ [ tt(-C) var(name) ] var(tags) ... ])(
+item(tt(_tags) [ [ tt(-C) var(name) ] var(tag) ... ])(
 If called with arguments, these are taken to be the names of tags
 valid for completions in the current context.  These tags are stored
 internally and sorted by using the tt(tag-order) style.
@@ -4938,7 +4957,7 @@ In that case the parameter tt(curcontext) should be made local instead
 of tt(context) (as described above).
 )
 findex(_wanted)
-item(tt(_wanted) [ tt(-x) ] [ tt(-C) var(name) ]  [ tt(-12VJ) ] var(tag) var(name) var(descr) var(command) var(args) ...)(
+item(tt(_wanted) [ tt(-x) ] [ tt(-C) var(name) ]  [ tt(-12VJ) ] var(tag) var(name) var(descr) var(command) [ var(arg) ...])(
 In many contexts, completion can only generate one particular set of
 matches, usually corresponding to a single tag.  However, it is
 still necessary to decide whether the user requires matches of this type.
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 37a568f58..0c0a15d41 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -59,8 +59,8 @@ texinode(Completion Special Parameters)(Completion Builtin Commands)()(Completio
 sect(Completion Special Parameters)
 
 The parameters tt(ZLE_REMOVE_SUFFIX_CHARS) and tt(ZLE_SPACE_SUFFIX_CHARS)
-are used by the completion mechanism, but are not special.
-ifzman(See em(Parameters Used By The Shell) in zmanref(zshparam))\
+are used by the completion mechanism, but are not special. See
+ifzman(em(Parameters Used By The Shell) in zmanref(zshparam))\
 ifnzman(noderef(Parameters Used By The Shell)).
 
 Inside completion widgets, and any functions called from them, some
@@ -445,16 +445,17 @@ sect(Completion Builtin Commands)
 startitem()
 findex(compadd)
 cindex(completion widgets, adding specified matches)
-xitem(tt(compadd) [ tt(-akqQfenUld12C) ] [ tt(-F) var(array) ])
-xitem([ tt(-P) var(prefix) ] [ tt(-S) var(suffix) ])
-xitem([ tt(-p) var(hidden-prefix) ] [ tt(-s) var(hidden-suffix) ])
-xitem([ tt(-i) var(ignored-prefix) ] [ tt(-I) var(ignored-suffix) ])
-xitem([ tt(-W) var(file-prefix) ] [ tt(-d) var(array) ])
-xitem([ tt(-J) var(name) ] [ tt(-V) var(name) ] [ tt(-X) var(explanation) ] [ tt(-x) var(message) ])
-xitem([ tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ])
-xitem([ tt(-D) var(array) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ])
-xitem([ tt(-E) var(number) ])
-item([ tt(-M) var(match-spec) ] [ tt(-)tt(-) ] [ var(words) ... ])(
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ ))ifnztexi(        )))
+xitem(tt(compadd )[ tt(-akqQfenUlo12C) ] [ tt(-F) var(array) ])
+xitem(SPACES()[tt(-P) var(prefix) ] [ tt(-S) var(suffix) ])
+xitem(SPACES()[tt(-p) var(hidden-prefix) ] [ tt(-s) var(hidden-suffix) ])
+xitem(SPACES()[tt(-i) var(ignored-prefix) ] [ tt(-I) var(ignored-suffix) ])
+xitem(SPACES()[tt(-W) var(file-prefix) ] [ tt(-d) var(array) ])
+xitem(SPACES()[tt(-J) var(name) ] [ tt(-V) var(name) ] [ tt(-X) var(explanation) ] [ tt(-x) var(message) ])
+xitem(SPACES()[tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ])
+xitem(SPACES()[tt(-D) var(array) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ])
+xitem(SPACES()[tt(-E) var(number) ])
+item(SPACES()[tt(-M) var(match-spec) ] [ tt(-)tt(-) ] [ var(words) ... ])(
 
 This builtin command can be used to add matches directly and control
 all the information the completion code stores with each possible
@@ -687,7 +688,7 @@ match.  If no string is given, it will be shown as a string containing
 the strings that would be inserted for the other matches, truncated to 
 the width of the screen.
 )
-item(tt(-E))(
+item(tt(-E) var(number))(
 This option adds var(number) empty matches after the var(words) have
 been added.  An empty match takes up space in completion listings but
 will never be inserted in the line and can't be selected with menu
@@ -821,7 +822,7 @@ texinode(Completion Condition Codes)(Completion Matching Control)(Completion Bui
 sect(Completion Condition Codes)
 cindex(completion widgets, condition codes)
 
-The following additional condition codes for use within the tt([[ ... ]])
+The following additional condition codes for use within the tt([[) var(...) tt(]])
 construct are available in completion widgets.  These work on the special
 parameters.  All of these tests can also be performed by the tt(compset)
 builtin, but in the case of the condition codes the contents of the special
@@ -937,9 +938,9 @@ like normal character classes.  In anchor patterns correspondence classes
 also behave like normal character classes.
 
 The standard `tt([:)var(name)tt(:])' forms described for standard shell
-patterns,
+patterns (see
 ifnzman(noderef(Filename Generation))\
-ifzman(see the section FILENAME GENERATION in zmanref(zshexpn)),
+ifzman(the section FILENAME GENERATION in zmanref(zshexpn)))
 may appear in correspondence classes as well as normal character
 classes.  The only special behaviour in correspondence classes is if
 the form on the left and the form on the right are each one of
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 24be63eb9..8b6b7d3b7 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -98,7 +98,7 @@ be used to keep function digests up to date.
 startitem()
 findex(zrecompile)
 xitem(tt(zrecompile) [ tt(-qt) ] [ var(name) ... ])
-item(tt(zrecompile) [ tt(-qt) ] tt(-p) var(args) [ tt(-)tt(-) var(args) ... ])(
+item(tt(zrecompile) [ tt(-qt) ] tt(-p) var(arg) ... [ tt(-)tt(-) var(arg) ... ])(
 This tries to find tt(*.zwc) files and automatically re-compile them if at
 least one of the original files is newer than the compiled file.  This
 works only if the names stored in the compiled files are full paths or are
@@ -118,7 +118,7 @@ Without the tt(-t) option, the return status is zero if all files that
 needed re-compilation could be compiled and non-zero if compilation for at
 least one of the files failed.
 
-If the tt(-p) option is given, the var(args) are interpreted as one
+If the tt(-p) option is given, the var(arg)s are interpreted as one
 or more sets of arguments for tt(zcompile), separated by `tt(-)tt(-)'.
 For example:
 
@@ -174,7 +174,7 @@ findex(zkbd)
 The large number of possible combinations of keyboards, workstations,
 terminals, emulators, and window systems makes it impossible for zsh to
 have built-in key bindings for every situation.  The tt(zkbd) utility,
-found in Functions/Misc, can help you quickly create key bindings for your
+found in tt(Functions/Misc), can help you quickly create key bindings for your
 configuration.
 
 Run tt(zkbd) either as an autoloaded function, or as a shell script:
@@ -291,7 +291,7 @@ cindex(hook function utility)
 
 startitem()
 findex(add-zsh-hook)
-item(tt(add-zsh-hook) [-dD] var(hook) var(function))(
+item(tt(add-zsh-hook) [ tt(-dD) ] [ tt(-Uzk) ] var(hook) var(function))(
 Several functions are special to the shell, as described in the section
 ifnzman(Special Functions, noderef(Functions))\
 ifzman(SPECIAL FUNCTIONS, see zmanref(zshmisc)),
@@ -635,7 +635,7 @@ PS1='%F{5}[%F{2}%n%F{5}] %F{3}%3~ ${vcs_info_msg_0_}%f%# ')
 
 Obviously, the last two lines are there for demonstration. You need to
 call tt(vcs_info) from your tt(precmd) function. Once that is done you need
-a tt(single quoted) tt('${vcs_info_msg_0_}') in your prompt.
+a em(single quoted) tt('${vcs_info_msg_0_}') in your prompt.
 
 To be able to use tt('${vcs_info_msg_0_}') directly in your prompt like
 this, you will need to have the tt(PROMPT_SUBST) option enabled.
@@ -865,7 +865,7 @@ in the repository.
 kindex(command)
 item(tt(command))(
 This style causes tt(vcs_info) to use the supplied string as the command
-to use as the VCS's binary. Note, that setting this in ':vcs_info:*' is
+to use as the VCS's binary. Note, that setting this in 'tt(:vcs_info:*)' is
 not a good idea.
 
 If the value of this style is empty (which is the default), the used binary
@@ -1219,12 +1219,12 @@ without restarting the shell.
 )
 enditem()
 
-All functions named VCS_INFO_* are for internal use only.
+All functions named tt(VCS_INFO_*) are for internal use only.
 
 subsect(Variable Description)
 
 startitem()
-item(tt(${vcs_info_msg_)var(N)tt(_}) (Note the trailing underscore))
+item(tt(${vcs_info_msg_)var(N)tt(_)}) (Note the trailing underscore))
 (
 Where var(N) is an integer, e.g., tt(vcs_info_msg_0_). These variables
 are the storage for the informational message the last tt(vcs_info) call
@@ -1237,7 +1237,7 @@ exported into the environment. (See the tt(max-exports) style above.)
 )
 enditem()
 
-All variables named VCS_INFO_* are for internal use only.
+All variables named tt(VCS_INFO_*) are for internal use only.
 
 subsect(Hooks in vcs_info)
 
@@ -1256,7 +1256,7 @@ example(zstyle ':vcs_info:*+foo:*' hooks bar baz)
 
 This registers functions to the hook `foo' for all backends. In order to
 avoid namespace problems, all registered function names are prepended by
-a `+vi-', so the actual functions called for the `foo' hook are
+a `tt(+vi-)', so the actual functions called for the `foo' hook are
 `tt(+vi-bar)' and `tt(+vi-baz)'.
 
 If you would like to register a function to a hook regardless of the
@@ -1377,7 +1377,7 @@ tt(patch-format) and tt(nopatch-format) styles.
 item(tt(no-vcs))(
 This hooks is called when no version control system was detected.
 
-The `hook_com' parameter is not used.
+The `tt(hook_com)' parameter is not used.
 )
 item(tt(post-backend))(
 Called as soon as the backend has finished collecting information.
@@ -1442,8 +1442,8 @@ will be used unchanged instead of an expanded format from tt(patch-format) or
 tt(nopatch-format).
 )
 item(tt(set-message))(
-Called each time before a `tt(vcs_info_msg_N_)' message is set.
-It takes two arguments; the first being the `N' in the message
+Called each time before a `tt(vcs_info_msg_)var(N)tt(_)' message is set.
+It takes two arguments; the first being the `var(N)' in the message
 variable name, the second is the currently configured tt(formats) or
 tt(actionformats).
 
@@ -1468,8 +1468,8 @@ tt(vcs_info).
 )
 enditem()
 
-If all of this sounds rather confusing, take a look at the tt(Examples)
-section below and also in the Misc/vcs_info-examples file in the Zsh source.
+If all of this sounds rather confusing, take a look at the bf(Examples)
+section below and also in the tt(Misc/vcs_info-examples) file in the Zsh source.
 They contain some explanatory code.
 
 subsect(Examples)
@@ -1487,8 +1487,8 @@ Provide a special formats for tt(git):
 example(zstyle ':vcs_info:git:*' formats       ' GIT, BABY! [%b]'
 zstyle ':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]')
 
-All tt(%x) expansion in all sorts of formats ("formats", "actionformats",
-branchformat, you name it) are done using the `tt(zformat)' builtin from
+All tt(%x) expansion in all sorts of formats (tt(formats), tt(actionformats),
+tt(branchformat), you name it) are done using the `tt(zformat)' builtin from
 the `tt(zsh/zutil)' module. That means you can do everything with these
 tt(%x) items what zformat supports. In particular, if you want something
 that is really long to have a fixed width, like a hash in a mercurial
@@ -1504,16 +1504,17 @@ example(zstyle ':vcs_info:bzr:*' use-simple true)
 If you do use tt(use-simple), please report if it does `the-right-thing[tm]'.
 
 Display the revision number in yellow for tt(bzr) and tt(svn):
-example(zstyle ':vcs_info:(svn|bzr):*' branchformat '%b%{'${fg[yellow]}'%}:%r')
+example(zstyle ':vcs_info:(svn|bzr):*' \ 
+       branchformat '%b%{'${fg[yellow]}'%}:%r')
 
-If you want colors, make sure you enclose the color codes in tt(%{...%})
+If you want colors, make sure you enclose the color codes in tt(%{)var(...)tt(%})
 if you want to use the string provided by tt(vcs_info) in prompts.
 
 Here is how to print the VCS information as a command (not in a prompt):
 example(alias vcsi='vcs_info command; vcs_info_lastmsg')
 
 This way, you can even define different formats for output via
-tt(vcs_info_lastmsg) in the ':vcs_info:*:command:*' namespace.
+tt(vcs_info_lastmsg) in the 'tt(:vcs_info:*:command:*)' namespace.
 
 Now as promised, some code that uses hooks:
 say, you'd like to replace the string `svn' by `subversion' in
@@ -1846,7 +1847,8 @@ Neither of the styles tt(word-chars) nor tt(word-class) is used in this case.
 Here are some examples of use of the tt(word-context) style to extend
 the context.
 
-example(zstyle ':zle:*' word-context "*/*" file "[[:space:]]" whitespace
+example(zstyle ':zle:*' word-context \ 
+       "*/*" file "[[:space:]]" whitespace
 zstyle ':zle:transpose-words:whitespace' word-style shell
 zstyle ':zle:transpose-words:filename' word-style normal
 zstyle ':zle:transpose-words:filename' word-chars '')
@@ -2268,8 +2270,9 @@ using a two-character mnemonic.
 )
 tindex(narrow-to-region)
 tindex(narrow-to-region-invisible)
-xitem(tt(narrow-to-region [ -p) var(pre) tt(] [ -P) var(post) tt(]))
-xitem(    tt([ -S) var(statepm) tt(| -R) var(statepm) tt(] [ -n ] [) var(start) var(end) tt(])))
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ ))ifnztexi(                 )))
+xitem(tt(narrow-to-region )[ tt(-p) var(pre) ] [ tt(-P) var(post) ])
+xitem(SPACES()[ tt(-S) var(statepm) | tt(-R) var(statepm) ] [ tt(-n) ] [ var(start) var(end) ])
 item(tt(narrow-to-region-invisible))(
 Narrow the editable portion of the buffer to the region between the cursor
 and the mark, which may be in either order.  The region may not be empty.
@@ -2920,8 +2923,8 @@ command to an appropriate viewer.
 startitem()
 findex(zsh-mime-setup)
 findex(zsh-mime-handler)
-xitem(tt(zsh-mime-setup) [ tt(-fv) ] [ tt(-l) [ var(suffix ...) ] ])
-item(tt(zsh-mime-handler [-l] var(command arguments ...)))(
+xitem(tt(zsh-mime-setup) [ tt(-fv) ] [ tt(-l) [ var(suffix) ... ] ])
+item(tt(zsh-mime-handler) [ tt(-l) ] var(command argument) ...)(
 These two functions use the files tt(~/.mime.types) and tt(/etc/mime.types),
 which associate types and extensions, as well as tt(~/.mailcap) and
 tt(/etc/mailcap) files, which associate types and the programs that
@@ -3805,11 +3808,13 @@ ifzman(above)\
 ifnzman((noderef(Utilities))).
 )
 findex(zmv)
-item(tt(zmv) [ tt(-finqQsvwW) ] [ -C | -L | -M | -[pP] var(program) ] [ -o var(optstring) ] var(srcpat) var(dest) )(
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ ))ifnztexi(    )))
+xitem(tt(zmv) [ tt(-finqQsvwW) ] [ tt(-C) | tt(-L) | tt(-M) | -{tt(p)|tt(P)} var(program) ] [ tt(-o) var(optstring) ])
+item(SPACES()var(srcpat) var(dest) )(
 Move (usually, rename) files matching the pattern var(srcpat) to
 corresponding files having names of the form given by var(dest), where
 var(srcpat) contains parentheses surrounding patterns which will be
-replaced in turn by $1, $2, ... in var(dest).  For example,
+replaced in turn by tt($1), tt($2), ... in var(dest).  For example,
 
 example(zmv '(*).lis' '$1.txt')
 
@@ -3829,7 +3834,7 @@ sitem(tt(-f))(Force overwriting of destination files.  Not currently
 passed down to the tt(mv)/tt(cp)/tt(ln) command due to vagaries of
 implementations (but you can use tt(-o-f) to do that).)
 sitem(tt(-i))(Interactive: show each line to be executed and ask the user
-whether to execute it.  `Y' or `y' will execute it, anything else will
+whether to execute it.  `tt(Y)' or `tt(y)' will execute it, anything else will
 skip it.  Note that you just need to type one character.)
 sitem(tt(-n))(No execution: print what would happen, but don't do it.)
 sitem(tt(-q))(Turn bare glob qualifiers off: now assumed by default, so
@@ -3841,7 +3846,7 @@ sitem(tt(-v))(Verbose: print each command as it's being executed.)
 sitem(tt(-w))(Pick out wildcard parts of the pattern, as described above,
 and implicitly add parentheses for referring to them.)
 sitem(tt(-W))(Just like tt(-w), with the addition of turning wildcards in
-the replacement pattern into sequential ${1} .. ${N} references.)
+the replacement pattern into sequential tt(${1}) .. tt(${N}) references.)
 sxitem(tt(-C))
 sxitem(tt(-L))
 sitem(tt(-M))(Force tt(cp), tt(ln) or tt(mv), respectively, regardless of
@@ -3879,18 +3884,18 @@ ifzman(above)\
 ifnzman((noderef(Utilities))).
 )
 findex(zstyle+)
-item(tt(zstyle+) var(context) var(style) var(value) [ + var(subcontext) var(style) var(value) ... ])(
+item(tt(zstyle+) var(context) var(style) var(value) [ tt(+) var(subcontext) var(style) var(value) ... ])(
 This makes defining styles a bit simpler by using a single `tt(+)' as a
 special token that allows you to append a context name to the previously
 used context name.  Like this:
 
-example(zstyle+ ':foo:bar' style1 value1 \ 
-      + ':baz'     style2 value2 \ 
-      + ':frob'    style3 value3)
+example(zstyle+ ':foo:bar' var(style1) var(value1) \ 
+      + ':baz'     var(style2) var(value2) \ 
+      + ':frob'    var(style3) var(value3))
 
-This defines `style1' with `value1' for the context tt(:foo:bar) as usual,
-but it also defines `style2' with `value2' for the context
-tt(:foo:bar:baz) and `style3' with `value3' for tt(:foo:bar:frob).  Any
+This defines var(style1) with var(value1) for the context tt(:foo:bar) as usual,
+but it also defines var(style2) with var(value2) for the context
+tt(:foo:bar:baz) and var(style3) with var(value3) for tt(:foo:bar:frob).  Any
 var(subcontext) may be the empty string to re-use the first context
 unchanged.
 )
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 8e5ab4bfd..1089ddf40 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -1014,25 +1014,6 @@ form of single quoting is used that only quotes the string if needed to
 protect special characters.  Typically this form gives the most readable
 output.
 )
-item(tt(b))(
-Quote with backslashes only characters that are special to pattern
-matching. This is useful when the contents of the variable are to be
-tested using tt(GLOB_SUBST), including the tt(${~)var(...)tt(}) switch.
-
-Quoting using one of the tt(q) family of flags does not work
-for this purpose since quotes are not stripped from non-pattern
-characters by tt(GLOB_SUBST).  In other words,
-
-example(pattern=${(q)str}
-[[ $str = ${~pattern} ]])
-
-works if tt($str) is tt('a*b') but not if it is tt('a b'), whereas
-
-example(pattern=${(b)str}
-[[ $str = ${~pattern} ]])
-
-is always true for any possible value of tt($str).
-)
 item(tt(Q))(
 Remove one level of quotes from the resulting words.
 )
@@ -1166,7 +1147,9 @@ be treated as patterns.  This applies to the string arguments of flags
 that follow tt(~) within the same set of parentheses.  Compare with tt(~)
 outside parentheses, which forces the entire substituted string to
 be treated as a pattern.  Hence, for example,
+
 example([[ "?" = ${(~j.|.)array} ]])
+
 treats `tt(|)' as a pattern and succeeds if and only if tt($array)
 contains the string `tt(?)' as an element.  The tt(~) may be
 repeated to toggle the behaviour; its effect only lasts to the
diff --git a/Doc/Zsh/mod_clone.yo b/Doc/Zsh/mod_clone.yo
index a0bf42b17..02dc5be0e 100644
--- a/Doc/Zsh/mod_clone.yo
+++ b/Doc/Zsh/mod_clone.yo
@@ -20,7 +20,8 @@ and non-zero on error.
 The target of tt(clone) should be an unused terminal, such as an unused virtual
 console or a virtual terminal created by
 
-xterm -e sh -c 'trap : INT QUIT TSTP; tty; while :; do sleep 100000000; done'
+example(xterm -e sh -c 'trap : INT QUIT TSTP; tty;
+        while :; do sleep 100000000; done')
 
 Some words of explanation are warranted about this long xterm command
 line: when doing clone on a pseudo-terminal, some other session
@@ -28,14 +29,15 @@ line: when doing clone on a pseudo-terminal, some other session
 the terminal. Hence the cloned zsh cannot acquire the pseudo-terminal
 as a controlling tty. That means two things:
 
-      the job control signals will go to the sh-started-by-xterm process
-      group (that's why we disable INT QUIT and TSTP with trap; otherwise
-      the while loop could get suspended or killed)
+startitemize()
+itemiz(the job control signals will go to the sh-started-by-xterm process
+group (that's why we disable INT QUIT and TSTP with trap; otherwise
+the while loop could get suspended or killed))
+itemiz(the cloned shell will have job control disabled, and the job
+control keys (control-C, control-\ and control-Z) will not work.)
+enditemize()
 
-      the cloned shell will have job control disabled, and the job
-      control keys (control-C, control-\ and control-Z) will not work.
-
-This does not apply when cloning to an bf(unused) vc.
+This does not apply when cloning to an em(unused) vc.
 
 Cloning to a used (and unprepared) terminal will result in two
 processes reading simultaneously from the same terminal, with
diff --git a/Doc/Zsh/mod_complist.yo b/Doc/Zsh/mod_complist.yo
index 09b2b4f8b..164b5b03f 100644
--- a/Doc/Zsh/mod_complist.yo
+++ b/Doc/Zsh/mod_complist.yo
@@ -22,7 +22,7 @@ are highlighted.  To turn on highlighting an empty value suffices, in
 which case all the default values given below will be used.  The format of
 the value of these parameters is the same as used by the GNU version of the
 tt(ls) command: a colon-separated list of specifications of the form
-`var(name)=var(value)'.  The var(name) may be one of the following strings,
+`var(name)tt(=)var(value)'.  The var(name) may be one of the following strings,
 most of which specify file types for which the var(value) will be used.
 The strings and their default values are:
 
@@ -167,7 +167,7 @@ is the empty string, a default prompt will be used.  The value may
 contain escapes of the form `tt(%x)'.  It supports the escapes
 `tt(%B)', `tt(%b)', `tt(%S)', `tt(%s)', `tt(%U)', `tt(%u)', `tt(%F)',
 `tt(%f)', `tt(%K)', `tt(%k)' and
-`tt(%{...%})' used also in shell prompts as well as three pairs of
+`tt(%{)var(...)tt(%})' used also in shell prompts as well as three pairs of
 additional sequences: a `tt(%l)' or `tt(%L)' is replaced by the number
 of the last line shown and the total number of lines in the form
 `var(number)tt(/)var(total)'; a `tt(%m)' or `tt(%M)' is replaced with
@@ -409,6 +409,6 @@ ifnzman(noderef(The zsh/zle Module))\
 ). For example, to make the return key leave menu selection without
 accepting the match currently selected one could call
 
-indent(tt(bindkey -M menuselect '^M' send-break))
+example(bindkey -M menuselect '^M' send-break)
 
 after loading the tt(zsh/complist) module.
diff --git a/Doc/Zsh/mod_curses.yo b/Doc/Zsh/mod_curses.yo
index 7ad772adb..8104572a6 100644
--- a/Doc/Zsh/mod_curses.yo
+++ b/Doc/Zsh/mod_curses.yo
@@ -21,11 +21,11 @@ xitem(tt(zcurses) tt(position) var(targetwin) var(array))
 xitem(tt(zcurses) tt(char) var(targetwin) var(character) )
 xitem(tt(zcurses) tt(string) var(targetwin) var(string) )
 xitem(tt(zcurses) tt(border) var(targetwin) var(border) )
-xitem(tt(zcurses) tt(attr) var(targetwin) [ var({+/-}attribute) | var(fg_col)tt(/)var(bg_col) ] [...])
-xitem(tt(zcurses) tt(bg) var(targetwin) [ var({+/-}attribute) | var(fg_col)tt(/)var(bg_col) | tt(@)var(char) ] [...])
-xitem(tt(zcurses) tt(scroll) var(targetwin) [ tt(on) | tt(off) | {+/-}var(lines) ])
+xitem(tt(zcurses) tt(attr) var(targetwin) [ [tt(+)|tt(-)]var(attribute) | var(fg_col)tt(/)var(bg_col) ] [...])
+xitem(tt(zcurses) tt(bg) var(targetwin) [ [tt(+)|tt(-)]var(attribute) | var(fg_col)tt(/)var(bg_col) | tt(@)var(char) ] [...])
+xitem(tt(zcurses) tt(scroll) var(targetwin) [ tt(on) | tt(off) | [tt(+)|tt(-)]var(lines) ])
 xitem(tt(zcurses) tt(input) var(targetwin) [ var(param) [ var(kparam) [ var(mparam) ] ] ])
-xitem(tt(zcurses) tt(mouse) [ tt(delay) var(num) | {+/-}tt(motion) ])
+xitem(tt(zcurses) tt(mouse) [ tt(delay) var(num) | [tt(+)|tt(-)]tt(motion) ])
 xitem(tt(zcurses) tt(timeout) var(targetwin) var(intval))
 item(tt(zcurses) tt(querychar) var(targetwin) [ var(param) ])(
 Manipulate curses windows.  All uses of this command should be
@@ -135,7 +135,7 @@ turned tt(on) to allow the window to be scrolled.
 The subcommand tt(input) reads a single character from the window
 without echoing it back.  If var(param) is supplied the character is
 assigned to the parameter var(param), else it is assigned to the
-parameter var(REPLY).
+parameter tt(REPLY).
 
 If both var(param) and var(kparam) are supplied, the key is read in
 `keypad' mode.  In this mode special keys such as function keys and
diff --git a/Doc/Zsh/mod_parameter.yo b/Doc/Zsh/mod_parameter.yo
index 09ceba258..9d1dc8b7d 100644
--- a/Doc/Zsh/mod_parameter.yo
+++ b/Doc/Zsh/mod_parameter.yo
@@ -151,11 +151,11 @@ item(tt(jobstates))(
 This associative array gives information about the states of the jobs
 currently known. The keys are the job numbers and the values are
 strings of the form
-`var(job-state):var(mark):var(pid)tt(=)var(state)tt(...)'. The
+`var(job-state)tt(:)var(mark)tt(:)var(pid)tt(=)var(state)...'. The
 var(job-state) gives the state the whole job is currently in, one of
 `tt(running)', `tt(suspended)', or `tt(done)'. The var(mark) is
 `tt(+)' for the current job, `tt(-)' for the previous job and empty
-otherwise. This is followed by one `var(pid)tt(=)var(state)' for every
+otherwise. This is followed by one `tt(:)var(pid)tt(=)var(state)' for every
 process in the job. The var(pid)s are, of course, the process IDs and
 the var(state) describes the state of that process.
 
diff --git a/Doc/Zsh/mod_pcre.yo b/Doc/Zsh/mod_pcre.yo
index faada28de..d6b4bd15d 100644
--- a/Doc/Zsh/mod_pcre.yo
+++ b/Doc/Zsh/mod_pcre.yo
@@ -31,18 +31,18 @@ PCRE.
 
 Upon successful match,
 if the expression captures substrings within parentheses,
-tt(pcre_match) will set the array var($match) to those
+tt(pcre_match) will set the array tt(match) to those
 substrings, unless the tt(-a) option is given, in which
 case it will set the array var(arr).  Similarly, the variable
-var(MATCH) will be set to the entire matched portion of the
+tt(MATCH) will be set to the entire matched portion of the
 string, unless the tt(-v) option is given, in which case the variable
 var(var) will be set.
 No variables are altered if there is no successful match.
 A tt(-n) option starts searching for a match from the
 byte var(offset) position in var(string).  If the tt(-b) option is given,
-the variable var(ZPCRE_OP) will be set to an offset pair string,
+the variable tt(ZPCRE_OP) will be set to an offset pair string,
 representing the byte offset positions of the entire matched portion
-within the var(string).  For example, a var(ZPCRE_OP) set to "32 45" indicates
+within the var(string).  For example, a tt(ZPCRE_OP) set to "32 45" indicates
 that the matched portion began on byte offset 32 and ended on byte offset 44.
 Here, byte offset position 45 is the position directly after the matched
 portion.  Keep in mind that the byte position isn't necessarily the same
@@ -75,7 +75,7 @@ The tt(zsh/pcre) module makes available the following test condition:
 
 startitem()
 findex(pcre-match)
-item(expr tt(-pcre-match) pcre)(
+item(var(expr) tt(-pcre-match) var(pcre))(
 Matches a string against a perl-compatible regular expression.
 
 For example,
diff --git a/Doc/Zsh/mod_sched.yo b/Doc/Zsh/mod_sched.yo
index 2d8d77c7a..1350b9e4c 100644
--- a/Doc/Zsh/mod_sched.yo
+++ b/Doc/Zsh/mod_sched.yo
@@ -8,7 +8,7 @@ startitem()
 findex(sched)
 cindex(timed execution)
 cindex(execution, timed)
-xitem(tt(sched) [tt(-o)] [tt(PLUS())]var(hh)tt(:)var(mm)[:var(ss)] var(command) ...)
+xitem(tt(sched) [tt(-o)] [tt(PLUS())]var(hh)tt(:)var(mm)[tt(:)var(ss)] var(command) ...)
 xitem(tt(sched) [tt(-o)] [tt(PLUS())]var(seconds) var(command) ...)
 item(tt(sched) [ tt(-)var(item) ])(
 Make an entry in the scheduled list of commands to execute.
@@ -54,7 +54,7 @@ tt(sched) builtin.  The indices of the array correspond to the numbers
 shown when tt(sched) is run with no arguments (provided that the
 tt(KSH_ARRAYS) option is not set).  The value of the array
 consists of the scheduled time in seconds since the epoch
-(see ifnzman(The zsh/datetime Module)\
+(see ifnzman(noderef(The zsh/datetime Module))\
 ifzman(the section `The zsh/datetime Module') for facilities for
 using this number), followed by a colon, followed by any options
 (which may be empty but will be preceded by a `tt(-)' otherwise),
diff --git a/Doc/Zsh/mod_stat.yo b/Doc/Zsh/mod_stat.yo
index 1c540bbb2..78649de5e 100644
--- a/Doc/Zsh/mod_stat.yo
+++ b/Doc/Zsh/mod_stat.yo
@@ -9,9 +9,11 @@ findex(zstat)
 findex(stat)
 cindex(files, listing)
 cindex(files, examining)
-xitem(tt(zstat) [ tt(-gnNolLtTrs) ] [ tt(-f) var(fd) ] \
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ ))ifnztexi(      )))
+xitem(tt(zstat )[ tt(-gnNolLtTrs) ] [ tt(-f) var(fd) ] \
     [ tt(-H) var(hash) ] [ tt(-A) var(array) ] \
-    [ tt(-F) var(fmt) ] [ tt(PLUS())var(element) ] [ var(file) ... ])
+    [ tt(-F) var(fmt) ])
+xitem(SPACES()[ tt(PLUS())var(element) ] [ var(file) ... ])
 item(tt(stat) var(...))(
 The command acts as a front end to the tt(stat) system call (see
 manref(stat)(2)).  The same command is provided with two names; as
diff --git a/Doc/Zsh/mod_system.yo b/Doc/Zsh/mod_system.yo
index 7101e37dc..7f9c011a7 100644
--- a/Doc/Zsh/mod_system.yo
+++ b/Doc/Zsh/mod_system.yo
@@ -8,7 +8,7 @@ subsect(Builtins)
 
 startitem()
 findex(syserror)
-item(tt(syserror) tt([ -e) var(errvar) tt(] [ -p) var(prefix) tt(] [) var(errno) tt(|) var(errname) tt(]))(
+item(tt(syserror) [ tt(-e) var(errvar) ] [ tt(-p) var(prefix) ] [ var(errno) | var(errname) ])(
 This command prints out the error message associated with var(errno), a
 system error number, followed by a newline to standard error.
 
@@ -29,11 +29,12 @@ parameters, and a return status of 2 indicates the error name was
 not recognised (no message is printed for this).
 )
 findex(sysread)
-xitem(tt(sysread [ -c) var(countvar) tt(] [ -i) var(infd) tt(] [ -o) var(outfd) tt(]))
-item(  tt([ -s) var(bufsize) tt(] [ -t) var(timeout) tt(] [) var(param) tt(]))(
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ ))ifnztexi(        )))
+xitem(tt(sysread )[ tt(-c) var(countvar) ] [ tt(-i) var(infd) ] [ tt(-o) var(outfd) ])
+item(SPACES()[ tt(-s) var(bufsize) ] [ tt(-t) var(timeout) ] [ var(param) ])(
 Perform a single system read from file descriptor var(infd), or zero if
 that is not given.  The result of the read is stored in var(param) or
-var(REPLY) if that is not given.  If var(countvar) is given, the number
+tt(REPLY) if that is not given.  If var(countvar) is given, the number
 of bytes read is assigned to the parameter named by var(countvar).
 
 The maximum number of bytes read is var(bufsize) or 8192 if that is not
@@ -88,7 +89,7 @@ usual rules; no write to var(outfd) is attempted.
 )
 enditem()
 )
-item(tt(syswrite [ -c) var(countvar) tt(] [ -o) var(outfd) tt(]) var(data))(
+item(tt(syswrite) [ tt(-c) var(countvar) ] [ tt(-o) var(outfd) ] var(data))(
 The data (a single string of bytes) are written to the file descriptor
 var(outfd), or 1 if that is not given, using the tt(write) system call.
 Multiple write operations may be used if the first does not write all
@@ -109,7 +110,7 @@ to the command, or 2 for an error on the write; no error message is
 printed in the last case, but the parameter tt(ERRNO) will reflect
 the error that occurred.
 )
-xitem(tt(zsystem flock [ -t) var(timeout) tt(] [ -f) var(var) tt(] [-er]) var(file))
+xitem(tt(zsystem flock) [ tt(-t) var(timeout) ] [ tt(-f) var(var) ] [tt(-er)] var(file))
 item(tt(zsystem flock -u) var(fd_expr))(
 The builtin tt(zsystem)'s subcommand tt(flock) performs advisory file
 locking (via the manref(fcntl)(2) system call) over the entire contents
@@ -126,7 +127,7 @@ the subshell exits.  Status 0 is returned if the lock succeeds, else
 status 1.
 
 In the second form the file descriptor given by the arithmetic
-expression tt(fd_expr) is closed, releasing a lock.  The file descriptor
+expression var(fd_expr) is closed, releasing a lock.  The file descriptor
 can be queried by using the `tt(-f) var(var)' form during the lock;
 on a successful lock, the shell variable var(var) is set to the file
 descriptor used for locking.  The lock will be released if the
diff --git a/Doc/Zsh/mod_zftp.yo b/Doc/Zsh/mod_zftp.yo
index de53cdbb3..fd997039e 100644
--- a/Doc/Zsh/mod_zftp.yo
+++ b/Doc/Zsh/mod_zftp.yo
@@ -128,15 +128,15 @@ item(tt(cdup))(
 Change the remote directory to the one higher in the directory tree.
 Note that tt(cd ..) will also work correctly on non-UNIX systems.
 )
-item(tt(dir) [ var(args...) ])(
-Give a (verbose) listing of the remote directory.  The var(args) are
+item(tt(dir) [ var(arg) ... ])(
+Give a (verbose) listing of the remote directory.  The var(arg)s are
 passed directly to the server. The command's behaviour is implementation
-dependent, but a UNIX server will typically interpret var(args) as
+dependent, but a UNIX server will typically interpret var(arg)s as
 arguments to the tt(ls) command and with no arguments return the
 result of `tt(ls -l)'. The directory is listed to standard output.
 )
-item(tt(ls) [ var(args) ])(
-Give a (short) listing of the remote directory.  With no var(args),
+item(tt(ls) [ var(arg) ... ])(
+Give a (short) listing of the remote directory.  With no var(arg),
 produces a raw list of the files in the directory, one per line.
 Otherwise, up to vagaries of the server implementation, behaves
 similar to tt(dir).
@@ -164,8 +164,8 @@ item(tt(mode) [ tt(S) | tt(B) ])(
 Set the mode type to stream (tt(S)) or block (tt(B)).  Stream mode is
 the default; block mode is not widely supported.
 )
-xitem(tt(remote) var(files...))
-item(tt(local) [ var(files...) ])(
+xitem(tt(remote) var(file) ...)
+item(tt(local) [ var(file) ... ])(
 Print the size and last modification time of the remote or local
 files.  If there is more than one item on the list, the name of the
 file is printed first.  The first number is the file size, the second
@@ -185,15 +185,15 @@ arguments, in which case the information comes from examining file
 descriptor zero.  This is the same file as seen by a tt(put) command
 with no further redirection.
 )
-item(tt(get) var(file) [...])(
+item(tt(get) var(file) ...)(
 Retrieve all var(file)s from the server, concatenating them
 and sending them to standard output.
 )
-item(tt(put) var(file) [...])(
+item(tt(put) var(file) ...)(
 For each var(file), read a file from standard input and send that to
 the remote host with the given name.
 )
-item(tt(append) var(file) [...])(
+item(tt(append) var(file) ...)(
 As tt(put), but if the remote var(file) already exists, data is
 appended to it instead of overwriting it.
 )
@@ -206,7 +206,7 @@ useful for appending to an incomplete local file.  However, note that
 this ability is not universally supported by servers (and is not quite
 the behaviour specified by the standard).
 )
-item(tt(delete) var(file) [...])(
+item(tt(delete) var(file) ...)(
 Delete the list of files on the server.
 )
 item(tt(mkdir) var(directory))(
@@ -218,11 +218,11 @@ Delete the directory var(directory)  on the server.
 item(tt(rename) var(old-name) var(new-name))(
 Rename file var(old-name) to var(new-name) on the server.
 )
-item(tt(site) var(args...))(
+item(tt(site) var(arg) ...)(
 Send a host-specific command to the server.  You will probably
 only need this if instructed by the server to use it.
 )
-item(tt(quote) var(args...))(
+item(tt(quote) var(arg) ...)(
 Send the raw FTP command sequence to the server.  You should be
 familiar with the FTP command set as defined in RFC959 before doing
 this.  Useful commands may include tt(STAT) and tt(HELP).  Note also
diff --git a/Doc/Zsh/mod_zpty.yo b/Doc/Zsh/mod_zpty.yo
index de471153e..340f98314 100644
--- a/Doc/Zsh/mod_zpty.yo
+++ b/Doc/Zsh/mod_zpty.yo
@@ -5,7 +5,7 @@ The tt(zsh/zpty) module offers one builtin:
 
 startitem()
 findex(zpty)
-item(tt(zpty) [ tt(-e) ] [ tt(-b) ] var(name) [ var(arg ...) ])(
+item(tt(zpty) [ tt(-e) ] [ tt(-b) ] var(name) [ var(arg) ... ])(
 The arguments following var(name) are concatenated with spaces between,
 then executed as a command, as if passed to the tt(eval) builtin.  The
 command runs under a newly assigned pseudo-terminal; this is useful for
@@ -19,18 +19,18 @@ characters are echoed.
 With the tt(-b) option, input to and output from the pseudo-terminal are
 made non-blocking.
 )
-item(tt(zpty) tt(-d) [ var(names) ... ])(
+item(tt(zpty) tt(-d) [ var(name) ... ])(
 The second form, with the tt(-d) option, is used to delete commands
 previously started, by supplying a list of their var(name)s.  If no
-var(names) are given, all commands are deleted.  Deleting a command causes
+var(name) is given, all commands are deleted.  Deleting a command causes
 the HUP signal to be sent to the corresponding process.
 )
-item(tt(zpty) tt(-w) [ tt(-n) ] var(name) [ var(strings ...) ])(
+item(tt(zpty) tt(-w) [ tt(-n) ] var(name) [ var(string) ... ])(
 The tt(-w) option can be used to send the to command var(name) the given
-var(strings) as input (separated by spaces).  If the tt(-n) option is
+var(string)s as input (separated by spaces).  If the tt(-n) option is
 em(not) given, a newline is added at the end.
 
-If no var(strings) are provided, the standard input is copied to the
+If no var(string) is provided, the standard input is copied to the
 pseudo-terminal; this may stop before copying the full input if the
 pseudo-terminal is non-blocking.
 
diff --git a/Doc/Zsh/mod_zselect.yo b/Doc/Zsh/mod_zselect.yo
index a374b2c34..e0651571e 100644
--- a/Doc/Zsh/mod_zselect.yo
+++ b/Doc/Zsh/mod_zselect.yo
@@ -7,7 +7,7 @@ startitem()
 findex(zselect)
 cindex(select, system call)
 cindex(file descriptors, waiting for)
-item(tt(zselect) [ tt(-rwe) tt(-t) var(timeout) tt(-a) var(array) ] [ var(fd) ... ])(
+item(tt(zselect) [ tt(-rwe) ] [ tt(-t) var(timeout) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] [ var(fd) ... ])(
 The tt(zselect) builtin is a front-end to the `select' system call, which
 blocks until a file descriptor is ready for reading or writing, or has an
 error condition, with an optional timeout.  If this is not available on
@@ -39,7 +39,7 @@ zselect with no file descriptors and a non-zero timeout for use as a
 finer-grained replacement for `sleep'; note, however, the return status is
 always 1 for a timeout.
 
-The option `tt(-a) var(array)' indicates that tt(array) should be set to
+The option `tt(-a) var(array)' indicates that var(array) should be set to
 indicate the file descriptor+LPAR()s+RPAR() which are ready.  If the option
 is not
 given, the array tt(reply) will be used for this purpose.  The array will
@@ -52,7 +52,7 @@ might return immediately with status 0 and tt($reply) containing `tt(-r 0 -w
 operations.
 
 The option `tt(-A) var(assoc)' indicates that the associative array
-tt(assoc) should be set to indicate the file descriptor+LPAR()s+LPAR()
+var(assoc) should be set to indicate the file descriptor+LPAR()s+RPAR()
 which are ready.  This option overrides the option tt(-a), nor will
 tt(reply) be modified.  The keys of tt(assoc) are the file descriptors, and
 the corresponding values are any of the characters `tt(rwe)' to indicate
diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
index 7e8911113..fd6f2f384 100644
--- a/Doc/Zsh/mod_zutil.yo
+++ b/Doc/Zsh/mod_zutil.yo
@@ -8,11 +8,11 @@ The tt(zsh/zutil) module only adds some builtins:
 startitem()
 findex(zstyle)
 xitem(tt(zstyle) [ tt(-L) [ var(pattern) [ var(style) ] ] ])
-xitem(tt(zstyle) [ tt(-e) | tt(-) | tt(-)tt(-) ] var(pattern) var(style) var(strings) ...)
-xitem(tt(zstyle -d) [ var(pattern) [ var(styles) ... ] ])
+xitem(tt(zstyle) [ tt(-e) | tt(-) | tt(-)tt(-) ] var(pattern) var(style) var(string) ...)
+xitem(tt(zstyle -d) [ var(pattern) [ var(style) ... ] ])
 xitem(tt(zstyle -g) var(name) [ var(pattern) [ var(style) ] ])
-xitem(tt(zstyle -abs) var(context) var(style) var(name) [ var(sep) ])
-xitem(tt(zstyle -Tt) var(context) var(style) [ var(strings) ...])
+xitem(tt(zstyle -){tt(a)|tt(b)|tt(s)} var(context) var(style) var(name) [ var(sep) ])
+xitem(tt(zstyle -){tt(T)|tt(t)} var(context) var(style) [ var(string) ... ])
 item(tt(zstyle -m) var(context) var(style) var(pattern))(
 This builtin command is used to define and lookup styles.  Styles are
 pairs of names and values, where the values consist of any number of
@@ -40,16 +40,16 @@ against the string supplied as the pattern for the context; note that
 this means, for example, `tt(zstyle -L ":completion:*")' will
 match any supplied pattern beginning `tt(:completion:)', not
 just tt(":completion:*"):  use tt(":completion:\*") to match that.
-The optional second argument limits the output to a specific style (not a
+The optional second argument limits the output to a specific var(style) (not a
 pattern).  tt(-L) is not compatible with any other options.
 
 The other forms are the following:
 
 startitem()
-item(tt(zstyle) [ tt(-) | tt(-)tt(-) | tt(-e) ] var(pattern) var(style) var(strings) ...)(
+item(tt(zstyle) [ tt(-) | tt(-)tt(-) | tt(-e) ] var(pattern) var(style) var(string) ...)(
 vindex(reply, use of)
-Defines the given var(style) for the var(pattern) with the var(strings) as
-the value.  If the tt(-e) option is given, the var(strings) will be
+Defines the given var(style) for the var(pattern) with the var(string)s as
+the value.  If the tt(-e) option is given, the var(string)s will be
 concatenated (separated by spaces) and the resulting string will be
 evaluated (in the same way as it is done by the tt(eval) builtin
 command) when the style is looked up.  In this case the parameter
@@ -58,16 +58,16 @@ evaluation.  Before evaluating the value, tt(reply) is unset, and
 if it is still unset after the evaluation, the style is treated as if
 it were not set.
 )
-item(tt(zstyle -d) [ var(pattern) [ var(styles) ... ] ])(
+item(tt(zstyle -d) [ var(pattern) [ var(style) ... ] ])(
 Delete style definitions. Without arguments all definitions are deleted,
 with a var(pattern) all definitions for that pattern are deleted and if
-any var(styles) are given, then only those styles are deleted for the
+any var(style)s are given, then only those styles are deleted for the
 var(pattern).
 )
 item(tt(zstyle -g) var(name) [ var(pattern) [ var(style) ] ])(
 Retrieve a style definition. The var(name) is
 used as the name of an array in which the results are stored. Without
-any further arguments, all var(patterns) defined are returned. With a
+any further arguments, all patterns defined are returned. With a
 var(pattern) the styles defined for that pattern are returned and with 
 both a var(pattern) and a var(style), the value strings of that
 combination is returned.
@@ -93,14 +93,14 @@ The value is stored in var(name) as an array. If var(name) is declared
 as an associative array,  the first, third, etc. strings are used as the
 keys and the other strings are used as the values.
 )
-xitem(tt(zstyle -t) var(context) var(style) [ var(strings) ...])
-item(tt(zstyle -T) var(context) var(style) [ var(strings) ...])(
+xitem(tt(zstyle -t) var(context) var(style) [ var(string) ... ])
+item(tt(zstyle -T) var(context) var(style) [ var(string) ... ])(
 Test the value of a style, i.e. the tt(-t) option only returns a status
-(sets tt($?)).  Without any var(strings) the return status is zero if the
+(sets tt($?)).  Without any var(string) the return status is zero if the
 style is defined for at least one matching pattern, has only one string in
 its value, and that is equal to one of `tt(true)', `tt(yes)', `tt(on)' or
-`tt(1)'. If any var(strings) are given the status is zero if and only if
-at least one of the var(strings) is equal to at least one of the strings
+`tt(1)'. If any var(string)s are given the status is zero if and only if
+at least one of the var(string)s is equal to at least one of the strings
 in the value. If the style is defined but doesn't match, the return status
 is tt(1). If the style is not defined, the status is tt(2).
 
@@ -115,12 +115,12 @@ var(pattern) matches at least one of the strings in the value.
 enditem()
 )
 findex(zformat)
-xitem(tt(zformat -f) var(param) var(format) var(specs) ...)
-item(tt(zformat -a) var(array) var(sep) var(specs) ...)(
+xitem(tt(zformat -f) var(param) var(format) var(spec) ...)
+item(tt(zformat -a) var(array) var(sep) var(spec) ...)(
 This builtin provides two different forms of formatting. The first form 
 is selected with the tt(-f) option. In this case the var(format)
 string will be modified by replacing sequences starting with a percent 
-sign in it with strings from the var(specs).  Each var(spec) should be
+sign in it with strings from the var(spec)s.  Each var(spec) should be
 of the form `var(char)tt(:)var(string)' which will cause every
 appearance of the sequence `tt(%)var(char)' in var(format) to be replaced 
 by the var(string).  The `tt(%)' sequence may also contain optional
@@ -132,7 +132,7 @@ width makes the result be padded with spaces to the right if the
 var(string) is shorter than the requested width.  Padding to the left
 can be achieved by giving a negative minimum field width.  If a maximum 
 field width is specified, the var(string) will be truncated after that
-many characters.  After all `tt(%)' sequences for the given var(specs)
+many characters.  After all `tt(%)' sequences for the given var(spec)s
 have been processed, the resulting string is stored in the parameter
 var(param).
 
@@ -162,7 +162,7 @@ specifier tt(c) is 3, agreeing with the digit argument to the ternary
 expression.
 
 The second form, using the tt(-a) option, can be used for aligning
-strings.  Here, the var(specs) are of the form
+strings.  Here, the var(spec)s are of the form
 `var(left)tt(:)var(right)' where `var(left)' and `var(right)' are
 arbitrary strings.  These strings are modified by replacing the colons
 by the var(sep) string and padding the var(left) strings with spaces 
@@ -179,7 +179,7 @@ item(tt(zregexparse))(
 This implements some internals of the tt(_regex_arguments) function.
 )
 findex(zparseopts)
-item(tt(zparseopts) [ tt(-D) ] [ tt(-K) ] [ tt(-M) ] [ tt(-E) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] var(specs))(
+item(tt(zparseopts) [ tt(-DKME) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] var(spec) ...)(
 This builtin simplifies the parsing of options in positional parameters,
 i.e. the set of arguments given by tt($*).  Each var(spec) describes one
 option and must be of the form `var(opt)[tt(=)var(array)]'.  If an option
@@ -191,7 +191,7 @@ Note that it is an error to give any var(spec) without an
 `tt(=)var(array)' unless one of the tt(-a) or tt(-A) options is used.
 
 Unless the tt(-E) option is given, parsing stops at the first string
-that isn't described by one of the var(specs).  Even with tt(-E),
+that isn't described by one of the var(spec)s.  Even with tt(-E),
 parsing always stops at a positional parameter equal to `tt(-)' or
 `tt(-)tt(-)'.
 
@@ -247,14 +247,14 @@ as the values.
 item(tt(-D))(
 If this option is given, all options found are removed from the positional
 parameters of the calling shell or shell function, up to but not including
-any not described by the var(specs).  This is similar to using the tt(shift)
+any not described by the var(spec)s.  This is similar to using the tt(shift)
 builtin.
 )
 item(tt(-K))(
 With this option, the arrays specified with the tt(-a) option and with the
-`tt(=)var(array)' forms are kept unchanged when none of the var(specs) for
+`tt(=)var(array)' forms are kept unchanged when none of the var(spec)s for
 them is used.  Otherwise the entire array is replaced when any of the
-var(specs) is used.  Individual elements of associative arrays specified
+var(spec)s is used.  Individual elements of associative arrays specified
 with the tt(-A) option are preserved by tt(-K).  This allows assignment of
 default values to arrays before calling tt(zparseopts).
 )
diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo
index fceb141e4..032423def 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -1037,7 +1037,7 @@ pindex(NO_GLOBAL_EXPORT)
 pindex(GLOBALEXPORT)
 pindex(NOGLOBALEXPORT)
 cindex(environment, and local parameters)
-item(tt(GLOBAL_EXPORT) (tt(<Z>)))(
+item(tt(GLOBAL_EXPORT) <Z>)(
 If this option is set, passing the tt(-x) flag to the builtins tt(declare),
 tt(float), tt(integer), tt(readonly) and tt(typeset) (but not tt(local))
 will also set the tt(-g) flag;  hence parameters exported to
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index e7fad2d76..44df07cbc 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -1675,7 +1675,7 @@ ifzman(zmanref(zshcompsys))\
 ifnzman(noderef(Completion System)).
 )
 vindex(ZLE_RPROMPT_INDENT)
-item(tt(ZLE_RPROMPT_INDENT <S>))(
+item(tt(ZLE_RPROMPT_INDENT) <S>)(
 If set, used to give the indentation between the right hand side of
 the right prompt in the line editor as given by tt(RPS1) or tt(RPROMPT)
 and the right hand side of the screen.  If not set, the value 1 is used.
diff --git a/Doc/Zsh/tcpsys.yo b/Doc/Zsh/tcpsys.yo
index 406785997..f9b403c5b 100644
--- a/Doc/Zsh/tcpsys.yo
+++ b/Doc/Zsh/tcpsys.yo
@@ -7,10 +7,10 @@ sect(Description)
 A module tt(zsh/net/tcp) is provided to provide network I/O over
 TCP/IP from within the shell; see its description in
 ifzman(\
-zmanref(zshmodules)
+zmanref(zshmodules)\
 )\
 ifnzman(\
-noderef(Zsh Modules)
+noderef(Zsh Modules)\
 ).  This manual page describes a function suite based on the module.  
 If the module is installed, the functions are usually installed at the
 same time, in which case they will be available for
@@ -19,10 +19,10 @@ tt(zsh/net/tcp) module, the tt(zsh/zselect) module is used to implement
 timeouts on read operations.  For troubleshooting tips, consult the
 corresponding advice for the tt(zftp) functions described in
 ifzman(\
-zmanref(zshzftpsys)
+zmanref(zshzftpsys)\
 )\
 ifnzman(\
-noderef(Zftp Function System)
+noderef(Zftp Function System)\
 ).
 
 There are functions corresponding to the basic I/O operations open, close,
@@ -53,9 +53,9 @@ subsect(Basic I/O)
 
 startitem()
 findex(tcp_open)
-xitem(tt(tcp_open [-qz]) var(host port) tt([) var(sess) tt(]))
-xitem(tt(tcp_open [-qz] [ -s) var(sess) tt(| -l) var(sess)tt(,... ] ... ))
-item(tt(tcp_open [-qz] [-a) var(fd) tt(| -f) var(fd) tt(] [) var(sess) tt(]))(
+xitem(tt(tcp_open) [ tt(-qz) ] var(host port) [ var(sess) ])
+xitem(tt(tcp_open) [ tt(-qz) ] [ tt(-s) var(sess) | tt(-l) var(sess)[tt(,)...] ] ... )
+item(tt(tcp_open) [ tt(-qz) ] [ tt(-a) var(fd) | tt(-f) var(fd) ] [ var(sess) ])(
 Open a new session.  In the first and simplest form, open a TCP connection
 to host var(host) at port var(port); numeric and symbolic forms are
 understood for both.
@@ -102,7 +102,7 @@ will not print informational messages, although it will in any case exit
 with an appropriate status.
 
 If the line editor (zle) is in use, which is typically the case if the
-shell is interactive, tt(tcp_open) installs a handler inside tt(zle) which
+shell is interactive, tt(tcp_open) installs a handler inside zle which
 will check for new data at the same time as it checks for keyboard input.
 This is convenient as the shell consumes no CPU time while waiting; the
 test is performed by the operating system.  Giving the option tt(-z) to
@@ -123,7 +123,7 @@ The function tt(tcp_on_open), if defined, is called when a session
 is opened.  See the description below.
 )
 findex(tcp_close)
-item(tt(tcp_close [-qn] [ -a | -l) var(sess)tt(,... |) var(sess) tt(... ]))(
+item(tt(tcp_close) [ tt(-qn) ] [ tt(-a) | tt(-l) var(sess)[tt(,)...] | var(sess) ... ])(
 Close the named sessions, or the current session if none is given,
 or all open sessions if tt(-a) is given.  The options tt(-l) and tt(-s) are
 both handled for consistency with tt(tcp_open), although the latter is
@@ -142,8 +142,9 @@ session.
 If the option tt(-q) is given, no informational messages will be printed.
 )
 findex(tcp_read)
-xitem(tt(tcp_read [-bdq] [ -t) var(TO) tt(] [ -T) var(TO) tt(]))
-item(    tt([ -a | -u) var(fd) tt(... | -l) var(sess)tt(,... | -s) var(sess) tt(...]))(
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ ))ifnztexi(         )))
+xitem(tt(tcp_read )[ tt(-bdq) ] [ tt(-t) var(TO) ] [ tt(-T) var(TO) ])
+item(SPACES()[ tt(-a) | tt(-u) var(fd)[tt(,)...] | tt(-l) var(sess)[tt(,)...] | tt(-s) var(sess) ... ])(
 Perform a read operation on the current session, or on a list of
 sessions if any are given with tt(-u), tt(-l) or tt(-s), or all open
 sessions if the option tt(-a) is given.  Any of the tt(-u), tt(-l) or
@@ -189,8 +190,8 @@ non-zero return status indicates some error condition.
 See tt(tcp_log) for how to control where data is sent by tt(tcp_read).
 )
 findex(tcp_send)
-xitem(tt(tcp_send [-cnq] [ -s) var(sess) tt(| -l) var(sess)tt(,... ]) var(data) tt(...))
-item(tt(tcp_send [-cnq] -a) var(data) tt(...))(
+xitem(tt(tcp_send) [ tt(-cnq) ] [ tt(-s) var(sess) | tt(-l) var(sess)[tt(,)...] ] var(data) ...)
+item(tt(tcp_send) [ tt(-cnq) ] tt(-a) var(data) ...)(
 Send the supplied data strings to all the specified sessions in turn.  The
 underlying operation differs little from a `tt(print -r)' to the session's
 file descriptor, although it attempts to prevent the shell from dying owing
@@ -220,9 +221,9 @@ subsect(Session Management)
 
 startitem()
 findex(tcp_alias)
-xitem(tt(tcp_alias [-q]) var(alias)tt(=)var(sess) tt(...))
-xitem(tt(tcp_alias [-q] [) var(alias) tt(] ...))
-item(tt(tcp_alias -d [-q]) var(alias) tt(...))(
+xitem(tt(tcp_alias) [ tt(-q) ] var(alias)tt(=)var(sess) ...)
+xitem(tt(tcp_alias) [ tt(-q) ] [ var(alias) ... ])
+item(tt(tcp_alias) tt(-d) [ tt(-q) ] var(alias) ...)(
 This function is not particularly well tested.
 
 The first form creates an alias for a session name; var(alias) can then be
@@ -238,14 +239,14 @@ The option tt(-q) suppresses an inconsistently chosen subset of error
 messages.
 )
 findex(tcp_log)
-item(tt(tcp_log [-asc] [ -n | -N ] [) var(logfile) tt(]))(
+item(tt(tcp_log) [ tt(-asc) ] [ tt(-n) | tt(-N) ] [ var(logfile) ])(
 With an argument var(logfile), all future input from tt(tcp_read) will be
 logged to the named file.  Unless tt(-a) (append) is given, this file will
 first be truncated or created empty.  With no arguments, show the current
 status of logging.
 
 With the option tt(-s), per-session logging is enabled.  Input from
-tt(tcp_read) is output to the file var(logfile).var(sess).  As the
+tt(tcp_read) is output to the file var(logfile)tt(.)var(sess).  As the
 session is automatically discriminated by the filename, the contents are
 raw (no tt($TCP_PROMPT)).  The option  tt(-a) applies as above.
 Per-session logging and logging of all data in one file are not mutually
@@ -265,7 +266,7 @@ item(tt(tcp_rename) var(old) var(new))(
 Rename session var(old) to session var(new).  The old name becomes invalid.
 )
 findex(tcp_sess)
-item(tt(tcp_sess [) var(sess) tt([) var(command)  tt(... ] ]))(
+item(tt(tcp_sess) [ var(sess) [ var(command) [ var(arg) ... ] ] ])(
 With no arguments, list all the open sessions and associated file
 descriptors.  The current session is marked with a star.  For use in
 functions, direct access to the parameters tt($tcp_by_name), tt($tcp_by_fd)
@@ -275,9 +276,9 @@ With a var(sess) argument, set the current session to var(sess).
 This is equivalent to changing tt($TCP_SESS) directly.
 
 With additional arguments, temporarily set the current session while
-executing the string tt(command ...).  The first argument is re-evaluated
-so as to expand aliases etc., but the remaining arguments are passed
-through as the appear to tt(tcp_sess).  The original session is restored
+executing `var(command) var(arg) ...'.  var(command) is re-evaluated
+so as to expand aliases etc., but the remaining var(arg)s are passed
+through as that appear to tt(tcp_sess).  The original session is restored
 when tt(tcp_sess) exits.
 )
 enditem()
@@ -286,7 +287,7 @@ subsect(Advanced I/O)
 
 startitem()
 findex(tcp_command)
-item(tt(tcp_command) var(send-options) tt(...) var(send-arguments) tt(...))(
+item(tt(tcp_command) var(send-option) ... var(send-argument) ...)(
 This is a convenient front-end to tt(tcp_send).  All arguments are passed
 to tt(tcp_send), then the function pauses waiting for data.  While data is
 arriving at least every tt($TCP_TIMEOUT) (default 0.3) seconds, data is
@@ -299,8 +300,9 @@ programme or function it is generally better to handle reading data by a
 more explicit method.
 )
 findex(tcp_expect)
-xitem(tt(tcp_expect [ -q ] [ -p ) var(var) tt( | -P ) var(var) tt(] [ -t ) var(to) tt(| -T) var(TO)tt(]))
-item(tt(    [ -a | -s) var(sess) tt(... | -l) var(sess)tt(,... ]) var(pattern) ...)(
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ @ @ ))ifnztexi(           )))
+xitem(tt(tcp_expect )[ tt(-q) ] [ tt(-p) var(var) | tt(-P) var(var) ] [ tt(-t) var(TO) | tt(-T) var(TO) ])
+item(SPACES()[ tt(-a) | tt(-s) var(sess) | tt(-l) var(sess)[tt(,)...] ] var(pattern) ...)(
 Wait for input matching any of the given var(pattern)s from any of the
 specified sessions.  Input is ignored until an input line matches one of
 the given patterns; at this point status zero is returned, the matching
@@ -371,8 +373,8 @@ The command is run in the background, so tt(tcp_proxy) can then accept new
 connections.  It continues to accept new connections until interrupted.
 )
 findex(tcp_spam)
-item(tt(tcp_spam [-ertv] [ -a | -s ) var(sess) tt(| -l) var(sess)tt(,... ]) var(cmd) tt(...))(
-Execute `var(cmd) tt(...)' for each session in turn.  Note this executes
+item(tt(tcp_spam) [ tt(-ertv) ] [ tt(-a) | tt(-s) var(sess) | tt(-l) var(sess)[tt(,)...] ] var(cmd) [ var(arg) ... ])(
+Execute `var(cmd) [ var(arg) ... ]' for each session in turn.  Note this executes
 the command and arguments; it does not send the command line as data
 unless the tt(-t) (transmit) option is given.
 
@@ -389,19 +391,19 @@ tt($tcp_spam_list) array or on the command line are spammed in the order
 given.  The tt(-r) flag reverses the order however it was arrived it.
 
 The tt(-v) flag specifies that a tt($TCP_PROMPT) will be output before each
-session.  This is output after any modification to TCP_SESS by the
+session.  This is output after any modification to tt(TCP_SESS) by the
 user-defined tt(tcp_on_spam) function described below.  (Obviously that
 function is able to generate its own output.)
 
-If the option tt(-e) is present, the line given as var(cmd ...) is executed
+If the option tt(-e) is present, the line given as `var(cmd) [ var(arg) ... ]' is executed
 using tt(eval), otherwise it is executed without any further processing.
 )
 findex(tcp_talk)
 item(tt(tcp_talk))(
 This is a fairly simple-minded attempt to force input to the line editor to
-go straight to the default TCP_SESSION.
+go straight to the default tt(TCP_SESS).
 
-An escape string, tt($TCP_TALK_ESCAPE), default `:', is used to allow
+An escape string, tt($TCP_TALK_ESCAPE), default `tt(:)', is used to allow
 access to normal shell operation.  If it is on its own at the start of the
 line, or followed only by whitespace, the line editor returns to normal
 operation.  Otherwise, the string and any following whitespace are skipped
@@ -507,7 +509,7 @@ This is called after a session has been renamed with the three arguments
 old session name, file descriptor, new session name.
 )
 findex(tcp_on_spam)
-item(tt(tcp_on_spam) var(sess) var(command) tt(...))(
+item(tt(tcp_on_spam) var(sess) var(command ...))(
 This is called once for each session spammed, just em(before) a command is
 executed for a session by tt(tcp_spam).  The arguments are the session name
 followed by the command list to be executed.  If tt(tcp_spam) was called
@@ -554,7 +556,7 @@ tt(tcp_on_read)) to tell if is being called when the shell is otherwise
 idle at the editor prompt.
 )
 findex(tcp_output)
-item(tt(tcp_output [ -q ] -P) var(prompt) tt(-F) var(fd) tt(-S) var(sess))(
+item(tt(tcp_output) [ tt(-q) ] tt(-P) var(prompt) tt(-F) var(fd) tt(-S) var(sess))(
 This function is used for both logging and handling output to standard
 output, from within tt(tcp_read) and (if tt($TCP_OUTPUT) is set)
 tt(tcp_send).
@@ -786,7 +788,7 @@ sect(TCP Examples)
 
 Here is a trivial example using a remote calculator.
 
-TO create a calculator server on port 7337 (see the tt(dc) manual page for
+To create a calculator server on port 7337 (see the tt(dc) manual page for
 quite how infuriating the underlying command is):
 
 example(tcp_proxy 7337 dc)
diff --git a/Doc/Zsh/zftpsys.yo b/Doc/Zsh/zftpsys.yo
index 56308302c..00062e43d 100644
--- a/Doc/Zsh/zftpsys.yo
+++ b/Doc/Zsh/zftpsys.yo
@@ -75,10 +75,10 @@ are treated literally (a single `tt(-)' is treated as an argument).
 subsect(Opening a connection)
 startitem()
 findex(zfparams)
-item(tt(zfparams [ var(host) [ var(user) [ var(password) ... ] ] ]))(
+item(tt(zfparams) [ var(host) [ var(user) [ var(password) ... ] ] ])(
 Set or show the parameters for a future tt(zfopen) with no arguments.  If
 no arguments are given, the current parameters are displayed (the password
-will be shown as a line of asterisks).  If a host is given, and either the
+will be shown as a line of asterisks).  If a var(host) is given, and either the
 var(user) or var(password) is not, they will be prompted for; also, any
 parameter given as `tt(?)' will be prompted for, and if the `tt(?)' is
 followed by a string, that will be used as the prompt.  As tt(zfopen) calls
@@ -90,7 +90,7 @@ also cause the memory of the last directory (and so on) on the other host
 to be deleted.
 )
 findex(zfopen)
-item(tt(zfopen [ -1 ] [ var(host) [ var(user) [ var(password) [ var(account) ] ] ] ]))(
+item(tt(zfopen) [ tt(-1) ] [ var(host) [ var(user) [ var(password) [ var(account) ] ] ] ])(
 If var(host) is present, open a connection to that host under username
 var(user) with password var(password) (and, on the rare occasions when it
 is necessary, account var(account)).  If a necessary parameter is missing or
@@ -119,7 +119,7 @@ to trigger recognition of the var(path).  Note prefixes other than
 slash beyond var(host) are significant in var(path).
 )
 findex(zfanon)
-item(tt(zfanon [ -1 ] var(host)))(
+item(tt(zfanon) [ tt(-1) ] var(host))(
 Open a connection var(host) for anonymous FTP.  The username used is
 `tt(anonymous)'.  The password (which will be reported the first time) is
 generated as var(user)tt(@)var(host); this is then stored in the shell
@@ -131,9 +131,9 @@ enditem()
 subsect(Directory management)
 startitem()
 findex(zfcd)
-xitem(tt(zfcd [ var(dir) ]))
+xitem(tt(zfcd) [ var(dir) ])
 xitem(tt(zfcd -))
-item(tt(zfcd var(old) var(new)))(
+item(tt(zfcd) var(old) var(new))(
 Change the current directory on the remote server:  this is implemented to
 have many of the features of the shell builtin tt(cd).
 
@@ -168,7 +168,7 @@ For example, if the current local directory is tt(~/foo/bar), then
 tt(zfhere) performs the effect of `tt(zfcd ~/foo/bar)'.
 )
 findex(zfdir)
-item(tt(zfdir [ -rfd ] [ - ] [ var(dir-options) ] [ var(dir) ]))(
+item(tt(zfdir) [ tt(-rfd) ] [ tt(-) ] [ var(dir-options) ] [ var(dir) ])(
 Produce a long directory listing.  The arguments var(dir-options) and
 var(dir) are passed directly to the server and their effect is
 implementation dependent, but specifying a particular remote directory
@@ -207,7 +207,7 @@ or binary.  With an argument, change the type: the types `tt(A)' or
 `tt(IMAGE)' for binary data are understood case-insensitively.
 )
 findex(zfstat)
-item(tt(zfstat) [ -v ])(
+item(tt(zfstat) [ tt(-v) ])(
 Show the status of the current or last connection, as well as the status of
 some of tt(zftp)'s status variables.  With the tt(-v) option, a more
 verbose listing is produced by querying the server for its version of
@@ -224,7 +224,7 @@ see the description of the function tt(zfrtime) below for more information.
 
 startitem()
 findex(zfget)
-item(tt(zfget [ -Gtc ] var(file1) ...))(
+item(tt(zfget) [ tt(-Gtc) ] var(file1) ...)(
 Retrieve all the listed files var(file1) ... one at a time from the remote
 server.  If a file contains a `tt(/)', the full name is passed to the
 remote server, but the file is stored locally under the name given by the
@@ -233,7 +233,7 @@ be sent as a single stream to standard output; in this case the tt(-t)
 option has no effect.
 )
 findex(zfuget)
-item(tt(zfuget [ -Gvst ] var(file1) ...))(
+item(tt(zfuget) [ tt(-Gvst) ] var(file1) ...)(
 As tt(zfget), but only retrieve files where the version on the remote
 server is newer (has a later modification time), or where the local file
 does not exist.  If the remote file is older but the files have different
@@ -244,7 +244,7 @@ option tt(-v), the command prints more information about the files while it
 is working out whether or not to transfer them.
 )
 findex(zfcget)
-item(tt(zfcget [ -Gt ] var(file1) ...))(
+item(tt(zfcget) [ tt(-Gt) ] var(file1) ...)(
 As tt(zfget), but if any of the local files exists, and is shorter than
 the corresponding remote file, the command assumes that it is the result of
 a partially completed transfer and attempts to transfer the rest of the
@@ -254,8 +254,8 @@ Note that this requires a commonly implemented, but non-standard, version
 of the FTP protocol, so is not guaranteed to work on all servers.
 )
 findex(zfgcp)
-xitem(tt(zfgcp [ -Gt ] var(remote-file) var(local-file)))
-item(tt(zfgcp [ -Gt ] var(rfile1) ... var(ldir)))(
+xitem(tt(zfgcp) [ tt(-Gt) ] var(remote-file) var(local-file))
+item(tt(zfgcp) [ tt(-Gt) ] var(rfile1) ... var(ldir))(
 This retrieves files from the remote server with arguments behaving
 similarly to the tt(cp) command.
 
@@ -271,7 +271,7 @@ enditem()
 subsect(Sending files)
 startitem()
 findex(zfput)
-item(tt(zfput [ -r ] var(file1) ...))(
+item(tt(zfput) [ tt(-r) ] var(file1) ...)(
 Send all the var(file1) ... given separately to the remote server.  If a
 filename contains a `tt(/)', the full filename is used locally to find the
 file, but only the basename is used for the remote file name.
@@ -282,13 +282,13 @@ with `tt(.)'.  This requires that the remote machine understand UNIX file
 semantics, since `tt(/)' is used as a directory separator.
 )
 findex(zfuput)
-item(tt(zfuput [ -vs ] var(file1) ...))(
+item(tt(zfuput) [ tt(-vs) ] var(file1) ...)(
 As tt(zfput), but only send files which are newer than their local
 equivalents, or if the remote file does not exist.  The logic is the same
 as for tt(zfuget), but reversed between local and remote files.
 )
 findex(zfcput)
-item(tt(zfcput var(file1) ...))(
+item(tt(zfcput) var(file1) ...)(
 As tt(zfput), but if any remote file already exists and is shorter than the
 local equivalent, assume it is the result of an incomplete transfer and
 send the rest of the file to append to the existing part.  As the FTP
@@ -296,8 +296,8 @@ append command is part of the standard set, this is in principle more
 likely to work than tt(zfcget).
 )
 findex(zfpcp)
-xitem(tt(zfpcp var(local-file) var(remote-file)))
-item(tt(zfpcp var(lfile1) ... var(rdir)))(
+xitem(tt(zfpcp) var(local-file) var(remote-file))
+item(tt(zfpcp) var(lfile1) ... var(rdir))(
 This sends files to the remote server with arguments behaving similarly to
 the tt(cp) command.
 
@@ -381,7 +381,7 @@ directory where your zsh startup files live (usually tt(~)).
 
 startitem()
 findex(zfmark)
-item(tt(zfmark [ )var(bookmark)tt( ]))(
+item(tt(zfmark) [ var(bookmark) ])(
 If given an argument, mark the current host, user and directory under the
 name var(bookmark) for later use by tt(zfgoto).  If there is no connection
 open, use the values for the last connection immediately before it was
@@ -394,7 +394,7 @@ this is the format in which they are stored, and the file may be edited
 directly.
 )
 findex(zfgoto)
-item(tt(zfgoto [ -n ] )var(bookmark))(
+item(tt(zfgoto) [ tt(-n) ] var(bookmark))(
 Return to the location given by var(bookmark), as previously set by
 tt(zfmark).  If the location has user `tt(ftp)' or `tt(anonymous)', open
 the connection with tt(zfanon), so that no password is required.  If the
@@ -417,13 +417,13 @@ alter tt(zftp_chpwd) and tt(zftp_progress), in particular.
 
 startitem()
 findex(zfinit)
-item(tt(zfinit [ -n ]))(
+item(tt(zfinit) [ tt(-n) ])(
 As described above, this is used to initialize the zftp function system.
 The tt(-n) option should be used if the zftp command is already built into
 the shell.
 )
 findex(zfautocheck)
-item(tt(zfautocheck [ -dn ]))(
+item(tt(zfautocheck) [ tt(-dn) ])(
 This function is called to implement automatic reopening behaviour, as
 described in more detail below.  The options must appear in the first
 argument; tt(-n) prevents the command from changing to the old directory,
@@ -458,7 +458,7 @@ were any matches, the same variable will be set to the expanded set of
 filenames on return.
 )
 findex(zfrtime)
-item(tt(zfrtime var(lfile) var(rfile) [ var(time) ]))(
+item(tt(zfrtime) var(lfile) var(rfile) [ var(time) ])(
 Set the local file var(lfile) to have the same modification time as the
 remote file var(rfile), or the explicit time var(time) in FTP format
 tt(CCYYMMDDhhmmSS) for the GMT timezone.  This uses the shell's
@@ -556,12 +556,12 @@ As described for tt(progress), tt(zfinit) will force this to default to 1.
 )
 kindex(remote-glob, zftp style)
 item(tt(remote-glob))(
-If set to `1', `yes' or `true', filename generation (globbing) is
+If set to `tt(1)', `tt(yes)' or `tt(true)', filename generation (globbing) is
 performed on the remote machine instead of by zsh itself; see below.
 )
 kindex(titlebar, zftp style)
 item(tt(titlebar))(
-If set to `1', `yes' or `true', tt(zftp_chpwd) will put the remote host and
+If set to `tt(1)', `tt(yes)' or `tt(true)', tt(zftp_chpwd) will put the remote host and
 remote directory into the titlebar of terminal emulators such as xterm or
 sun-cmd that allow this.
 
@@ -569,7 +569,7 @@ As described for tt(progress), tt(zfinit) will force this to default to 1.
 )
 kindex(chpwd, zftp style)
 item(tt(chpwd))(
-If set to `1' `yes' or `true', tt(zftp_chpwd) will call the function
+If set to `tt(1)' `tt(yes)' or `tt(true)', tt(zftp_chpwd) will call the function
 tt(chpwd) when a connection is closed.  This is useful if the remote host
 details were put into the terminal title bar by tt(zftp_chpwd) and your
 usual tt(chpwd) also modifies the title bar.
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index c7835675f..16d661f06 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -339,10 +339,11 @@ by `tt(bindkey -m)'.
 findex(vared)
 cindex(parameters, editing)
 cindex(editing parameters)
-xitem(tt(vared) [ tt(-Aache) ] [ tt(-p) var(prompt) ] [ tt(-r) var(rprompt) ])
-xitem(  [ tt(-M) var(main-keymap) ] [ tt(-m) var(vicmd-keymap) ])
-xitem(  [ tt(-i) var(init-widget) ] [ tt(-f) var(finish-widget) ])
-item(  [ tt(-t) var(tty) ] var(name))(
+redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ ))ifnztexi(      )))
+xitem(tt(vared )[ tt(-Aache) ] [ tt(-p) var(prompt) ] [ tt(-r) var(rprompt) ])
+xitem(SPACES()[ tt(-M) var(main-keymap) ] [ tt(-m) var(vicmd-keymap) ])
+xitem(SPACES()[ tt(-i) var(init-widget) ] [ tt(-f) var(finish-widget) ])
+item(SPACES()[ tt(-t) var(tty) ] var(name))(
 The value of the parameter var(name) is loaded into the edit
 buffer, and the line editor is invoked.  When the editor exits,
 var(name) is set to the string value returned by the editor.