PATCH: doc changes

[Peter Stephenson <pws@xxxxxxxxxxxxxxxxxxxxxxxx>]

I finally finished looking through the docs.  Unfortunately Bart meanwhile
changed the order of compsys.yo, so it'll be another hour's work to sort
that out and it won't appear in 3.1.7-pre-4.  Here are the rest of the
changes.

Index: Doc/Zsh/mod_complist.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/mod_complist.yo,v
retrieving revision 1.8
diff -u -r1.8 mod_complist.yo
--- Doc/Zsh/mod_complist.yo	2000/05/11 08:40:11	1.8
+++ Doc/Zsh/mod_complist.yo	2000/05/21 18:18:51
@@ -18,13 +18,13 @@
 vindex(ZLS_COLORS)
 vindex(ZLS_COLOURS)
 The parameters tt(ZLS_COLORS) and tt(ZLS_COLOURS) describe how matches
-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
+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,
-most of which specify file types for which the var(value) will be used. The
-strings and their default values are:
+`var(name)=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:
 
 startitem()
 item(tt(no 0))(
@@ -55,7 +55,7 @@
 for executable files
 )
 item(tt(mi) var(none))(
-for non-existent file (default is the value defined for tt(fi))
+for a non-existent file (default is the value defined for tt(fi))
 )
 item(tt(lc \e[))(
 for the left code (see below)
@@ -79,31 +79,31 @@
 (`tt(*)') followed by any string. The var(value) given for such a
 string will be used for all files whose name ends with the string.
 The var(name) may also be a equal sign (`tt(=)') followed by a
-pattern. The var(value) given for this pattern will be used for all
-matches (not only filenames) whose display string are matched by
-the pattern. Definitions for both of these take precedence over the
+pattern.  The var(value) given for this pattern will be used for all
+matches (not just filenames) whose display string are matched by
+the pattern.  Definitions for both of these take precedence over the
 values defined for file types and the form with the leading asterisk 
 takes precedence over the form with the leading equal sign.
 
-The last form also allows to color separate parts of the displayed
-strings using different colors. For this, the pattern has to use the
+The last form also allows different parts of the displayed
+strings to be colored differently.  For this, the pattern has to use the
 `tt((#b))' globbing flag and pairs of parentheses surrounding the
-parts of the strings that are to be colored differently. In this case 
+parts of the strings that are to be colored differently.  In this case 
 the var(value) may consist of more than one color code separated by
-equal signs. The first code will be used for all parts for which no
+equal signs.  The first code will be used for all parts for which no
 explicit code is specified and the following codes will be used for
-the parts matched by the sub-patterns in parentheses. For example,
+the parts matched by the sub-patterns in parentheses.  For example,
 the specification `tt(=(#b)(?)*(?)=0=3=7)' will be used for all
 matches which are at least two characters long and will make the use
 the code `tt(3)' for the first character, `tt(7)' for the last
 character and `tt(0)' for the rest.
 
 All three forms of var(name) may be preceded by a pattern in
-parentheses. If such a pattern is given, the var(value) will be used
+parentheses.  If this is given, the var(value) will be used
 only for matches in groups whose names are matched by the pattern
-given in the parentheses. E.g. `tt((g*)m*=43)' says to highlight all
+given in the parentheses.  For example, `tt((g*)m*=43)' highlights all
 matches beginning with `tt(m)' in groups whose names  begin with
-`tt(g)' using the color code `tt(43)'. In case of the `tt(lc)',
+`tt(g)' using the color code `tt(43)'.  In case of the `tt(lc)',
 `tt(rc)', and `tt(ec)' codes, the group pattern is ignored.
 
 Note also that all patterns are tried in the order in which they
@@ -117,38 +117,39 @@
 tt(no), and tt(rc) if tt(ec) is not defined.
 
 The default values are ISO 6429 (ANSI) compliant and can be used on
-vt100 compatible terminals such as tt(xterm)s. On monochrome terminals
-the default values will have no visual effect.
+vt100 compatible terminals such as tt(xterm)s.  On monochrome terminals
+the default values will have no visible effect.
 
-If the shell function based completion system is used, these
+If the completion system based around shell functions is used, these
 parameters should not be set directly because the system controls them 
-itself. Instead, the tt(list-colors) style should be used (see
+itself.  Instead, the tt(list-colors) style should be used (see
 ifzman(the section `Completion System Configuration' in zmanref(zshcompsys))\
 ifnzman(noderef(Completion System Configuration))\
 ).
 
 subsect(Scrolling in completion listings)
-To be able to scroll through a completion list, the tt(LISTPROMPT)
-parameter has to be set. Its value will be used as the prompt, if it
+To enable scrolling through a completion list, the tt(LISTPROMPT)
+parameter must be set.  Its value will be used as the prompt; if it
 is the empty string, a default prompt will be used.  The value may
-contain escapes of the form `tt(%x)'. It supports the escapes
+contain escapes of the form `tt(%x)'.  It supports the escapes
 `tt(%B)', `tt(%b)', `tt(%S)', `tt(%s)', `tt(%U)', `tt(%u)' and
-`tt(%{...%})' known from the shell prompts and three pairs of
-additional sequences. A `tt(%l)' or `tt(%L)' is replaced by the number
+`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
-the number of the last match shown and the total number of matches and 
+`var(number)tt(/)var(total)'; a `tt(%m)' or `tt(%M)' is replaced with
+the number of the last match shown and the total number of matches; and 
 `tt(%p)' or `tt(%P)' is replaced with `tt(Top)', `tt(Bottom)' or the
 position of the first line shown in percent of the total number of
-lines, respectively. In each of these cases the one with the uppercase
+lines, respectively.  In each of these cases the form with the uppercase
 letter will be replaced with a string of fixed width, padded to the
-right with spaces.
+right with spaces, while the lowercase form will not be padded.
 
-If tt(LISTPROMPT) is set, the completion code will not ask if the list
-should be shown. Instead it immediately starts displaying the list,
-stopping after the first screenful, showing the prompt at the bottom,
-waiting for a keypress after temporarily switching to the
-tt(listscroll) keymap. Some of the zle functions have special meaning:
+If the option att(LISTPROMPT) is set, the completion code will not ask if
+the list should be shown.  Instead it immediately starts displaying the
+list, stopping after the first screenful, showing the prompt at the bottom,
+waiting for a keypress after temporarily switching to the tt(listscroll)
+keymap.  Some of the zle functions have a special meaning while scrolling
+lists:
 
 startitem()
 item(tt(send-break))(
@@ -165,13 +166,13 @@
 enditem()
 
 Every other character stops listing and immediately processes the key
-as usual. Any key that is not bound in the tt(listscroll) keymap or
+as usual.  Any key that is not bound in the tt(listscroll) keymap or
 that is bound to tt(undefined-key) is looked up in the keymap
 currently selected.
 
 As for the tt(ZLS_COLORS) and tt(ZLS_COLOURS) parameters,
 tt(LISTPROMPT) should not be set directly when using the shell
-function based completion system. Instead, the tt(list-prompt) style
+function based completion system.  Instead, the tt(list-prompt) style
 should be used.
 
 subsect(Menu selection)
@@ -184,7 +185,7 @@
 completion list (see the tt(ALWAYS_LAST_PROMPT) option in
 ifzman(zmanref(zshoptions))\
 ifnzman(noderef(Options))\
-). It can be invoked directly by
+).  It can be invoked directly by
 the widget tt(menu-select) defined by the module.  Alternatively,
 the parameter tt(MENUSELECT) can be set to an integer, which give the
 minimum number of matches that must be present before menu selection is
@@ -194,58 +195,58 @@
 tt(MENUSELECT) is set, but is 0, 1 or empty, menu selection will always be
 started during an ambiguous menu completion.
 
-When using the shell function based completion system, the
+When using the completion system based on shell functions, the
 tt(MENUSELECT) parameter should not be used (like the tt(ZLS_COLORS)
-and tt(ZLS_COLOURS) parameters described above). Instead, the tt(menu) 
-style should be used.
+and tt(ZLS_COLOURS) parameters described above).  Instead, the tt(menu) 
+style should be used with the tt(select=)var(...) keyword.
 
 After menu-selection is started, the matches will be listed. If there
 are more matches than fit on the screen, only the first screenful is
-shown. The
+shown.  The
 matches to insert into the command line can be selected from this
-list. In the list one match is highlighted using the value for tt(ma)
-from the tt(ZLS_COLORS) or tt(ZLS_COLOURS) parameter. The default
+list.  In the list one match is highlighted using the value for tt(ma)
+from the tt(ZLS_COLORS) or tt(ZLS_COLOURS) parameter.  The default
 value for this is `tt(7)' which forces the selected match to be
-highlighted using standout mode on a vt100-compatible terminal. If
+highlighted using standout mode on a vt100-compatible terminal.  If
 neither tt(ZLS_COLORS) nor tt(ZLS_COLOURS) is set, the same terminal
 control sequence as for the `tt(%S)' escape in prompts is used.
 
 If there are more matches than fit on the screen and the parameter
-tt(MENUPROMPT) is set, its value will be shown below the matches. It
+tt(MENUPROMPT) is set, its value will be shown below the matches.  It
 supports the same escape sequences as tt(LISTPROMPT), but the number
 of the match or line shown will be that of the one where the mark is
-placed. If its value is the empty string, a default prompt will be
+placed.  If its value is the empty string, a default prompt will be
 used.
 
 The tt(MENUSCROLL) parameter can be used to specify how the list is
-scrolled. If the parameter is unset, this is done line by line, if it
+scrolled.  If the parameter is unset, this is done line by line, if it
 is set to `tt(0)' (zero), the list will scrolled half the number of
-lines of the screen. If the value is positive, it gives the number of
+lines of the screen.  If the value is positive, it gives the number of
 lines to scroll and if it is negative, the list will be scrolled
 the number of lines of the screen minus the (absolute) value.
 
 As for the tt(ZLS_COLORS), tt(ZLS_COLOURS) and tt(LISTPROMPT)
 parameters, neither tt(MENUPROMPT) nor tt(MENUSCROLL) should be
 set directly when using the shell function based completion
-system. Instead, the tt(select-prompt) and tt(select-scroll) styles
+system.  Instead, the tt(select-prompt) and tt(select-scroll) styles
 should be used.
 
 The completion code sometimes decides not to show all of the matches
-in the list. These hidden matches are either matches for which the
+in the list.  These hidden matches are either matches for which the
 completion function which added them explicitly requested that they
 not appear in the list (using the tt(-n) option of the tt(compadd)
 builtin command) or they are matches which duplicate a string already
 in the list (because they differ only in things like prefixes or
-suffixes that are not displayed). In the list used for menu-selection,
+suffixes that are not displayed).  In the list used for menu-selection,
 however, even these matches are shown so that it is possible to select
-them. To highlight such matches the tt(hi) and tt(du) capabilities in
+them.  To highlight such matches the tt(hi) and tt(du) capabilities in
 the tt(ZLS_COLORS) and tt(ZLS_COLOURS) parameters are supported for
 hidden matches of the first and second kind, respectively.
 
 Selecting matches is done by moving the mark around using the zle movement
-functions. When not all matches can be shown on the screen at the same 
+functions.  When not all matches can be shown on the screen at the same 
 time, the list will scroll up and down when crossing the top or
-bottom line. The following zle functions have special meaning during
+bottom line.  The following zle functions have special meaning during
 menu selection:
 
 startitem()
@@ -322,18 +323,17 @@
 )
 enditem()
 
-All movement function do wrap-around at the edges and
-any other zle function leaves menu-selection and executes that function.
-It is possible to make widgets in the above list do the same by using the
-form of the widget with a `tt(.)' in front.  For example, the widget
-`tt(.accept-line)' has the effect of leaving menu selection and accepting
-the entire command line.
+All movement functions wrap around at the edges; any other zle function not
+listed leaves menu-selection and executes that function.  It is possible to
+make widgets in the above list do the same by using the form of the widget
+with a `tt(.)' in front.  For example, the widget `tt(.accept-line)' has
+the effect of leaving menu selection and accepting the entire command line.
 
-During this selection the widget uses the keymap tt(menuselect). Any
+During this selection the widget uses the keymap tt(menuselect).  Any
 key that is not defined in this keymap or that is bound to
-tt(undefined-key) is looked up in the keymap currently selected. This
+tt(undefined-key) is looked up in the keymap currently selected.  This
 is used to ensure that the most important keys used during selection
-have sensible default (namely the cursor keys, return, and TAB). However,
+(namely the cursor keys, return, and TAB) have sensible defaults.  However,
 keys in the the tt(menuselect) keymap can be modified directly using the
 tt(bindkey) builtin command (see
 ifzman(zmanref(zshmodules))\
Index: Doc/Zsh/mod_computil.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/mod_computil.yo,v
retrieving revision 1.2
diff -u -r1.2 mod_computil.yo
--- Doc/Zsh/mod_computil.yo	2000/05/11 00:01:03	1.2
+++ Doc/Zsh/mod_computil.yo	2000/05/21 18:18:51
@@ -4,22 +4,22 @@
 !MOD!)
 cindex(completion, utility)
 The tt(zsh/computil) module adds several builtin commands that are used by
-some of the completion functions in the shell function based
-completions system (see
+some of the completion functions in the completion system based on shell
+functions (see 
 ifzman(zmanref(zshcompsys))\
 ifnzman(noderef(Completion System))
-). Except for tt(compquote) these builtin commands are very
+).  Except for tt(compquote) these builtin commands are very
 specialised and thus not very interesting when writing your own
-completion functions. In short, these builtin commands are:
+completion functions.  In summary, these builtin commands are:
 
 startitem()
 item(tt(compquote) var(names) ...)(
 There may be reasons to write completion functions that have to add
-the matches using the tt(-Q) option to tt(compadd) and do the quoting
-themselves. Instead of interpreting the first character of the
+the matches using the tt(-Q) option to tt(compadd) and perform quoting
+themselves.  Instead of interpreting the first character of the
 tt(all_quotes) key of the tt(compstate) special association and using
 the tt(q) flag for parameter expansions, one can use this builtin
-command. The arguments are the names of scalar or array parameters
+command.  The arguments are the names of scalar or array parameters
 and the values of these parameters are quoted as needed for the
 innermost quoting level.
 
@@ -28,25 +28,25 @@
 item(tt(compdescribe))(
 This is used by the tt(_describe) function to build the displays for
 the matches and to get the strings to add as matches with their
-options. The first call has to give the tt(-i) or tt(-I) option as the 
-first argument. In the first case, display strings without the
-descriptions will be generated, in the second case, the string used to
-separate the matches from their descriptions has to be given as the
-second argument and the descriptions (if any) will be shown. All other 
+options.  On the first call one of the options tt(-i) or tt(-I) should be
+supplied as the first argument.  In the first case, display strings without
+the descriptions will be generated, in the second case, the string used to
+separate the matches from their descriptions must be given as the
+second argument and the descriptions (if any) will be shown.  All other 
 arguments are like the definition arguments to tt(_describe) itself.
 
 Once tt(compdescribe) has been called with either the tt(-i) or the
 tt(-I) option, it can be repeatedly called with the tt(-g) option and
-the names of five arrays as its arguments. This will step through the
+the names of five arrays as its arguments.  This will step through the
 different sets of matches and store the options in the first array,
 the strings with descriptions in the second, the matches for these in
 the third, the strings without descriptions in the fourth, and the
-matches for them in the fifth array. These are then directly given to
+matches for them in the fifth array.  These are then directly given to
 tt(compadd) to register the matches with the completion code.
 )
 item(tt(comparguments))(
 This is used by the tt(_arguments) function to do the argument and
-command line parsing. Like tt(compdescribe) it has an option tt(-i) to 
+command line parsing.  Like tt(compdescribe) it has an option tt(-i) to 
 do the parsing and initialize some internal state and various options
 to access the state information to decide what should be completed.
 )
Index: Doc/Zsh/mod_parameter.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/mod_parameter.yo,v
retrieving revision 1.2
diff -u -r1.2 mod_parameter.yo
--- Doc/Zsh/mod_parameter.yo	2000/05/11 00:01:03	1.2
+++ Doc/Zsh/mod_parameter.yo	2000/05/21 18:18:53
@@ -28,7 +28,7 @@
 )
 vindex(functions)
 item(tt(functions))(
-This association maps names of enabled functions to their
+This associative array maps names of enabled functions to their
 definitions. Setting a key in it is like defining a function with the
 name given by the key and the body given by the value. Unsetting a key
 removes the definition for the function named by the key.
@@ -39,7 +39,7 @@
 )
 vindex(builtins)
 item(tt(builtins))(
-This association gives information about the builtin commands
+This associative array gives information about the builtin commands
 currently enabled. The keys are the names of the builtin commands and
 the values are either `tt(undefined)' for builtin commands that will
 automatically be loaded from a module if invoked or `tt(defined)' for
@@ -90,7 +90,7 @@
 )
 vindex(modules)
 item(tt(modules))(
-An association giving information about module. The keys are the names
+An associative array giving information about modules. The keys are the names
 of the modules builtin, loaded, or registered to be autoloaded. The
 value says which state the named module is in and is one of the
 strings tt(builtin), tt(loaded), or tt(autoloaded).
@@ -105,7 +105,7 @@
 )
 vindex(history)
 item(tt(history))(
-This association maps history event numbers to the full history lines.
+This associative array maps history event numbers to the full history lines.
 )
 vindex(historywords)
 item(tt(historywords))(
@@ -113,16 +113,17 @@
 )
 vindex(jobdirs)
 item(tt(jobdirs))(
-This association maps job numbers to the directories from which the job was started (which may not be the current directory of the job).
+This associative array maps job numbers to the directories from which the
+job was started (which may not be the current directory of the job).
 )
 vindex(jobtexts)
 item(tt(jobtexts))(
-This association maps job numbers to the texts of the command lines
+This associative array maps job numbers to the texts of the command lines
 that were used to start the jobs.
 )
 vindex(jobstates)
 item(tt(jobstates))(
-This association gives information about the states of the jobs
+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(pid)tt(=)var(state)tt(...)'. The var(job-state)
@@ -134,12 +135,12 @@
 )
 vindex(nameddirs)
 item(tt(nameddirs))(
-This association maps the names of named directories to the pathnames
+This associative array maps the names of named directories to the pathnames
 they stand for.
 )
 vindex(userdirs)
 item(tt(userdirs))(
-This association maps user names to the pathnames of their home
+This associative array maps user names to the pathnames of their home
 directories.
 )
 vindex(funcstack)
Index: Doc/Zsh/mod_zle.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/mod_zle.yo,v
retrieving revision 1.4
diff -u -r1.4 mod_zle.yo
--- Doc/Zsh/mod_zle.yo	2000/05/11 00:01:03	1.4
+++ Doc/Zsh/mod_zle.yo	2000/05/21 18:18:54
@@ -259,20 +259,20 @@
 )
 item(tt(-M) var(string))(
 As with the tt(-R) option, the var(string) will be displayed below the 
-command line. But unlike the tt(-R) option the string not be put into
+command line; unlike the tt(-R) option, the string will not be put into
 the status line but will instead be printed normally below the
-prompt. This means that the var(string) will still be displayed after
+prompt.  This means that the var(string) will still be displayed after
 the widget returns (until it is overwritten by subsequent commands).
 )
 item(tt(-U) var(string))(
 This pushes the characters in the var(string) onto the input stack of
-ZLE. After the widget currently executed finishes ZLE will behave as
+ZLE.  After the widget currently executed finishes ZLE will behave as
 if the characters in the var(string) were typed by the user.
 
-Note that since ZLE uses a stack, using tt(zle) with this option more
-than once will make the last string pushed be used first. The
-characters in each var(string) will be used in the order in which they
-appear in the string, though.
+As ZLE uses a stack, if this option is used repeatedly
+the last string pushed onto the stack will be processed first.  However,
+the characters in each var(string) will be processed in the order in which
+they appear in the string.
 )
 item(var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)(
 Invoke the specified widget.  This can only be done when ZLE is
@@ -303,7 +303,7 @@
 )
 enditem()
 
-With no options and no arguments, only the returns status will be
+With no options and no arguments, only the return status will be
 set. It is zero if ZLE is currently active and widgets could be
 invoked using this builtin command and non-zero if ZLE is not active.
 )
Index: Doc/Zsh/mod_zprof.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/mod_zprof.yo,v
retrieving revision 1.1.1.2
diff -u -r1.1.1.2 mod_zprof.yo
--- Doc/Zsh/mod_zprof.yo	1999/12/20 11:24:40	1.1.1.2
+++ Doc/Zsh/mod_zprof.yo	2000/05/21 18:18:54
@@ -2,60 +2,59 @@
 A module allowing profiling for shell functions.
 !MOD!)
 cindex(functions, profiling)
-When loaded, the tt(zsh/zprof) module makes shell functions be
-profiled. The profiling results can be obtained with the tt(zprof)
-builtin command made available by this module. There is no way to turn 
-profiling off other than unloading this module.
+When loaded, the tt(zsh/zprof) causes shell functions to be profiled.
+The profiling results can be obtained with the tt(zprof)
+builtin command made available by this module.  There is no way to turn 
+profiling off other than unloading the module.
 
 startitem()
 findex(zprof)
 item(tt(zprof) [ tt(-c) ])(
 Without the tt(-c) option, tt(zprof) lists profiling results to
-standard output. The format is comparable to that of commands like
+standard output.  The format is comparable to that of commands like
 tt(gprof).
 
 At the top there is a summary listing all functions that were called
-at least once. This summary is sorted in decreasing order by the
-amount of time spent in the functions themselves. Each line is
-preceded by the number of the function in this order (which is used in 
+at least once.  This summary is sorted in decreasing order of the
+amount of time spent in each.  The lines contain
+the number of the function in order, which is used in 
 other parts of the list in suffixes of the form
-`tt([)var(num)tt(])'). The second column gives the number of calls
-made to this function. The next three columns list the time in
+`tt([)var(num)tt(])'), then the number of calls made to the function.
+The next three columns list the time in
 milliseconds spent in the function and its descendents, the average
 time in milliseconds spent in the function and its descendents per
 call and the percentage of time spent in all shell functions used in
-this function and its descendents. The following three columns give
+this function and its descendents.  The following three columns give
 the same information, but counting only the time spent in the function 
-itself. The last column finally shows the name of the function.
+itself.  The final column shows the name of the function.
 
 After the summary, detailed information about every function that was
-invoked is listed, sorted in decreasing order by the amount of time
-spent in the functions and their descendents. Each of these entries
-consists of descriptions for the functions that called the function
-described, the function itself, and the functions that were called
-from it. The description for the function itself has the same format
-as in the summary (and shows the same information). The other lines
-don't show the number of the function at the beginning and have their
-function named indented to make it easier to visually distinguish the
-line showing the function described in the section from the
-surrounding lines.
-
-The information shown for the calling and the called functions is
-almost the same as in the summary, but is always only for the call arc 
-described. For example, for a calling function the column showing the
-total running time lists the time spent in the described function and
-its descendents when it was called from the calling
-function. Likewise, for a called function, this columns lists the
-total time spent in the called function and its descendents when it
-was called from the function described.
-
-For the calling and the called functions, the column showing the
-number of calls to a function also show the total number of
-invocations made to the called function after a slash.
+invoked is listed, sorted in decreasing order of the amount of time spent
+in each function and its descendents.  Each of these entries consists of
+descriptions for the functions that called the function described, the
+function itself, and the functions that were called from it.  The
+description for the function itself has the same format as in the summary
+(and shows the same information).  The other lines don't show the number of
+the function at the beginning and have their function named indented to
+make it easier to distinguish the line showing the function described in
+the section from the surrounding lines.
+
+The information shown in this case is almost the same as in the summary,
+but only refers to the call hierarchy being displayed.  For example, for a
+calling function the column showing the total running time lists the time
+spent in the described function and its descendents only for the times when
+it was called from that particular calling function.  Likewise, for a
+called function, this columns lists the total time spent in the called
+function and its descendents only for the times when it was called from the
+function described.
+
+Also in this case, the column showing the number of calls to a function
+also shows a slash and then the total number of invocations made to the
+called function.
 
 As long as the tt(zsh/zprof) module is loaded, profiling will be done and
 multiple invocations of the tt(zprof) builtin command will show the
-times and numbers of calls since the module was loaded. With the
+times and numbers of calls since the module was loaded.  With the
 tt(-c) option, the tt(zprof) builtin command will reset its internal
 counters and will not show the listing.
 )
Index: Doc/Zsh/mod_zpty.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/mod_zpty.yo,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 mod_zpty.yo
--- Doc/Zsh/mod_zpty.yo	2000/01/20 18:44:54	1.1.1.1
+++ Doc/Zsh/mod_zpty.yo	2000/05/21 18:18:54
@@ -11,30 +11,32 @@
 xitem(tt(zpty) tt(-r) var(name) [ var(param) [ var(pattern) ] ])
 item(tt(zpty) [ tt(-L) ])(
 In the first form, the var(command) is started with the var(args) as
-arguments. After this, the var(name) can be used in further calls to
-tt(zpty) to refer to this command. With the tt(-e) option given, the
+arguments.  The command runs under a newly assigned pseudo-terminal; this
+is useful for running commands non-interactively which expect an
+interactive environment.  The var(name) given is used to refer to this
+command in later calls to tt(pty).  With the tt(-e) option given, the
 pseudo-terminal will be set up so that input characters are echoed and 
 with the tt(-b) option given, input and output from and to the
 pseudo-terminal will be blocking.
 
 The second form with the tt(-d) option is used to delete commands
-started before by giving their var(names). If no var(names) are given, 
-all commands are deleted. Deleting a command makes the HUP signal be
-sent to the process started for it.
+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
+the HUP signal to be sent to the corresponding process.
 
-The tt(-w) option can be used to sent the command var(name) the given
-var(strings) as input (separated by spaces). If the tt(-n) option is
-not given, a newline will be sent after the last var(string).
+The tt(-w) option can be used to send the command var(name) the given
+var(strings) as input (separated by spaces).  If the tt(-n) option is
+not given, a newline will be added at the end.
 
 The tt(-r) option can be used to read the output of the command
-var(name). Without a var(param) argument, the string read will be
-printed to standard output. With a var(param) argument, the string
-read will be put in the parameter named var(param). If the
+var(name).  Without a var(param) argument, the string read will be
+printed to standard output.  With a var(param) argument, the string
+read will be put in the parameter named var(param).  If the
 var(pattern) is also given, output will be read until the whole string 
 read matches the var(pattern).
 
 The last form without any arguments is used to list the commands
-currently defined. If the tt(-L) option is given, this is done in the
+currently defined.  If the tt(-L) option is given, this is done in the
 form of calls to the tt(zpty) builtin.
 )
 enditem()
Index: Doc/Zsh/mod_zutil.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/mod_zutil.yo,v
retrieving revision 1.4
diff -u -r1.4 mod_zutil.yo
--- Doc/Zsh/mod_zutil.yo	2000/05/17 08:36:10	1.4
+++ Doc/Zsh/mod_zutil.yo	2000/05/21 18:18:59
@@ -14,14 +14,14 @@
 xitem(tt(zstyle -abhs) var(context) var(style) var(name) [ var(sep) ])
 xitem(tt(zstyle -Tt) var(context) var(style) [ var(strings) ...])
 item(tt(zstyle -m) var(context) var(style) var(pattern))(
-This builtin command is used to define and lookup styles. Styles are
+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
-strings. They are stored together with patterns and lookup is done by
+strings.  They are stored together with patterns and lookup is done by
 giving a string, called the `context', which is compared to the
-patterns. The definition stored for the first matching pattern will be 
-returned. For this, the patterns are ordered from most specific to
+patterns.  The definition stored for the first matching pattern will be 
+returned.  For this, the patterns are ordered from most specific to
 less specific and patterns that are equally specific keep the order in 
-which they were defined. A pattern is considered to be more specific
+which they were defined.  A pattern is considered to be more specific
 than another if it contains more components (substrings separated by
 colons) or if the patterns for the components are more specific, where 
 simple strings are considered to be more specific than patterns and
@@ -95,36 +95,36 @@
 findex(zformat)
 xitem(tt(zformat -f) var(param) var(format) var(specs) ...)
 item(tt(zformat -a) var(array) var(sep) var(specs) ...)(
-This builtin provides to different forms of formatting. The first form 
-is selected with the tt(-f) option. If this is given, the var(format)
+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) has to be
-of the form `var(char)tt(:)var(string)' and this will make every
-appearance of the sequence `tt(%)var(char)' in var(format) be replaced 
-with the var(string). The `tt(%)' sequence may also contain optional
+sign in it with strings from the var(specs).  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
 minimum and maximum field width specifications between the `tt(%)' and 
 the `var(char)' in the form `tt(%)var(min)tt(.)var(max)tt(c)',
 i.e. the minimum field width is given first and if the maximum field
-width is used, it has to be preceded by a dot. Giving a minimum field
+width is used, it has to be preceded by a dot.  Specifying a minimum field
 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 given, the var(string) will be truncated after that
-many characters. After all `tt(%)' sequences for the given var(specs)
+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)
 have been processed, the resulting string is stored in the parameter
 var(param).
 
-The second form, using the tt(-a) option, can be used to get aligned
-strings. Here, the var(specs) are of the form
+The second form, using the tt(-a) option, can be used for alignin
+strings.  Here, the var(specs) 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
-with the var(sep) string and padding the var(left) strings with spaces 
+arbitrary strings.  These strings are modified by replacing the colons
+by the var(sep) string and padding the var(left) strings with spaces 
 to the right so that the var(sep) strings in the result (and hence the 
 var(right) strings after them) are all aligned if the strings are
-printed below each other. All strings without a colon are left
+printed below each other.  All strings without a colon are left
 unchanged and all strings with a empty var(right) string have the
-trailing colon removed. In both cases the lengths of the strings
-are not used to determine how the other strings have to be aligned.
+trailing colon removed.  In both cases the lengths of the strings
+are not used to determine how the other strings are to be aligned.
 The resulting strings are stored in the var(array).
 )
 findex(zregexparse)
@@ -133,46 +133,51 @@
 )
 findex(zparseopts)
 item(tt(zparseopts) [ tt(-D) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] var(specs))(
-This builtin simplifies the parsing of options in the positional
-parameters. Each var(spec) describes one option and should be of the
-form `var(name)[tt(+)][tt(:)[tt(:)][tt(-)]][tt(=)var(array)]'. The var(name)
-is the name of the option (without the leading `tt(-)'). If only that
-is given, the option takes no argument and if it is found in the
-positional parameters it will be placed in the var(array) given with
-the tt(-a) option. If the optional `tt(=)var(array)' is given, it will 
-be put into that array instead. If one or two colons are given, the
-option takes an argument. With one colon, this argument is mandatory
-and with two colons it is optional. The argument will be inserted into 
-the var(array), too. For mandatory arguments it is added as a separate 
-string and for optional arguments it is put into one string together
-with the option name unless the `tt(-)' option is given. In this case
-the argument will be put into the same word even for mandatory
+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 should be of the form
+`var(name)[tt(+)][tt(:)[tt(:)][tt(-)]][tt(=)var(array)]'.  The var(name) is
+the name of the option (without the leading `tt(-)').  If only the option
+name is given, the option takes no argument and if it is found in the
+positional parameters it will be placed in the var(array) specified with
+the tt(-a) option; if the optional `tt(=)var(array)' is given, it will
+instead be put into that array.  If one or two colons are given, the
+option takes an argument; with one colon, the argument is mandatory
+and with two colons it is optional.  The argument will also be inserted into 
+the var(array).  A mandatory arguments is added as a separate 
+string and an optional argument is put into a single string together
+with the option name, unless a `tt(-)' appears after the colon, in
+which case the argument will be put into the same word even for mandatory
 arguments (note that this makes empty strings as arguments
-indistinguishable). Finally, if the `tt(+)' is given and the option
-appears more than once in the positional parameters, it will be
-inserted more than once in the var(array), too. Without the `tt(+)'
+indistinguishable).  Finally, if a `tt(+)' appears after var(name) the
+option may appears more than once in the positional parameters and will
+hence be inserted more than once in the var(array); without the `tt(+)'
 the option will be inserted only once in the var(array) with arguments 
-of later options overwriting earlier once. If any of the special
-character needs to appear in the option name it must be preceded by a
+of later options overwriting earlier once.  Any of the special
+characters can appear in the option name provided it is preceded by a
 backslash.
 
 If the tt(-A) option is given, the options and their values will also
 be put into an associative array with the option names as keys and the 
-arguments (if any) as the values. Note that it is an error to give
+arguments (if any) as the values.  Note that it is an error to give
 var(specs) without a `tt(=)var(array)' and not use either the tt(-a)
 or tt(-A) option.
 
 If the tt(-D) option is given, all options found are removed from the
-positional parameters leaving only the strings from the first one that 
-was not described by any of the var(specs) to the last (note that this 
-is the usual rule used by tt(zparseopts) to find out when to stop
-processing options).
-
-For example, calling `tt(zparseopts a=foo b:=bar c+:=bar)' with the
-strings `tt(-a)', `tt(-bx)', `tt(-c)', `tt(y)', `tt(-cz)', `tt(baz)'
-and `tt(-cend)' as positional arguments will set the array tt(foo) to
-contain the element `tt(-a)' and the array tt(bar) to the strings
-`tt(-b)', `tt(x)', `tt(-c)', `tt(y)', `tt(-c)', and `tt(z)'. The
-`tt(baz)' and all strings after it will not be used.
+positional parameters, up to but not including any not described by the
+var(specs).  This means that any options processed by tt(zparseopts) are
+removed from the positional parameters.
+
+For example,
+
+example(set -- -a -bx -c y -cz baz -cend
+zparseopts a=foo b:=bar c+:=bar)
+
+will have the effect of
+
+example(foo=(-a)
+bar=(-b x -c y -c z))
+
+The arguments from `tt(baz)' on will not be used.
 )
 enditem()
Index: Doc/Zsh/zftpsys.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/zftpsys.yo,v
retrieving revision 1.4
diff -u -r1.4 zftpsys.yo
--- Doc/Zsh/zftpsys.yo	2000/05/11 00:01:03	1.4
+++ Doc/Zsh/zftpsys.yo	2000/05/21 18:19:00
@@ -279,7 +279,7 @@
 With the option tt(-r), if any of the var(files) are directories they are
 sent recursively with all their subdirectories, including files beginning
 with `tt(.)'.  This requires that the remote machine understand UNIX file
-semantics. as `tt(/)' is used as a directory separator.
+semantics, since `tt(/)' is used as a directory separator.
 )
 findex(zfuput)
 item(tt(zfuput [ -vs ] var(file1) ...))(
@@ -367,7 +367,7 @@
 
 The operation is performed using pipes, so it is required that the
 connections still be valid in a subshell, which is not the case under some
-operating systems.
+versions operating systems, presumably due to a system bug.
 )
 enditem()
 
@@ -376,7 +376,7 @@
 present location (host, user and directory) of the current FTP connection
 for later use.  The file to be used for storing and retrieving bookmarks is
 given by the parameter tt($ZFTP_BMFILE); if not set when one of the two
-functions is called, it will be set to the file tt(.zfbfmarks) in the
+functions is called, it will be set to the file tt(.zfbkmarks) in the
 directory where your zsh startup files live (usually tt(~)).
 
 startitem()
@@ -471,7 +471,7 @@
 item(tt(zftp_chpwd))(
 This function is called every time a connection is opened, or closed, or
 the remote directory changes.  This version alters the title bar of an
-tt(xterm) compatible or tt(sun-cmd) terminal emulator to reflect the 
+tt(xterm)-compatible or tt(sun-cmd) terminal emulator to reflect the 
 local and remote hostnames and current directories.  It works best when
 combined with the function tt(chpwd).  In particular, a function of 
 the form

-- 
Peter Stephenson <pws@xxxxxxxxxxxxxxxxxxxxxxxx>
Work: pws@xxxxxxxxxxxxxxxxxxxxxxxxx
Web: http://www.pwstephenson.fsnet.co.uk