PATCH: pws-25: doc and administrative text changes

[Peter Stephenson <pws@xxxxxxxxxxxxxxxxx>]

This alters some administrative files, in particular NEWS, CONTRIBUTORS and
BUGS (which is still severely out of date), which you can look at to see if
I've missed anything.

There are also some documentation changes, partly because I was looking for
and failed to find something I remember thinking was wrong in the parameter
stuff.  Mostly these are uninteresting, but the changes to mod_complist.yo
are more detailed.  I discovered that you could bind (e.g.) .accept-line
instead of accept-line in the menuselect keymap to do a real accept-line,
leaving the current completion; and on my keyboard I need to bind ^M, not
^J, to alter the return key:  if it's known when the difference occurs, that
can be mentioned.

One administrative file I haven't changed is the PGP public keyring that
Zefram introduced.  That's because pgp 5 seems to be a botched upgrade
where you can't specify alternative keyrings, while not all of the keys in
Etc/pubring.pgp can be handled by pgp 2.  If I can find a non-botched way
of handling this I'll start adding public keys again.  But the pgp fad in
email seems to have died down for the time being.  (You can tell real
postings from me because they all contain at least one entirely deliberate
mistake.)

--- Etc/BUGS.doc	Wed Oct 28 22:22:53 1998
+++ Etc/BUGS	Thu Jul  8 14:34:43 1999
@@ -2,9 +2,20 @@
 KNOWN BUGS IN ZSH
 -----------------
 
+On some terminals, display of lines with exactly 80 characters is
+problematic.  zsh assumes that the terminal does not print and extra
+newline in this case, but some terminals (e.g. aixterm) do.
 ------------------------------------------------------------------------
-Completion has a habit of doing the wrong thing after a
-backslash/newline.
+When interrupting code like the following with ^C:
+  while true; do
+    sh -c '...'
+  done
+if the `sh' is executing, zsh does not know that the sh received a ^C and
+continues with the next iteration.  This happens for any program which
+handles the interrupt, then exits after tidying up; it does not happen for
+zsh, which exits directly from the signal handler.  The workaround is to
+use ^Z which forks the shell and makes the loop a separate job, then kill
+the suspended loop.
 ------------------------------------------------------------------------
 If you suspend "man", zle seems to get into cooked mode.  It works ok
 for plain "less".
@@ -25,12 +36,6 @@
 Then if you suspend
 % foo less something
 from zsh/bash, zle/readline gets into cooked mode.
-------------------------------------------------------------------------
-% zsh -c 'cat a_long_file | less ; :'
-can be interrupted with ^C. The prompt comes back and less is orphaned.
-If you go to the end of the file with less and cat terminates, ^C
-will not terminate less. The `; :' after less forces zsh to fork before
-executing less.
 ------------------------------------------------------------------------
 The pattern %?* matches names beginning with %? instead of names with at
 least two characters beginning with %. This is a hack to allow %?foo job
--- Etc/CONTRIBUTORS.doc	Wed Oct 28 22:11:36 1998
+++ Etc/CONTRIBUTORS	Thu Jul  8 13:25:43 1999
@@ -4,8 +4,8 @@
 
 Zsh was originally written by Paul Falstad <pf@xxxxxxx>.  Zsh is
 now maintained by the members of the zsh-workers mailing list
-<zsh-workers@xxxxxxxxxxxxxxx>.  The development is currently coordinated
-by Andrew Main (Zefram) <zefram@xxxxxxx>.
+<zsh-workers@xxxxxxxxxxxxxx>.  The development is currently coordinated
+by Peter Stephenson <pws@xxxxxxx>.
 
 This file credits only the major contributors to the current release.
 See the ChangeLog files for a complete list of people who have submitted
@@ -14,6 +14,40 @@
 to be currently accurate.  If you feel that you or someone else have
 been unfairly omitted from this list please mail the current maintainer
 at <coordinator@xxxxxxx>.
