35075: improve manual format

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

1 files changed, 41 insertions, 36 deletions

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.
 )