+
+Version 3.1.6
+-------------
+
+* Sven Wishnowsky <wischnow@xxxxxxxxxxxxxxxxxxxxxxx>: completion code,
+  major rewrite and enhancements, including matching control, completion
+  widgets and function system, complist module; zle code additions; job
+  control code changes; parameters code changes; parameter module;
+  additional autoloading code; general code changes for extra efficiency;
+  subscripting and ordering of globbing lists.
+  
+* Peter Stephenson <pws@xxxxxxxxxxxxxxxxx>: zftp and mapfile modules and
+  zf* functions; local parameters and typeset changes; changes in autoconf
+  system; case-independent and approximate pattern matching; various
+  options; a few completion modules; some zle changes; FAQ.
+
+* Bart Schaefer <schaefer@xxxxxxxxxxxxxxxxxxxxxxx>: associative array
+  implementation; other parameter changes; keeping track of missing
+  patches; function autoloading changes.
+  
+* Wayne Davison <wayne@xxxxxxxxx>:  History code novelties and improvements
+  with new options.
+  
+* Geoff Wing <mason@xxxxxxxxxxxxxxx>:  Zle display code fixes, mailing
+  list and patch archive.
+
+* Zoltán Hidvégi <hzoli@xxxxxxxxxx>: AIX dynamic loading code.
+
+* Matt Armstrong: cygwin configuration changes.
+
+Other improvements, bug fixes and design suggestions from all the above
+plus Andrej Borsenkow, Oliver Kiddle, Tanaka Akira, Naoki Wakamatsu, Tatuso
+Furukawa, Ville Herva, Will Day, Lehti Rahmi, Larry P. Schrof, Helmut
+Jarausch, Phil Pennock, Wilfredo Sanchez, Bruce Stephens.
 
 Version 3.0
 -----------
--- Etc/NEWS.doc	Wed Oct 28 22:20:00 1998
+++ Etc/NEWS	Thu Jul  8 14:26:13 1999
@@ -2,6 +2,92 @@
 CHANGES FROM PREVIOUS VERSIONS OF ZSH
 -------------------------------------
 
+New features in zsh version 3.1.6 (beta version)
+------------------------------------------------
+
+New completion system via shell functions; massive degree of
+programmability and configurability:
+ - ready-made function suite to use, see zshcompsys(1)
+ - approximate completion and spelling correction via completion
+ - control over matching for case-independence, partial word completion, etc.
+ - menu selection:  choose a completion by moving the cursor
+ - coloured completion lists
+
+Other editing changes:
+  - enhancements to function/editing interface:  new parameters, numeric
+    arguments, string argument passing, reading keys from widgets.
+  - the old history-search-{back,for}ward behaviour and bindings have
+    returned (up to minor details).
+  - BASH_AUTO_LIST option to show completion list only on second key press.
+  - the ZBEEP parameter gives a string to output instead of beeping,
+    allowing you to have a visual bell.
+
+History changes: new options HIST_NO_FUNCTIONS, HIST_EXPIRE_DUPS_FIRST,
+HIST_FIND_NO_DUPS, HIST_IGNORE_ALL_DUPS, INC_APPEND_HISTORY,
+HIST_SAVE_NO_DUPS, SHARE_HISTORY, allow better control of when history is
+read and written and how duplicates are handled.
+
+Associative arrays plus enhanced parameter substitutions to retrieve keys
+and values.
+
+Globbing changes:
+  - Case-insensitive and approximate globbing.
+  - Ordering and indexing of globbing matches, e.g. *(om[1]) picks
+    most recently modified file.
+
+New loadable modules:
+  - zftp, plus associated function suite, for turning your zsh session
+    into an FTP session too
+  - parameter, for examining and altering shell hash tables via an
+    associative array interface.
+  - mapfile, for reading and writing external files via an associative
+    array interface.
+
+Debugging and prompt enhancements:
+  - LINENO is now very much more useful in scripts and functions and has
+    corresponding prompt escape %i
+  - $PS4 can contain %i as well as %N for script or function names
+    (default PS4 changed), also %_ for current shell structure executing; 
+  - Prompt truncation %<...< is now more flexible: it applies to a
+    whole section of the prompt, not just one escape.  You need to put
+    %<< after the truncated escape to get the old behaviour.
+  - %20(l.yes.no) in prompts prints yes if at least 20 characters have
+    been output, else no (e.g. for outputting extra newlines).
+
+Parameter and expansion changes
+  - typeset -t MYPATH mypath creates tied path/PATH variables
+  - typeset -g allows operations on parameters without making them local
+  - New expansions
+    - ${(t)param} prints type information for $param
+    - ${(P)param} treats value of $param as the name of a param to
+      substitute
+    - ${foo:q} can quote replaced parameter text from expansion
+    - ${foo/old/new} substitution, like bash; also (S) flag for shortest
+      match
+    - $foo[(b.2.i)bar] starts searching $foo for bar starting at 2nd match
+    - more logical behaviour of nested parameters, now properly documented
+    - quote only nested expansion, e.g. ${(f)"$(<file)"} reads complete
+      `file', then splits lines into array.
+
+Builtin and function changes
+  - stat module: `stat -H hash foo' gives you e.g. $hash[mtime]
+  - autoload -U autoloads functions without alias expansion.
+
+Other new options:
+  - LOCAL_TRAPS allows signal traps to be local to functions (as in ksh).
+  - NO_RCS can now be turned on at any point in initialization files.
+  - NO_GLOBAL_RCS can force /etc/z* files after /etc/zshenv to be skipped.
+    (Please don't use this as an excuse to stuff more into /etc/zshenv!)
+  - existing MAGIC_EQUAL_SUBST option is more useful; any argument containing
+    ...=~...:~... will perform filename expansion on the ~.
+
+Configuration changes:
+  - Large file and 64-bit integers on 32-bit machines supported where
+    provided by OS.
+  - generation of signal names should be more reliable
+  - Customizable installation of shell functions from distribution.
+
+
 New features in zsh version 3.1 (beta version)
 ----------------------------------------------
 
--- Doc/Zsh/builtins.yo.doc	Thu Jul  8 09:37:20 1999
+++ Doc/Zsh/builtins.yo	Thu Jul  8 10:43:51 1999
@@ -58,8 +58,9 @@
 interpreted as glob patterns), and the aliases matching these patterns
 are printed.  When printing aliases and the tt(-g) or tt(-r) flags
 are present, then restrict the printing to global or regular
-aliases, respectively.  Using `tt(PLUS())' instead of `tt(-)' prevents
-the values of the aliases from being printed.
+aliases, respectively.  Using `tt(PLUS())' instead of `tt(-)', or ending
+the option list with a single `tt(PLUS())', prevents the values of the
+aliases from being printed.
 
 If the tt(-L) flag is present, then print each
 alias in a manner suitable for putting in a startup script.  The exit
@@ -932,9 +933,11 @@
 var(name) set to var(value).  Note that arrays currently cannot be
 assigned in tt(typeset) expressions; scalars and integers only.
 
-For each remaining var(name) that refers to a parameter that is set,
-the name and value of the parameter are printed in the form of an
-assignment.  Nothing is printed for newly-created parameters.
+For each remaining var(name) that refers to a parameter that is set, the
+name and value of the parameter are printed in the form of an assignment.
+Nothing is printed for newly-created parameters, or if any attribute flags
+listed below are given.  Using `tt(PLUS())' instead of minus to introduce
+an attribute turns it off.
 
 If the tt(-T) option is given, exactly two (or zero) var(name)
 arguments must be present.  They represent a scalar and an array (in
@@ -960,13 +963,16 @@
 have any effect.
 
 If no var(name) is present, the names and values of all parameters are
-printed.  In this case the attribute flags restrict the display to
-only those parameters that have the specified attributes.  Using
-`tt(PLUS())' rather than `tt(-)' to introduce the flag causes the
-attribute to be turned off, and suppresses printing of the names and
-values.  If only the tt(-m) flag is given the arguments are taken as
-patterns (should be quoted) and all parameters (or functions with the
-tt(-f) flag) with matching names are printed.
+printed.  In this case the attribute flags restrict the display to only
+those parameters that have the specified attributes, and using `tt(PLUS())'
+rather than `tt(-)' to introduce the flag suppresses printing of the values
+of parameters when there is no parameter name.  Also, if the option list
+ends with `tt(PLUS())', values will not be printed.  If only the tt(-m)
+flag is given the arguments are taken as patterns (should be quoted) and
+all parameters (or functions with the tt(-f) flag) with matching names are
+printed.  If no attribute flags and no tt(-m) flag is present, the
+parameter names will be preceded by a list of any attributes (tt(array),
+tt(association), tt(exported), tt(integer), tt(readonly)).
 
 The following attribute flags may be specified:
 
--- Doc/Zsh/expn.yo.doc	Thu Jul  8 11:04:27 1999
+++ Doc/Zsh/expn.yo	Thu Jul  8 11:31:13 1999
@@ -248,6 +248,9 @@
 
 The character sequence `tt(^)var(foo)tt(^)var(bar)'
 repeats the last command, replacing the string var(foo) with var(bar).
+More precisely, the sequence `tt(^)var(foo)tt(^)var(bar)tt(^)' is
+synonymous with `tt(!!:s)tt(^)var(foo)tt(^)var(bar)tt(^)', hence other
+modifiers may follow the final `tt(^)'.
 
 If the shell encounters the character sequence `tt(!")'
 in the input, the history mechanism is temporarily disabled until
@@ -855,10 +858,10 @@
 sect(Command Substitution)
 cindex(command substitution)
 cindex(substitution, command)
-A command enclosed in parentheses
-preceded by a dollar sign, like `tt($LPAR())...tt(RPAR())', or quoted with grave
-accents, like `tt(`)...tt(`)', is replaced with its standard output, with any
-trailing newlines deleted.
+A command enclosed in parentheses preceded by a dollar sign, like
+`tt($LPAR())...tt(RPAR())', or quoted with grave 
+accents, like `tt(`)...tt(`)', is replaced with its standard output, with
+any trailing newlines deleted.
 If the substitution is not enclosed in double quotes, the
 output is broken into words using the tt(IFS) parameter.
 vindex(IFS, use of)
--- Doc/Zsh/mod_complist.yo.doc	Thu Jul  8 10:00:01 1999
+++ Doc/Zsh/mod_complist.yo	Thu Jul  8 10:23:09 1999
@@ -5,6 +5,12 @@
 the ability to highlight matches in such a list and a different
 style of menu-completion.
 
+Whenever one of the parameters tt(ZLS_COLORS) or tt(ZLS_COLOURS) is set 
+and the tt(complist) module is loaded or linked into the shell,
+completion lists will be colored.  Note, however, that tt(complist) will
+not automatically be loaded if it is not linked in:  on systems with
+dynamic loading, `tt(zmodload complist)' is required.
+
 subsect(Parameters)
 For both extensions one of the parameters tt(ZLS_COLORS) or tt(ZLS_COLOURS)
 must be set, even if the value is empty (which uses all the default values
@@ -12,12 +18,12 @@
 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
+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))(
-for normal text (not the string displayed for a match)
+for normal text (i.e. when displaying something other than a matched file)
 )
 item(tt(fi 0))(
 for regular files
@@ -44,7 +50,7 @@
 for executable files
 )
 item(tt(mi) var(none))(
-for names not naming a file (default is the value defined for tt(fi))
+for non-existent file (default is the value defined for tt(fi))
 )
 item(tt(lc \e[))(
 for the left code (see below)
@@ -71,50 +77,51 @@
 vt100 compatible terminals such as tt(xterm)s. On monochrome terminals
 the default values will have no visual effect.
 
-Whenever one of the parameters tt(ZLS_COLORS) or tt(ZLS_COLOURS) is set 
-and the tt(complist) module is loaded or linked into the shell,
-completion lists will be colored.
-
 subsect(Menu selection)
-The tt(complist) module also offers a different style of selecting
-matches from a list called menu-selection. It can be invoked directly by
+The tt(complist) module also offers an alternative style of selecting
+matches from a list, called menu-selection. It can be invoked directly by
 the widget tt(menu-select) defined by the module.  Alternatively,
-the parameter tt(SELECTMIN) can be set to an integer giving the minimum
-number of matches which must be present before menu selection is
+the parameter tt(SELECTMIN) can be set to an integer, which give the
+minimum number of matches that must be present before menu selection is
 automatically turned on.  This second method requires that menu completion
 be started, either directly from a widget such as tt(menu-complete), or due
 to one of the options tt(MENU_COMPLETE) or tt(AUTO_MENU) being set.  If
 tt(SELECTMIN) is set, but is 0, 1 or empty, menu selection will always be
-started during menu completion if the completion is ambiguous.
+started during an ambiguous menu completion.
 
 After menu-selection is started, the matches will be listed. 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
 value for this it `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 is used as for the `tt(%S)' escape in prompts.
+control sequence as for the `tt(%S)' escape in prompts is used.
 
 Selecting matches is done by moving the mark around using the zle movement
 functions. The zle functions tt(send-break) and tt(accept-line) can be used
 to leave menu-selection, leaving the match currently inserted into the line
-in place. In the case of tt(accept-line), the match currently inserted
-will be accepted and immediatly trying completion again will
-complete after it. Using tt(send-break) leaves menu-selection and
-continues with normal menu-completion. The functions tt(accept-and-hold) and
+in place.  In the case of tt(accept-line), the match currently inserted
+will be accepted and a new completion may be attempted.
+Using tt(send-break) leaves menu-selection and continues with normal
+menu-completion.  The functions tt(accept-and-hold) and
 tt(accept-and-menu-complete) can be used to accept the match currently
-inserted and continue inserting matches after that. Matches inserted this
-way can be removed by invoking the tt(undo) function. The function
-tt(accept-and-infer-next-history) accepts the current match and
-immediatly tries completion with menu-selection again. In the case of
-files this allows one to select a directory and then to directly
-continue with completing files in it. Keys bound to one of
+inserted and continue inserting matches from the same list. Matches
+inserted this way can be removed by invoking the tt(undo) function. The
+function tt(accept-and-infer-next-history) accepts the current match and
+then tries completion with menu-selection again. In the case of
+files this allows one to select a directory and immediately attempt to
+complete files in it. Keys bound to one of
 the completion functions will cycle to the next (or, in case of
 tt(reverse-menu-complete), the previous) match, and the tt(redisplay) and
 tt(clear-screen) functions work as usual without leaving
-menu-selection. Any other zle function leaves menu-selection and executes
-that function.
+menu-selection.
+
+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.
 
 During this selection the widget uses the keymap tt(menuselect). Any
 key that is not defined in this keymap or that is bound to
@@ -128,6 +135,6 @@
 ). For example, to make the return key leave menu-selection and
 continue with normal menu-completion one can call
 
-indent(tt(bindkey -M menuselect '^J' send-break))
+indent(tt(bindkey -M menuselect '^M' send-break))
 
 after loading the tt(complist) module.
--- Doc/Zsh/params.yo.doc	Thu Jul  8 10:42:40 1999
+++ Doc/Zsh/params.yo	Thu Jul  8 10:58:27 1999
@@ -108,14 +108,15 @@
 
 startitem()
 item(tt(e))(
-this option has no effect and retained for backward compatibility only.
+This option has no effect and retained for backward compatibility only.
 )
 item(tt(w))(
-if the parameter subscripted is a scalar than this flag makes
-subscription work on a per-word basis instead of characters.
+If the parameter subscripted is a scalar than this flag makes
+subscripting work on words instead of characters.  The default word
+separator is whitespace.
 )
 item(tt(s:)var(string)tt(:))(
-this gives the var(string) that separates words (for use with the
+This gives the var(string) that separates words (for use with the
 tt(w) flag).
 )
 item(tt(p))(
@@ -123,21 +124,22 @@
 the string argument of a subsequent `tt(s)' flag.
 )
 item(tt(f))(
-if the parameter subscripted is a scalar than this flag makes
-subscription work on a per-line basis instead of characters.
-This is a shorthand for `tt(pws:\n:)'.
+If the parameter subscripted is a scalar than this flag makes
+subscripting work on lines instead of characters, i.e. with elements
+separated by newlines.  This is a shorthand for `tt(pws:\n:)'.
 )
 item(tt(r))(
-if this flag is given the var(exp) is taken as a pattern and the
-result is the first matching array element, substring or word (if the
-parameter is an array, if it is a scalar, or if it is a scalar and the
-`tt(w)' flag is given, respectively); note that this is like giving a
-number: `tt($foo[(r))var(??)tt(,3])' and `tt($foo[(r))var(??)tt(,(r)f*])' work.
-If the parameter is an associative array, only the value part of each pair
-is compared to the pattern.
+Reverse subscripting:  if this flag is given, the var(exp) is taken as a
+pattern and the  result is the first matching array element, substring or
+word (if the parameter is an array, if it is a scalar, or if it is a scalar
+and the `tt(w)' flag is given, respectively).  The subscript used is the
+number of the matching element, so that pairs of subscripts such as
+`tt($foo[(r))var(??)tt(,3])' and `tt($foo[(r))var(??)tt(,(r)f*])'
+are possible.  If the parameter is an associative array, only the value part
+of each pair is compared to the pattern.
 )
 item(tt(R))(
-like `tt(r)', but gives the last match.  For associative arrays, gives
+Like `tt(r)', but gives the last match.  For associative arrays, gives
 all possible matches.
 )
 item(tt(i))(
@@ -731,12 +733,12 @@
 command, and are reset when it finishes or is suspended. If the command is
 suspended and continued later with the tt(fg) or tt(wait) builtins it will
 see the modes specified by tt(STTY), as if it were not suspended.  This
-(intentionally) does not apply if the command is continued via `tt(kill -CONT)'.
-tt(STTY) is ignored if the command is run in the background, or if it is in the
-environment of the shell but not explicitly assigned to in the input line. This
-avoids running stty at every external command by accidentally exporting it.
-Also note that tt(STTY) should not be used for window size specifications; these
-will not be local to the command.
+(intentionally) does not apply if the command is continued via `tt(kill
+-CONT)'.  tt(STTY) is ignored if the command is run in the background, or
+if it is in the environment of the shell but not explicitly assigned to in
+the input line. This avoids running stty at every external command by
+accidentally exporting it. Also note that tt(STTY) should not be used for
+window size specifications; these will not be local to the command.
 )
 vindex(TERM)
 item(tt(TERM) <S>)(

-- 
Peter Stephenson <pws@xxxxxxxxxxxxxxxxx>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56127 Pisa, Italy