new repository

1 files changed, 7230 insertions, 0 deletions

diff --git a/assets/info/zsh.info-5 b/assets/info/zsh.info-5
new file mode 100644
index 00000000..5720d6b2
--- /dev/null
+++ b/assets/info/zsh.info-5
@@ -0,0 +1,7230 @@
+This is zsh.info, produced by makeinfo version 4.8 from ./zsh.texi.
+
+INFO-DIR-SECTION Utilities
+START-INFO-DIR-ENTRY
+* ZSH: (zsh).                     The Z Shell Manual.
+END-INFO-DIR-ENTRY
+
+
+File: zsh.info,  Node: Calendar System User Functions,  Next: Calendar Styles,  Prev: Calendar File and Date Formats,  Up: Calendar Function System
+
+23.3 User Functions
+===================
+
+This section describes functions that are designed to be called
+directly by the user.  The first part describes those functions
+associated with the user's calendar; the second part describes the use
+in glob qualifiers.
+
+
+
+23.3.1 Calendar system functions
+--------------------------------
+
+
+calendar [ -abdDsv ] [ -C CALFILE ] [ -n NUM ] [ -S SHOWPROG ]
+         [ [ START ] END ]
+calendar -r [ -abdDrsv ] [ -C CALFILE ] [ -n NUM ] [ -S SHOWPROG ]
+         [ START ]
+     Show events in the calendar.
+
+     With no arguments, show events from the start of today until the
+     end of the next working day after today.  In other words, if today
+     is Friday, Saturday, or Sunday, show up to the end of the
+     following Monday, otherwise show today and tomorrow.
+
+     If END is given, show events from the start of today up to the time
+     and date given, which is in the format described in the previous
+     section.  Note that if this is a date the time is assumed to be
+     midnight at the start of the date, so that effectively this shows
+     all events before the given date.
+
+     END may start with a +, in which case the remainder of the
+     specification is a relative time format as described in the
+     previous section indicating the range of time from the start time
+     that is to be included.
+
+     If START is also given, show events starting from that time and
+     date.  The word now can be used to indicate the current time.
+
+     To implement an alert when events are due, include calendar -s in
+     your ~/.zshrc file.
+
+     Options:
+
+
+    -a
+          Show all items in the calendar, regardless of the start and
+          end.
+
+    -b
+          Brief:  don't display continuation lines (i.e. indented lines
+          following the line with the date/time), just the first line.
+
+    -B LINES
+          Brief: display at most the first LINES lines of the calendar
+          entry.  `-B 1' is equivalent to `-b'.
+
+    -C CALFILE
+          Explicitly specify a calendar file instead of the value of
+          the calendar-file style or the default ~/calendar.
+
+    -d
+          Move any events that have passed from the calendar file to the
+          "done" file, as given by the done-file style or the default
+          which is the calendar file with .done appended.  This option
+          is implied by the -s option.
+
+    -D
+          Turns off the option -d, even if the -s option is also
+          present.
+
+    -n NUM, -NUM
+          Show at least NUM events, if present in the calendar file,
+          regardless of the start and end.
+
+    -r
+          Show all the remaining options in the calendar, ignoring the
+          given END time.  The START time is respected; any argument
+          given is treated as a START time.
+
+    -s
+          Use the shell's sched command to schedule a timed event that
+          will warn the user when an event is due.  Note that the sched
+          command only runs if the shell is at an interactive prompt; a
+          foreground task blocks the scheduled task from running until
+          it is finished.
+
+          The timed event usually runs the programme calendar_show to
+          show the event, as described in *Note Calendar Utility
+          Functions::.
+
+          By default, a warning of the event is shown five minutes
+          before it is due.  The warning period can be configured by
+          the style warn-time or for a single calendar entry by
+          including WARN RELTIME in the first line of the entry, where
+          RELTIME is one of the usual relative time formats.
+
+          A repeated event may be indicated by including RPT RELDATE in
+          the first line of the entry.  After the scheduled event has
+          been displayed it will be re-entered into the calendar file
+          at a time RELDATE after the existing event.  Note that this
+          is currently the only use made of the repeat count, so that
+          it is not possible to query the schedule for a recurrence of
+          an event in the calendar until the previous event has passed.
+
+          If RPT is used, it is also possible to specify that certain
+          recurrences of an event are rescheduled or cancelled.  This is
+          done with the OCCURRENCE keyword, followed by whitespace and
+          the date and time of the occurrence in the regular sequence,
+          followed by whitespace and either the date and time of the
+          rescheduled event or the exact string CANCELLED.  In this
+          case the date and time must be in exactly the "date with
+          local time" format used by the text/calendar MIME type (RFC
+          2445), <YYYY><MM><DD>T<HH><MM><SS> (note the presence of the
+          literal character T).  The first word (the regular
+          recurrence) may be something other than a proper date/time to
+          indicate that the event is additional to the normal sequence;
+          a convention that retains the formatting appearance is
+          XXXXXXXXTXXXXXX.
+
+          Furthermore, it is useful to record the next regular
+          recurrence (as then the displayed date may be for a
+          rescheduled event so cannot be used for calculating the
+          regular sequence).  This is specified by RECURRENCE and a
+          time or date in the same format.  calendar_add adds such an
+          indication when it encounters a recurring event that does not
+          include one, based on the headline date/time.
+
+          If calendar_add is used to update occurrences the UID keyword
+          described there should be present in both the existing entry
+          and the added occurrence in order to identify recurring event
+          sequences.
+
+          For example,
+
+
+               Thu May 6, 2010 11:00 Informal chat RPT 1 week
+                 # RECURRENCE 20100506T110000
+                 # OCCURRENCE 20100513T110000 20100513T120000
+                 # OCCURRENCE 20100520T110000 CANCELLED
+
+          The event that occurs at 11:00 on 13th May 2010 is
+          rescheduled an hour later.  The event that occurs a week
+          later is cancelled.  The occurrences are given on a
+          continuation line starting with a # character so will not
+          usually be displayed as part of the event.  As elsewhere, no
+          account of time zones is taken with the times. After the next
+          event occurs the headline date/time will be `Thu May 13, 2010
+          12:00' while the RECURRENCE date/time will be
+          `20100513T110000' (note that cancelled and moved events are
+          not taken account of in the RECURRENCE, which records what
+          the next regular recurrence is, but they are accounted for in
+          the headline date/time).
+
+          It is safe to run calendar -s to reschedule an existing event
+          (if the calendar file has changed, for example), and also to
+          have it running in multiples instances of the shell since the
+          calendar file is locked when in use.
+
+          By default, expired events are moved to the "done" file; see
+          the -d option.  Use -D to prevent this.
+
+    -S SHOWPROG
+          Explicitly specify a programme to be used for showing events
+          instead of the value of the show-prog style or the default
+          calendar_show.
+
+    -v
+          Verbose:  show more information about stages of processing.
+          This is useful for confirming that the function has
+          successfully parsed the dates in the calendar file.
+
+
+calendar_add [ -BL ] EVENT ...
+     Adds a single event to the calendar in the appropriate location.
+     The event can contain multiple lines, as described in *Note
+     Calendar File and Date Formats::.  Using this function ensures
+     that the calendar file is sorted in date and time order.  It also
+     makes special arrangements for locking the file while it is
+     altered.  The old calendar is left in a file with the suffix .old.
+
+     The option -B indicates that backing up the calendar file will be
+     handled by the caller and should not be performed by calendar_add.
+     The option -L indicates that calendar_add does not need to lock
+     the calendar file as it is already locked.  These options will not
+     usually be needed by users.
+
+     If the style reformat-date is true, the date and time of the new
+     entry will be rewritten into the standard date format:  see the
+     descriptions of this style and the style date-format.
+
+     The function can use a unique identifier stored with each event to
+     ensure that updates to existing events are treated correctly.  The
+     entry should contain the word UID, followed by whitespace,
+     followed by a word consisting entirely of hexadecimal digits of
+     arbitrary length (all digits are significant, including leading
+     zeroes).  As the UID is not directly useful to the user, it is
+     convenient to hide it on an indented continuation line starting
+     with a #, for example:
+
+
+          Aug 31, 2007 09:30  Celebrate the end of the holidays
+            # UID 045B78A0
+
+     The second line will not be shown by the calendar function.
+
+     It is possible to specify the RPT keyword followed by CANCELLED
+     instead of a relative time.  This causes any matched event or
+     series of events to be cancelled (the original event does not have
+     to be marked as recurring in order to be cancelled by this
+     method).  A UID is required in order to match an existing event in
+     the calendar.
+
+     calendar_add will attempt to manage recurrences and occurrences of
+     repeating events as described for event scheduling by calendar -s
+     above.  To reschedule or cancel a single event calendar_add should
+     be called with an entry that includes the correct UID but does
+     _not_ include the RPT keyword as this is taken to mean the entry
+     applies to a series of repeating events and hence replaces all
+     existing information.  Each rescheduled or cancelled occurrence
+     must have an OCCURRENCE keyword in the entry passed to
+     calendar_add which will be merged into the calendar file.  Any
+     existing reference to the occurrence is replaced.  An occurrence
+     that does not refer to a valid existing event is added as a
+     one-off occurrence to the same calendar entry.
+
+calendar_edit
+     This calls the user's editor to edit the calendar file.  If there
+     are arguments, they are taken as the editor to use (the file name
+     is appended to the commands); otherwise, the editor is given by the
+     variable VISUAL, if set, else the variable EDITOR.
+
+     If the calendar scheduler was running, then after editing the file
+     calendar -s is called to update it.
+
+     This function locks out the calendar system during the edit.
+     Hence it should be used to edit the calendar file if there is any
+     possibility of a calendar event occurring meanwhile.  Note this
+     can lead to another shell with calendar functions enabled hanging
+     waiting for a lock, so it is necessary to quit the editor as soon
+     as possible.
+
+calendar_parse CALENDAR-ENTRY
+     This is the internal function that analyses the parts of a calendar
+     entry, which is passed as the only argument.  The function returns
+     status 1 if the argument could not be parsed as a calendar entry
+     and status 2 if the wrong number of arguments were passed; it also
+     sets the parameter reply to an empty associative array.  Otherwise,
+     it returns status 0 and sets elements of the associative array
+     reply as follows:
+
+
+    time
+          The time as a string of digits in the same units as
+          $EPOCHSECONDS
+
+    schedtime
+          The regularly scheduled time.  This may differ from the
+          actual event time time if this is a recurring event and the
+          next occurrence has been rescheduled.  Then time gives the
+          actual time and schedtime the time of the regular recurrence
+          before modification.
+
+    text1
+          The text from the line not including the date and time of the
+          event, but including any WARN or RPT keywords and values.
+
+    warntime
+          Any warning time given by the WARN keyword as a string of
+          digits containing the time at which to warn in the same units
+          as $EPOCHSECONDS.  (Note this is an absolute time, not the
+          relative time passed down.)  Not set no WARN keyword and
+          value were matched.
+
+    warnstr
+          The raw string matched after the WARN keyword, else unset.
+
+    rpttime
+          Any recurrence time given by the RPT keyword as a string of
+          digits containing the time of the recurrence in the same units
+          as $EPOCHSECONDS.  (Note this is an absolute time.)  Not set
+          if no RPT keyword and value were matched.
+
+    schedrpttime
+          The next regularly scheduled occurrence of a recurring event
+          before modification.  This may differ from rpttime, which is
+          the actual time of the event that may have been rescheduled
+          from the regular time.
+
+    rptstr
+          The raw string matched after the RPT keyword, else unset.
+
+    text2
+          The text from the line after removal of the date and any
+          keywords and values.
+
+
+     
+calendar_showdate [ -r ] [ -f FMT ] DATE-SPEC ...
+     The given DATE-SPEC is interpreted and the corresponding date and
+     time printed.  If the initial DATE-SPEC begins with a + or - it is
+     treated as relative to the current time; DATE-SPECs after the
+     first are treated as relative to the date calculated so far and a
+     leading + is optional in that case.  This allows one to use the
+     system as a date calculator.  For example, calendar_showdate '+1
+     month, 1st Friday' shows the date of the first Friday of next
+     month.
+
+     With the option -r nothing is printed but the value of the date and
+     time in seconds since the epoch is stored in the parameter REPLY.
+
+     With the option -f FMT the given date/time conversion format is
+     passed to strftime; see notes on the date-format style below.
+
+     In order to avoid ambiguity with negative relative date
+     specifications, options must occur in separate words; in other
+     words, -r and -f should not be combined in the same word.
+
+calendar_sort
+     Sorts the calendar file into date and time order.    The old
+     calendar is left in a file with the suffix .old.
+
+
+
+23.3.2 Glob qualifiers
+----------------------
+
+
+age
+     The function age can be autoloaded and use separately from the
+     calendar system, although it uses the function calendar_scandate
+     for date formatting.  It requires the zsh/stat builtin, but uses
+     only the builtin zstat.
+
+     age selects files having a given modification time for use as a
+     glob qualifier.  The format of the date is the same as that
+     understood by the calendar system, described in *Note Calendar
+     File and Date Formats::.
+
+     The function can take one or two arguments, which can be supplied
+     either directly as command or arguments, or separately as shell
+     parameters.
+
+
+          print *(e:age 2006/10/04 2006/10/09:)
+
+     The example above matches all files modified between the start of
+     those dates.  The second argument may alternatively be a relative
+     time introduced by a +:
+
+
+          print *(e:age 2006/10/04 +5d:)
+
+     The example above is equivalent to the previous example.
+
+     In addition to the special use of days of the week, today and
+     yesterday, times with no date may be specified; these apply to
+     today.  Obviously such uses become problematic around midnight.
+
+
+          print *(e-age 12:00 13:30-)
+
+     The example above shows files modified between 12:00 and 13:00
+     today.
+
+
+          print *(e:age 2006/10/04:)
+
+     The example above matches all files modified on that date.  If the
+     second argument is omitted it is taken to be exactly 24 hours
+     after the first argument (even if the first argument contains a
+     time).
+
+
+          print *(e-age 2006/10/04:10:15 2006/10/04:10:45-)
+
+     The example above supplies times.  Note that whitespace within the
+     time and date specification must be quoted to ensure age receives
+     the correct arguments, hence the use of the additional colon to
+     separate the date and time.
+
+
+          AGEREF=2006/10/04:10:15
+          AGEREF2=2006/10/04:10:45
+          print *(+age)
+
+     This shows the same example before using another form of argument
+     passing.  The dates and times in the parameters AGEREF and AGEREF2
+     stay in effect until unset, but will be overridden if any argument
+     is passed as an explicit argument to age.  Any explicit argument
+     causes both parameters to be ignored.
+
+     Instead of an explicit date and time, it's possible to use the
+     modification time of a file as the date and time for either
+     argument by introducing the file name with a colon:
+
+
+          print *(e-age :file1-)
+
+     matches all files created on the same day (24 hours starting from
+     midnight) as file1.
+
+
+          print *(e-age :file1 :file2-)
+
+     matches all files modified no earlier than file1 and no later than
+     file2; precision here is to the nearest second.
+
+after
+before
+     The functions after and before are simpler versions of age that
+     take just one argument.  The argument is parsed similarly to an
+     argument of age; if it is not given the variable AGEREF is
+     consulted.  As the names of the functions suggest, a file matches
+     if its modification time is after or before the time and date
+     specified.  If a time only is given the date is today.
+
+     The two following examples are therefore equivalent:
+          print *(e-after 12:00-)
+          print *(e-after today:12:00-)
+
+
+
+
+File: zsh.info,  Node: Calendar Styles,  Next: Calendar Utility Functions,  Prev: Calendar System User Functions,  Up: Calendar Function System
+
+23.4 Styles
+===========
+
+The zsh style mechanism using the zstyle command is describe in *Note
+The zsh/zutil Module::.  This is the same mechanism used in the
+completion system.
+
+The styles below are all examined in the context :datetime:FUNCTION:,
+for example :datetime:calendar:.
+
+
+calendar-file
+     The location of the main calendar.  The default is ~/calendar.
+
+date-format
+     A strftime format string (see man page strftime(3)) with the zsh
+     extensions providing various numbers with no leading zero or space
+     if the number is a single digit as described for the %D{STRING}
+     prompt format in *Note Prompt Expansion::.
+
+     This is used for outputting dates in calendar, both to support the
+     -v option and when adding recurring events back to the calendar
+     file, and in calendar_showdate as the final output format.
+
+     If the style is not set, the default used is similar the standard
+     system format as output by the date command (also known as `ctime
+     format'): `%a %b %d %H:%M:%S %Z %Y'.
+
+done-file
+     The location of the file to which events which have passed are
+     appended.  The default is the calendar file location with the
+     suffix .done.  The style may be set to an empty string in which
+     case a "done" file will not be maintained.
+
+reformat-date
+     Boolean, used by calendar_add.  If it is true, the date and time
+     of new entries added to the calendar will be reformatted to the
+     format given by the style date-format or its default.  Only the
+     date and time of the event itself is reformatted; any subsidiary
+     dates and times such as those associated with repeat and warning
+     times are left alone.
+
+show-prog
+     The programme run by calendar for showing events.  It will be
+     passed the start time and stop time of the events requested in
+     seconds since the epoch followed by the event text.  Note that
+     calendar -s uses a start time and stop time equal to one another
+     to indicate alerts for specific events.
+
+     The default is the function calendar_show.
+
+warn-time
+     The time before an event at which a warning will be displayed, if
+     the first line of the event does not include the text EVENT
+     RELTIME.  The default is 5 minutes.
+
+
+
+
+File: zsh.info,  Node: Calendar Utility Functions,  Next: Calendar Bugs,  Prev: Calendar Styles,  Up: Calendar Function System
+
+23.5 Utility functions
+======================
+
+
+calendar_lockfiles
+     Attempt to lock the files given in the argument.  To prevent
+     problems with network file locking this is done in an ad hoc
+     fashion by attempting to create a symbolic link to the file with
+     the name FILE.lockfile.  No other system level functions are used
+     for locking, i.e. the file can be accessed and modified by any
+     utility that does not use this mechanism.  In particular, the user
+     is not prevented from editing the calendar file at the same time
+     unless calendar_edit is used.
+
+     Three attempts are made to lock the file before giving up.  If the
+     module zsh/zselect is available, the times of the attempts are
+     jittered so that multiple instances of the calling function are
+     unlikely to retry at the same time.
+
+     The files locked are appended to the array lockfiles, which should
+     be local to the caller.
+
+     If all files were successfully locked, status zero is returned,
+     else status one.
+
+     This function may be used as a general file locking function,
+     although this will only work if only this mechanism is used to
+     lock files.
+
+calendar_read
+     This is a backend used by various other functions to parse the
+     calendar file, which is passed as the only argument.  The array
+     calendar_entries is set to the list of events in the file; no
+     pruning is done except that ampersands are removed from the start
+     of the line.  Each entry may contain multiple lines.
+
+calendar_scandate
+     This is a generic function to parse dates and times that may be
+     used separately from the calendar system.  The argument is a date
+     or time specification as described in *Note Calendar File and Date
+     Formats::.  The parameter REPLY is set to the number of seconds
+     since the epoch corresponding to that date or time.  By default,
+     the date and time may occur anywhere within the given argument.
+
+     Returns status zero if the date and time were successfully parsed,
+     else one.
+
+     Options:
+    -a
+          The date and time are anchored to the start of the argument;
+          they will not be matched if there is preceding text.
+
+    -A
+          The date and time are anchored to both the start and end of
+          the argument; they will not be matched if the is any other
+          text in the argument.
+
+    -d
+          Enable additional debugging output.
+
+    -m
+          Minus.  When -R ANCHOR_TIME is also given the relative time is
+          calculated backwards from ANCHOR_TIME.
+
+    -r
+          The argument passed is to be parsed as a relative time.
+
+    -R ANCHOR_TIME
+          The argument passed is to be parsed as a relative time.  The
+          time is relative to ANCHOR_TIME, a time in seconds since the
+          epoch, and the returned value is the absolute time
+          corresponding to advancing ANCHOR_TIME by the relative time
+          given.  This allows lengths of months to be correctly taken
+          into account.  If the final day does not exist in the given
+          month, the last day of the final month is given.  For
+          example, if the anchor time is during 31st January 2007 and
+          the relative time is 1 month, the final time is the same time
+          of day during 28th February 2007.
+
+    -s
+          In addition to setting REPLY, set REPLY2 to the remainder of
+          the argument after the date and time have been stripped.
+          This is empty if the option -A was given.
+
+    -t
+          Allow a time with no date specification.  The date is assumed
+          to be today.  The behaviour is unspecified if the iron tongue
+          of midnight is tolling twelve.
+
+
+calendar_show
+     The function used by default to display events.  It accepts a
+     start time and end time for events, both in epoch seconds, and an
+     event description.
+
+     The event is always printed to standard output.  If the command
+     line editor is active (which will usually be the case) the command
+     line will be redisplayed after the output.
+
+     If the parameter DISPLAY is set and the start and end times are
+     the same (indicating a scheduled event), the function uses the
+     command xmessage to display a window with the event details.
+
+
+
+
+File: zsh.info,  Node: Calendar Bugs,  Prev: Calendar Utility Functions,  Up: Calendar Function System
+
+23.6 Bugs
+=========
+
+As the system is based entirely on shell functions (with a little
+support from the zsh/datetime module) the mechanisms used are not as
+robust as those provided by a dedicated calendar utility.  Consequently
+the user should not rely on the shell for vital alerts.
+
+There is no calendar_delete function.
+
+There is no localization support for dates and times, nor any support
+for the use of time zones.
+
+Relative periods of months and years do not take into account the
+variable number of days.
+
+The calendar_show function is currently hardwired to use xmessage for
+displaying alerts on X Window System displays.  This should be
+configurable and ideally integrate better with the desktop.
+
+calendar_lockfiles hangs the shell while waiting for a lock on a file.
+If called from a scheduled task, it should instead reschedule the event
+that caused it.
+
+
+File: zsh.info,  Node: TCP Function System,  Next: Zftp Function System,  Prev: Calendar Function System,  Up: Top
+
+24 TCP Function System
+**********************
+
+
+
+24.1 Description
+================
+
+A module zsh/net/tcp is provided to provide network I/O over TCP/IP
+from within the shell; see its description in *Note 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 autoloading in the
+default function search path.  In addition to the zsh/net/tcp module,
+the zsh/zselect module is used to implement timeouts on read
+operations.  For troubleshooting tips, consult the corresponding advice
+for the zftp functions described in *Note Zftp Function System::.
+
+There are functions corresponding to the basic I/O operations open,
+close, read and send, named tcp_open etc., as well as a function
+tcp_expect for pattern match analysis of data read as input.  The
+system makes it easy to receive data from and send data to multiple
+named sessions at once.  In addition, it can be linked with the shell's
+line editor in such a way that input data is automatically shown at the
+terminal.  Other facilities available including logging, filtering and
+configurable output prompts.
+
+To use the system where it is available, it should be enough to
+`autoload -U tcp_open' and run tcp_open as documented below to start a
+session.  The tcp_open function will autoload the remaining functions.
+
+
+
+* Menu:
+
+* TCP Functions::
+* TCP Parameters::
+* TCP Examples::
+* TCP Bugs::
+
+
+
+File: zsh.info,  Node: TCP Functions,  Next: TCP Parameters,  Up: TCP Function System
+
+24.2 TCP User Functions
+=======================
+
+
+
+24.2.1 Basic I/O
+----------------
+
+
+tcp_open [ -qz ] HOST PORT [ SESS ]
+tcp_open [ -qz ] [ -s SESS | -l SESS[,...] ] ...
+tcp_open [ -qz ] [ -a FD | -f FD ] [ SESS ]
+     Open a new session.  In the first and simplest form, open a TCP
+     connection to host HOST at port PORT; numeric and symbolic forms
+     are understood for both.
+
+     If SESS is given, this becomes the name of the session which can be
+     used to refer to multiple different TCP connections.  If SESS is
+     not given, the function will invent a numeric name value (note
+     this is _not_ the same as the file descriptor to which the session
+     is attached).  It is recommended that session names not include
+     `funny' characters, where funny characters are not well-defined
+     but certainly do not include alphanumerics or underscores, and
+     certainly do include whitespace.
+
+     In the second case, one or more sessions to be opened are given by
+     name.  A single session name is given after -s and a
+     comma-separated list after -l; both options may be repeated as
+     many times as necessary.  A failure to open any session causes
+     tcp_open to abort.  The host and port are read from the file
+     .ztcp_sessions in the same directory as the user's zsh
+     initialisation files, i.e. usually the home directory, but
+     $ZDOTDIR if that is set.  The file consists of lines each giving a
+     session name and the corresponding host and port, in that order
+     (note the session name comes first, not last), separated by
+     whitespace.
+
+     The third form allows passive and fake TCP connections.  If the
+     option -a is used, its argument is a file descriptor open for
+     listening for connections.  No function front-end is provided to
+     open such a file descriptor, but a call to `ztcp -l PORT' will
+     create one with the file descriptor stored in the parameter
+     $REPLY.  The listening port can be closed with `ztcp -c FD'.  A
+     call to `tcp_open -a FD' will block until a remote TCP connection
+     is made to PORT on the local machine.  At this point, a session is
+     created in the usual way and is largely indistinguishable from an
+     active connection created with one of the first two forms.
+
+     If the option -f is used, its argument is a file descriptor which
+     is used directly as if it were a TCP session.  How well the
+     remainder of the TCP function system copes with this depends on
+     what actually underlies this file descriptor.  A regular file is
+     likely to be unusable; a FIFO (pipe) of some sort will work
+     better, but note that it is not a good idea for two different
+     sessions to attempt to read from the same FIFO at once.
+
+     If the option -q is given with any of the three forms, tcp_open
+     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, 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 -z to any of the forms of tcp_open prevents the
+     handler from being installed, so data must be read explicitly.
+     Note, however, this is not necessary for executing complete sets
+     of send and read commands from a function, as zle is not active at
+     this point.  Generally speaking, the handler is only active when
+     the shell is waiting for input at a command prompt or in the vared
+     builtin.  The option has no effect if zle is not active; `[[ -o
+     zle]]' will test for this.
+
+     The first session to be opened becomes the current session and
+     subsequent calls to tcp_open do not change it.  The current
+     session is stored in the parameter $TCP_SESS; see below for more
+     detail about the parameters used by the system.
+
+     The function tcp_on_open, if defined, is called when a session is
+     opened.  See the description below.
+
+tcp_close [ -qn ] [ -a | -l SESS[,...] | SESS ... ]
+     Close the named sessions, or the current session if none is given,
+     or all open sessions if -a is given.  The options -l and -s are
+     both handled for consistency with tcp_open, although the latter is
+     redundant.
+
+     If the session being closed is the current one, $TCP_SESS is unset,
+     leaving no current session, even if there are other sessions still
+     open.
+
+     If the session was opened with tcp_open -f, the file descriptor is
+     closed so long as it is in the range 0 to 9 accessible directly
+     from the command line.  If the option -n is given, no attempt will
+     be made to close file descriptors in this case.  The -n option is
+     not used for genuine ztcp session; the file descriptors are always
+     closed with the session.
+
+     If the option -q is given, no informational messages will be
+     printed.
+
+tcp_read [ -bdq ] [ -t TO ] [ -T TO ]
+         [ -a | -u FD[,...] | -l SESS[,...] | -s SESS ... ]
+     Perform a read operation on the current session, or on a list of
+     sessions if any are given with -u, -l or -s, or all open sessions
+     if the option -a is given.  Any of the -u, -l or -s options may be
+     repeated or mixed together.  The -u option specifies a file
+     descriptor directly (only those managed by this system are
+     useful), the other two specify sessions as described for tcp_open
+     above.
+
+     The function checks for new data available on all the sessions
+     listed.  Unless the -b option is given, it will not block waiting
+     for new data.  Any one line of data from any of the available
+     sessions will be read, stored in the parameter $TCP_LINE, and
+     displayed to standard output unless $TCP_SILENT contains a
+     non-empty string.  When printed to standard output the string
+     $TCP_PROMPT will be shown at the start of the line; the default
+     form for this includes the name of the session being read.  See
+     below for more information on these parameters.  In this mode,
+     tcp_read can be called repeatedly until it returns status 2 which
+     indicates all pending input from all specified sessions has been
+     handled.
+
+     With the option -b, equivalent to an infinite timeout, the function
+     will block until a line is available to read from one of the
+     specified sessions.  However, only a single line is returned.
+
+     The option -d indicates that all pending input should be drained.
+     In this case tcp_read may process multiple lines in the manner
+     given above; only the last is stored in $TCP_LINE, but the
+     complete set is stored in the array $tcp_lines.  This is cleared
+     at the start of each call to tcp_read.
+
+     The options -t and -T specify a timeout in seconds, which may be a
+     floating point number for increased accuracy.  With -t the timeout
+     is applied before each line read.  With -T, the timeout applies to
+     the overall operation, possibly including multiple read operations
+     if the option -d is present; without this option, there is no
+     distinction between -t and -T.
+
+     The function does not print informational messages, but if the
+     option -q is given, no error message is printed for a non-existent
+     session.
+
+     A return status of 2 indicates a timeout or no data to read.  Any
+     other non-zero return status indicates some error condition.
+
+     See tcp_log for how to control where data is sent by tcp_read.
+
+tcp_send [ -cnq ] [ -s SESS | -l SESS[,...] ] DATA ...
+tcp_send [ -cnq ] -a DATA ...
+     Send the supplied data strings to all the specified sessions in
+     turn.  The underlying operation differs little from a `print -r'
+     to the session's file descriptor, although it attempts to prevent
+     the shell from dying owing to a SIGPIPE caused by an attempt to
+     write to a defunct session.
+
+     The option -c causes tcp_send to behave like cat.  It reads lines
+     from standard input until end of input and sends them in turn to
+     the specified session(s) exactly as if they were given as DATA
+     arguments to individual tcp_send commands.
+
+     The option -n prevents tcp_send from putting a newline at the end
+     of the data strings.
+
+     The remaining options all behave as for tcp_read.
+
+     The data arguments are not further processed once they have been
+     passed to tcp_send; they are simply passed down to print -r.
+
+     If the parameter $TCP_OUTPUT is a non-empty string and logging is
+     enabled then the data sent to each session will be echoed to the
+     log file(s) with $TCP_OUTPUT in front where appropriate, much in
+     the manner of $TCP_PROMPT.
+
+
+
+24.2.2 Session Management
+-------------------------
+
+
+tcp_alias [ -q ] ALIAS=SESS ...
+tcp_alias [ -q ] [ ALIAS ... ]
+tcp_alias -d [ -q ] ALIAS ...
+     This function is not particularly well tested.
+
+     The first form creates an alias for a session name; ALIAS can then
+     be used to refer to the existing session SESS.  As many aliases
+     may be listed as required.
+
+     The second form lists any aliases specified, or all aliases if
+     none.
+
+     The third form deletes all the aliases listed.  The underlying
+     sessions are not affected.
+
+     The option -q suppresses an inconsistently chosen subset of error
+     messages.
+
+tcp_log [ -asc ] [ -n | -N ] [ LOGFILE ]
+     With an argument LOGFILE, all future input from tcp_read will be
+     logged to the named file.  Unless -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 -s, per-session logging is enabled.  Input from
+     tcp_read is output to the file LOGFILE.SESS.  As the session is
+     automatically discriminated by the filename, the contents are raw
+     (no $TCP_PROMPT).  The option  -a applies as above.  Per-session
+     logging and logging of all data in one file are not mutually
+     exclusive.
+
+     The option -c closes all logging, both complete and per-session
+     logs.
+
+     The options -n and -N respectively turn off or restore output of
+     data read by tcp_read to standard output; hence `tcp_log -cn' turns
+     off all output by tcp_read.
+
+     The function is purely a convenient front end to setting the
+     parameters $TCP_LOG, $TCP_LOG_SESS, $TCP_SILENT, which are
+     described below.
+
+tcp_rename OLD NEW
+     Rename session OLD to session NEW.  The old name becomes invalid.
+
+tcp_sess [ SESS [ COMMAND [ 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 $tcp_by_name,
+     $tcp_by_fd and $TCP_SESS is probably more convenient; see below.
+
+     With a SESS argument, set the current session to SESS.  This is
+     equivalent to changing $TCP_SESS directly.
+
+     With additional arguments, temporarily set the current session
+     while executing `COMMAND ARG ...'.  COMMAND is re-evaluated so as
+     to expand aliases etc., but the remaining ARGs are passed through
+     as that appear to tcp_sess.  The original session is restored when
+     tcp_sess exits.
+
+
+
+24.2.3 Advanced I/O
+-------------------
+
+
+tcp_command SEND-OPTION ... SEND-ARGUMENT ...
+     This is a convenient front-end to tcp_send.  All arguments are
+     passed to tcp_send, then the function pauses waiting for data.
+     While data is arriving at least every $TCP_TIMEOUT (default 0.3)
+     seconds, data is handled and printed out according to the current
+     settings.  Status 0 is always returned.
+
+     This is generally only useful for interactive use, to prevent the
+     display becoming fragmented by output returned from the
+     connection.  Within a programme or function it is generally better
+     to handle reading data by a more explicit method.
+
+tcp_expect [ -q ] [ -p VAR | -P VAR ] [ -t TO | -T TO ]
+           [ -a | -s SESS | -l SESS[,...] ] PATTERN ...
+     Wait for input matching any of the given PATTERNs 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 line is stored in $TCP_LINE, and the full set of
+     lines read during the call to tcp_expect is stored in the array
+     $tcp_expect_lines.
+
+     Sessions are specified in the same way as tcp_read: the default is
+     to use the current session, otherwise the sessions specified by -a,
+     -s, or -l are used.
+
+     Each PATTERN is a standard zsh extended-globbing pattern; note
+     that it needs to be quoted to avoid it being expanded immediately
+     by filename generation.  It must match the full line, so to match
+     a substring there must be a `*' at the start and end.  The line
+     matched against includes the $TCP_PROMPT added by tcp_read.  It is
+     possible to include the globbing flags `#b' or `#m' in the
+     patterns to make backreferences available in the parameters
+     $MATCH, $match, etc., as described in the base zsh documentation
+     on pattern matching.
+
+     Unlike tcp_read, the default behaviour of tcp_expect is to block
+     indefinitely until the required input is found.  This can be
+     modified by specifying a timeout with -t or -T; these function as
+     in tcp_read, specifying a per-read or overall timeout,
+     respectively, in seconds, as an integer or floating-point number.
+     As tcp_read, the function returns status 2 if a timeout occurs.
+
+     The function returns as soon as any one of the patterns given
+     match.  If the caller needs to know which of the patterns matched,
+     the option -p VAR can be used; on return, $var is set to the
+     number of the pattern using ordinary zsh indexing, i.e. the first
+     is 1, and so on.  Note the absence of a `$' in front of VAR.  To
+     avoid clashes, the parameter cannot begin with `_expect'.  The
+     index -1 is used if there is a timeout and 0 if there is no match.
+
+     The option -P VAR works similarly to -p, but instead of numerical
+     indexes the regular arguments must begin with a prefix followed by
+     a colon: that prefix is then used as a tag to which VAR is set
+     when the argument matches.  The tag timeout is used if there is a
+     timeout and the empty string if there is no match.  Note it is
+     acceptable for different arguments to start with the same prefix
+     if the matches do not need to be distinguished.
+
+     The option -q is passed directly down to tcp_read.
+
+     As all input is done via tcp_read, all the usual rules about
+     output of lines read apply.  One exception is that the parameter
+     $tcp_lines will only reflect the line actually matched by
+     tcp_expect; use $tcp_expect_lines for the full set of lines read
+     during the function call.
+
+tcp_proxy
+     This is a simple-minded function to accept a TCP connection and
+     execute a command with I/O redirected to the connection.  Extreme
+     caution should be taken as there is no security whatsoever and
+     this can leave your computer open to the world.  Ideally, it
+     should only be used behind a firewall.
+
+     The first argument is a TCP port on which the function will listen.
+
+     The remaining arguments give a command and its arguments to
+     execute with standard input, standard output and standard error
+     redirected to the file descriptor on which the TCP session has
+     been accepted.  If no command is given, a new zsh is started.
+     This gives everyone on your network direct access to your account,
+     which in many cases will be a bad thing.
+
+     The command is run in the background, so tcp_proxy can then accept
+     new connections.  It continues to accept new connections until
+     interrupted.
+
+tcp_spam [ -ertv ] [ -a | -s SESS | -l SESS[,...] ] CMD [ ARG ... ]
+     Execute `CMD [ ARG ... ]' for each session in turn.  Note this
+     executes the command and arguments; it does not send the command
+     line as data unless the -t (transmit) option is given.
+
+     The sessions may be selected explicitly with the standard -a, -s or
+     -l options, or may be chosen implicitly.  If none of the three
+     options is given the rules are: first, if the array $tcp_spam_list
+     is set, this is taken as the list of sessions, otherwise all
+     sessions are taken.  Second, any sessions given in the array
+     $tcp_no_spam_list are removed from the list of sessions.
+
+     Normally, any sessions added by the `-a' flag or when all sessions
+     are chosen implicitly are spammed in alphabetic order; sessions
+     given by the $tcp_spam_list array or on the command line are
+     spammed in the order given.  The -r flag reverses the order
+     however it was arrived it.
+
+     The -v flag specifies that a $TCP_PROMPT will be output before each
+     session.  This is output after any modification to TCP_SESS by the
+     user-defined tcp_on_spam function described below.  (Obviously that
+     function is able to generate its own output.)
+
+     If the option -e is present, the line given as `CMD [ ARG ... ]'
+     is executed using eval, otherwise it is executed without any
+     further processing.
+
+tcp_talk
+     This is a fairly simple-minded attempt to force input to the line
+     editor to go straight to the default TCP_SESS.
+
+     An escape string, $TCP_TALK_ESCAPE, default `:', 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 and the remainder of the line
+     executed as shell input without any change of the line editor's
+     operating mode.
+
+     The current implementation is somewhat deficient in terms of use
+     of the command history.  For this reason, many users will prefer
+     to use some form of alternative approach for sending data easily
+     to the current session.  One simple approach is to alias some
+     special character (such as `%') to `tcp_command --'.
+
+tcp_wait
+     The sole argument is an integer or floating point number which
+     gives the seconds to delay.  The shell will do nothing for that
+     period except wait for input on all TCP sessions by calling
+     tcp_read -a.  This is similar to the interactive behaviour at the
+     command prompt when zle handlers are installed.
+
+
+
+24.2.4 `One-shot' file transfer
+-------------------------------
+
+
+tcp_point PORT
+tcp_shoot HOST PORT
+     This pair of functions provide a simple way to transfer a file
+     between two hosts within the shell.  Note, however, that bulk data
+     transfer is currently done using cat.  tcp_point reads any data
+     arriving at PORT and sends it to standard output; tcp_shoot
+     connects to PORT on HOST and sends its standard input.  Any unused
+     PORT may be used; the standard mechanism for picking a port is to
+     think of a random four-digit number above 1024 until one works.
+
+     To transfer a file from host woodcock to host springes, on
+     springes:
+
+
+          tcp_point 8091 >output_file
+
+     and on woodcock:
+
+
+          tcp_shoot springes 8091 <input_file
+
+     As these two functions do not require tcp_open to set up a TCP
+     connection first, they may need to be autoloaded separately.
+
+
+
+24.3 TCP User-defined Functions
+===============================
+
+Certain functions, if defined by the user, will be called by the
+function system in certain contexts.  This facility depends on the
+module zsh/parameter, which is usually available in interactive shells
+as the completion system depends on it.  None of the functions need be
+defined; they simply provide convenient hooks when necessary.
+
+Typically, these are called after the requested action has been taken,
+so that the various parameters will reflect the new state.
+
+
+tcp_on_alias ALIAS FD
+     When an alias is defined, this function will be called with two
+     arguments: the name of the alias, and the file descriptor of the
+     corresponding session.
+
+tcp_on_awol SESS FD
+     If the function tcp_fd_handler is handling input from the line
+     editor and detects that the file descriptor is no longer reusable,
+     by default it removes it from the list of file descriptors handled
+     by this method and prints a message.  If the function tcp_on_awol
+     is defined it is called immediately before this point.  It may
+     return status 100, which indicates that the normal handling should
+     still be performed; any other return status indicates that no
+     further action should be taken and the tcp_fd_handler should return
+     immediately with the given status.  Typically the action of
+     tcp_on_awol will be to close the session.
+
+     The variable TCP_INVALIDATE_ZLE will be a non-empty string if it is
+     necessary to invalidate the line editor display using `zle -I'
+     before printing output from the function.
+
+     (`AWOL' is military jargon for `absent without leave' or some
+     variation.  It has no pre-existing technical meaning known to the
+     author.)
+
+tcp_on_close SESS FD
+     This is called with the name of a session being closed and the file
+     descriptor which corresponded to that session.  Both will be
+     invalid by the time the function is called.
+
+tcp_on_open SESS FD
+     This is called after a new session has been defined with the
+     session name and file descriptor as arguments.  If it returns a
+     non-zero status, opening the session is assumed to fail and the
+     session is closed again; however, tcp_open will continue to
+     attempt to open any remaining sessions given on the command line.
+
+tcp_on_rename OLDSESS FD NEWSESS
+     This is called after a session has been renamed with the three
+     arguments old session name, file descriptor, new session name.
+
+tcp_on_spam SESS COMMAND ...
+     This is called once for each session spammed, just _before_ a
+     command is executed for a session by tcp_spam.  The arguments are
+     the session name followed by the command list to be executed.  If
+     tcp_spam was called with the option -t, the first command will be
+     tcp_send.
+
+     This function is called after $TCP_SESS is set to reflect the
+     session to be spammed, but before any use of it is made.  Hence it
+     is possible to alter the value of $TCP_SESS within this function.
+     For example, the session arguments to tcp_spam could include extra
+     information to be stripped off and processed in tcp_on_spam.
+
+     If the function sets the parameter $REPLY to `done', the command
+     line is not executed; in addition, no prompt is printed for the -v
+     option to tcp_spam.
+
+tcp_on_unalias ALIAS FD
+     This is called with the name of an alias and the corresponding
+     session's file descriptor after an alias has been deleted.
+
+
+
+24.4 TCP Utility Functions
+==========================
+
+The following functions are used by the TCP function system but will
+rarely if ever need to be called directly.
+
+
+tcp_fd_handler
+     This is the function installed by tcp_open for handling input from
+     within the line editor, if that is required.  It is in the format
+     documented for the builtin `zle -F' in *Note Zle Builtins:: .
+
+     While active, the function sets the parameter TCP_HANDLER_ACTIVE
+     to 1.  This allows shell code called internally (for example, by
+     setting tcp_on_read) to tell if is being called when the shell is
+     otherwise idle at the editor prompt.
+
+tcp_output [ -q ] -P PROMPT -F FD -S SESS
+     This function is used for both logging and handling output to
+     standard output, from within tcp_read and (if $TCP_OUTPUT is set)
+     tcp_send.
+
+     The PROMPT to use is specified by -P; the default is the empty
+     string.  It can contain:
+    %c
+          Expands to 1 if the session is the current session, otherwise
+          0.  Used with ternary expressions such as `%(c.-.+)' to
+          output `+' for the current session and `-' otherwise.
+
+    %f
+          Replaced by the session's file descriptor.
+
+    %s
+          Replaced by the session name.
+
+    %%
+          Replaced by a single `%'.
+
+
+     The option -q suppresses output to standard output, but not to any
+     log files which are configured.
+
+     The -S and -F options are used to pass in the session name and file
+     descriptor for possible replacement in the prompt.
+
+
+
+
+File: zsh.info,  Node: TCP Parameters,  Next: TCP Examples,  Prev: TCP Functions,  Up: TCP Function System
+
+24.5 TCP User Parameters
+========================
+
+Parameters follow the usual convention that uppercase is used for
+scalars and integers, while lowercase is used for normal and
+associative array.  It is always safe for user code to read these
+parameters.  Some parameters may also be set; these are noted
+explicitly.  Others are included in this group as they are set by the
+function system for the user's benefit, i.e. setting them is typically
+not useful but is benign.
+
+It is often also useful to make settable parameters local to a function.
+For example, `local TCP_SILENT=1' specifies that data read during the
+function call will not be printed to standard output, regardless of the
+setting outside the function.  Likewise, `local TCP_SESS=SESS' sets a
+session for the duration of a function, and `local TCP_PROMPT='
+specifies that no prompt is used for input during the function.
+
+
+tcp_expect_lines
+     Array.  The set of lines read during the last call to tcp_expect,
+     including the last ($TCP_LINE).
+
+tcp_filter
+     Array. May be set directly.  A set of extended globbing patterns
+     which, if matched in tcp_output, will cause the line not to be
+     printed to standard output.  The patterns should be defined as
+     described for the arguments to tcp_expect.  Output of line to log
+     files is not affected.
+
+TCP_HANDLER_ACTIVE
+     Scalar.  Set to 1 within tcp_fd_handler to indicate to functions
+     called recursively that they have been called during an editor
+     session.  Otherwise unset.
+
+TCP_LINE
+     The last line read by tcp_read, and hence also tcp_expect.
+
+TCP_LINE_FD
+     The file descriptor from which $TCP_LINE was read.
+     ${tcp_by_fd[$TCP_LINE_FD]} will give the corresponding session
+     name.
+
+tcp_lines
+     Array. The set of lines read during the last call to tcp_read,
+     including the last ($TCP_LINE).
+
+TCP_LOG
+     May be set directly, although it is also controlled by tcp_log.
+     The name of a file to which output from all sessions will be sent.
+     The output is proceeded by the usual $TCP_PROMPT.  If it is not an
+     absolute path name, it will follow the user's current directory.
+
+TCP_LOG_SESS
+     May be set directly, although it is also controlled by tcp_log.
+     The prefix for a set of files to which output from each session
+     separately will be sent; the full filename is ${TCP_LOG_SESS}.SESS.
+     Output to each file is raw; no prompt is added.  If it is not an
+     absolute path name, it will follow the user's current directory.
+
+tcp_no_spam_list
+     Array.  May be set directly.  See tcp_spam for how this is used.
+
+TCP_OUTPUT
+     May be set directly.  If a non-empty string, any data sent to a
+     session by tcp_send will be logged.  This parameter gives the
+     prompt to be used in a file specified by $TCP_LOG but not in a
+     file generated from $TCP_LOG_SESS.  The prompt string has the same
+     format as TCP_PROMPT and the same rules for its use apply.
+
+TCP_PROMPT
+     May be set directly.  Used as the prefix for data read by tcp_read
+     which is printed to standard output or to the log file given by
+     $TCP_LOG, if any.  Any `%s', `%f' or `%%' occurring in the string
+     will be replaced by the name of the session, the session's
+     underlying file descriptor, or a single `%', respectively.  The
+     expression `%c' expands to 1 if the session being read is the
+     current session, else 0; this is most useful in ternary
+     expressions such as `%(c.-.+)' which outputs `+' if the session is
+     the current one, else `-'.
+
+     If the prompt starts with %P, this is stripped and the complete
+     result of the previous stage is passed through standard prompt
+     %-style formatting before being output.
+
+TCP_READ_DEBUG
+     May be set directly.  If this has non-zero length, tcp_read will
+     give some limited diagnostics about data being read.
+
+TCP_SECONDS_START
+     This value is created and initialised to zero by tcp_open.
+
+     The functions tcp_read and tcp_expect use the shell's SECONDS
+     parameter for their own timing purposes.  If that parameter is not
+     of floating point type on entry to one of the functions, it will
+     create a local parameter SECONDS which is floating point and set
+     the parameter TCP_SECONDS_START to the previous value of $SECONDS.
+     If the parameter is already floating point, it is used without a
+     local copy being created and TCP_SECONDS_START is not set.  As the
+     global value is zero, the shell elapsed time is guaranteed to be
+     the sum of $SECONDS and $TCP_SECONDS_START.
+
+     This can be avoided by setting SECONDS globally to a floating point
+     value using `typeset -F SECONDS'; then the TCP functions will never
+     make a local copy and never set TCP_SECONDS_START to a non-zero
+     value.
+
+TCP_SESS
+     May be set directly.  The current session; must refer to one of the
+     sessions established by tcp_open.
+
+TCP_SILENT
+     May be set directly, although it is also controlled by tcp_log.
+     If of non-zero length, data read by tcp_read will not be written to
+     standard output, though may still be written to a log file.
+
+tcp_spam_list
+     Array.  May be set directly.  See the description of the function
+     tcp_spam for how this is used.
+
+TCP_TALK_ESCAPE
+     May be set directly.  See the description of the function tcp_talk
+     for how this is used.
+
+TCP_TIMEOUT
+     May be set directly.  Currently this is only used by the function
+     tcp_command, see above.
+
+
+
+24.6 TCP User-defined Parameters
+================================
+
+The following parameters are not set by the function system, but have a
+special effect if set by the user.
+
+
+tcp_on_read
+     This should be an associative array; if it is not, the behaviour is
+     undefined.  Each key is the name of a shell function or other
+     command, and the corresponding value is a shell pattern (using
+     EXTENDED_GLOB).  Every line read from a TCP session directly or
+     indirectly using tcp_read (which includes lines read by
+     tcp_expect) is compared against the pattern.  If the line matches,
+     the command given in the key is called with two arguments: the
+     name of the session from which the line was read, and the line
+     itself.
+
+     If any function called to handle a line returns a non-zero status,
+     the line is not output.  Thus a tcp_on_read handler containing only
+     the instruction `return 1' can be used to suppress output of
+     particular lines (see, however, tcp_filter above).  However, the
+     line is still stored in TCP_LINE and tcp_lines; this occurs after
+     all tcp_on_read processing.
+
+
+
+24.7 TCP Utility Parameters
+===========================
+
+These parameters are controlled by the function system; they may be read
+directly, but should not usually be set by user code.
+
+
+tcp_aliases
+     Associative array.  The keys are the names of sessions established
+     with tcp_open; each value is a space-separated list of aliases
+     which refer to that session.
+
+tcp_by_fd
+     Associative array.  The keys are session file descriptors; each
+     value is the name of that session.
+
+tcp_by_name
+     Associative array.  The keys are the names of sessions; each value
+     is the file descriptor associated with that session.
+
+
+
+
+File: zsh.info,  Node: TCP Examples,  Next: TCP Bugs,  Prev: TCP Parameters,  Up: TCP Function System
+
+24.8 TCP Examples
+=================
+
+Here is a trivial example using a remote calculator.
+
+To create a calculator server on port 7337 (see the dc manual page for
+quite how infuriating the underlying command is):
+
+
+     tcp_proxy 7337 dc
+
+To connect to this from the same host with a session also named `dc':
+
+
+     tcp_open localhost 7337 dc
+
+To send a command to the remote session and wait a short while for
+output (assuming dc is the current session):
+
+
+     tcp_command 2 4 + p
+
+To close the session:
+
+
+     tcp_close
+
+The tcp_proxy needs to be killed to be stopped.  Note this will not
+usually kill any connections which have already been accepted, and also
+that the port is not immediately available for reuse.
+
+The following chunk of code puts a list of sessions into an xterm
+header, with the current session followed by a star.
+
+
+     print -n "\033]2;TCP:" ${(k)tcp_by_name:/$TCP_SESS/$TCP_SESS\*} "\a"
+
+
+
+File: zsh.info,  Node: TCP Bugs,  Prev: TCP Examples,  Up: TCP Function System
+
+24.9 TCP Bugs
+=============
+
+The function tcp_read uses the shell's normal read builtin.  As this
+reads a complete line at once, data arriving without a terminating
+newline can cause the function to block indefinitely.
+
+Though the function suite works well for interactive use and for data
+arriving in small amounts, the performance when large amounts of data
+are being exchanged is likely to be extremely poor.
+
+
+File: zsh.info,  Node: Zftp Function System,  Next: User Contributions,  Prev: TCP Function System,  Up: Top
+
+25 Zftp Function System
+***********************
+
+
+
+25.1 Description
+================
+
+This describes the set of shell functions supplied with the source
+distribution as an interface to the zftp builtin command, allowing you
+to perform FTP operations from the shell command line or within
+functions or scripts.  The interface is similar to a traditional FTP
+client (e.g. the ftp command itself, see man page ftp(1)), but as it is
+entirely done within the shell all the familiar completion, editing and
+globbing features, and so on, are present, and macros are particularly
+simple to write as they are just ordinary shell functions.
+
+The prerequisite is that the zftp command, as described in *Note The
+zsh/zftp Module:: , must be available in the version of zsh installed
+at your site.  If the shell is configured to load new commands at run
+time, it probably is: typing `zmodload zsh/zftp' will make sure (if
+that runs silently, it has worked).  If this is not the case, it is
+possible zftp was linked into the shell anyway: to test this, type
+`which zftp' and if zftp is available you will get the message `zftp:
+shell built-in command'.
+
+Commands given directly with zftp builtin may be interspersed between
+the functions in this suite; in a few cases, using zftp directly may
+cause some of the status information stored in shell parameters to
+become invalid.  Note in particular the description of the variables
+$ZFTP_TMOUT, $ZFTP_PREFS and $ZFTP_VERBOSE for zftp.
+
+
+
+* Menu:
+
+* Installation::
+* Zftp Functions::
+* Miscellaneous Features::
+
+
+
+File: zsh.info,  Node: Installation,  Next: Zftp Functions,  Up: Zftp Function System
+
+25.2 Installation
+=================
+
+You should make sure all the functions from the Functions/Zftp
+directory of the source distribution are available; they all begin with
+the two letters `zf'.  They may already have been installed on your
+system; otherwise, you will need to find them and copy them.  The
+directory should appear as one of the elements of the $fpath array
+(this should already be the case if they were installed), and at least
+the function zfinit should be autoloaded; it will autoload the rest.
+Finally, to initialize the use of the system you need to call the
+zfinit function.  The following code in your .zshrc will arrange for
+this; assume the functions are stored in the directory ~/myfns:
+
+
+     fpath=(~/myfns $fpath)
+     autoload -U zfinit
+     zfinit
+
+Note that zfinit assumes you are using the zmodload method to load the
+zftp command.  If it is already built into the shell, change zfinit to
+zfinit -n.  It is helpful (though not essential) if the call to zfinit
+appears after any code to initialize the new completion system, else
+unnecessary compctl commands will be given.
+
+
+
+
+File: zsh.info,  Node: Zftp Functions,  Next: Miscellaneous Features,  Prev: Installation,  Up: Zftp Function System
+
+25.3 Functions
+==============
+
+The sequence of operations in performing a file transfer is essentially
+the same as that in a standard FTP client.  Note that, due to a quirk
+of the shell's getopts builtin, for those functions that handle options
+you must use `--' rather than `-' to ensure the remaining arguments are
+treated literally (a single `-' is treated as an argument).
+
+
+
+25.3.1 Opening a connection
+---------------------------
+
+
+zfparams [ HOST [ USER [ PASSWORD ... ] ] ]
+     Set or show the parameters for a future 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 USER or PASSWORD is not, they will be
+     prompted for; also, any parameter given as `?' will be prompted
+     for, and if the `?' is followed by a string, that will be used as
+     the prompt.  As zfopen calls zfparams to store the parameters,
+     this usually need not be called directly.
+
+     A single argument `-' will delete the stored parameters.  This will
+     also cause the memory of the last directory (and so on) on the
+     other host to be deleted.
+
+zfopen [ -1 ] [ HOST [ USER [ PASSWORD [ ACCOUNT ] ] ] ]
+     If HOST is present, open a connection to that host under username
+     USER with password PASSWORD (and, on the rare occasions when it is
+     necessary, account ACCOUNT).  If a necessary parameter is missing
+     or given as `?' it will be prompted for.  If HOST is not present,
+     use a previously stored set of parameters.
+
+     If the command was successful, and the terminal is compatible with
+     xterm or is sun-cmd, a summary will appear in the title bar,
+     giving the local host:directory and the remote host:directory;
+     this is handled by the function zftp_chpwd, described below.
+
+     Normally, the HOST, USER and PASSWORD are internally recorded for
+     later re-opening, either by a zfopen with no arguments, or
+     automatically (see below).  With the option `-1', no information is
+     stored.  Also, if an open command with arguments failed, the
+     parameters will not be retained (and any previous parameters will
+     also be deleted).  A zfopen on its own, or a zfopen -1, never
+     alters the stored parameters.
+
+     Both zfopen and zfanon (but not zfparams) understand URLs of the
+     form ftp://HOST/PATH... as meaning to connect to the HOST, then
+     change directory to PATH (which must be a directory, not a file).
+     The `ftp://' can be omitted; the trailing `/' is enough to trigger
+     recognition of the PATH.  Note prefixes other than `ftp:' are not
+     recognized, and that all characters after the first slash beyond
+     HOST are significant in PATH.
+
+zfanon [ -1 ] HOST
+     Open a connection HOST for anonymous FTP.  The username used is
+     `anonymous'.  The password (which will be reported the first time)
+     is generated as USER@HOST; this is then stored in the shell
+     parameter $EMAIL_ADDR which can alternatively be set manually to a
+     suitable string.
+
+
+
+25.3.2 Directory management
+---------------------------
+
+
+zfcd [ DIR ]
+zfcd -
+zfcd OLD NEW
+     Change the current directory on the remote server:  this is
+     implemented to have many of the features of the shell builtin cd.
+
+     In the first form with DIR present, change to the directory DIR.
+     The command `zfcd ..' is treated specially, so is guaranteed to
+     work on non-UNIX servers (note this is handled internally by
+     zftp).  If DIR is omitted, has the effect of `zfcd ~'.
+
+     The second form changes to the directory previously current.
+
+     The third form attempts to change the current directory by
+     replacing the first occurrence of the string OLD with the string
+     NEW in the current directory.
+
+     Note that in this command, and indeed anywhere a remote filename is
+     expected, the string which on the local host corresponds to `~' is
+     converted back to a `~' before being passed to the remote machine.
+     This is convenient because of the way expansion is performed on
+     the command line before zfcd receives a string.  For example,
+     suppose the command is `zfcd ~/foo'.  The shell will expand this
+     to a full path such as `zfcd /home/user2/pws/foo'.  At this stage,
+     zfcd recognises the initial path as corresponding to `~' and will
+     send the directory to the remote host as ~/foo, so that the `~'
+     will be expanded by the server to the correct remote host
+     directory.  Other named directories of the form `~name' are not
+     treated in this fashion.
+
+zfhere
+     Change directory on the remote server to the one corresponding to
+     the current local directory, with special handling of `~' as in
+     zfcd.  For example, if the current local directory is ~/foo/bar,
+     then zfhere performs the effect of `zfcd ~/foo/bar'.
+
+zfdir [ -rfd ] [ - ] [ DIR-OPTIONS ] [ DIR ]
+     Produce a long directory listing.  The arguments DIR-OPTIONS and
+     DIR are passed directly to the server and their effect is
+     implementation dependent, but specifying a particular remote
+     directory DIR is usually possible.  The output is passed through a
+     pager given by the environment variable $PAGER, or `more' if that
+     is not set.
+
+     The directory is usually cached for re-use.  In fact, two caches
+     are maintained.  One is for use when there is no DIR-OPTIONS or
+     DIR, i.e. a full listing of the current remote directory; it is
+     flushed when the current remote directory changes.  The other is
+     kept for repeated use of zfdir with the same arguments; for
+     example, repeated use of `zfdir /pub/gnu' will only require the
+     directory to be retrieved on the first call.  Alternatively, this
+     cache can be re-viewed with the -r option.  As relative
+     directories will confuse zfdir, the -f option can be used to force
+     the cache to be flushed before the directory is listed.  The
+     option -d will delete both caches without showing a directory
+     listing; it will also delete the cache of file names in the
+     current remote directory, if any.
+
+zfls [ LS-OPTIONS ] [ DIR ]
+     List files on the remote server.  With no arguments, this will
+     produce a simple list of file names for the current remote
+     directory.  Any arguments are passed directly to the server.  No
+     pager and no caching is used.
+
+
+
+25.3.3 Status commands
+----------------------
+
+
+zftype [ TYPE ]
+     With no arguments, show the type of data to be transferred,
+     usually ASCII or binary.  With an argument, change the type: the
+     types `A' or `ASCII' for ASCII data and `B' or `BINARY', `I' or
+     `IMAGE' for binary data are understood case-insensitively.
+
+zfstat [ -v ]
+     Show the status of the current or last connection, as well as the
+     status of some of zftp's status variables.  With the -v option, a
+     more verbose listing is produced by querying the server for its
+     version of events, too.
+
+
+
+25.3.4 Retrieving files
+-----------------------
+
+The commands for retrieving files all take at least two options. -G
+suppresses remote filename expansion which would otherwise be performed
+(see below for a more detailed description of that).  -t attempts to
+set the modification time of the local file to that of the remote file:
+see the description of the function zfrtime below for more information.
+
+
+zfget [ -Gtc ] FILE1 ...
+     Retrieve all the listed files FILE1 ... one at a time from the
+     remote server.  If a file contains a `/', the full name is passed
+     to the remote server, but the file is stored locally under the
+     name given by the part after the final `/'.  The option -c (cat)
+     forces all files to be sent as a single stream to standard output;
+     in this case the -t option has no effect.
+
+zfuget [ -Gvst ] FILE1 ...
+     As 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 sizes, or if the sizes are the same but the
+     remote file is newer, the user will usually be queried.  With the
+     option -s, the command runs silently and will always retrieve the
+     file in either of those two cases.  With the option -v, the
+     command prints more information about the files while it is
+     working out whether or not to transfer them.
+
+zfcget [ -Gt ] FILE1 ...
+     As 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 file.  This is useful on a poor connection which
+     keeps failing.
+
+     Note that this requires a commonly implemented, but non-standard,
+     version of the FTP protocol, so is not guaranteed to work on all
+     servers.
+
+zfgcp [ -Gt ] REMOTE-FILE LOCAL-FILE
+zfgcp [ -Gt ] RFILE1 ... LDIR
+     This retrieves files from the remote server with arguments behaving
+     similarly to the cp command.
+
+     In the first form, copy REMOTE-FILE from the server to the local
+     file LOCAL-FILE.
+
+     In the second form, copy all the remote files RFILE1 ... into the
+     local directory LDIR retaining the same basenames.  This assumes
+     UNIX directory semantics.
+
+
+
+25.3.5 Sending files
+--------------------
+
+
+zfput [ -r ] FILE1 ...
+     Send all the FILE1 ... given separately to the remote server.  If a
+     filename contains a `/', the full filename is used locally to find
+     the file, but only the basename is used for the remote file name.
+
+     With the option -r, if any of the FILES are directories they are
+     sent recursively with all their subdirectories, including files
+     beginning with `.'.  This requires that the remote machine
+     understand UNIX file semantics, since `/' is used as a directory
+     separator.
+
+zfuput [ -vs ] FILE1 ...
+     As zfput, but only send files which are newer than their remote
+     equivalents, or if the remote file does not exist.  The logic is
+     the same as for zfuget, but reversed between local and remote
+     files.
+
+zfcput FILE1 ...
+     As 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 append command is part of the standard
+     set, this is in principle more likely to work than zfcget.
+
+zfpcp LOCAL-FILE REMOTE-FILE
+zfpcp LFILE1 ... RDIR
+     This sends files to the remote server with arguments behaving
+     similarly to the cp command.
+
+     With two arguments, copy LOCAL-FILE to the server as REMOTE-FILE.
+
+     With more than two arguments, copy all the local files LFILE1 ...
+     into the existing remote directory RDIR retaining the same
+     basenames.  This assumes UNIX directory semantics.
+
+     A problem arises if you attempt to use zfpcp LFILE1 RDIR, i.e. the
+     second form of copying but with two arguments, as the command has
+     no simple way of knowing if RDIR corresponds to a directory or a
+     filename.  It attempts to resolve this in various ways.  First, if
+     the RDIR argument is `.' or `..' or ends in a slash, it is assumed
+     to be a directory.  Secondly, if the operation of copying to a
+     remote file in the first form failed, and the remote server sends
+     back the expected failure code 553 and a reply including the
+     string `Is a directory', then zfpcp will retry using the second
+     form.
+
+
+
+25.3.6 Closing the connection
+-----------------------------
+
+
+zfclose
+     Close the connection.
+
+
+
+25.3.7 Session management
+-------------------------
+
+
+zfsession [ -lvod ] [ SESSNAME ]
+     Allows you to manage multiple FTP sessions at once.  By default,
+     connections take place in a session called `default'; by giving the
+     command `zfsession SESSNAME' you can change to a new or existing
+     session with a name of your choice.  The new session remembers its
+     own connection, as well as associated shell parameters, and also
+     the host/user parameters set by zfparams.  Hence you can have
+     different sessions set up to connect to different hosts, each
+     remembering the appropriate host, user and password.
+
+     With no arguments, zfsession prints the name of the current
+     session; with the option -l it lists all sessions which currently
+     exist, and with the option -v it gives a verbose list showing the
+     host and directory for each session, where the current session is
+     marked with an asterisk.  With -o, it will switch to the most
+     recent previous session.
+
+     With -d, the given session (or else the current one) is removed;
+     everything to do with it is completely forgotten.  If it was the
+     only session, a new session called `default' is created and made
+     current.  It is safest not to delete sessions while background
+     commands using zftp are active.
+
+zftransfer SESS1:FILE1 SESS2:FILE2
+     Transfer files between two sessions; no local copy is made.  The
+     file is read from the session SESS1 as FILE1 and written to session
+     SESS2 as file FILE2; FILE1 and FILE2 may be relative to the
+     current directories of the session.  Either SESS1 or SESS2 may be
+     omitted (though the colon should be retained if there is a
+     possibility of a colon appearing in the file name) and defaults to
+     the current session; FILE2 may be omitted or may end with a slash,
+     in which case the basename of FILE1 will be added.  The sessions
+     SESS1 and SESS2 must be distinct.
+
+     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 versions of some operating systems, presumably due to a
+     system bug.
+
+
+
+25.3.8 Bookmarks
+----------------
+
+The two functions zfmark and zfgoto allow you to `bookmark' the 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 $ZFTP_BMFILE; if not set when one of the two
+functions is called, it will be set to the file .zfbkmarks in the
+directory where your zsh startup files live (usually ~).
+
+
+zfmark [ BOOKMARK ]
+     If given an argument, mark the current host, user and directory
+     under the name BOOKMARK for later use by zfgoto.  If there is no
+     connection open, use the values for the last connection
+     immediately before it was closed; it is an error if there was
+     none.  Any existing bookmark under the same name will be silently
+     replaced.
+
+     If not given an argument, list the existing bookmarks and the
+     points to which they refer in the form USER@HOST:DIRECTORY; this
+     is the format in which they are stored, and the file may be edited
+     directly.
+
+zfgoto [ -n ] BOOKMARK
+     Return to the location given by BOOKMARK, as previously set by
+     zfmark.  If the location has user `ftp' or `anonymous', open the
+     connection with zfanon, so that no password is required.  If the
+     user and host parameters match those stored for the current
+     session, if any, those will be used, and again no password is
+     required.  Otherwise a password will be prompted for.
+
+     With the option -n, the bookmark is taken to be a nickname stored
+     by the ncftp program in its bookmark file, which is assumed to be
+     ~/.ncftp/bookmarks.  The function works identically in other ways.
+     Note that there is no mechanism for adding or modifying ncftp
+     bookmarks from the zftp functions.
+
+
+
+25.3.9 Other functions
+----------------------
+
+Mostly, these functions will not be called directly (apart from
+zfinit), but are described here for completeness.  You may wish to
+alter zftp_chpwd and zftp_progress, in particular.
+
+
+zfinit [ -n ]
+     As described above, this is used to initialize the zftp function
+     system.  The -n option should be used if the zftp command is
+     already built into the shell.
+
+zfautocheck [ -dn ]
+     This function is called to implement automatic reopening
+     behaviour, as described in more detail below.  The options must
+     appear in the first argument; -n prevents the command from
+     changing to the old directory, while -d prevents it from setting
+     the variable do_close, which it otherwise does as a flag for
+     automatically closing the connection after a transfer.  The host
+     and directory for the last session are stored in the variable
+     $zflastsession, but the internal host/user/password parameters
+     must also be correctly set.
+
+zfcd_match PREFIX SUFFIX
+     This performs matching for completion of remote directory names.
+     If the remote server is UNIX, it will attempt to persuade the
+     server to list the remote directory with subdirectories marked,
+     which usually works but is not guaranteed.  On other hosts it
+     simply calls zfget_match and hence completes all files, not just
+     directories.  On some systems, directories may not even look like
+     filenames.
+
+zfget_match PREFIX SUFFIX
+     This performs matching for completion of remote filenames.  It
+     caches files for the current directory (only) in the shell
+     parameter $zftp_fcache.  It is in the form to be called by the -K
+     option of compctl, but also works when called from a widget-style
+     completion function with PREFIX and SUFFIX set appropriately.
+
+zfrglob VARNAME
+     Perform remote globbing, as describes in more detail below.
+     VARNAME is the name of a variable containing the pattern to be
+     expanded; if there were any matches, the same variable will be set
+     to the expanded set of filenames on return.
+
+zfrtime LFILE RFILE [ TIME ]
+     Set the local file LFILE to have the same modification time as the
+     remote file RFILE, or the explicit time TIME in FTP format
+     CCYYMMDDhhmmSS for the GMT timezone.  This uses the shell's
+     zsh/datetime module to perform the conversion from GMT to local
+     time.
+
+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 xterm-compatible or sun-cmd terminal emulator to
+     reflect the local and remote hostnames and current directories.
+     It works best when combined with the function chpwd.  In
+     particular, a function of the form
+
+
+          chpwd() {
+            if [[ -n $ZFTP_USER ]]; then
+              zftp_chpwd
+            else
+              # usual chpwd e.g put host:directory in title bar
+            fi
+          }
+
+     fits in well.
+
+zftp_progress
+     This function shows the status of the transfer.  It will not write
+     anything unless the output is going to a terminal; however, if you
+     transfer files in the background, you should turn off progress
+     reports by hand using `zstyle ':zftp:*' progress none'.  Note also
+     that if you alter it, any output _must_ be to standard error, as
+     standard output may be a file being received.  The form of the
+     progress meter, or whether it is used at all, can be configured
+     without altering the function, as described in the next section.
+
+zffcache
+     This is used to implement caching of files in the current
+     directory for each session separately.  It is used by zfget_match
+     and zfrglob.
+
+
+
+
+File: zsh.info,  Node: Miscellaneous Features,  Prev: Zftp Functions,  Up: Zftp Function System
+
+25.4 Miscellaneous Features
+===========================
+
+
+
+25.4.1 Configuration
+--------------------
+
+
+
+Various styles are available using the standard shell style mechanism,
+described in *Note The zsh/zutil Module::. Briefly, the command `zstyle
+':zftp:*' STYLE VALUE ...'.  defines the STYLE to have value VALUE;
+more than one value may be given, although that is not useful in the
+cases described here.  These values will then be used throughout the
+zftp function system.  For more precise control, the first argument,
+which gives a context in which the style applies, can be modified to
+include a particular function, as for example `:zftp:zfget': the style
+will then have the given value only in the zfget function.  Values for
+the same style in different contexts may be set; the most specific
+function will be used, where strings are held to be more specific than
+patterns, and longer patterns and shorter patterns.  Note that only the
+top level function name, as called by the user, is used; calling of
+lower level functions is transparent to the user.  Hence modifications
+to the title bar in zftp_chpwd use the contexts :zftp:zfopen,
+:zftp:zfcd, etc., depending where it was called from.  The following
+styles are understood:
+
+
+progress
+     Controls the way that zftp_progress reports on the progress of a
+     transfer.  If empty, unset, or `none', no progress report is made;
+     if `bar' a growing bar of inverse video is shown; if `percent' (or
+     any other string, though this may change in future), the
+     percentage of the file transferred is shown.  The bar meter
+     requires that the width of the terminal be available via the
+     $COLUMNS parameter (normally this is set automatically).  If the
+     size of the file being transferred is not available, bar and
+     percent meters will simply show the number of bytes transferred so
+     far.
+
+     When zfinit is run, if this style is not defined for the context
+     :zftp:*, it will be set to `bar'.
+
+update
+     Specifies the minimum time interval between updates of the
+     progress meter in seconds.  No update is made unless new data has
+     been received, so the actual time interval is limited only by
+     $ZFTP_TIMEOUT.
+
+     As described for progress, zfinit will force this to default to 1.
+
+remote-glob
+     If set to `1', `yes' or `true', filename generation (globbing) is
+     performed on the remote machine instead of by zsh itself; see
+     below.
+
+titlebar
+     If set to `1', `yes' or `true', 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.
+
+     As described for progress, zfinit will force this to default to 1.
+
+chpwd
+     If set to `1' `yes' or `true', zftp_chpwd will call the function
+     chpwd when a connection is closed.  This is useful if the remote
+     host details were put into the terminal title bar by zftp_chpwd
+     and your usual chpwd also modifies the title bar.
+
+     When zfinit is run, it will determine whether chpwd exists and if
+     so it will set the default value for the style to 1 if none exists
+     already.
+
+
+Note that there is also an associative array zfconfig which contains
+values used by the function system.  This should not be modified or
+overwritten.
+
+
+
+25.4.2 Remote globbing
+----------------------
+
+
+
+The commands for retrieving files usually perform filename generation
+(globbing) on their arguments; this can be turned off by passing the
+option -G to each of the commands.  Normally this operates by
+retrieving a complete list of files for the directory in question, then
+matching these locally against the pattern supplied.  This has the
+advantage that the full range of zsh patterns (respecting the setting
+of the option EXTENDED_GLOB) can be used.  However, it means that the
+directory part of a filename will not be expanded and must be given
+exactly.  If the remote server does not support the UNIX directory
+semantics, directory handling is problematic and it is recommended that
+globbing only be used within the current directory.  The list of files
+in the current directory, if retrieved, will be cached, so that
+subsequent globs in the same directory without an intervening zfcd are
+much faster.
+
+If the remote-glob style (see above) is set, globbing is instead
+performed on the remote host: the server is asked for a list of matching
+files.  This is highly dependent on how the server is implemented,
+though typically UNIX servers will provide support for basic glob
+patterns.  This may in some cases be faster, as it avoids retrieving
+the entire list of directory contents.
+
+
+
+25.4.3 Automatic and temporary reopening
+----------------------------------------
+
+
+
+As described for the zfopen command, a subsequent zfopen with no
+parameters will reopen the connection to the last host (this includes
+connections made with the zfanon command).  Opened in this fashion, the
+connection starts in the default remote directory and will remain open
+until explicitly closed.
+
+Automatic re-opening is also available.  If a connection is not
+currently open and a command requiring a connection is given, the last
+connection is implicitly reopened.  In this case the directory which
+was current when the connection was closed again becomes the current
+directory (unless, of course, the command given changes it).  Automatic
+reopening will also take place if the connection was close by the
+remote server for whatever reason (e.g. a timeout).  It is not
+available if the -1 option to zfopen or zfanon was used.
+
+Furthermore, if the command issued is a file transfer, the connection
+will be closed after the transfer is finished, hence providing a
+one-shot mode for transfers.  This does not apply to directory changing
+or listing commands; for example a zfdir may reopen a connection but
+will leave it open.  Also, automatic closure will only ever happen in
+the same command as automatic opening, i.e a zfdir directly followed by
+a zfget will never close the connection automatically.
+
+Information about the previous connection is given by the zfstat
+function.  So, for example, if that reports:
+
+
+     Session:        default
+     Not connected.
+     Last session:   ftp.bar.com:/pub/textfiles
+
+then the command zfget file.txt will attempt to reopen a connection to
+ftp.bar.com, retrieve the file /pub/textfiles/file.txt, and immediately
+close the connection again.  On the other hand, zfcd ..  will open the
+connection in the directory /pub and leave it open.
+
+Note that all the above is local to each session; if you return to a
+previous session, the connection for that session is the one which will
+be reopened.
+
+
+
+25.4.4 Completion
+-----------------
+
+Completion of local and remote files, directories, sessions and
+bookmarks is supported.  The older, compctl-style completion is defined
+when zfinit is called; support for the new widget-based completion
+system is provided in the function Completion/Zsh/Command/_zftp, which
+should be installed with the other functions of the completion system
+and hence should automatically be available.
+
+
+File: zsh.info,  Node: User Contributions,  Prev: Zftp Function System,  Up: Top
+
+26 User Contributions
+*********************
+
+
+
+26.1 Description
+================
+
+The Zsh source distribution includes a number of items contributed by
+the user community.  These are not inherently a part of the shell, and
+some may not be available in every zsh installation.  The most
+significant of these are documented here.  For documentation on other
+contributed items such as shell functions, look for comments in the
+function source files.
+
+
+
+* Menu:
+
+* Utilities::
+* Recent Directories::
+* Other Directory Functions::
+* Version Control Information::
+* Prompt Themes::
+* ZLE Functions::
+* Exception Handling::
+* MIME Functions::
+* Mathematical Functions::
+* User Configuration Functions::
+* Other Functions::
+
+
+
+File: zsh.info,  Node: Utilities,  Next: Recent Directories,  Up: User Contributions
+
+26.2 Utilities
+==============
+
+
+
+26.2.1 Accessing On-Line Help
+-----------------------------
+
+
+
+The key sequence ESC h is normally bound by ZLE to execute the run-help
+widget (see *Note Zsh Line Editor::).  This invokes the run-help
+command with the command word from the current input line as its
+argument.  By default, run-help is an alias for the man command, so
+this often fails when the command word is a shell builtin or a
+user-defined function.  By redefining the run-help alias, one can
+improve the on-line help provided by the shell.
+
+The helpfiles utility, found in the Util directory of the distribution,
+is a Perl program that can be used to process the zsh manual to produce
+a separate help file for each shell builtin and for many other shell
+features as well.  The autoloadable run-help function, found in
+Functions/Misc, searches for these helpfiles and performs several other
+tests to produce the most complete help possible for the command.
+
+Help files are installed by default to a subdirectory of /usr/share/zsh
+or /usr/local/share/zsh.
+
+To create your own help files with helpfiles, choose or create a
+directory where the individual command help files will reside.  For
+example, you might choose ~/zsh_help.  If you unpacked the zsh
+distribution in your home directory, you would use the commands:
+
+
+     mkdir ~/zsh_help
+     perl ~/zsh-5.8.1/Util/helpfiles ~/zsh_help
+
+The HELPDIR parameter tells run-help where to look for the help files.
+When unset, it uses the default installation path.  To use your own set
+of help files, set this to the appropriate path in one of your startup
+files:
+
+
+     HELPDIR=~/zsh_help
+
+To use the run-help function, you need to add lines something like the
+following to your .zshrc or equivalent startup file:
+
+
+     unalias run-help
+     autoload run-help
+
+Note that in order for `autoload run-help' to work, the run-help file
+must be in one of the directories named in your fpath array (see *Note
+Parameters Used By The Shell::).  This should already be the case if
+you have a standard zsh installation; if it is not, copy
+Functions/Misc/run-help to an appropriate directory.
+
+
+
+26.2.2 Recompiling Functions
+----------------------------
+
+
+
+If you frequently edit your zsh functions, or periodically update your
+zsh installation to track the latest developments, you may find that
+function digests compiled with the zcompile builtin are frequently out
+of date with respect to the function source files.  This is not usually
+a problem, because zsh always looks for the newest file when loading a
+function, but it may cause slower shell startup and function loading.
+Also, if a digest file is explicitly used as an element of fpath, zsh
+won't check whether any of its source files has changed.
+
+The zrecompile autoloadable function, found in Functions/Misc, can be
+used to keep function digests up to date.
+
+
+zrecompile [ -qt ] [ NAME ... ]
+zrecompile [ -qt ] -p ARG ... [ -- ARG ... ]
+     This tries to find *.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 relative to the directory that contains the
+     .zwc file.
+
+     In the first form, each NAME is the name of a compiled file or a
+     directory containing *.zwc files that should be checked.  If no
+     arguments are given, the directories and *.zwc files in fpath are
+     used.
+
+     When -t is given, no compilation is performed, but a return status
+     of zero (true) is set if there are files that need to be
+     re-compiled and non-zero (false) otherwise.  The -q option quiets
+     the chatty output that describes what zrecompile is doing.
+
+     Without the -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 -p option is given, the ARGs are interpreted as one or more
+     sets of arguments for zcompile, separated by `--'.  For example:
+
+
+          zrecompile -p \
+                     -R ~/.zshrc -- \
+                     -M ~/.zcompdump -- \
+                     ~/zsh/comp.zwc ~/zsh/Completion/*/_*
+
+     This compiles ~/.zshrc into ~/.zshrc.zwc if that doesn't exist or
+     if it is older than ~/.zshrc. The compiled file will be marked for
+     reading instead of mapping. The same is done for ~/.zcompdump and
+     ~/.zcompdump.zwc, but this compiled file is marked for mapping. The
+     last line re-creates the file ~/zsh/comp.zwc if any of the files
+     matching the given pattern is newer than it.
+
+     Without the -p option, zrecompile does not create function digests
+     that do not already exist, nor does it add new functions to the
+     digest.
+
+
+The following shell loop is an example of a method for creating function
+digests for all functions in your fpath, assuming that you have write
+permission to the directories:
+
+
+     for ((i=1; i <= $#fpath; ++i)); do
+       dir=$fpath[i]
+       zwc=${dir:t}.zwc
+       if [[ $dir == (.|..) || $dir == (.|..)/* ]]; then
+         continue
+       fi
+       files=($dir/*(N-.))
+       if [[ -w $dir:h && -n $files ]]; then
+         files=(${${(M)files%/*/*}#/})
+         if ( cd $dir:h &&
+              zrecompile -p -U -z $zwc $files ); then
+           fpath[i]=$fpath[i].zwc
+         fi
+       fi
+     done
+
+The -U and -z options are appropriate for functions in the default zsh
+installation fpath; you may need to use different options for your
+personal function directories.
+
+Once the digests have been created and your fpath modified to refer to
+them, you can keep them up to date by running zrecompile with no
+arguments.
+
+
+
+26.2.3 Keyboard Definition
+--------------------------
+
+
+
+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 zkbd utility,
+found in Functions/Misc, can help you quickly create key bindings for
+your configuration.
+
+Run zkbd either as an autoloaded function, or as a shell script:
+
+
+     zsh -f ~/zsh-5.8.1/Functions/Misc/zkbd
+
+When you run zkbd, it first asks you to enter your terminal type; if
+the default it offers is correct, just press return.  It then asks you
+to press a number of different keys to determine characteristics of your
+keyboard and terminal; zkbd warns you if it finds anything out of the
+ordinary, such as a Delete key that sends neither ^H nor ^?.
+
+The keystrokes read by zkbd are recorded as a definition for an
+associative array named key, written to a file in the subdirectory
+.zkbd within either your HOME or ZDOTDIR directory.  The name of the
+file is composed from the TERM, VENDOR and OSTYPE parameters, joined by
+hyphens.
+
+You may read this file into your .zshrc or another startup file with
+the `source' or `.' commands, then reference the key parameter in
+bindkey commands, like this:
+
+
+     source ${ZDOTDIR:-$HOME}/.zkbd/$TERM-$VENDOR-$OSTYPE
+     [[ -n ${key[Left]} ]] && bindkey "${key[Left]}" backward-char
+     [[ -n ${key[Right]} ]] && bindkey "${key[Right]}" forward-char
+     # etc.
+
+Note that in order for `autoload zkbd' to work, the zkdb file must be
+in one of the directories named in your fpath array (see *Note
+Parameters Used By The Shell::).  This should already be the case if
+you have a standard zsh installation; if it is not, copy
+Functions/Misc/zkbd to an appropriate directory.
+
+
+
+26.2.4 Dumping Shell State
+--------------------------
+
+
+
+Occasionally you may encounter what appears to be a bug in the shell,
+particularly if you are using a beta version of zsh or a development
+release.  Usually it is sufficient to send a description of the problem
+to one of the zsh mailing lists (see *Note Mailing Lists::), but
+sometimes one of the zsh developers will need to recreate your
+environment in order to track the problem down.
+
+The script named reporter, found in the Util directory of the
+distribution, is provided for this purpose.  (It is also possible to
+autoload reporter, but reporter is not installed in fpath by default.)
+This script outputs a detailed dump of the shell state, in the form of
+another script that can be read with `zsh -f' to recreate that state.
+
+To use reporter, read the script into your shell with the `.'  command
+and redirect the output into a file:
+
+
+     . ~/zsh-5.8.1/Util/reporter > zsh.report
+
+You should check the zsh.report file for any sensitive information such
+as passwords and delete them by hand before sending the script to the
+developers.  Also, as the output can be voluminous, it's best to wait
+for the developers to ask for this information before sending it.
+
+You can also use reporter to dump only a subset of the shell state.
+This is sometimes useful for creating startup files for the first time.
+Most of the output from reporter is far more detailed than usually is
+necessary for a startup file, but the aliases, options, and zstyles
+states may be useful because they include only changes from the
+defaults.  The bindings state may be useful if you have created any of
+your own keymaps, because reporter arranges to dump the keymap creation
+commands as well as the bindings for every keymap.
+
+As is usual with automated tools, if you create a startup file with
+reporter, you should edit the results to remove unnecessary commands.
+Note that if you're using the new completion system, you should _not_
+dump the functions state to your startup files with reporter; use the
+compdump function instead (see *Note Completion System::).
+
+
+reporter [ STATE ... ]
+     Print to standard output the indicated subset of the current shell
+     state.  The STATE arguments may be one or more of:
+
+
+    all
+          Output everything listed below.
+
+    aliases
+          Output alias definitions.
+
+    bindings
+          Output ZLE key maps and bindings.
+
+    completion
+          Output old-style compctl commands.  New completion is covered
+          by functions and zstyles.
+
+    functions
+          Output autoloads and function definitions.
+
+    limits
+          Output limit commands.
+
+    options
+          Output setopt commands.
+
+    styles
+          Same as zstyles.
+
+    variables
+          Output shell parameter assignments, plus export commands for
+          any environment variables.
+
+    zstyles
+          Output zstyle commands.
+
+     If the STATE is omitted, all is assumed.
+
+     With the exception of `all', every STATE can be abbreviated by any
+     prefix, even a single letter; thus a is the same as aliases, z is
+     the same as zstyles, etc.
+
+
+26.2.5 Manipulating Hook Functions
+----------------------------------
+
+
+
+
+add-zsh-hook [ -L | -dD ] [ -Uzk ] HOOK FUNCTION
+     Several functions are special to the shell, as described in the
+     section Special Functions, *Note Functions::, in that they are
+     automatically called at specific points during shell execution.
+     Each has an associated array consisting of names of functions to be
+     called at the same point; these are so-called `hook functions'.
+     The shell function add-zsh-hook provides a simple way of adding or
+     removing functions from the array.
+
+     HOOK is one of chpwd, periodic, precmd, preexec, zshaddhistory,
+     zshexit, or zsh_directory_name, the special functions in question.
+     Note that zsh_directory_name is called in a different way from
+     the other functions, but may still be manipulated as a hook.
+
+     FUNCTION is name of an ordinary shell function.  If no options are
+     given this will be added to the array of functions to be executed
+     in the given context.  Functions are invoked in the order they
+     were added.
+
+     If the option -L is given, the current values for the hook arrays
+     are listed with typeset.
+
+     If the option -d is given, the FUNCTION is removed from the array
+     of functions to be executed.
+
+     If the option -D is given, the FUNCTION is treated as a pattern
+     and any matching names of functions are removed from the array of
+     functions to be executed.
+
+     The options -U, -z and -k are passed as arguments to autoload for
+     FUNCTION.  For functions contributed with zsh, the options -Uz are
+     appropriate.
+
+add-zle-hook-widget [ -L | -dD ] [ -Uzk ] HOOK WIDGETNAME
+     Several widget names are special to the line editor, as described
+     in the section Special Widgets, *Note Zle Widgets::, in that they
+     are automatically called at specific points during editing.
+     Unlike function hooks, these do not use a predefined array of
+     other names to call at the same point; the shell function
+     add-zle-hook-widget maintains a similar array and arranges for the
+     special widget to invoke those additional widgets.
+
+     HOOK is one of isearch-exit, isearch-update, line-pre-redraw,
+     line-init, line-finish, history-line-set, or keymap-select,
+     corresponding to each of the special widgets zle-isearch-exit,
+     etc.  The special widget names are also accepted as the HOOK
+     argument.
+
+     WIDGETNAME is the name of a ZLE widget.  If no options are given
+     this is added to the array of widgets to be invoked in the given
+     hook context.  Widgets are invoked in the order they were added,
+     with
+          zle WIDGETNAME -Nw -- "$@"
+
+     Note that this means that the `WIDGET' special parameter tracks the
+     WIDGETNAME when the widget function is called, rather than tracking
+     the name of the corresponding special hook widget.
+
+     If the option -d is given, the WIDGETNAME is removed from the
+     array of widgets to be executed.
+
+     If the option -D is given, the WIDGETNAME is treated as a pattern
+     and any matching names of widgets are removed from the array.
+
+     If WIDGETNAME does not name an existing widget when added to the
+     array, it is assumed that a shell function also named WIDGETNAME is
+     meant to provide the implementation of the widget.  This name is
+     therefore marked for autoloading, and the options -U, -z and -k are
+     passed as arguments to autoload as with add-zsh-hook.  The widget
+     is also created with `zle -N WIDGETNAME' to cause the
+     corresponding function to be loaded the first time the hook is
+     called.
+
+     The arrays of WIDGETNAME are currently maintained in zstyle
+     contexts, one for each HOOK context, with a style of `widgets'.
+     If the -L option is given, this set of styles is listed with
+     `zstyle -L'.  This implementation may change, and the special
+     widgets that refer to the styles are created only if
+     add-zle-hook-widget is called to add at least one widget, so if
+     this function is used for any hooks, then all hooks should be
+     managed only via this function.
+
+
+
+
+File: zsh.info,  Node: Recent Directories,  Next: Other Directory Functions,  Prev: Utilities,  Up: User Contributions
+
+26.3 Remembering Recent Directories
+===================================
+
+The function cdr allows you to change the working directory to a
+previous working directory from a list maintained automatically.  It is
+similar in concept to the directory stack controlled by the pushd, popd
+and dirs builtins, but is more configurable, and as it stores all
+entries in files it is maintained across sessions and (by default)
+between terminal emulators in the current session.  Duplicates are
+automatically removed, so that the list reflects the single most recent
+use of each directory.
+
+Note that the pushd directory stack is not actually modified or used by
+cdr unless you configure it to do so as described in the configuration
+section below.
+
+
+
+26.3.1 Installation
+-------------------
+
+The system works by means of a hook function that is called every time
+the directory changes.  To install the system, autoload the required
+functions and use the add-zsh-hook function described above:
+
+
+     autoload -Uz chpwd_recent_dirs cdr add-zsh-hook
+     add-zsh-hook chpwd chpwd_recent_dirs
+
+Now every time you change directly interactively, no matter which
+command you use, the directory to which you change will be remembered
+in most-recent-first order.
+
+
+
+26.3.2 Use
+----------
+
+All direct user interaction is via the cdr function.
+
+The argument to cdr is a number N corresponding to the Nth most
+recently changed-to directory.  1 is the immediately preceding
+directory; the current directory is remembered but is not offered as a
+destination.  Note that if you have multiple windows open 1 may refer
+to a directory changed to in another window; you can avoid this by
+having per-terminal files for storing directory as described for the
+recent-dirs-file style below.
+
+If you set the recent-dirs-default style described below cdr will
+behave the same as cd if given a non-numeric argument, or more than one
+argument.  The recent directory list is updated just the same however
+you change directory.
+
+If the argument is omitted, 1 is assumed.  This is similar to pushd's
+behaviour of swapping the two most recent directories on the stack.
+
+Completion for the argument to cdr is available if compinit has been
+run; menu selection is recommended, using:
+
+
+     zstyle ':completion:*:*:cdr:*:*' menu selection
+
+to allow you to cycle through recent directories; the order is
+preserved, so the first choice is the most recent directory before the
+current one.  The verbose style is also recommended to ensure the
+directory is shown; this style is on by default so no action is
+required unless you have changed it.
+
+
+
+26.3.3 Options
+--------------
+
+The behaviour of cdr may be modified by the following options.
+
+
+-l
+     lists the numbers and the corresponding directories in abbreviated
+     form (i.e. with ~ substitution reapplied), one per line.  The
+     directories here are not quoted (this would only be an issue if a
+     directory name contained a newline).  This is used by the
+     completion system.
+
+-r
+     sets the variable reply to the current set of directories.  Nothing
+     is printed and the directory is not changed.
+
+-e
+     allows you to edit the list of directories, one per line.  The
+     list can be edited to any extent you like; no sanity checking is
+     performed.  Completion is available.  No quoting is necessary
+     (except for newlines, where I have in any case no sympathy);
+     directories are in unabbreviated from and contain an absolute
+     path, i.e. they start with /.  Usually the first entry should be
+     left as the current directory.
+
+-p 'PATTERN'
+     Prunes any items in the directory list that match the given
+     extended glob pattern; the pattern needs to be quoted from
+     immediate expansion on the command line.  The pattern is matched
+     against each completely expanded file name in the list; the full
+     string must match, so wildcards at the end (e.g. '*removeme*') are
+     needed to remove entries with a given substring.
+
+     If output is to a terminal, then the function will print the new
+     list after pruning and prompt for confirmation by the user.  This
+     output and confirmation step can be skipped by using -P instead of
+     -p.
+
+
+
+26.3.4 Configuration
+--------------------
+
+Configuration is by means of the styles mechanism that should be
+familiar from completion; if not, see the description of the zstyle
+command in *Note The zsh/zutil Module::.  The context for setting styles
+should be ':chpwd:*' in case the meaning of the context is extended in
+future, for example:
+
+
+     zstyle ':chpwd:*' recent-dirs-max 0
+
+sets the value of the recent-dirs-max style to 0.  In practice the
+style name is specific enough that a context of '*' should be fine.
+
+An exception is recent-dirs-insert, which is used exclusively by the
+completion system and so has the usual completion system context
+(':completion:*' if nothing more specific is needed), though again '*'
+should be fine in practice.
+
+
+recent-dirs-default
+     If true, and the command is expecting a recent directory index, and
+     either there is more than one argument or the argument is not an
+     integer, then fall through to "cd".  This allows the lazy to use
+     only one command for directory changing.  Completion recognises
+     this, too; see recent-dirs-insert for how to control completion
+     when this option is in use.
+
+recent-dirs-file
+     The file where the list of directories is saved.  The default is
+     ${ZDOTDIR:-$HOME}/.chpwd-recent-dirs, i.e. this is in your home
+     directory unless you have set the variable ZDOTDIR to point
+     somewhere else.  Directory names are saved in $'...' quoted form,
+     so each line in the file can be supplied directly to the shell as
+     an argument.
+
+     The value of this style may be an array.  In this case, the first
+     file in the list will always be used for saving directories while
+     any other files are left untouched.  When reading the recent
+     directory list, if there are fewer than the maximum number of
+     entries in the first file, the contents of later files in the
+     array will be appended with duplicates removed from the list
+     shown.  The contents of the two files are not sorted together,
+     i.e. all the entries in the first file are shown first.  The
+     special value + can appear in the list to indicate the default
+     file should be read at that point.  This allows effects like the
+     following:
+
+
+          zstyle ':chpwd:*' recent-dirs-file \
+          ~/.chpwd-recent-dirs-${TTY##*/} +
+
+     Recent directories are read from a file numbered according to the
+     terminal.  If there are insufficient entries the list is
+     supplemented from the default file.
+
+     It is possible to use zstyle -e to make the directory configurable
+     at run time:
+
+
+          zstyle -e ':chpwd:*' recent-dirs-file pick-recent-dirs-file
+          pick-recent-dirs-file() {
+            if [[ $PWD = ~/text/writing(|/*) ]]; then
+              reply=(~/.chpwd-recent-dirs-writing)
+            else
+              reply=(+)
+            fi
+          }
+
+     In this example, if the current directory is ~/text/writing or a
+     directory under it, then use a special file for saving recent
+     directories, else use the default.
+
+recent-dirs-insert
+     Used by completion.  If recent-dirs-default is true, then setting
+     this to true causes the actual directory, rather than its index, to
+     be inserted on the command line; this has the same effect as using
+     the corresponding index, but makes the history clearer and the line
+     easier to edit.  With this setting, if part of an argument was
+     already typed, normal directory completion rather than recent
+     directory completion is done; this is because recent directory
+     completion is expected to be done by cycling through entries menu
+     fashion.
+
+     If the value of the style is always, then only recent directories
+     will be completed; in that case, use the cd command when you want
+     to complete other directories.
+
+     If the value is fallback, recent directories will be tried first,
+     then normal directory completion is performed if recent directory
+     completion failed to find a match.
+
+     Finally, if the value is both then both sets of completions are
+     presented; the usual tag mechanism can be used to distinguish
+     results, with recent directories tagged as recent-dirs.  Note that
+     the recent directories inserted are abbreviated with directory
+     names where appropriate.
+
+recent-dirs-max
+     The maximum number of directories to save to the file.  If this is
+     zero or negative there is no maximum.  The default is 20.  Note
+     this includes the current directory, which isn't offered, so the
+     highest number of directories you will be offered is one less than
+     the maximum.
+
+recent-dirs-prune
+     This style is an array determining what directories should (or
+     should not) be added to the recent list.  Elements of the array
+     can include:
+
+
+    parent
+          Prune parents (more accurately, ancestors) from the recent
+          list.  If present, changing directly down by any number of
+          directories causes the current directory to be overwritten.
+          For example, changing from ~pws to ~pws/some/other/dir causes
+          ~pws not to be left on the recent directory stack.  This only
+          applies to direct changes to descendant directories; earlier
+          directories on the list are not pruned.  For example,
+          changing from ~pws/yet/another to ~pws/some/other/dir does
+          not cause ~pws to be pruned.
+
+    pattern:PATTERN
+          Gives a zsh pattern for directories that should not be added
+          to the recent list (if not already there).  This element can
+          be repeated to add different patterns.  For example,
+          'pattern:/tmp(|/*)' stops /tmp or its descendants from being
+          added.  The EXTENDED_GLOB option is always turned on for
+          these patterns.
+
+
+recent-dirs-pushd
+     If set to true, cdr will use pushd instead of cd to change the
+     directory, so the directory is saved on the directory stack.  As
+     the directory stack is completely separate from the list of files
+     saved by the mechanism used in this file there is no obvious
+     reason to do this.
+
+
+
+26.3.5 Use with dynamic directory naming
+----------------------------------------
+
+It is possible to refer to recent directories using the dynamic
+directory name syntax by using the supplied function
+zsh_directory_name_cdr a hook:
+
+
+     autoload -Uz add-zsh-hook
+     add-zsh-hook -Uz zsh_directory_name zsh_directory_name_cdr
+
+When this is done, ~[1] will refer to the most recent directory other
+than $PWD, and so on.  Completion after ~[...  also works.
+
+
+
+26.3.6 Details of directory handling
+------------------------------------
+
+This section is for the curious or confused; most users will not need
+to know this information.
+
+Recent directories are saved to a file immediately and hence are
+preserved across sessions.  Note currently no file locking is applied:
+the list is updated immediately on interactive commands and nowhere else
+(unlike history), and it is assumed you are only going to change
+directory in one window at once.  This is not safe on shared accounts,
+but in any case the system has limited utility when someone else is
+changing to a different set of directories behind your back.
+
+To make this a little safer, only directory changes instituted from the
+command line, either directly or indirectly through shell function calls
+(but not through subshells, evals, traps, completion functions and the
+like) are saved.  Shell functions should use cd -q or pushd -q to avoid
+side effects if the change to the directory is to be invisible at the
+command line.  See the contents of the function chpwd_recent_dirs for
+more details.
+
+
+
+
+File: zsh.info,  Node: Other Directory Functions,  Next: Version Control Information,  Prev: Recent Directories,  Up: User Contributions
+
+26.4 Abbreviated dynamic references to directories
+==================================================
+
+The dynamic directory naming system is described in the subsection
+_Dynamic named directories_ of *Note Filename Expansion::.  In this, a
+reference to ~[...] is expanded by a function found by the hooks
+mechanism.
+
+The contributed function zsh_directory_name_generic provides a system
+allowing the user to refer to directories with only a limited amount of
+new code.  It supports all three of the standard interfaces for
+directory naming: converting from a name to a directory, converting in
+the reverse direction to find a short name, and completion of names.
+
+The main feature of this function is a path-like syntax, combining
+abbreviations at multiple levels separated by ":".  As an example,
+~[g:p:s] might specify:
+g
+     The top level directory for your git area.  This first component
+     has to match, or the function will return indicating another
+     directory name hook function should be tried.
+
+p
+     The name of a project within your git area.
+
+s
+     The source area within that project.
+
+   This allows you to collapse references to long hierarchies to a very
+compact form, particularly if the hierarchies are similar across
+different areas of the disk.
+
+Name components may be completed: if a description is shown at the top
+of the list of completions, it includes the path to which previous
+components expand, while the description for an individual completion
+shows the path segment it would add.  No additional configuration is
+needed for this as the completion system is aware of the dynamic
+directory name mechanism.
+
+
+
+26.4.1 Usage
+------------
+
+To use the function, first define a wrapper function for your specific
+case.  We'll assume it's to be autoloaded.  This can have any name but
+we'll refer to it as zdn_mywrapper.  This wrapper function will define
+various variables and then call this function with the same arguments
+that the wrapper function gets.  This configuration is described below.
+
+Then arrange for the wrapper to be run as a zsh_directory_name hook:
+
+
+     autoload -Uz add-zsh-hook zsh_diretory_name_generic zdn_mywrapper
+     add-zsh-hook -U zsh_directory_name zdn_mywrapper
+
+
+26.4.2 Configuration
+--------------------
+
+The wrapper function should define a local associative array zdn_top.
+Alternatively, this can be set with a style called mapping.  The
+context for the style is :zdn:WRAPPER-NAME where WRAPPER-NAME is the
+function calling zsh_directory_name_generic; for example:
+
+
+     zstyle :zdn:zdn_mywrapper: mapping zdn_mywrapper_top
+
+The keys in this associative array correspond to the first component of
+the name.  The values are matching directories.  They may have an
+optional suffix with a slash followed by a colon and the name of a
+variable in the same format to give the next component.  (The slash
+before the colon is to disambiguate the case where a colon is needed in
+the path for a drive.  There is otherwise no syntax for escaping this,
+so path components whose names start with a colon are not supported.)  A
+special component :default: specifies a variable in the form /:VAR (the
+path section is ignored and so is usually empty) that will be used for
+the next component if no variable is given for the path.  Variables
+referred to within zdn_top have the same format as zdn_top itself, but
+contain relative paths.
+
+For example,
+
+
+     local -A zdn_top=(
+       g   ~/git
+       ga  ~/alternate/git
+       gs  /scratch/$USER/git/:second2
+       :default: /:second1
+     )
+
+This specifies the behaviour of a directory referred to as ~[g:...]  or
+~[ga:...] or ~[gs:...].  Later path components are optional; in that
+case ~[g] expands to ~/git, and so on.  gs expands to
+/scratch/$USER/git and uses the associative array second2 to match the
+second component; g and ga use the associative array second1 to match
+the second component.
+
+When expanding a name to a directory, if the first component is not g or
+ga or gs, it is not an error; the function simply returns 1 so that a
+later hook function can be tried.  However, matching the first component
+commits the function, so if a later component does not match, an error
+is printed (though this still does not stop later hooks from being
+executed).
+
+For components after the first, a relative path is expected, but note
+that multiple levels may still appear.  Here is an example of second1:
+
+
+     local -A second1=(
+       p   myproject
+       s   somproject
+       os  otherproject/subproject/:third
+     )
+
+The path as found from zdn_top is extended with the matching directory,
+so ~[g:p] becomes ~/git/myproject.  The slash between is added
+automatically (it's not possible to have a later component modify the
+name of a directory already matched).  Only os specifies a variable for
+a third component, and there's no :default:, so it's an error to use a
+name like ~[g:p:x] or ~[ga:s:y] because there's nowhere to look up the
+x or y.
+
+The associative arrays need to be visible within this function; the
+generic function therefore uses internal variable names beginning _zdn_
+in order to avoid clashes.  Note that the variable reply needs to be
+passed back to the shell, so should not be local in the calling
+function.
+
+The function does not test whether directories assembled by component
+actually exist; this allows the system to work across automounted file
+systems.  The error from the command trying to use a non-existent
+directory should be sufficient to indicate the problem.
+
+
+
+26.4.3 Complete example
+-----------------------
+
+Here is a full fictitious but usable autoloadable definition of the
+example function defined by the code above.  So ~[gs:p:s] expands to
+/scratch/$USER/git/myscratchproject/top/srcdir (with $USER also
+expanded).
+
+
+     local -A zdn_top=(
+       g   ~/git
+       ga  ~/alternate/git
+       gs  /scratch/$USER/git/:second2
+       :default: /:second1
+     )
+
+     local -A second1=(
+       p   myproject
+       s   somproject
+       os  otherproject/subproject/:third
+     )
+
+     local -A second2=(
+       p   myscratchproject
+       s   somescratchproject
+     )
+
+     local -A third=(
+       s   top/srcdir
+       d   top/documentation
+     )
+
+     # autoload not needed if you did this at initialisation...
+     autoload -Uz zsh_directory_name_generic
+     zsh_directory_name_generic "$@
+
+It is also possible to use global associative arrays, suitably named,
+and set the style for the context of your wrapper function to refer to
+this.  Then your set up code would contain the following:
+
+
+     typeset -A zdn_mywrapper_top=(...)
+     # ... and so on for other associative arrays ...
+     zstyle ':zdn:zdn_mywrapper:' mapping zdn_mywrapper_top
+     autoload -Uz add-zsh-hook zsh_directory_name_generic zdn_mywrapper
+     add-zsh-hook -U zsh_directory_name zdn_mywrapper
+
+and the function zdn_mywrapper would contain only the following:
+
+
+     zsh_directory_name_generic "$@"
+
+
+
+File: zsh.info,  Node: Version Control Information,  Next: Prompt Themes,  Prev: Other Directory Functions,  Up: User Contributions
+
+26.5 Gathering information from version control systems
+=======================================================
+
+
+
+In a lot of cases, it is nice to automatically retrieve information from
+version control systems (VCSs), such as subversion, CVS or git, to be
+able to provide it to the user; possibly in the user's prompt. So that
+you can instantly tell which branch you are currently on, for example.
+
+In order to do that, you may use the vcs_info function.
+
+The following VCSs are supported, showing the abbreviated name by which
+they are referred to within the system:
+Bazaar (bzr)
+     `https://bazaar.canonical.com/'
+
+Codeville (cdv)
+     `http://freecode.com/projects/codeville/'
+
+Concurrent Versioning System (cvs)
+     `https://www.nongnu.org/cvs/'
+
+Darcs (darcs)
+     `http://darcs.net/'
+
+Fossil (fossil)
+     `https://fossil-scm.org/'
+
+Git (git)
+     `https://git-scm.com/'
+
+GNU arch (tla)
+     `https://www.gnu.org/software/gnu-arch/'
+
+Mercurial (hg)
+     `https://www.mercurial-scm.org/'
+
+Monotone (mtn)
+     `https://monotone.ca/'
+
+Perforce (p4)
+     `https://www.perforce.com/'
+
+Subversion (svn)
+     `https://subversion.apache.org/'
+
+SVK (svk)
+     `https://svk.bestpractical.com/'
+
+There is also support for the patch management system quilt
+(`https://savannah.nongnu.org/projects/quilt'). See *Note vcs_info
+Quilt Support:: below for details.
+
+To load vcs_info:
+
+
+     autoload -Uz vcs_info
+
+It can be used in any existing prompt, because it does not require any
+specific $psvar entries to be available.
+
+
+
+* Menu:
+
+* vcs_info Quickstart::
+* vcs_info Configuration::
+* vcs_info Oddities::
+* vcs_info Quilt Support::
+* vcs_info API::
+* vcs_info Variables::
+* vcs_info Hooks::
+* vcs_info Examples::
+
+
+
+File: zsh.info,  Node: vcs_info Quickstart,  Next: vcs_info Configuration,  Up: Version Control Information
+
+26.5.1 Quickstart
+-----------------
+
+To get this feature working quickly (including colors), you can do the
+following (assuming, you loaded vcs_info properly - see above):
+
+
+     zstyle ':vcs_info:*' actionformats \
+         '%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{3}|%F{1}%a%F{5}]%f '
+     zstyle ':vcs_info:*' formats       \
+         '%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{5}]%f '
+     zstyle ':vcs_info:(sv[nk]|bzr):*' branchformat '%b%F{1}:%F{3}%r'
+     precmd () { vcs_info }
+     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 vcs_info from your precmd function. Once that is done you need a
+_single quoted_ '${vcs_info_msg_0_}' in your prompt.
+
+To be able to use '${vcs_info_msg_0_}' directly in your prompt like
+this, you will need to have the PROMPT_SUBST option enabled.
+
+Now call the vcs_info_printsys utility from the command line:
+
+
+     % vcs_info_printsys
+     ## list of supported version control backends:
+     ## disabled systems are prefixed by a hash sign (#)
+     bzr
+     cdv
+     cvs
+     darcs
+     fossil
+     git
+     hg
+     mtn
+     p4
+     svk
+     svn
+     tla
+     ## flavours (cannot be used in the enable or disable styles; they
+     ## are enabled and disabled with their master [git-svn -> git])
+     ## they *can* be used in contexts: ':vcs_info:git-svn:*'.
+     git-p4
+     git-svn
+     hg-git
+     hg-hgsubversion
+     hg-hgsvn
+
+You may not want all of these because there is no point in running the
+code to detect systems you do not use.  So there is a way to disable
+some backends altogether:
+
+
+     zstyle ':vcs_info:*' disable bzr cdv darcs mtn svk tla
+
+You may also pick a few from that list and enable only those:
+
+
+     zstyle ':vcs_info:*' enable git cvs svn
+
+If you rerun vcs_info_printsys after one of these commands, you will
+see the backends listed in the disable style (or backends not in the
+enable style - if you used that) marked as disabled by a hash sign.
+That means the detection of these systems is skipped _completely_. No
+wasted time there.
+
+
+
+
+File: zsh.info,  Node: vcs_info Configuration,  Next: vcs_info Oddities,  Prev: vcs_info Quickstart,  Up: Version Control Information
+
+26.5.2 Configuration
+--------------------
+
+The vcs_info feature can be configured via zstyle.
+
+First, the context in which we are working:
+     :vcs_info:VCS-STRING:USER-CONTEXT:REPO-ROOT-NAME
+
+
+VCS-STRING
+     is one of: git, git-svn, git-p4, hg, hg-git, hg-hgsubversion,
+     hg-hgsvn, darcs, bzr, cdv, mtn, svn, cvs, svk, tla, p4 or fossil.
+     This is followed by `.quilt-QUILT-MODE' in Quilt mode (see *Note
+     vcs_info Quilt Support:: for details) and by `+HOOK-NAME' while
+     hooks are active (see *Note vcs_info Hooks:: for details).
+
+     Currently, hooks in quilt mode don't add the `.quilt-QUILT-MODE'
+     information.  This may change in the future.
+
+USER-CONTEXT
+     is a freely configurable string, assignable by the user as the
+     first argument to vcs_info (see its description below).
+
+REPO-ROOT-NAME
+     is the name of a repository in which you want a style to match.
+     So, if you want a setting specific to /usr/src/zsh, with that
+     being a CVS checkout, you can set REPO-ROOT-NAME to zsh to make it
+     so.
+
+
+There are three special values for VCS-STRING: The first is named
+-init-, that is in effect as long as there was no decision what VCS
+backend to use. The second is -preinit-; it is used _before_ vcs_info
+is run, when initializing the data exporting variables. The third
+special value is formats and is used by the vcs_info_lastmsg for
+looking up its styles.
+
+The initial value of REPO-ROOT-NAME is -all- and it is replaced with
+the actual name, as soon as it is known. Only use this part of the
+context for defining the formats, actionformats or branchformat styles,
+as it is guaranteed that REPO-ROOT-NAME is set up correctly for these
+only. For all other styles, just use '*' instead.
+
+There are two pre-defined values for USER-CONTEXT:
+default
+     the one used if none is specified
+
+command
+     used by vcs_info_lastmsg to lookup its styles
+
+You can of course use ':vcs_info:*' to match all VCSs in all
+user-contexts at once.
+
+This is a description of all styles that are looked up.
+
+
+formats
+     A list of formats, used when actionformats is not used (which is
+     most of the time).
+
+actionformats
+     A list of formats, used if there is a special action going on in
+     your current repository; like an interactive rebase or a merge
+     conflict.
+
+branchformat
+     Some backends replace %b in the formats and actionformats styles
+     above, not only by a branch name but also by a revision number.
+     This style lets you modify how that string should look.
+
+nvcsformats
+     These "formats" are set when we didn't detect a version control
+     system for the current directory or vcs_info was disabled. This is
+     useful if you want vcs_info to completely take over the generation
+     of your prompt. You would do something like
+     PS1='${vcs_info_msg_0_}' to accomplish that.
+
+hgrevformat
+     hg uses both a hash and a revision number to reference a specific
+     changeset in a repository. With this style you can format the
+     revision string (see branchformat) to include either or both. It's
+     only useful when get-revision is true. Note, the full 40-character
+     revision id is not available (except when using the use-simple
+     option) because executing hg more than once per prompt is too
+     slow; you may customize this behavior using hooks.
+
+max-exports
+     Defines the maximum number of vcs_info_msg_*_ variables vcs_info
+     will set.
+
+enable
+     A list of backends you want to use. Checked in the -init- context.
+     If this list contains an item called NONE no backend is used at
+     all and vcs_info will do nothing. If this list contains ALL,
+     vcs_info will use all known backends. Only with ALL in enable will
+     the disable style have any effect. ALL and NONE are case
+     insensitive.
+
+disable
+     A list of VCSs you don't want vcs_info to test for repositories
+     (checked in the -init- context, too). Only used if enable contains
+     ALL.
+
+disable-patterns
+     A list of patterns that are checked against $PWD. If a pattern
+     matches, vcs_info will be disabled. This style is checked in the
+     :vcs_info:-init-:*:-all- context.
+
+     Say, ~/.zsh is a directory under version control, in which you do
+     not want vcs_info to be active, do:
+          zstyle ':vcs_info:*' disable-patterns "${(b)HOME}/.zsh(|/*)"
+
+use-quilt
+     If enabled, the quilt support code is active in `addon' mode.  See
+     *Note vcs_info Quilt Support:: for details.
+
+quilt-standalone
+     If enabled, `standalone' mode detection is attempted if no VCS is
+     active in a given directory. See *Note vcs_info Quilt Support::
+     for details.
+
+quilt-patch-dir
+     Overwrite the value of the $QUILT_PATCHES environment variable. See
+     *Note vcs_info Quilt Support:: for details.
+
+quiltcommand
+     When quilt itself is called in quilt support, the value of this
+     style is used as the command name.
+
+check-for-changes
+     If enabled, this style causes the %c and %u format escapes to show
+     when the working directory has uncommitted changes. The strings
+     displayed by these escapes can be controlled via the stagedstr and
+     unstagedstr styles. The only backends that currently support this
+     option are git, hg, and bzr (the latter two only support unstaged).
+
+     For this style to be evaluated with the hg backend, the
+     get-revision style needs to be set and the use-simple style needs
+     to be unset. The latter is the default; the former is not.
+
+     With the bzr backend, _lightweight checkouts_ only honor this
+     style if the use-server style is set.
+
+     Note, the actions taken if this style is enabled are potentially
+     expensive (read: they may be slow, depending on how big the
+     current repository is).  Therefore, it is disabled by default.
+
+check-for-staged-changes
+     This style is like check-for-changes, but it never checks the
+     worktree files, only the metadata in the .${vcs} dir.  Therefore,
+     this style initializes only the %c escape (with stagedstr) but not
+     the %u escape.  This style is faster than check-for-changes.
+
+     In the git backend, this style checks for changes in the index.
+     Other backends do not currently implement this style.
+
+     This style is disabled by default.
+
+stagedstr
+     This string will be used in the %c escape if there are staged
+     changes in the repository.
+
+unstagedstr
+     This string will be used in the %u escape if there are unstaged
+     changes in the repository.
+
+command
+     This style causes 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 not a good idea.
+
+     If the value of this style is empty (which is the default), the
+     used binary name is the name of the backend in use (e.g. svn is
+     used in an svn repository).
+
+     The repo-root-name part in the context is always the default -all-
+     when this style is looked up.
+
+     For example, this style can be used to use binaries from
+     non-default installation directories. Assume, git is installed in
+     /usr/bin but your sysadmin installed a newer version in
+     /usr/local/bin. Instead of changing the order of your $PATH
+     parameter, you can do this:
+          zstyle ':vcs_info:git:*:-all-' command /usr/local/bin/git
+
+use-server
+     This is used by the Perforce backend (p4) to decide if it should
+     contact the Perforce server to find out if a directory is managed
+     by Perforce.  This is the only reliable way of doing this, but runs
+     the risk of a delay if the server name cannot be found.  If the
+     server (more specifically, the host:port pair describing the
+     server) cannot be contacted, its name is put into the associative
+     array vcs_info_p4_dead_servers and is not contacted again during
+     the session until it is removed by hand.  If you do not set this
+     style, the p4 backend is only usable if you have set the
+     environment variable P4CONFIG to a file name and have
+     corresponding files in the root directories of each Perforce
+     client.  See comments in the function VCS_INFO_detect_p4 for more
+     detail.
+
+     The Bazaar backend (bzr) uses this to permit contacting the server
+     about lightweight checkouts, see the check-for-changes style.
+
+use-simple
+     If there are two different ways of gathering information, you can
+     select the simpler one by setting this style to true; the default
+     is to use the not-that-simple code, which is potentially a lot
+     slower but might be more accurate in all possible cases. This
+     style is used by the bzr and hg backends. In the case of hg it
+     will invoke the external hexdump program to parse the binary
+     dirstate cache file; this method will not return the local
+     revision number.
+
+get-revision
+     If set to true, vcs_info goes the extra mile to figure out the
+     revision of a repository's work tree (currently for the git and hg
+     backends, where this kind of information is not always vital). For
+     git, the hash value of the currently checked out commit is
+     available via the %i expansion. With hg, the local revision number
+     and the corresponding global hash are available via %i.
+
+get-mq
+     If set to true, the hg backend will look for a Mercurial Queue (mq)
+     patch directory. Information will be available via the `%m'
+     replacement.
+
+get-bookmarks
+     If set to true, the hg backend will try to get a list of current
+     bookmarks. They will be available via the `%m' replacement.
+
+     The default is to generate a comma-separated list of all bookmark
+     names that refer to the currently checked out revision.  If a
+     bookmark is active, its name is suffixed an asterisk and placed
+     first in the list.
+
+use-prompt-escapes
+     Determines if we assume that the assembled string from vcs_info
+     includes prompt escapes. (Used by vcs_info_lastmsg.)
+
+debug
+     Enable debugging output to track possible problems. Currently this
+     style is only used by vcs_info's hooks system.
+
+hooks
+     A list style that defines hook-function names. See *Note vcs_info
+     Hooks:: below for details.
+
+patch-format
+nopatch-format
+     This pair of styles format the patch information used by the %m
+     expando in formats and actionformats for the git and hg backends.
+     The value is subject to certain %-expansions described below.  The
+     expanded value is made available in the global backend_misc array
+     as ${backend_misc[patches]} (also if a set-patch-format hook is
+     used).
+
+get-unapplied
+     This boolean style controls whether a backend should attempt to
+     gather a list of unapplied patches (for example with Mercurial
+     Queue patches).
+
+     Used by the quilt and hg backends.
+
+
+The default values for these styles in all contexts are:
+
+
+formats
+     " (%s)-[%b]%u%c-"
+
+actionformats
+     " (%s)-[%b|%a]%u%c-"
+
+branchformat
+     "%b:%r" (for bzr, svn, svk and hg)
+
+nvcsformats
+     ""
+
+hgrevformat
+     "%r:%h"
+
+max-exports
+     2
+
+enable
+     ALL
+
+disable
+     (empty list)
+
+disable-patterns
+     (empty list)
+
+check-for-changes
+     false
+
+check-for-staged-changes
+     false
+
+stagedstr
+     (string: "S")
+
+unstagedstr
+     (string: "U")
+
+command
+     (empty string)
+
+use-server
+     false
+
+use-simple
+     false
+
+get-revision
+     false
+
+get-mq
+     true
+
+get-bookmarks
+     false
+
+use-prompt-escapes
+     true
+
+debug
+     false
+
+hooks
+     (empty list)
+
+use-quilt
+     false
+
+quilt-standalone
+     false
+
+quilt-patch-dir
+     empty - use $QUILT_PATCHES
+
+quiltcommand
+     quilt
+
+patch-format
+     BACKEND DEPENDENT
+
+nopatch-format
+     BACKEND DEPENDENT
+
+get-unapplied
+     false
+
+In normal formats and actionformats the following replacements are done:
+
+
+%s
+     The VCS in use (git, hg, svn, etc.).
+
+%b
+     Information about the current branch.
+
+%a
+     An identifier that describes the action. Only makes sense in
+     actionformats.
+
+%i
+     The current revision number or identifier. For hg the hgrevformat
+     style may be used to customize the output.
+
+%c
+     The string from the stagedstr style if there are staged changes in
+     the repository.
+
+%u
+     The string from the unstagedstr style if there are unstaged
+     changes in the repository.
+
+%R
+     The base directory of the repository.
+
+%r
+     The repository name. If %R is /foo/bar/repoXY, %r is repoXY.
+
+%S
+     A subdirectory within a repository. If $PWD is
+     /foo/bar/repoXY/beer/tasty, %S is beer/tasty.
+
+%m
+     A "misc" replacement. It is at the discretion of the backend to
+     decide what this replacement expands to.
+
+     The hg and git backends use this expando to display patch
+     information.  hg sources patch information from the mq extensions;
+     git from in-progress rebase and cherry-pick operations and from
+     the stgit extension.  The patch-format and nopatch-format styles
+     control the generated string.  The former is used when at least
+     one patch from the patch queue has been applied, and the latter
+     otherwise.
+
+     The hg backend displays bookmark information in this expando (in
+     addition to mq information).  See the get-mq and get-bookmarks
+     styles.  Both of these styles may be enabled at the same time.  If
+     both are enabled, both resulting strings will be shown separated
+     by a semicolon (that cannot currently be customized).
+
+     The quilt `standalone' backend sets this expando to the same value
+     as the %Q expando.
+
+%Q
+     Quilt series information.  When quilt is used (either in `addon'
+     mode or as a `standalone' backend), this expando is set to quilt
+     series' patch-format string.  The set-patch-format hook and
+     nopatch-format style are honoured.
+
+     See *Note vcs_info Quilt Support:: below for details.
+
+
+In branchformat these replacements are done:
+
+
+%b
+     The branch name.
+
+%r
+     The current revision number or the hgrevformat style for hg.
+
+In hgrevformat these replacements are done:
+
+
+%r
+     The current local revision number.
+
+%h
+     The current global revision identifier.
+
+In patch-format and nopatch-format these replacements are done:
+
+
+%p
+     The name of the top-most applied patch; may be overridden by the
+     applied-string hook.
+
+%u
+     The number of unapplied patches; may be overridden by the
+     unapplied-string hook.
+
+%n
+     The number of applied patches.
+
+%c
+     The number of unapplied patches.
+
+%a
+     The number of all patches (%a = %n + %c).
+
+%g
+     The names of active mq guards (hg backend).
+
+%G
+     The number of active mq guards (hg backend).
+
+Not all VCS backends have to support all replacements. For nvcsformats
+no replacements are performed at all, it is just a string.
+
+
+
+
+File: zsh.info,  Node: vcs_info Oddities,  Next: vcs_info Quilt Support,  Prev: vcs_info Configuration,  Up: Version Control Information
+
+26.5.3 Oddities
+---------------
+
+If you want to use the %b (bold off) prompt expansion in formats, which
+expands %b itself, use %%b. That will cause the vcs_info expansion to
+replace %%b with %b, so that zsh's prompt expansion mechanism can
+handle it. Similarly, to hand down %b from branchformat, use %%%%b.
+Sorry for this inconvenience, but it cannot be easily avoided. Luckily
+we do not clash with a lot of prompt expansions and this only needs to
+be done for those.
+
+When one of the gen-applied-string, gen-unapplied-string, and
+set-patch-format hooks is defined, applying %-escaping
+(`foo=${foo//'%'/%%}') to the interpolated values for use in the prompt
+is the responsibility of those hooks (jointly); when neither of those
+hooks is defined, vcs_info handles escaping by itself.  We regret this
+coupling, but it was required for backwards compatibility.
+
+
+
+
+File: zsh.info,  Node: vcs_info Quilt Support,  Next: vcs_info API,  Prev: vcs_info Oddities,  Up: Version Control Information
+
+26.5.4 Quilt Support
+--------------------
+
+`Quilt' is not a version control system, therefore this is not
+implemented as a backend. It can help keeping track of a series of
+patches. People use it to keep a set of changes they want to use on top
+of software packages (which is tightly integrated into the package
+build process - the Debian project does this for a large number of
+packages). Quilt can also help individual developers keep track of
+their own patches on top of real version control systems.
+
+The vcs_info integration tries to support both ways of using quilt by
+having two slightly different modes of operation: `addon' mode and
+`standalone' mode).
+
+Quilt integration is off by default; to enable it, set the use-quilt
+style, and add %Q to your formats or actionformats style:
+     zstyle ':vcs_info:*' use-quilt true
+
+Styles looked up from the Quilt support code include `.quilt-QUILT-MODE'
+in the VCS-STRING part of the context, where QUILT-MODE is either addon
+or standalone.  Example:
+:vcs_info:git.quilt-addon:default:REPO-ROOT-NAME.
+
+For `addon' mode to become active vcs_info must have already detected a
+real version control system controlling the directory. If that is the
+case, a directory that holds quilt's patches needs to be found. That
+directory is configurable via the `QUILT_PATCHES' environment variable.
+If that variable exists its value is used, otherwise the value
+`patches' is assumed. The value from $QUILT_PATCHES can be overwritten
+using the `quilt-patches' style. (Note: you can use vcs_info to keep
+the value of $QUILT_PATCHES correct all the time via the post-quilt
+hook).
+
+When the directory in question is found, quilt is assumed to be active.
+To gather more information, vcs_info looks for a directory called `.pc';
+Quilt uses that directory to track its current state. If this directory
+does not exist we know that quilt has not done anything to the working
+directory (read: no patches have been applied yet).
+
+If patches are applied, vcs_info will try to find out which. If you want
+to know which patches of a series are not yet applied, you need to
+activate the get-unapplied style in the appropriate context.
+
+vcs_info allows for very detailed control over how the gathered
+information is presented (see *Note vcs_info Configuration:: and *Note
+vcs_info Hooks::), all of which are documented below. Note there are a
+number of other patch tracking systems that work on top of a certain
+version control system (like stgit for `git', or mq for `hg'); the
+configuration for systems like that are generally configured the same
+way as the `quilt' support.
+
+If the `quilt' support is working in `addon' mode, the produced string
+is available as a simple format replacement (%Q to be precise), which
+can be used in formats and actionformats; see below for details).
+
+If, on the other hand, the support code is working in `standalone' mode,
+vcs_info will pretend as if quilt were an actual version control
+system. That means that the version control system identifier (which
+otherwise would be something like `svn' or `cvs') will be set to
+`-quilt-'. This has implications on the used style context where this
+identifier is the second element. vcs_info will have filled in a proper
+value for the "repository's" root directory and the string containing
+the information about quilt's state will be available as the `misc'
+replacement (and %Q for compatibility with `addon' mode).
+
+What is left to discuss is how `standalone' mode is detected. The
+detection itself is a series of searches for directories. You can have
+this detection enabled all the time in every directory that is not
+otherwise under version control. If you know there is only a limited
+set of trees where you would like vcs_info to try and look for Quilt in
+`standalone' mode to minimise the amount of searching on every call to
+vcs_info, there are a number of ways to do that:
+
+Essentially, `standalone' mode detection is controlled by a style called
+`quilt-standalone'. It is a string style and its value can have
+different effects. The simplest values are: `always' to run detection
+every time vcs_info is run, and `never' to turn the detection off
+entirely.
+
+If the value of quilt-standalone is something else, it is interpreted
+differently. If the value is the name of a scalar variable the value of
+that variable is checked and that value is used in the same
+`always'/`never' way as described above.
+
+If the value of quilt-standalone is an array, the elements of that array
+are used as directory names under which you want the detection to be
+active.
+
+If quilt-standalone is an associative array, the keys are taken as
+directory names under which you want the detection to be active, but
+only if the corresponding value is the string `true'.
+
+Last, but not least, if the value of quilt-standalone is the name of a
+function, the function is called without arguments and the return value
+decides whether detection should be active. A `0' return value is true;
+a non-zero return value is interpreted as false.
+
+Note, if there is both a function and a variable by the name of
+quilt-standalone, the function will take precedence.
+
+
+
+
+File: zsh.info,  Node: vcs_info API,  Next: vcs_info Variables,  Prev: vcs_info Quilt Support,  Up: Version Control Information
+
+26.5.5 Function Descriptions (Public API)
+-----------------------------------------
+
+
+vcs_info [USER-CONTEXT]
+     The main function, that runs all backends and assembles all data
+     into ${vcs_info_msg_*_}. This is the function you want to call from
+     precmd if you want to include up-to-date information in your
+     prompt (see *Note vcs_info Variables:: below).  If an argument is
+     given, that string will be used instead of default in the
+     USER-CONTEXT field of the style context.
+
+vcs_info_hookadd
+     Statically registers a number of functions to a given hook. The
+     hook needs to be given as the first argument; what follows is a
+     list of hook-function names to register to the hook. The `+vi-'
+     prefix needs to be left out here. See *Note vcs_info Hooks:: below
+     for details.
+
+vcs_info_hookdel
+     Remove hook-functions from a given hook. The hook needs to be
+     given as the first non-option argument; what follows is a list of
+     hook-function names to un-register from the hook. If `-a' is used
+     as the first argument, all occurrences of the functions are
+     unregistered. Otherwise only the last occurrence is removed (if a
+     function was registered to a hook more than once). The `+vi-'
+     prefix needs to be left out here.  See *Note vcs_info Hooks::
+     below for details.
+
+vcs_info_lastmsg
+     Outputs the last ${vcs_info_msg_*_} value.  Takes into account the
+     value of the use-prompt-escapes style in
+     ':vcs_info:formats:command:-all-'. It also only prints max-exports
+     values.
+
+vcs_info_printsys [USER-CONTEXT]
+     Prints a list of all supported version control systems. Useful to
+     find out possible contexts (and which of them are enabled) or
+     values for the disable style.
+
+vcs_info_setsys
+     Initializes vcs_info's internal list of available backends. With
+     this function, you can add support for new VCSs without restarting
+     the shell.
+
+
+All functions named VCS_INFO_* are for internal use only.
+
+
+
+
+File: zsh.info,  Node: vcs_info Variables,  Next: vcs_info Hooks,  Prev: vcs_info API,  Up: Version Control Information
+
+26.5.6 Variable Description
+---------------------------
+
+
+${vcs_info_msg_N_} (Note the trailing underscore)
+     Where N is an integer, e.g., vcs_info_msg_0_. These variables are
+     the storage for the informational message the last vcs_info call
+     has assembled. These are strongly connected to the formats,
+     actionformats and nvcsformats styles described above. Those styles
+     are lists. The first member of that list gets expanded into
+     ${vcs_info_msg_0_}, the second into ${vcs_info_msg_1_} and the Nth
+     into ${vcs_info_msg_N-1_}. (See the max-exports style above.)
+
+
+All variables named VCS_INFO_* are for internal use only.
+
+
+
+
+File: zsh.info,  Node: vcs_info Hooks,  Next: vcs_info Examples,  Prev: vcs_info Variables,  Up: Version Control Information
+
+26.5.7 Hooks in vcs_info
+------------------------
+
+Hooks are places in vcs_info where you can run your own code. That code
+can communicate with the code that called it and through that, change
+the system's behaviour.
+
+For configuration, hooks change the style context:
+     :vcs_info:VCS-STRING+HOOK-NAME:USER-CONTEXT:REPO-ROOT-NAME
+
+To register functions to a hook, you need to list them in the hooks
+style in the appropriate context.
+
+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
+`+vi-bar' and `+vi-baz'.
+
+If you would like to register a function to a hook regardless of the
+current context, you may use the vcs_info_hookadd function. To remove a
+function that was added like that, the vcs_info_hookdel function can be
+used.
+
+If something seems weird, you can enable the `debug' boolean style in
+the proper context and the hook-calling code will print what it tried
+to execute and whether the function in question existed.
+
+When you register more than one function to a hook, all functions are
+executed one after another until one function returns non-zero or until
+all functions have been called. Context-sensitive hook functions are
+executed before statically registered ones (the ones added by
+vcs_info_hookadd).
+
+You may pass data between functions via an associative array, user_data.
+For example:
+
+     +vi-git-myfirsthook(){
+         user_data[myval]=$myval
+     }
+     +vi-git-mysecondhook(){
+         # do something with ${user_data[myval]}
+     }
+
+There are a number of variables that are special in hook contexts:
+
+
+ret
+     The return value that the hooks system will return to the caller.
+     The default is an integer `zero'. If and how a changed ret value
+     changes the execution of the caller depends on the specific hook.
+     See the hook documentation below for details.
+
+hook_com
+     An associated array which is used for bidirectional communication
+     from the caller to hook functions. The used keys depend on the
+     specific hook.
+
+context
+     The active context of the hook. Functions that wish to change this
+     variable should make it local scope first.
+
+vcs
+     The current VCS after it was detected. The same values as in the
+     enable/disable style are used. Available in all hooks except
+     start-up.
+
+
+Finally, the full list of currently available hooks:
+
+
+start-up
+     Called after starting vcs_info but before the VCS in this
+     directory is determined. It can be used to deactivate vcs_info
+     temporarily if necessary. When ret is set to 1, vcs_info aborts
+     and does nothing; when set to 2, vcs_info sets up everything as if
+     no version control were active and exits.
+
+pre-get-data
+     Same as start-up but after the VCS was detected.
+
+gen-hg-bookmark-string
+     Called in the Mercurial backend when a bookmark string is
+     generated; the get-revision and get-bookmarks styles must be true.
+
+     This hook gets the names of the Mercurial bookmarks that vcs_info
+     collected from `hg'.
+
+     If a bookmark is active, the key ${hook_com[hg-active-bookmark]} is
+     set to its name.  The key is otherwise unset.
+
+     When setting ret to non-zero, the string in
+     ${hook_com[hg-bookmark-string]} will be used in the %m escape in
+     formats and actionformats and will be available in the global
+     backend_misc array as ${backend_misc[bookmarks]}.
+
+gen-applied-string
+     Called in the git (with stgit or during rebase or merge), and hg
+     (with mq) backends and in quilt support when the applied-string is
+     generated; the use-quilt zstyle must be true for quilt (the mq and
+     stgit backends are active by default).
+
+     This hook gets the names of all applied patches which vcs_info
+     collected so far in the opposite order, which means that the first
+     argument is the top-most patch and so forth.
+
+     When setting ret to non-zero, the string in
+     ${hook_com[applied-string]} will be available as %p in the
+     patch-format and nopatch-format styles.  This hook is, in concert
+     with set-patch-format, responsible for %-escaping that value for
+     use in the prompt.  (See *Note vcs_info Oddities::.)
+
+gen-unapplied-string
+     Called in the git (with stgit or during rebase), and hg (with mq)
+     backend and in quilt support when the unapplied-string is
+     generated; the get-unapplied style must be true.
+
+     This hook gets the names of all unapplied patches which vcs_info
+     collected so far in order, which means that the first argument is
+     the patch next-in-line to be applied and so forth.
+
+     When setting ret to non-zero, the string in
+     ${hook_com[unapplied-string]} will be available as %u in the
+     patch-format and nopatch-format styles.  This hook is, in concert
+     with set-patch-format, responsible for %-escaping that value for
+     use in the prompt.  (See *Note vcs_info Oddities::.)
+
+gen-mqguards-string
+     Called in the hg backend when guards-string is generated; the
+     get-mq style must be true (default).
+
+     This hook gets the names of any active mq guards.
+
+     When setting ret to non-zero, the string in
+     ${hook_com[guards-string]} will be used in the %g escape in the
+     patch-format and nopatch-format styles.
+
+no-vcs
+     This hooks is called when no version control system was detected.
+
+     The `hook_com' parameter is not used.
+
+post-backend
+     Called as soon as the backend has finished collecting information.
+
+     The `hook_com' keys available are as for the set-message hook.
+
+post-quilt
+     Called after the quilt support is done. The following information
+     is passed as arguments to the hook: 1. the quilt-support mode
+     (`addon' or `standalone'); 2. the directory that contains the
+     patch series; 3. the directory that holds quilt's status
+     information (the `.pc' directory) or the string "-nopc-" if that
+     directory wasn't found.
+
+     The `hook_com' parameter is not used.
+
+set-branch-format
+     Called before `branchformat' is set. The only argument to the hook
+     is the format that is configured at this point.
+
+     The `hook_com' keys considered are `branch' and `revision'.  They
+     are set to the values figured out so far by vcs_info and any
+     change will be used directly when the actual replacement is done.
+
+     If ret is set to non-zero, the string in
+     ${hook_com[branch-replace]} will be used unchanged as the `%b'
+     replacement in the variables set by vcs_info.
+
+set-hgrev-format
+     Called before a `hgrevformat' is set. The only argument to the
+     hook is the format that is configured at this point.
+
+     The `hook_com' keys considered are `hash' and `localrev'.  They
+     are set to the values figured out so far by vcs_info and any
+     change will be used directly when the actual replacement is done.
+
+     If ret is set to non-zero, the string in ${hook_com[rev-replace]}
+     will be used unchanged as the `%i' replacement in the variables
+     set by vcs_info.
+
+pre-addon-quilt
+     This hook is used when vcs_info's quilt functionality is active in
+     "addon" mode (quilt used on top of a real version control system).
+     It is activated right before any quilt specific action is taken.
+
+     Setting the `ret' variable in this hook to a non-zero value avoids
+     any quilt specific actions from being run at all.
+
+set-patch-format
+     This hook is used to control some of the possible expansions in
+     patch-format and nopatch-format styles with patch queue systems
+     such as quilt, mqueue and the like.
+
+     This hook is used in the git, hg and quilt backends.
+
+     The hook allows the control of the %p (${hook_com[applied]}) and %u
+     (${hook_com[unapplied]}) expansion in all backends that use the
+     hook. With the mercurial backend, the %g (${hook_com[guards]})
+     expansion is controllable in addition to that.
+
+     If ret is set to non-zero, the string in ${hook_com[patch-replace]}
+     will be used unchanged instead of an expanded format from
+     patch-format or nopatch-format.
+
+     This hook is, in concert with the gen-applied-string or
+     gen-unapplied-string hooks if they are defined, responsible for
+     %-escaping the final patch-format value for use in the prompt.
+     (See *Note vcs_info Oddities::.)
+
+set-message
+     Called each time before a `vcs_info_msg_N_' message is set.  It
+     takes two arguments; the first being the `N' in the message
+     variable name, the second is the currently configured formats or
+     actionformats.
+
+     There are a number of `hook_com' keys, that are used here:
+     `action', `branch', `base', `base-name', `subdir', `staged',
+     `unstaged', `revision', `misc', `vcs' and one `miscN' entry for
+     each backend-specific data field (N starting at zero). They are
+     set to the values figured out so far by vcs_info and any change
+     will be used directly when the actual replacement is done.
+
+     Since this hook is triggered multiple times (once for each
+     configured formats or actionformats), each of the `hook_com' keys
+     mentioned above (except for the miscN entries) has an `_orig'
+     counterpart, so even if you changed a value to your liking you can
+     still get the original value in the next run. Changing the `_orig'
+     values is probably not a good idea.
+
+     If ret is set to non-zero, the string in ${hook_com[message]} will
+     be used unchanged as the message by vcs_info.
+
+
+If all of this sounds rather confusing, take a look at *Note vcs_info
+Examples:: and also in the Misc/vcs_info-examples file in the Zsh
+source.  They contain some explanatory code.
+
+
+
+
+File: zsh.info,  Node: vcs_info Examples,  Prev: vcs_info Hooks,  Up: Version Control Information
+
+26.5.8 Examples
+---------------
+
+Don't use vcs_info at all (even though it's in your prompt):
+     zstyle ':vcs_info:*' enable NONE
+
+Disable the backends for bzr and svk:
+     zstyle ':vcs_info:*' disable bzr svk
+
+Disable everything _but_ bzr and svk:
+     zstyle ':vcs_info:*' enable bzr svk
+
+Provide a special formats for git:
+     zstyle ':vcs_info:git:*' formats       ' GIT, BABY! [%b]'
+     zstyle ':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]'
+
+All %x expansion in all sorts of formats (formats, actionformats,
+branchformat, you name it) are done using the `zformat' builtin from
+the `zsh/zutil' module. That means you can do everything with these %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
+branchformat, you can do this: %12.12i. That'll shrink the 40 character
+hash to its 12 leading characters. The form is actually `%MIN.MAXx'.
+More is possible.  See *Note The zsh/zutil Module:: for details.
+
+Use the quicker bzr backend
+     zstyle ':vcs_info:bzr:*' use-simple true
+
+If you do use use-simple, please report if it does
+`the-right-thing[tm]'.
+
+Display the revision number in yellow for bzr and svn:
+     zstyle ':vcs_info:(svn|bzr):*' \
+            branchformat '%b%{'${fg[yellow]}'%}:%r'
+
+If you want colors, make sure you enclose the color codes in %{...%} if
+you want to use the string provided by vcs_info in prompts.
+
+Here is how to print the VCS information as a command (not in a prompt):
+     alias vcsi='vcs_info command; vcs_info_lastmsg'
+
+This way, you can even define different formats for output via
+vcs_info_lastmsg in the ':vcs_info:*:command:*' namespace.
+
+Now as promised, some code that uses hooks: say, you'd like to replace
+the string `svn' by `subversion' in vcs_info's %s formats replacement.
+
+First, we will tell vcs_info to call a function when populating the
+message variables with the gathered information:
+     zstyle ':vcs_info:*+set-message:*' hooks svn2subversion
+
+Nothing happens. Which is reasonable, since we didn't define the actual
+function yet. To see what the hooks subsystem is trying to do, enable
+the `debug' style:
+     zstyle ':vcs_info:*+*:*' debug true
+
+That should give you an idea what is going on. Specifically, the
+function that we are looking for is `+vi-svn2subversion'. Note, the
+`+vi-' prefix. So, everything is in order, just as documented. When you
+are done checking out the debugging output, disable it again:
+     zstyle ':vcs_info:*+*:*' debug false
+
+Now, let's define the function:
+
+     function +vi-svn2subversion() {
+         [[ ${hook_com[vcs_orig]} == svn ]] && hook_com[vcs]=subversion
+     }
+
+Simple enough. And it could have even been simpler, if only we had
+registered our function in a less generic context. If we do it only in
+the `svn' backend's context, we don't need to test which the active
+backend is:
+     zstyle ':vcs_info:svn+set-message:*' hooks svn2subversion
+
+
+     function +vi-svn2subversion() {
+         hook_com[vcs]=subversion
+     }
+
+And finally a little more elaborate example, that uses a hook to create
+a customised bookmark string for the hg backend.
+
+Again, we start off by registering a function:
+     zstyle ':vcs_info:hg+gen-hg-bookmark-string:*' hooks hgbookmarks
+
+And then we define the `+vi-hgbookmarks' function:
+
+     function +vi-hgbookmarks() {
+         # The default is to connect all bookmark names by
+         # commas. This mixes things up a little.
+         # Imagine, there's one type of bookmarks that is
+         # special to you. Say, because it's *your* work.
+         # Those bookmarks look always like this: "sh/*"
+         # (because your initials are sh, for example).
+         # This makes the bookmarks string use only those
+         # bookmarks. If there's more than one, it
+         # concatenates them using commas.
+         # The bookmarks returned by `hg' are available in
+         # the function's positional parameters.
+         local s="${(Mj:,:)@:#sh/*}"
+         # Now, the communication with the code that calls
+         # the hook functions is done via the hook_com[]
+         # hash. The key at which the `gen-hg-bookmark-string'
+         # hook looks is `hg-bookmark-string'. So:
+         hook_com[hg-bookmark-string]=$s
+         # And to signal that we want to use the string we
+         # just generated, set the special variable `ret' to
+         # something other than the default zero:
+         ret=1
+         return 0
+     }
+
+Some longer examples and code snippets which might be useful are
+available in the examples file located at Misc/vcs_info-examples in the
+Zsh source directory.
+
+This concludes our guided tour through zsh's vcs_info.
+
+
+
+
+File: zsh.info,  Node: Prompt Themes,  Next: ZLE Functions,  Prev: Version Control Information,  Up: User Contributions
+
+26.6 Prompt Themes
+==================
+
+
+
+26.6.1 Installation
+-------------------
+
+You should make sure all the functions from the Functions/Prompts
+directory of the source distribution are available; they all begin with
+the string `prompt_' except for the special function`promptinit'.  You
+also need the `colors' and `add-zsh-hook' functions from Functions/Misc.
+All these functions may already be installed on your system; if not,
+you will need to find them and copy them.  The directory should appear
+as one of the elements of the fpath array (this should already be the
+case if they were installed), and at least the function promptinit
+should be autoloaded; it will autoload the rest.  Finally, to initialize
+the use of the system you need to call the promptinit function.  The
+following code in your .zshrc will arrange for this; assume the
+functions are stored in the directory ~/myfns:
+
+
+     fpath=(~/myfns $fpath)
+     autoload -U promptinit
+     promptinit
+
+
+26.6.2 Theme Selection
+----------------------
+
+Use the prompt command to select your preferred theme.  This command
+may be added to your .zshrc following the call to promptinit in order
+to start zsh with a theme already selected.
+
+
+prompt [ -c | -l ]
+prompt [ -p | -h ] [ THEME ... ]
+prompt [ -s ] THEME [ ARG ... ]
+     Set or examine the prompt theme.  With no options and a THEME
+     argument, the theme with that name is set as the current theme.
+     The available themes are determined at run time; use the -l option
+     to see a list.  The special THEME `random' selects at random one
+     of the available themes and sets your prompt to that.
+
+     In some cases the THEME may be modified by one or more arguments,
+     which should be given after the theme name.  See the help for each
+     theme for descriptions of these arguments.
+
+     Options are:
+
+
+    -c
+          Show the currently selected theme and its parameters, if any.
+
+    -l
+          List all available prompt themes.
+
+    -p
+          Preview the theme named by THEME, or all themes if no THEME
+          is given.
+
+    -h
+          Show help for the theme named by THEME, or for the prompt
+          function if no THEME is given.
+
+    -s
+          Set THEME as the current theme and save state.
+
+prompt_THEME_setup
+     Each available THEME has a setup function which is called by the
+     prompt function to install that theme.  This function may define
+     other functions as necessary to maintain the prompt, including
+     functions used to preview the prompt or provide help for its use.
+     You should not normally call a theme's setup function directly.
+
+
+
+26.6.3 Utility Themes
+---------------------
+
+
+prompt off
+     The theme `off' sets all the prompt variables to minimal values
+     with no special effects.
+
+prompt default
+     The theme `default' sets all prompt variables to the same state as
+     if an interactive zsh was started with no initialization files.
+
+prompt restore
+     The special theme `restore' erases all theme settings and sets
+     prompt variables to their state before the first time the `prompt'
+     function was run, provided each theme has properly defined its
+     cleanup (see below).
+
+     Note that you can undo `prompt off' and `prompt default' with
+     `prompt restore', but a second restore does not undo the first.
+
+
+
+26.6.4 Writing Themes
+---------------------
+
+The first step for adding your own theme is to choose a name for it,
+and create a file `prompt_NAME_setup' in a directory in your fpath,
+such as ~/myfns in the example above.  The file should at minimum
+contain assignments for the prompt variables that your theme wishes to
+modify.  By convention, themes use PS1, PS2, RPS1, etc., rather than
+the longer PROMPT and RPROMPT.
+
+The file is autoloaded as a function in the current shell context, so
+it may contain any necessary commands to customize your theme, including
+defining additional functions.  To make some complex tasks easier, your
+setup function may also do any of the following:
+
+
+Assign prompt_opts
+     The array prompt_opts may be assigned any of "bang", "cr",
+     "percent", "sp", and/or "subst" as values.  The corresponding
+     setopts (promptbang, etc.) are turned on, all other prompt-related
+     options are turned off.  The prompt_opts array preserves setopts
+     even beyond the scope of localoptions, should your function need
+     that.
+
+Modify precmd and preexec
+     Use of add-zsh-hook is recommended.  The precmd and preexec hooks
+     are automatically adjusted if the prompt theme changes or is
+     disabled.
+
+Declare cleanup
+     If your function makes any other changes that should be undone
+     when the theme is disabled, your setup function may call
+          prompt_cleanup COMMAND
+     where COMMAND should be suitably quoted.  If your theme is ever
+     disabled or replaced by another, COMMAND is executed with eval.
+     You may declare more than one such cleanup hook.
+
+Define preview
+     Define or autoload a function prompt_NAME_preview to display a
+     simulated version of your prompt.  A simple default previewer is
+     defined by promptinit for themes that do not define their own.
+     This preview function is called by `prompt -p'.
+
+Provide help
+     Define or autoload a function prompt_NAME_help to display
+     documentation or help text for your theme.  This help function is
+     called by `prompt -h'.
+
+
+
+
+File: zsh.info,  Node: ZLE Functions,  Next: Exception Handling,  Prev: Prompt Themes,  Up: User Contributions
+
+26.7 ZLE Functions
+==================
+
+
+
+26.7.1 Widgets
+--------------
+
+These functions all implement user-defined ZLE widgets (see *Note Zsh
+Line Editor::) which can be bound to keystrokes in interactive shells.
+To use them, your .zshrc should contain lines of the form
+
+
+     autoload FUNCTION
+     zle -N FUNCTION
+
+followed by an appropriate bindkey command to associate the function
+with a key sequence.  Suggested bindings are described below.
+
+
+bash-style word functions
+     If you are looking for functions to implement moving over and
+     editing words in the manner of bash, where only alphanumeric
+     characters are considered word characters, you can use the
+     functions described in the next section.  The following is
+     sufficient:
+
+
+          autoload -U select-word-style
+          select-word-style bash
+
+     
+forward-word-match, backward-word-match
+kill-word-match, backward-kill-word-match
+transpose-words-match, capitalize-word-match
+up-case-word-match, down-case-word-match
+delete-whole-word-match, select-word-match
+select-word-style, match-word-context, match-words-by-style
+     The first eight `-match' functions are drop-in replacements for the
+     builtin widgets without the suffix.  By default they behave in a
+     similar way.  However, by the use of styles and the function
+     select-word-style, the way words are matched can be altered.
+     select-word-match is intended to be used as a text object in vi
+     mode but with custom word styles. For comparison, the widgets
+     described in *Note Text Objects:: use fixed definitions of words,
+     compatible with the vim editor.
+
+     The simplest way of configuring the functions is to use
+     select-word-style, which can either be called as a normal function
+     with the appropriate argument, or invoked as a user-defined widget
+     that will prompt for the first character of the word style to be
+     used.  The first time it is invoked, the first eight -match
+     functions will automatically replace the builtin versions, so they
+     do not need to be loaded explicitly.
+
+     The word styles available are as follows.  Only the first character
+     is examined.
+
+
+    bash
+          Word characters are alphanumeric characters only.
+
+    normal
+          As in normal shell operation:  word characters are
+          alphanumeric characters plus any characters present in the
+          string given by the parameter $WORDCHARS.
+
+    shell
+          Words are complete shell command arguments, possibly
+          including complete quoted strings, or any tokens special to
+          the shell.
+
+    whitespace
+          Words are any set of characters delimited by whitespace.
+
+    default
+          Restore the default settings; this is usually the same as
+          `normal'.
+
+
+     All but `default' can be input as an upper case character, which
+     has the same effect but with subword matching turned on.  In this
+     case, words with upper case characters are treated specially: each
+     separate run of upper case characters, or an upper case character
+     followed by any number of other characters, is considered a word.
+     The style subword-range can supply an alternative character range
+     to the default `[:upper:]'; the value of the style is treated as
+     the contents of a `[...]'  pattern (note that the outer brackets
+     should not be supplied, only those surrounding named ranges).
+
+     More control can be obtained using the zstyle command, as
+     described in *Note The zsh/zutil Module::.  Each style is looked
+     up in the context :zle:WIDGET where WIDGET is the name of the
+     user-defined widget, not the name of the function implementing it,
+     so in the case of the definitions supplied by select-word-style the
+     appropriate contexts are :zle:forward-word, and so on.  The
+     function select-word-style itself always defines styles for the
+     context `:zle:*' which can be overridden by more specific (longer)
+     patterns as well as explicit contexts.
+
+     The style word-style specifies the rules to use.  This may have the
+     following values.
+
+
+    normal
+          Use the standard shell rules, i.e. alphanumerics and
+          $WORDCHARS, unless overridden by the styles word-chars or
+          word-class.
+
+    specified
+          Similar to normal, but _only_ the specified characters, and
+          not also alphanumerics, are considered word characters.
+
+    unspecified
+          The negation of specified.  The given characters are those
+          which will _not_ be considered part of a word.
+
+    shell
+          Words are obtained by using the syntactic rules for
+          generating shell command arguments.  In addition, special
+          tokens which are never command arguments such as `()' are
+          also treated as words.
+
+    whitespace
+          Words are whitespace-delimited strings of characters.
+
+
+     The first three of those rules usually use $WORDCHARS, but the
+     value in the parameter can be overridden by the style word-chars,
+     which works in exactly the same way as $WORDCHARS.  In addition,
+     the style word-class uses character class syntax to group
+     characters and takes precedence over word-chars if both are set.
+     The word-class style does not include the surrounding brackets of
+     the character class; for example, `-:[:alnum:]' is a valid
+     word-class to include all alphanumerics plus the characters `-'
+     and `:'.  Be careful including `]', `^' and `-' as these are
+     special inside character classes.
+
+     word-style may also have `-subword' appended to its value to turn
+     on subword matching, as described above.
+
+     The style skip-chars is mostly useful for transpose-words and
+     similar functions.  If set, it gives a count of characters
+     starting at the cursor position which will not be considered part
+     of the word and are treated as space, regardless of what they
+     actually are.  For example, if
+
+
+          zstyle ':zle:transpose-words' skip-chars 1
+
+     has been set, and transpose-words-match is called with the cursor
+     on the X of fooXbar, where X can be any character, then the
+     resulting expression is barXfoo.
+
+     Finer grained control can be obtained by setting the style
+     word-context to an array of pairs of entries.  Each pair of
+     entries consists of a PATTERN and a SUBCONTEXT.  The shell
+     argument the cursor is on is matched against each PATTERN in turn
+     until one matches; if it does, the context is extended by a colon
+     and the corresponding SUBCONTEXT.  Note that the test is made
+     against the original word on the line, with no stripping of
+     quotes.  Special handling is done between words: the current
+     context is examined and if it contains the string between the word
+     is set to a single space; else if it is contains the string back,
+     the word before the cursor is considered, else the word after
+     cursor is considered. Some examples are given below.
+
+     The style skip-whitespace-first is only used with the forward-word
+     widget.  If it is set to true, then forward-word skips any
+     non-word-characters, followed by any non-word-characters: this is
+     similar to the behaviour of other word-orientated widgets, and
+     also that used by other editors, however it differs from the
+     standard zsh behaviour.  When using select-word-style the widget
+     is set in the context :zle:* to true if the word style is bash and
+     false otherwise.  It may be overridden by setting it in the more
+     specific context :zle:forward-word*.
+
+     It is possible to create widgets with specific behaviour by
+     defining a new widget implemented by the appropriate generic
+     function, then setting a style for the context of the specific
+     widget.  For example, the following defines a widget
+     backward-kill-space-word using backward-kill-word-match, the
+     generic widget implementing backward-kill-word behaviour, and
+     ensures that the new widget always implements space-delimited
+     behaviour.
+
+
+          zle -N backward-kill-space-word backward-kill-word-match
+          zstyle :zle:backward-kill-space-word word-style space
+
+     The widget backward-kill-space-word can now be bound to a key.
+
+     Here are some further examples of use of the styles, actually
+     taken from the simplified interface in select-word-style:
+
+
+          zstyle ':zle:*' word-style standard
+          zstyle ':zle:*' word-chars ''
+
+     Implements bash-style word handling for all widgets, i.e. only
+     alphanumerics are word characters; equivalent to setting the
+     parameter WORDCHARS empty for the given context.
+
+
+          style ':zle:*kill*' word-style space
+
+     Uses space-delimited words for widgets with the word `kill' in the
+     name.  Neither of the styles word-chars nor word-class is used in
+     this case.
+
+     Here are some examples of use of the word-context style to extend
+     the context.
+
+
+          zstyle ':zle:*' word-context \
+                 "*/*" filename "[[: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 ''
+
+     This provides two different ways of using transpose-words
+     depending on whether the cursor is on whitespace between words or
+     on a filename, here any word containing a /.  On whitespace,
+     complete arguments as defined by standard shell rules will be
+     transposed.  In a filename, only alphanumerics will be transposed.
+     Elsewhere, words will be transposed using the default style for
+     :zle:transpose-words.
+
+     The word matching and all the handling of zstyle settings is
+     actually implemented by the function match-words-by-style.  This
+     can be used to create new user-defined widgets.  The calling
+     function should set the local parameter curcontext to :zle:WIDGET,
+     create the local parameter matched_words and call
+     match-words-by-style with no arguments.  On return, matched_words
+     will be set to an array with the elements: (1) the start of the
+     line (2) the word before the cursor (3) any non-word characters
+     between that word and the cursor (4) any non-word character at the
+     cursor position plus any remaining non-word characters before the
+     next word, including all characters specified by the skip-chars
+     style, (5) the word at or following the cursor (6) any non-word
+     characters following that word (7) the remainder of the line.  Any
+     of the elements may be an empty string; the calling function
+     should test for this to decide whether it can perform its function.
+
+     If the variable matched_words is defined by the caller to
+     match-words-by-style as an associative array (local -A
+     matched_words), then the seven values given above should be
+     retrieved from it as elements named start, word-before-cursor,
+     ws-before-cursor, ws-after-cursor, word-after-cursor,
+     ws-after-word, and end.  In addition the element is-word-start is
+     1 if the cursor is on the start of a word or subword, or on white
+     space before it (the cases can be distinguished by testing the
+     ws-after-cursor element) and 0 otherwise.  This form is
+     recommended for future compatibility.
+
+     It is possible to pass options with arguments to
+     match-words-by-style to override the use of styles.  The options
+     are:
+    -w
+          WORD-STYLE
+
+    -s
+          SKIP-CHARS
+
+    -c
+          WORD-CLASS
+
+    -C
+          WORD-CHARS
+
+    -r
+          SUBWORD-RANGE
+
+     For example, match-words-by-style -w shell -c 0 may be used to
+     extract the command argument around the cursor.
+
+     The word-context style is implemented by the function
+     match-word-context.  This should not usually need to be called
+     directly.
+
+bracketed-paste-magic
+     The bracketed-paste widget (see *Note Miscellaneous:: in *Note Zle
+     Widgets::) inserts pasted text literally into the editor buffer
+     rather than interpret it as keystrokes.  This disables some common
+     usages where the self-insert widget is replaced in order to
+     accomplish some extra processing.  An example is the contributed
+     url-quote-magic widget described below.
+
+     The bracketed-paste-magic widget is meant to replace
+     bracketed-paste with a wrapper that re-enables these self-insert
+     actions, and other actions as selected by zstyles.  Therefore this
+     widget is installed with
+
+          autoload -Uz bracketed-paste-magic
+          zle -N bracketed-paste bracketed-paste-magic
+
+     Other than enabling some widget processing, bracketed-paste-magic
+     attempts to replicate bracketed-paste as faithfully as possible.
+
+     The following zstyles may be set to control processing of pasted
+     text.  All are looked up in the context `:bracketed-paste-magic'.
+
+
+    active-widgets
+          A list of patterns matching widget names that should be
+          activated during the paste.  All other key sequences are
+          processed as self-insert-unmeta.  The default is `self-*' so
+          any user-defined widgets named with that prefix are active
+          along with the builtin self-insert.
+
+          If this style is not set (explicitly deleted) or set to an
+          empty value, no widgets are active and the pasted text is
+          inserted literally.  If the value includes `undefined-key',
+          any unknown sequences are discarded from the pasted text.
+
+    inactive-keys
+          The inverse of active-widgets, a list of key sequences that
+          always use self-insert-unmeta even when bound to an active
+          widget.  Note that this is a list of literal key sequences,
+          not patterns.
+
+    paste-init
+          A list of function names, called in widget context (but not
+          as widgets).  The functions are called in order until one of
+          them returns a non-zero status.  The parameter `PASTED'
+          contains the initial state of the pasted text.  All other ZLE
+          parameters such as `BUFFER' have their normal values and
+          side-effects, and full history is available, so for example
+          paste-init functions may move words from BUFFER into PASTED
+          to make those words visible to the active-widgets.
+
+          A non-zero return from a paste-init function does _not_
+          prevent the paste itself from proceeding.
+
+          Loading bracketed-paste-magic defines backward-extend-paste, a
+          helper function for use in paste-init.
+
+
+               zstyle :bracketed-paste-magic paste-init \
+                      backward-extend-paste
+
+          When a paste would insert into the middle of a word or append
+          text to a word already on the line, backward-extend-paste
+          moves the prefix from LBUFFER into PASTED so that the
+          active-widgets see the full word so far.  This may be useful
+          with url-quote-magic.
+
+    paste-finish
+          Another list of function names called in order until one
+          returns non-zero.  These functions are called _after_ the
+          pasted text has been processed by the active-widgets, but
+          _before_ it is inserted into `BUFFER'.  ZLE parameters have
+          their normal values and side-effects.
+
+          A non-zero return from a paste-finish function does _not_
+          prevent the paste itself from proceeding.
+
+          Loading bracketed-paste-magic also defines quote-paste, a
+          helper function for use in paste-finish.
+
+
+               zstyle :bracketed-paste-magic paste-finish \
+                      quote-paste
+               zstyle :bracketed-paste-magic:finish quote-style \
+                      qqq
+
+          When the pasted text is inserted into BUFFER, it is quoted
+          per the quote-style value.  To forcibly turn off the built-in
+          numeric prefix quoting of bracketed-paste, use:
+
+
+               zstyle :bracketed-paste-magic:finish quote-style \
+                      none
+
+
+     _Important:_ During active-widgets processing of the paste (after
+     paste-init and before paste-finish), BUFFER starts empty and
+     history is restricted, so cursor motions, etc., may not pass
+     outside of the pasted content.  Text assigned to BUFFER by the
+     active widgets is copied back into PASTED before paste-finish.
+
+copy-earlier-word
+     This widget works like a combination of insert-last-word and
+     copy-prev-shell-word.  Repeated invocations of the widget retrieve
+     earlier words on the relevant history line.  With a numeric
+     argument N, insert the Nth word from the history line; N may be
+     negative to count from the end of the line.
+
+     If insert-last-word has been used to retrieve the last word on a
+     previous history line, repeated invocations will replace that word
+     with earlier words from the same line.
+
+     Otherwise, the widget applies to words on the line currently being
+     edited.  The widget style can be set to the name of another widget
+     that should be called to retrieve words.  This widget must accept
+     the same three arguments as insert-last-word.
+
+cycle-completion-positions
+     After inserting an unambiguous string into the command line, the
+     new function based completion system may know about multiple
+     places in this string where characters are missing or differ from
+     at least one of the possible matches.  It will then place the
+     cursor on the position it considers to be the most interesting
+     one, i.e. the one where one can disambiguate between as many
+     matches as possible with as little typing as possible.
+
+     This widget allows the cursor to be easily moved to the other
+     interesting spots.  It can be invoked repeatedly to cycle between
+     all positions reported by the completion system.
+
+delete-whole-word-match
+     This is another function which works like the -match functions
+     described immediately above, i.e. using styles to decide the word
+     boundaries.  However, it is not a replacement for any existing
+     function.
+
+     The basic behaviour is to delete the word around the cursor.
+     There is no numeric argument handling; only the single word around
+     the cursor is considered.  If the widget contains the string kill,
+     the removed text will be placed in the cutbuffer for future
+     yanking.  This can be obtained by defining kill-whole-word-match
+     as follows:
+
+
+          zle -N kill-whole-word-match delete-whole-word-match
+
+     and then binding the widget kill-whole-word-match.
+
+up-line-or-beginning-search, down-line-or-beginning-search
+     These widgets are similar to the builtin functions
+     up-line-or-search and down-line-or-search:  if in a multiline
+     buffer they move up or down within the buffer, otherwise they
+     search for a history line matching the start of the current line.
+     In this case, however, they search for a line which matches the
+     current line up to the current cursor position, in the manner of
+     history-beginning-search-backward and -forward, rather than the
+     first word on the line.
+
+edit-command-line
+     Edit the command line using your visual editor, as in ksh.
+
+
+          bindkey -M vicmd v edit-command-line
+
+expand-absolute-path
+     Expand the file name under the cursor to an absolute path,
+     resolving symbolic links.  Where possible, the initial path
+     segment is turned into a named directory or reference to a user's
+     home directory.
+
+history-search-end
+     This function implements the widgets
+     history-beginning-search-backward-end and
+     history-beginning-search-forward-end.  These commands work by first
+     calling the corresponding builtin widget (see *Note History
+     Control::) and then moving the cursor to the end of the line.  The
+     original cursor position is remembered and restored before calling
+     the builtin widget a second time, so that the same search is
+     repeated to look farther through the history.
+
+     Although you autoload only one function, the commands to use it are
+     slightly different because it implements two widgets.
+
+
+          zle -N history-beginning-search-backward-end \
+                 history-search-end
+          zle -N history-beginning-search-forward-end \
+                 history-search-end
+          bindkey '\e^P' history-beginning-search-backward-end
+          bindkey '\e^N' history-beginning-search-forward-end
+
+history-beginning-search-menu
+     This function implements yet another form of history searching.
+     The text before the cursor is used to select lines from the
+     history, as for history-beginning-search-backward except that all
+     matches are shown in a numbered menu.  Typing the appropriate
+     digits inserts the full history line.  Note that leading zeroes
+     must be typed (they are only shown when necessary for removing
+     ambiguity).  The entire history is searched; there is no
+     distinction between forwards and backwards.
+
+     With a numeric argument, the search is not anchored to the start of
+     the line; the string typed by the use may appear anywhere in the
+     line in the history.
+
+     If the widget name contains `-end' the cursor is moved to the end
+     of the line inserted.  If the widget name contains `-space' any
+     space in the text typed is treated as a wildcard and can match
+     anything (hence a leading space is equivalent to giving a numeric
+     argument).  Both forms can be combined, for example:
+
+
+          zle -N history-beginning-search-menu-space-end \
+                 history-beginning-search-menu
+
+history-pattern-search
+     The function history-pattern-search implements widgets which prompt
+     for a pattern with which to search the history backwards or
+     forwards.  The pattern is in the usual zsh format, however the
+     first character may be ^ to anchor the search to the start of the
+     line, and the last character may be $ to anchor the search to the
+     end of the line.  If the search was not anchored to the end of the
+     line the cursor is positioned just after the pattern found.
+
+     The commands to create bindable widgets are similar to those in the
+     example immediately above:
+
+
+          autoload -U history-pattern-search
+          zle -N history-pattern-search-backward history-pattern-search
+          zle -N history-pattern-search-forward history-pattern-search
+
+incarg
+     Typing the keystrokes for this widget with the cursor placed on or
+     to the left of an integer causes that integer to be incremented by
+     one.  With a numeric argument, the number is incremented by the
+     amount of the argument (decremented if the numeric argument is
+     negative).  The shell parameter incarg may be set to change the
+     default increment to something other than one.
+
+
+          bindkey '^X+' incarg
+
+incremental-complete-word
+     This allows incremental completion of a word.  After starting this
+     command, a list of completion choices can be shown after every
+     character you type, which you can delete with ^H or DEL.  Pressing
+     return accepts the completion so far and returns you to normal
+     editing (that is, the command line is _not_ immediately executed).
+     You can hit TAB to do normal completion, ^G to abort back to the
+     state when you started, and ^D to list the matches.
+
+     This works only with the new function based completion system.
+
+
+          bindkey '^Xi' incremental-complete-word
+
+insert-composed-char
+     This function allows you to compose characters that don't appear
+     on the keyboard to be inserted into the command line.  The command
+     is followed by two keys corresponding to ASCII characters (there
+     is no prompt).  For accented characters, the two keys are a base
+     character followed by a code for the accent, while for other
+     special characters the two characters together form a mnemonic for
+     the character to be inserted.  The two-character codes are a
+     subset of those given by RFC 1345 (see for example
+     `http://www.faqs.org/rfcs/rfc1345.html').
+
+     The function may optionally be followed by up to two characters
+     which replace one or both of the characters read from the
+     keyboard; if both characters are supplied, no input is read.  For
+     example, insert-composed-char a: can be used within a widget to
+     insert an a with umlaut into the command line.  This has the
+     advantages over use of a literal character that it is more
+     portable.
+
+     For best results zsh should have been built with support for
+     multibyte characters (configured with -enable-multibyte); however,
+     the function works for the limited range of characters available
+     in single-byte character sets such as ISO-8859-1.
+
+     The character is converted into the local representation and
+     inserted into the command line at the cursor position.  (The
+     conversion is done within the shell, using whatever facilities the
+     C library provides.)  With a numeric argument, the character and
+     its code are previewed in the status line
+
+     The function may be run outside zle in which case it prints the
+     character (together with a newline) to standard output.  Input is
+     still read from keystrokes.
+
+     See insert-unicode-char for an alternative way of inserting Unicode
+     characters using their hexadecimal character number.
+
+     The set of accented characters is reasonably complete up to Unicode
+     character U+0180, the set of special characters less so.  However,
+     it is very sporadic from that point.  Adding new characters is
+     easy, however; see the function define-composed-chars.  Please
+     send any additions to zsh-workers@zsh.org.
+
+     The codes for the second character when used to accent the first
+     are as follows.  Note that not every character can take every
+     accent.
+    !
+          Grave.
+
+    '
+          Acute.
+
+    >
+          Circumflex.
+
+    ?
+          Tilde.  (This is not ~ as RFC 1345 does not assume that
+          character is present on the keyboard.)
+
+    -
+          Macron.  (A horizontal bar over the base character.)
+
+    (
+          Breve.  (A shallow dish shape over the base character.)
+
+    .
+          Dot above the base character, or in the case of i no dot, or
+          in the case of L and l a centered dot.
+
+    :
+          Diaeresis (Umlaut).
+
+    c
+          Cedilla.
+
+    _
+          Underline, however there are currently no underlined
+          characters.
+
+    /
+          Stroke through the base character.
+
+    "
+          Double acute (only supported on a few letters).
+
+    ;
+          Ogonek.  (A little forward facing hook at the bottom right of
+          the character.)
+
+    <
+          Caron.  (A little v over the letter.)
+
+    0
+          Circle over the base character.
+
+    2
+          Hook over the base character.
+
+    9
+          Horn over the base character.
+
+     The most common characters from the Arabic, Cyrillic, Greek and
+     Hebrew alphabets are available; consult RFC 1345 for the
+     appropriate sequences.  In addition, a set of two letter codes not
+     in RFC 1345 are available for the double-width characters
+     corresponding to ASCII characters from !  to ~ (0x21 to 0x7e) by
+     preceding the character with ^, for example ^A for a double-width
+     A.
+
+     The following other two-character sequences are understood.
+
+
+    ASCII characters
+          These are already present on most keyboards:
+         <(
+               Left square bracket
+
+         //
+               Backslash (solidus)
+
+         )>
+               Right square bracket
+
+         (!
+               Left brace (curly bracket)
+
+         !!
+               Vertical bar (pipe symbol)
+
+         !)
+               Right brace (curly bracket)
+
+         '?
+               Tilde
+
+    Special letters
+          Characters found in various variants of the Latin alphabet:
+         ss
+               Eszett (scharfes S)
+
+         D-, d-
+               Eth
+
+         TH, th
+               Thorn
+
+         kk
+               Kra
+
+         'n
+               'n
+
+         NG, ng
+               Ng
+
+         OI, oi
+               Oi
+
+         yr
+               yr
+
+         ED
+               ezh
+
+    Currency symbols
+
+         Ct
+               Cent
+
+         Pd
+               Pound sterling (also lira and others)
+
+         Cu
+               Currency
+
+         Ye
+               Yen
+
+         Eu
+               Euro (N.B. not in RFC 1345)
+
+    Punctuation characters
+          References to "right" quotes indicate the shape (like a 9
+          rather than 6) rather than their grammatical use.  (For
+          example, a "right" low double quote is used to open
+          quotations in German.)
+         !I
+               Inverted exclamation mark
+
+         BB
+               Broken vertical bar
+
+         SE
+               Section
+
+         Co
+               Copyright
+
+         -a
+               Spanish feminine ordinal indicator
+
+         <<
+               Left guillemet
+
+         --
+               Soft hyphen
+
+         Rg
+               Registered trade mark
+
+         PI
+               Pilcrow (paragraph)
+
+         -o
+               Spanish masculine ordinal indicator
+
+         >>
+               Right guillemet
+
+         ?I
+               Inverted question mark
+
+         -1
+               Hyphen
+
+         -N
+               En dash
+
+         -M
+               Em dash
+
+         -3
+               Horizontal bar
+
+         :3
+               Vertical ellipsis
+
+         .3
+               Horizontal midline ellipsis
+
+         !2
+               Double vertical line
+
+         =2
+               Double low line
+
+         '6
+               Left single quote
+
+         '9
+               Right single quote
+
+         .9
+               "Right" low quote
+
+         9'
+               Reversed "right" quote
+
+         "6
+               Left double quote
+
+         "9
+               Right double quote
+
+         :9
+               "Right" low double quote
+
+         9"
+               Reversed "right" double quote
+
+         /-
+               Dagger
+
+         /=
+               Double dagger
+
+    Mathematical symbols
+
+         DG
+               Degree
+
+         -2, +-, -+
+               - sign, +/- sign, -/+ sign
+
+         2S
+               Superscript 2
+
+         3S
+               Superscript 3
+
+         1S
+               Superscript 1
+
+         My
+               Micro
+
+         .M
+               Middle dot
+
+         14
+               Quarter
+
+         12
+               Half
+
+         34
+               Three quarters
+
+         *X
+               Multiplication
+
+         -:
+               Division
+
+         %0
+               Per mille
+
+         FA, TE, /0
+               For all, there exists, empty set
+
+         dP, DE, NB
+               Partial derivative, delta (increment), del (nabla)
+
+         (-, -)
+               Element of, contains
+
+         *P, +Z
+               Product, sum
+
+         *-, Ob, Sb
+               Asterisk, ring, bullet
+
+         RT, 0(, 00
+               Root sign, proportional to, infinity
+
+    Other symbols
+
+         cS, cH, cD, cC
+               Card suits: spades, hearts, diamonds, clubs
+
+         Md, M8, M2, Mb, Mx, MX
+               Musical notation: crotchet (quarter note), quaver
+               (eighth note), semiquavers (sixteenth notes), flag sign,
+               natural sign, sharp sign
+
+         Fm, Ml
+               Female, male
+
+    Accents on their own
+
+         '>
+               Circumflex (same as caret, ^)
+
+         '!
+               Grave (same as backtick, `)
+
+         ',
+               Cedilla
+
+         ':
+               Diaeresis (Umlaut)
+
+         'm
+               Macron
+
+         "
+               Acute
+
+
+insert-files
+     This function allows you type a file pattern, and see the results
+     of the expansion at each step.  When you hit return, all
+     expansions are inserted into the command line.
+
+
+          bindkey '^Xf' insert-files
+
+insert-unicode-char
+     When first executed, the user inputs a set of hexadecimal digits.
+     This is terminated with another call to insert-unicode-char.  The
+     digits are then turned into the corresponding Unicode character.
+     For example, if the widget is bound to ^XU, the character sequence
+     `^XU 4 c ^XU' inserts L (Unicode U+004c).
+
+     See insert-composed-char for a way of inserting characters using a
+     two-character mnemonic.
+
+narrow-to-region [ -p PRE ] [ -P POST ]
+                 [ -S STATEPM | -R STATEPM | [ -l LBUFVAR ] [ -r RBUFVAR ] ]
+                 [ -n ] [ START END ]
+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.
+
+     narrow-to-region may be used as a widget or called as a function
+     from a user-defined widget; by default, the text outside the
+     editable area remains visible.  A recursive-edit is performed and
+     the original widening status is then restored.  Various options
+     and arguments are available when it is called as a function.
+
+     The options -p PRETEXT and -P POSTTEXT may be used to replace the
+     text before and after the display for the duration of the
+     function; either or both may be an empty string.
+
+     If the option -n is also given, PRETEXT or POSTTEXT will only be
+     inserted if there is text before or after the region respectively
+     which will be made invisible.
+
+     Two numeric arguments may be given which will be used instead of
+     the cursor and mark positions.
+
+     The option -S STATEPM is used to narrow according to the other
+     options while saving the original state in the parameter with name
+     STATEPM, while the option -R STATEPM is used to restore the state
+     from the parameter; note in both cases the _name_ of the parameter
+     is required.  In the second case, other options and arguments are
+     irrelevant.  When this method is used, no recursive-edit is
+     performed; the calling widget should call this function with the
+     option -S, perform its own editing on the command line or pass
+     control to the user via `zle recursive-edit', then call this
+     function with the option -R.  The argument STATEPM must be a
+     suitable name for an ordinary parameter, except that parameters
+     beginning with the prefix _ntr_ are reserved for use within
+     narrow-to-region.  Typically the parameter will be local to the
+     calling function.
+
+     The options -l LBUFVAR and -r RBUFVAR may be used to specify
+     parameters where the widget will store the resulting text from the
+     operation.  The parameter LBUFVAR will contain LBUFFER and RBUFVAR
+     will contain RBUFFER.  Neither of these two options may be used
+     with -S or -R.
+
+     narrow-to-region-invisible is a simple widget which calls
+     narrow-to-region with arguments which replace any text outside the
+     region with `...'.  It does not take any arguments.
+
+     The display is restored (and the widget returns) upon any zle
+     command which would usually cause the line to be accepted or
+     aborted.  Hence an additional such command is required to accept
+     or abort the current line.
+
+     The return status of both widgets is zero if the line was
+     accepted, else non-zero.
+
+     Here is a trivial example of a widget using this feature.
+          local state
+          narrow-to-region -p $'Editing restricted region\n' \
+            -P '' -S state
+          zle recursive-edit
+          narrow-to-region -R state
+
+predict-on
+     This set of functions implements predictive typing using history
+     search.  After predict-on, typing characters causes the editor to
+     look backward in the history for the first line beginning with
+     what you have typed so far.  After predict-off, editing returns to
+     normal for the line found.  In fact, you often don't even need to
+     use predict-off, because if the line doesn't match something in
+     the history, adding a key performs standard completion, and then
+     inserts itself if no completions were found.  However, editing in
+     the middle of a line is liable to confuse prediction; see the
+     toggle style below.
+
+     With the function based completion system (which is needed for
+     this), you should be able to type TAB at almost any point to
+     advance the cursor to the next ``interesting'' character position
+     (usually the end of the current word, but sometimes somewhere in
+     the middle of the word).  And of course as soon as the entire line
+     is what you want, you can accept with return, without needing to
+     move the cursor to the end first.
+
+     The first time predict-on is used, it creates several additional
+     widget functions:
+
+
+    delete-backward-and-predict
+          Replaces the backward-delete-char widget.  You do not need to
+          bind this yourself.
+
+    insert-and-predict
+          Implements predictive typing by replacing the self-insert
+          widget.  You do not need to bind this yourself.
+
+    predict-off
+          Turns off predictive typing.
+
+     Although you autoload only the predict-on function, it is
+     necessary to create a keybinding for predict-off as well.
+
+
+          zle -N predict-on
+          zle -N predict-off
+          bindkey '^X^Z' predict-on
+          bindkey '^Z' predict-off
+
+read-from-minibuffer
+     This is most useful when called as a function from inside a
+     widget, but will work correctly as a widget in its own right.  It
+     prompts for a value below the current command line; a value may be
+     input using all of the standard zle operations (and not merely the
+     restricted set available when executing, for example,
+     execute-named-cmd).  The value is then returned to the calling
+     function in the parameter $REPLY and the editing buffer restored
+     to its previous state.  If the read was aborted by a keyboard
+     break (typically ^G), the function returns status 1 and $REPLY is
+     not set.
+
+     If one argument is supplied to the function it is taken as a
+     prompt, otherwise `? ' is used.  If two arguments are supplied,
+     they are the prompt and the initial value of $LBUFFER, and if a
+     third argument is given it is the initial value of $RBUFFER.  This
+     provides a default value and starting cursor placement.  Upon
+     return the entire buffer is the value of $REPLY.
+
+     One option is available: `-k NUM' specifies that NUM characters
+     are to be read instead of a whole line.  The line editor is not
+     invoked recursively in this case, so depending on the terminal
+     settings the input may not be visible, and only the input keys are
+     placed in $REPLY, not the entire buffer.  Note that unlike the
+     read builtin NUM must be given; there is no default.
+
+     The name is a slight misnomer, as in fact the shell's own
+     minibuffer is not used.  Hence it is still possible to call
+     executed-named-cmd and similar functions while reading a value.
+
+replace-argument, replace-argument-edit
+     The function replace-argument can be used to replace a command
+     line argument in the current command line or, if the current
+     command line is empty, in the last command line executed (the new
+     command line is not executed).  Arguments are as delimited by
+     standard shell syntax,
+
+     If a numeric argument is given, that specifies the argument to be
+     replaced.  0 means the command name, as in history expansion.  A
+     negative numeric argument counts backward from the last word.
+
+     If no numeric argument is given, the current argument is replaced;
+     this is the last argument if the previous history line is being
+     used.
+
+     The function prompts for a replacement argument.
+
+     If the widget contains the string edit, for example is defined as
+
+
+          zle -N replace-argument-edit replace-argument
+
+     then the function presents the current value of the argument for
+     editing, otherwise the editing buffer for the replacement is
+     initially empty.
+
+replace-string, replace-pattern
+replace-string-again, replace-pattern-again
+     The function replace-string implements three widgets.  If defined
+     under the same name as the function, it prompts for two strings;
+     the first (source) string will be replaced by the second
+     everywhere it occurs in the line editing buffer.
+
+     If the widget name contains the word `pattern', for example by
+     defining the widget using the command `zle -N replace-pattern
+     replace-string', then the matching is performed using zsh
+     patterns.  All zsh extended globbing patterns can be used in the
+     source string; note that unlike filename generation the pattern
+     does not need to match an entire word, nor do glob qualifiers have
+     any effect.  In addition, the replacement string can contain
+     parameter or command substitutions.  Furthermore, a `&' in the
+     replacement string will be replaced with the matched source
+     string, and a backquoted digit `\N' will be replaced by the Nth
+     parenthesised expression matched.  The form `\{N}' may be used to
+     protect the digit from following digits.
+
+     If the widget instead contains the word `regex' (or `regexp'),
+     then the matching is performed using regular expressions,
+     respecting the setting of the option RE_MATCH_PCRE (see the
+     description of the function regexp-replace below).  The special
+     replacement facilities described above for pattern matching are
+     available.
+
+     By default the previous source or replacement string will not be
+     offered for editing.  However, this feature can be activated by
+     setting the style edit-previous in the context :zle:WIDGET (for
+     example, :zle:replace-string) to true.  In addition, a positive
+     numeric argument forces the previous values to be offered, a
+     negative or zero argument forces them not to be.
+
+     The function replace-string-again can be used to repeat the
+     previous replacement; no prompting is done.  As with
+     replace-string, if the name of the widget contains the word
+     `pattern' or `regex', pattern or regular expression matching is
+     performed, else a literal string replacement.  Note that the
+     previous source and replacement text are the same whether pattern,
+     regular expression or string matching is used.
+
+     In addition, replace-string shows the previous replacement above
+     the prompt, so long as there was one during the current session;
+     if the source string is empty, that replacement will be repeated
+     without the widget prompting for a replacement string.
+
+     For example, starting from the line:
+
+
+          print This line contains fan and fond
+
+     and invoking replace-pattern with the source string `f(?)n' and
+     the replacement string `c\1r' produces the not very useful line:
+
+
+          print This line contains car and cord
+
+     The range of the replacement string can be limited by using the
+     narrow-to-region-invisible widget.  One limitation of the current
+     version is that undo will cycle through changes to the replacement
+     and source strings before undoing the replacement itself.
+
+send-invisible
+     This is similar to read-from-minibuffer in that it may be called
+     as a function from a widget or as a widget of its own, and
+     interactively reads input from the keyboard.  However, the input
+     being typed is concealed and a string of asterisks (`*') is shown
+     instead.  The value is saved in the parameter $INVISIBLE to which
+     a reference is inserted into the editing buffer at the restored
+     cursor position.  If the read was aborted by a keyboard break
+     (typically ^G) or another escape from editing such as push-line,
+     $INVISIBLE is set to empty and the original buffer is restored
+     unchanged.
+
+     If one argument is supplied to the function it is taken as a
+     prompt, otherwise `Non-echoed text: ' is used (as in emacs).  If a
+     second and third argument are supplied they are used to begin and
+     end the reference to $INVISIBLE that is inserted into the buffer.
+     The default is to open with ${, then INVISIBLE, and close with },
+     but many other effects are possible.
+
+smart-insert-last-word
+     This function may replace the insert-last-word widget, like so:
+
+
+          zle -N insert-last-word smart-insert-last-word
+
+     With a numeric argument, or when passed command line arguments in
+     a call from another widget, it behaves like insert-last-word,
+     except that words in comments are ignored when
+     INTERACTIVE_COMMENTS is set.
+
+     Otherwise, the rightmost ``interesting'' word from the previous
+     command is found and inserted.  The default definition of
+     ``interesting'' is that the word contains at least one alphabetic
+     character, slash, or backslash.  This definition may be overridden
+     by use of the match style.  The context used to look up the style
+     is the widget name, so usually the context is :insert-last-word.
+     However, you can bind this function to different widgets to use
+     different patterns:
+
+
+          zle -N insert-last-assignment smart-insert-last-word
+          zstyle :insert-last-assignment match '[[:alpha:]][][[:alnum:]]#=*'
+          bindkey '\e=' insert-last-assignment
+
+     If no interesting word is found and the auto-previous style is set
+     to a true value, the search continues upward through the history.
+     When auto-previous is unset or false (the default), the widget
+     must be invoked repeatedly in order to search earlier history
+     lines.
+
+transpose-lines
+     Only useful with a multi-line editing buffer; the lines here are
+     lines within the current on-screen buffer, not history lines.  The
+     effect is similar to the function of the same name in Emacs.
+
+     Transpose the current line with the previous line and move the
+     cursor to the start of the next line.  Repeating this (which can
+     be done by providing a positive numeric argument) has the effect
+     of moving the line above the cursor down by a number of lines.
+
+     With a negative numeric argument, requires two lines above the
+     cursor.  These two lines are transposed and the cursor moved to the
+     start of the previous line.  Using a numeric argument less than -1
+     has the effect of moving the line above the cursor up by minus that
+     number of lines.
+
+url-quote-magic
+     This widget replaces the built-in self-insert to make it easier to
+     type URLs as command line arguments.  As you type, the input
+     character is analyzed and, if it may need quoting, the current
+     word is checked for a URI scheme.  If one is found and the current
+     word is not already in quotes, a backslash is inserted before the
+     input character.
+
+     Styles to control quoting behavior:
+
+
+    url-metas
+          This style is looked up in the context
+          `:url-quote-magic:SCHEME' (where SCHEME is that of the
+          current URL, e.g. "ftp").  The value is a string listing the
+          characters to be treated as globbing metacharacters when
+          appearing in a URL using that scheme.  The default is to
+          quote all zsh extended globbing characters, excluding '<' and
+          '>' but including braces (as in brace expansion).  See also
+          url-seps.
+
+    url-seps
+          Like url-metas, but lists characters that should be
+          considered command separators, redirections, history
+          references, etc.  The default is to quote the standard set of
+          shell separators, excluding those that overlap with the
+          extended globbing characters, but including '<' and '>' and
+          the first character of $histchars.
+
+    url-globbers
+          This style is looked up in the context `:url-quote-magic'.
+          The values form a list of command names that are expected to
+          do their own globbing on the URL string.  This implies that
+          they are aliased to use the `noglob' modifier.  When the
+          first word on the line matches one of the values _and_ the
+          URL refers to a local file (see url-local-schema), only the
+          url-seps characters are quoted; the url-metas are left alone,
+          allowing them to affect command-line parsing, completion,
+          etc.  The default values are a literal `noglob' plus (when
+          the zsh/parameter module is available) any commands aliased
+          to the helper function `urlglobber' or its alias `globurl'.
+
+    url-local-schema
+          This style is always looked up in the context `:urlglobber',
+          even though it is used by both url-quote-magic and
+          urlglobber.  The values form a list of URI schema that should
+          be treated as referring to local files by their real local
+          path names, as opposed to files which are specified relative
+          to a web-server-defined document root.  The defaults are
+          "ftp" and "file".
+
+    url-other-schema
+          Like url-local-schema, but lists all other URI schema upon
+          which urlglobber and url-quote-magic should act.  If the URI
+          on the command line does not have a scheme appearing either
+          in this list or in url-local-schema, it is not magically
+          quoted.  The default values are "http", "https", and "ftp".
+          When a scheme appears both here and in url-local-schema, it
+          is quoted differently depending on whether the command name
+          appears in url-globbers.
+
+
+     Loading url-quote-magic also defines a helper function `urlglobber'
+     and aliases `globurl' to `noglob urlglobber'.  This function takes
+     a local URL apart, attempts to pattern-match the local file
+     portion of the URL path, and then puts the results back into URL
+     format again.
+
+vi-pipe
+     This function reads a movement command from the keyboard and then
+     prompts for an external command. The part of the buffer covered by
+     the movement is piped to the external command and then replaced by
+     the command's output. If the movement command is bound to vi-pipe,
+     the current line is used.
+
+     The function serves as an example for reading a vi movement command
+     from within a user-defined widget.
+
+which-command
+     This function is a drop-in replacement for the builtin widget
+     which-command.  It has enhanced behaviour, in that it correctly
+     detects whether or not the command word needs to be expanded as an
+     alias; if so, it continues tracing the command word from the
+     expanded alias until it reaches the command that will be executed.
+
+     The style whence is available in the context :zle:$WIDGET; this
+     may be set to an array to give the command and options that will
+     be used to investigate the command word found.  The default is
+     whence -c.
+
+zcalc-auto-insert
+     This function is useful together with the zcalc function described
+     in *Note Mathematical Functions::.  It should be bound to a key
+     representing a binary operator such as `+', `-', `*' or `/'.  When
+     running in zcalc, if the key occurs at the start of the line or
+     immediately following an open parenthesis, the text "ans " is
+     inserted before the representation of the key itself.  This allows
+     easy use of the answer from the previous calculation in the
+     current line.  The text to be inserted before the symbol typed can
+     be modified by setting the variable ZCALC_AUTO_INSERT_PREFIX.
+
+     Hence, for example, typing `+12' followed by return adds 12 to the
+     previous result.
+
+     If zcalc is in RPN mode (-r option) the effect of this binding is
+     automatically suppressed as operators alone on a line are
+     meaningful.
+
+     When not in zcalc, the key simply inserts the symbol itself.
+
+
+
+26.7.2 Utility Functions
+------------------------
+
+These functions are useful in constructing widgets.  They should be
+loaded with `autoload -U FUNCTION' and called as indicated from
+user-defined widgets.
+
+
+split-shell-arguments
+     This function splits the line currently being edited into shell
+     arguments and whitespace.  The result is stored in the array
+     reply.  The array contains all the parts of the line in order,
+     starting with any whitespace before the first argument, and
+     finishing with any whitespace after the last argument.  Hence (so
+     long as the option KSH_ARRAYS is not set) whitespace is given by
+     odd indices in the array and arguments by even indices.  Note that
+     no stripping of quotes is done; joining together all the elements
+     of reply in order is guaranteed to produce the original line.
+
+     The parameter REPLY is set to the index of the word in reply which
+     contains the character after the cursor, where the first element
+     has index 1.  The parameter REPLY2 is set to the index of the
+     character under the cursor in that word, where the first character
+     has index 1.
+
+     Hence reply, REPLY and REPLY2 should all be made local to the
+     enclosing function.
+
+     See the function modify-current-argument, described below, for an
+     example of how to call this function.
+
+modify-current-argument [ EXPR-USING-$ARG | FUNC ]
+     This function provides a simple method of allowing user-defined
+     widgets to modify the command line argument under the cursor (or
+     immediately to the left of the cursor if the cursor is between
+     arguments).
+
+     The argument can be an expression which when evaluated operates on
+     the shell parameter ARG, which will have been set to the command
+     line argument under the cursor.  The expression should be suitably
+     quoted to prevent it being evaluated too early.
+
+     Alternatively, if the argument does not contain the string ARG, it
+     is assumed to be a shell function, to which the current command
+     line argument is passed as the only argument.  The function should
+     set the variable REPLY to the new value for the command line
+     argument.  If the function returns non-zero status, so does the
+     calling function.
+
+     For example, a user-defined widget containing the following code
+     converts the characters in the argument under the cursor into all
+     upper case:
+
+
+          modify-current-argument '${(U)ARG}'
+
+     The following strips any quoting from the current word (whether
+     backslashes or one of the styles of quotes), and replaces it with
+     single quoting throughout:
+
+
+          modify-current-argument '${(qq)${(Q)ARG}}'
+
+     The following performs directory expansion on the command line
+     argument and replaces it by the absolute path:
+
+
+          expand-dir() {
+            REPLY=${~1}
+            REPLY=${REPLY:a}
+          }
+          modify-current-argument expand-dir
+
+     In practice the function expand-dir would probably not be defined
+     within the widget where modify-current-argument is called.
+
+
+
+26.7.3 Styles
+-------------
+
+The behavior of several of the above widgets can be controlled by the
+use of the zstyle mechanism.  In particular, widgets that interact with
+the completion system pass along their context to any completions that
+they invoke.
+
+
+break-keys
+     This style is used by the incremental-complete-word widget. Its
+     value should be a pattern, and all keys matching this pattern will
+     cause the widget to stop incremental completion without the key
+     having any further effect. Like all styles used directly by
+     incremental-complete-word, this style is looked up using the
+     context `:incremental'.
+
+completer
+     The incremental-complete-word and insert-and-predict widgets set
+     up their top-level context name before calling completion.  This
+     allows one to define different sets of completer functions for
+     normal completion and for these widgets.  For example, to use
+     completion, approximation and correction for normal completion,
+     completion and correction for incremental completion and only
+     completion for prediction one could use:
+
+
+          zstyle ':completion:*' completer \
+                  _complete _correct _approximate
+          zstyle ':completion:incremental:*' completer \
+                  _complete _correct
+          zstyle ':completion:predict:*' completer \
+                  _complete
+
+     It is a good idea to restrict the completers used in prediction,
+     because they may be automatically invoked as you type.  The _list
+     and _menu completers should never be used with prediction.  The
+     _approximate, _correct, _expand, and _match completers may be
+     used, but be aware that they may change characters anywhere in the
+     word behind the cursor, so you need to watch carefully that the
+     result is what you intended.
+
+cursor
+     The insert-and-predict widget uses this style, in the context
+     `:predict', to decide where to place the cursor after completion
+     has been tried.  Values are:
+
+
+    complete
+          The cursor is left where it was when completion finished, but
+          only if it is after a character equal to the one just
+          inserted by the user.  If it is after another character, this
+          value is the same as `key'.
+
+    key
+          The cursor is left after the Nth occurrence of the character
+          just inserted, where N is the number of times that character
+          appeared in the word before completion was attempted.  In
+          short, this has the effect of leaving the cursor after the
+          character just typed even if the completion code found out
+          that no other characters need to be inserted at that position.
+
+
+     Any other value for this style unconditionally leaves the cursor
+     at the position where the completion code left it.
+
+list
+     When using the incremental-complete-word widget, this style says
+     if the matches should be listed on every key press (if they fit on
+     the screen).  Use the context prefix `:completion:incremental'.
+
+     The insert-and-predict widget uses this style to decide if the
+     completion should be shown even if there is only one possible
+     completion.  This is done if the value of this style is the string
+     always.  In this case the context is `:predict' (_not_
+     `:completion:predict').
+
+match
+     This style is used by smart-insert-last-word to provide a pattern
+     (using full EXTENDED_GLOB syntax) that matches an interesting word.
+     The context is the name of the widget to which
+     smart-insert-last-word is bound (see above).  The default behavior
+     of smart-insert-last-word is equivalent to:
+
+
+          zstyle :insert-last-word match '*[[:alpha:]/\\]*'
+
+     However, you might want to include words that contain spaces:
+
+
+          zstyle :insert-last-word match '*[[:alpha:][:space:]/\\]*'
+
+     Or include numbers as long as the word is at least two characters
+     long:
+
+
+          zstyle :insert-last-word match '*([[:digit:]]?|[[:alpha:]/\\])*'
+
+     The above example causes redirections like "2>" to be included.
+
+prompt
+     The incremental-complete-word widget shows the value of this style
+     in the status line during incremental completion.  The string
+     value may contain any of the following substrings in the manner of
+     the PS1 and other prompt parameters:
+
+
+    %c
+          Replaced by the name of the completer function that generated
+          the matches (without the leading underscore).
+
+    %l
+          When the list style is set, replaced by `...' if the list of
+          matches is too long to fit on the screen and with an empty
+          string otherwise.  If the list style is `false' or not set,
+          `%l' is always removed.
+
+    %n
+          Replaced by the number of matches generated.
+
+    %s
+          Replaced by `-no match-', `-no prefix-', or an empty string
+          if there is no completion matching the word on the line, if
+          the matches have no common prefix different from the word on
+          the line, or if there is such a common prefix, respectively.
+
+    %u
+          Replaced by the unambiguous part of all matches, if there is
+          any, and if it is different from the word on the line.
+
+
+     Like `break-keys', this uses the `:incremental' context.
+
+stop-keys
+     This style is used by the incremental-complete-word widget.  Its
+     value is treated similarly to the one for the break-keys style
+     (and uses the same context: `:incremental').  However, in this
+     case all keys matching the pattern given as its value will stop
+     incremental completion and will then execute their usual function.
+
+toggle
+     This boolean style is used by predict-on and its related widgets in
+     the context `:predict'.  If set to one of the standard `true'
+     values, predictive typing is automatically toggled off in
+     situations where it is unlikely to be useful, such as when editing
+     a multi-line buffer or after moving into the middle of a line and
+     then deleting a character.  The default is to leave prediction
+     turned on until an explicit call to predict-off.
+
+verbose
+     This boolean style is used by predict-on and its related widgets in
+     the context `:predict'.  If set to one of the standard `true'
+     values, these widgets display a message below the prompt when the
+     predictive state is toggled.  This is most useful in combination
+     with the toggle style.  The default does not display these
+     messages.
+
+widget
+     This style is similar to the command style: For widget functions
+     that use zle to call other widgets, this style can sometimes be
+     used to override the widget which is called.  The context for this
+     style is the name of the calling widget (_not_ the name of the
+     calling function, because one function may be bound to multiple
+     widget names).
+
+
+          zstyle :copy-earlier-word widget smart-insert-last-word
+
+     Check the documentation for the calling widget or function to
+     determine whether the widget style is used.
+
+
+
+
+File: zsh.info,  Node: Exception Handling,  Next: MIME Functions,  Prev: ZLE Functions,  Up: User Contributions
+
+26.8 Exception Handling
+=======================
+
+Two functions are provided to enable zsh to provide exception handling
+in a form that should be familiar from other languages.
+
+
+throw EXCEPTION
+     The function throw throws the named EXCEPTION.  The name is an
+     arbitrary string and is only used by the throw and catch
+     functions.  An exception is for the most part treated the same as a
+     shell error, i.e. an unhandled exception will cause the shell to
+     abort all processing in a function or script and to return to the
+     top level in an interactive shell.
+
+catch EXCEPTION-PATTERN
+     The function catch returns status zero if an exception was thrown
+     and the pattern EXCEPTION-PATTERN matches its name.  Otherwise it
+     returns status 1.  EXCEPTION-PATTERN is a standard shell pattern,
+     respecting the current setting of the EXTENDED_GLOB option.  An
+     alias catch is also defined to prevent the argument to the
+     function from matching filenames, so patterns may be used
+     unquoted.  Note that as exceptions are not fundamentally different
+     from other shell errors it is possible to catch shell errors by
+     using an empty string as the exception name.  The shell variable
+     CAUGHT is set by catch to the name of the exception caught.  It is
+     possible to rethrow an exception by calling the throw function
+     again once an exception has been caught.  
+
+
+The functions are designed to be used together with the always construct
+described in *Note Complex Commands::.  This is important as only this
+construct provides the required support for exceptions.  A typical
+example is as follows.
+
+
+     {
+       # "try" block
+       # ... nested code here calls "throw MyExcept"
+     } always {
+       # "always" block
+       if catch MyExcept; then
+         print "Caught exception MyExcept"
+       elif catch ''; then
+         print "Caught a shell error.  Propagating..."
+         throw ''
+       fi
+       # Other exceptions are not handled but may be caught further
+       # up the call stack.
+     }
+
+If all exceptions should be caught, the following idiom might be
+preferable.
+
+
+     {
+       # ... nested code here throws an exception
+     } always {
+       if catch *; then
+         case $CAUGHT in
+           (MyExcept)
+           print "Caught my own exception"
+           ;;
+           (*)
+           print "Caught some other exception"
+           ;;
+         esac
+       fi
+     }
+
+In common with exception handling in other languages, the exception may
+be thrown by code deeply nested inside the `try' block.  However, note
+that it must be thrown inside the current shell, not in a subshell
+forked for a pipeline, parenthesised current-shell construct, or some
+form of command or process substitution.
+
+The system internally uses the shell variable EXCEPTION to record the
+name of the exception between throwing and catching.  One drawback of
+this scheme is that if the exception is not handled the variable
+EXCEPTION remains set and may be incorrectly recognised as the name of
+an exception if a shell error subsequently occurs.  Adding unset
+EXCEPTION at the start of the outermost layer of any code that uses
+exception handling will eliminate this problem.
+
+
+
+
+File: zsh.info,  Node: MIME Functions,  Next: Mathematical Functions,  Prev: Exception Handling,  Up: User Contributions
+
+26.9 MIME Functions
+===================
+
+Three functions are available to provide handling of files recognised by
+extension, for example to dispatch a file text.ps when executed as a
+command to an appropriate viewer.
+
+
+zsh-mime-setup [ -fv ] [ -l [ SUFFIX ... ] ]
+zsh-mime-handler [ -l ] COMMAND ARGUMENT ...
+     These two functions use the files ~/.mime.types and
+     /etc/mime.types, which associate types and extensions, as well as
+     ~/.mailcap and /etc/mailcap files, which associate types and the
+     programs that handle them.  These are provided on many systems
+     with the Multimedia Internet Mail Extensions.
+
+     To enable the system, the function zsh-mime-setup should be
+     autoloaded and run.  This allows files with extensions to be
+     treated as executable; such files be completed by the function
+     completion system.  The function zsh-mime-handler should not need
+     to be called by the user.
+
+     The system works by setting up suffix aliases with `alias -s'.
+     Suffix aliases already installed by the user will not be
+     overwritten.
+
+     For suffixes defined in lower case, upper case variants will also
+     automatically be handled (e.g. PDF is automatically handled if
+     handling for the suffix pdf is defined), but not vice versa.
+
+     Repeated calls to zsh-mime-setup do not override the existing
+     mapping between suffixes and executable files unless the option -f
+     is given.  Note, however, that this does not override existing
+     suffix aliases assigned to handlers other than zsh-mime-handler.
+
+     Calling zsh-mime-setup with the option -l lists the existing
+     mappings without altering them.  Suffixes to list (which may
+     contain pattern characters that should be quoted from immediate
+     interpretation on the command line) may be given as additional
+     arguments, otherwise all suffixes are listed.
+
+     Calling zsh-mime-setup with the option -v causes verbose output to
+     be shown during the setup operation.
+
+     The system respects the mailcap flags needsterminal and
+     copiousoutput, see man page mailcap(4).
+
+     The functions use the following styles, which are defined with the
+     zstyle builtin command (*Note The zsh/zutil Module::).  They
+     should be defined before zsh-mime-setup is run.  The contexts used
+     all start with :mime:, with additional components in some cases.
+     It is recommended that a trailing * (suitably quoted) be appended
+     to style patterns in case the system is extended in future.  Some
+     examples are given below.
+
+     For files that have multiple suffixes, e.g. .pdf.gz, where the
+     context includes the suffix it will be looked up starting with the
+     longest possible suffix until a match for the style is found.  For
+     example, if .pdf.gz produces a match for the handler, that will be
+     used; otherwise the handler for .gz will be used.  Note that,
+     owing to the way suffix aliases work, it is always required that
+     there be a handler for the shortest possible suffix, so in this
+     example .pdf.gz can only be handled if .gz is also handled (though
+     not necessarily in the same way).  Alternatively, if no handling
+     for .gz on its own is needed, simply adding the command
+
+
+          alias -s gz=zsh-mime-handler
+
+     to the initialisation code is sufficient; .gz will not be handled
+     on its own, but may be in combination with other suffixes.
+
+
+    current-shell
+          If this boolean style is true, the mailcap handler for the
+          context in question is run using the eval builtin instead of
+          by starting a new sh process.  This is more efficient, but
+          may not work in the occasional cases where the mailcap
+          handler uses strict POSIX syntax.
+
+    disown
+          If this boolean style is true, mailcap handlers started in the
+          background will be disowned, i.e. not subject to job control
+          within the parent shell.  Such handlers nearly always produce
+          their own windows, so the only likely harmful side effect of
+          setting the style is that it becomes harder to kill jobs from
+          within the shell.
+
+    execute-as-is
+          This style gives a list of patterns to be matched against
+          files passed for execution with a handler program.  If the
+          file matches the pattern, the entire command line is executed
+          in its current form, with no handler.  This is useful for
+          files which might have suffixes but nonetheless be executable
+          in their own right.  If the style is not set, the pattern
+          *(*) *(/) is used; hence executable files are executed
+          directly and not passed to a handler, and the option AUTO_CD
+          may be used to change to directories that happen to have MIME
+          suffixes.
+
+    execute-never
+          This style is useful in combination with execute-as-is.  It is
+          set to an array of patterns corresponding to full paths to
+          files that should never be treated as executable, even if the
+          file passed to the MIME handler matches execute-as-is.  This
+          is useful for file systems that don't handle execute
+          permission or that contain executables from another operating
+          system.  For example, if /mnt/windows is a Windows mount, then
+
+
+               zstyle ':mime:*' execute-never '/mnt/windows/*'
+
+          will ensure that any files found in that area will be
+          executed as MIME types even if they are executable.  As this
+          example shows, the complete file name is matched against the
+          pattern, regardless of how the file was passed to the
+          handler.  The file is resolved to a full path using the :P
+          modifier described in *Note Modifiers::; this means that
+          symbolic links are resolved where possible, so that links
+          into other file systems behave in the correct fashion.
+
+    file-path
+          Used if the style find-file-in-path is true for the same
+          context.  Set to an array of directories that are used for
+          searching for the file to be handled; the default is the
+          command path given by the special parameter path.  The shell
+          option PATH_DIRS is respected; if that is set, the
+          appropriate path will be searched even if the name of the
+          file to be handled as it appears on the command line contains
+          a `/'.  The full context is :mime:.SUFFIX:, as described for
+          the style handler.
+
+    find-file-in-path
+          If set, allows files whose names do not contain absolute paths
+          to be searched for in the command path or the path specified
+          by the file-path style.  If the file is not found in the
+          path, it is looked for locally (whether or not the current
+          directory is in the path); if it is not found locally, the
+          handler will abort unless the handle-nonexistent style is
+          set.  Files found in the path are tested as described for the
+          style execute-as-is.  The full context is :mime:.SUFFIX:, as
+          described for the style handler.
+
+    flags
+          Defines flags to go with a handler; the context is as for the
+          handler style, and the format is as for the flags in mailcap.
+
+    handle-nonexistent
+          By default, arguments that don't correspond to files are not
+          passed to the MIME handler in order to prevent it from
+          intercepting commands found in the path that happen to have
+          suffixes.  This style may be set to an array of extended glob
+          patterns for arguments that will be passed to the handler
+          even if they don't exist.  If it is not explicitly set it
+          defaults to [[:alpha:]]#:/* which allows URLs to be passed to
+          the MIME handler even though they don't exist in that format
+          in the file system.  The full context is :mime:.SUFFIX:, as
+          described for the style handler.
+
+    handler
+          Specifies a handler for a suffix; the suffix is given by the
+          context as :mime:.SUFFIX:, and the format of the handler is
+          exactly that in mailcap.  Note in particular the `.' and
+          trailing colon to distinguish this use of the context.  This
+          overrides any handler specified by the mailcap files.  If the
+          handler requires a terminal, the flags style should be set to
+          include the word needsterminal, or if the output is to be
+          displayed through a pager (but not if the handler is itself a
+          pager), it should include copiousoutput.
+
+    mailcap
+          A list of files in the format of ~/.mailcap and /etc/mailcap
+          to be read during setup, replacing the default list which
+          consists of those two files.  The context is :mime:.  A + in
+          the list will be replaced by the default files.
+
+    mailcap-priorities
+          This style is used to resolve multiple mailcap entries for
+          the same MIME type.  It consists of an array of the following
+          elements, in descending order of priority; later entries will
+          be used if earlier entries are unable to resolve the entries
+          being compared.  If none of the tests resolve the entries,
+          the first entry encountered is retained.
+
+
+         files
+               The order of files (entries in the mailcap style) read.
+               Earlier files are preferred.  (Note this does not
+               resolve entries in the same file.)
+
+         priority
+               The priority flag from the mailcap entry.  The priority
+               is an integer from 0 to 9 with the default value being 5.
+
+         flags
+               The test given by the mailcap-prio-flags option is used
+               to resolve entries.
+
+         place
+               Later entries are preferred; as the entries are strictly
+               ordered, this test always succeeds.
+
+
+          Note that as this style is handled during initialisation, the
+          context is always :mime:, with no discrimination by suffix.
+
+    mailcap-prio-flags
+          This style is used when the keyword flags is encountered in
+          the list of tests specified by the mailcap-priorities style.
+          It should be set to a list of patterns, each of which is
+          tested against the flags specified in the mailcap entry (in
+          other words, the sets of assignments found with some entries
+          in the mailcap file).  Earlier patterns in the list are
+          preferred to later ones, and matched patterns are preferred
+          to unmatched ones.
+
+    mime-types
+          A list of files in the format of ~/.mime.types and
+          /etc/mime.types to be read during setup, replacing the
+          default list which consists of those two files.  The context
+          is :mime:.  A + in the list will be replaced by the default
+          files.
+
+    never-background
+          If this boolean style is set, the handler for the given
+          context is always run in the foreground, even if the flags
+          provided in the mailcap entry suggest it need not be (for
+          example, it doesn't require a terminal).
+
+    pager
+          If set, will be used instead of $PAGER or more to handle
+          suffixes where the copiousoutput flag is set.  The context is
+          as for handler, i.e. :mime:.SUFFIX: for handling a file with
+          the given SUFFIX.
+
+
+     Examples:
+
+
+          zstyle ':mime:*' mailcap ~/.mailcap /usr/local/etc/mailcap
+          zstyle ':mime:.txt:' handler less %s
+          zstyle ':mime:.txt:' flags needsterminal
+
+     When zsh-mime-setup is subsequently run, it will look for mailcap
+     entries in the two files given.  Files of suffix .txt will be
+     handled by running `less FILE.TXT'.  The flag needsterminal is set
+     to show that this program must run attached to a terminal.
+
+     As there are several steps to dispatching a command, the following
+     should be checked if attempting to execute a file by extension
+     .EXT does not have the expected effect.
+
+     The command `alias -s EXT' should show `ps=zsh-mime-handler'.  If
+     it shows something else, another suffix alias was already
+     installed and was not overwritten.  If it shows nothing, no
+     handler was installed:  this is most likely because no handler was
+     found in the .mime.types and mailcap combination for .ext files.
+     In that case, appropriate handling should be added to
+     ~/.mime.types and mailcap.
+
+     If the extension is handled by zsh-mime-handler but the file is
+     not opened correctly, either the handler defined for the type is
+     incorrect, or the flags associated with it are in appropriate.
+     Running zsh-mime-setup -l will show the handler and, if there are
+     any, the flags.  A %s in the handler is replaced by the file
+     (suitably quoted if necessary).  Check that the handler program
+     listed lists and can be run in the way shown.  Also check that the
+     flags needsterminal or copiousoutput are set if the handler needs
+     to be run under a terminal; the second flag is used if the output
+     should be sent to a pager.  An example of a suitable mailcap entry
+     for such a program is:
+
+
+          text/html; /usr/bin/lynx '%s'; needsterminal
+
+     Running `zsh-mime-handler -l COMMAND LINE' prints the command line
+     that would be executed, simplified to remove the effect of any
+     flags, and quoted so that the output can be run as a complete zsh
+     command line.  This is used by the completion system to decide how
+     to complete after a file handled by zsh-mime-setup.
+
+pick-web-browser
+     This function is separate from the two MIME functions described
+     above and can be assigned directly to a suffix:
+
+
+          autoload -U pick-web-browser
+          alias -s html=pick-web-browser
+
+     It is provided as an intelligent front end to dispatch a web
+     browser.  It may be run as either a function or a shell script.
+     The status 255 is returned if no browser could be started.
+
+     Various styles are available to customize the choice of browsers:
+
+
+    browser-style
+          The value of the style is an array giving preferences in
+          decreasing order for the type of browser to use.  The values
+          of elements may be
+
+
+         running
+               Use a GUI browser that is already running when an X
+               Window display is available.  The browsers listed in the
+               x-browsers style are tried in order until one is found;
+               if it is, the file will be displayed in that browser, so
+               the user may need to check whether it has appeared.  If
+               no running browser is found, one is not started.
+               Browsers other than Firefox, Opera and Konqueror are
+               assumed to understand the Mozilla syntax for opening a
+               URL remotely.
+
+         x
+               Start a new GUI browser when an X Window display is
+               available.  Search for the availability of one of the
+               browsers listed in the x-browsers style and start the
+               first one that is found.  No check is made for an already
+               running browser.
+
+         tty
+               Start a terminal-based browser.  Search for the
+               availability of one of the browsers listed in the
+               tty-browsers style and start the first one that is found.
+
+
+          If the style is not set the default running x tty is used.
+
+    x-browsers
+          An array in decreasing order of preference of browsers to use
+          when running under the X Window System.  The array consists
+          of the command name under which to start the browser.  They
+          are looked up in the context :mime: (which may be extended in
+          future, so appending `*' is recommended).  For example,
+
+
+               zstyle ':mime:*' x-browsers opera konqueror firefox
+
+          specifies that pick-web-browser should first look for a
+          running instance of Opera, Konqueror or Firefox, in that
+          order, and if it fails to find any should attempt to start
+          Opera.  The default is firefox mozilla netscape opera
+          konqueror.
+
+    tty-browsers
+          An array similar to x-browsers, except that it gives browsers
+          to use when no X Window display is available.  The default is
+          elinks links lynx.
+
+    command
+          If it is set this style is used to pick the command used to
+          open a page for a browser.  The context is
+          :mime:browser:new:$browser: to start a new browser or
+          :mime:browser:running:$browser: to open a URL in a browser
+          already running on the current X display, where $browser is
+          the value matched in the x-browsers or tty-browsers style.
+          The escape sequence %b in the style's value will be replaced
+          by the browser, while %u will be replaced by the URL.  If the
+          style is not set, the default for all new instances is
+          equivalent to %b %u and the defaults for using running
+          browsers are equivalent to the values kfmclient openURL %u for
+          Konqueror, firefox -new-tab %u for Firefox, opera -newpage %u
+          for Opera, and %b -remote "openUrl(%u)" for all others.
+
+
+
+
+
+File: zsh.info,  Node: Mathematical Functions,  Next: User Configuration Functions,  Prev: MIME Functions,  Up: User Contributions
+
+26.10 Mathematical Functions
+============================
+
+
+zcalc [ -erf ] [ EXPRESSION ... ]
+     A reasonably powerful calculator based on zsh's arithmetic
+     evaluation facility.  The syntax is similar to that of formulae in
+     most programming languages; see *Note Arithmetic Evaluation:: for
+     details.
+
+     Non-programmers should note that, as in many other programming
+     languages, expressions involving only integers (whether constants
+     without a `.', variables containing such constants as strings, or
+     variables declared to be integers) are by default evaluated using
+     integer arithmetic, which is not how an ordinary desk calculator
+     operates.  To force floating point operation, pass the option -f;
+     see further notes below.
+
+     If the file ~/.zcalcrc exists it will be sourced inside the
+     function once it is set up and about to process the command line.
+     This can be used, for example, to set shell options; emulate -L zsh
+     and setopt extendedglob are in effect at this point.  Any failure
+     to source the file if it exists is treated as fatal.  As with
+     other initialisation files, the directory $ZDOTDIR is used instead
+     of $HOME if it is set.
+
+     The mathematical library zsh/mathfunc will be loaded if it is
+     available; see *Note The zsh/mathfunc Module::.  The mathematical
+     functions correspond to the raw system libraries, so trigonometric
+     functions are evaluated using radians, and so on.
+
+     Each line typed is evaluated as an expression.  The prompt shows a
+     number, which corresponds to a positional parameter where the
+     result of that calculation is stored.  For example, the result of
+     the calculation on the line preceded by `4> ' is available as $4.
+     The last value calculated is available as ans.  Full command line
+     editing, including the history of previous calculations, is
+     available; the history is saved in the file ~/.zcalc_history.  To
+     exit, enter a blank line or type `:q' on its own (`q' is allowed
+     for historical compatibility).
+
+     A line ending with a single backslash is treated in the same
+     fashion as it is in command line editing:  the backslash is
+     removed, the function prompts for more input (the prompt is
+     preceded by `...'  to indicate this), and the lines are combined
+     into one to get the final result.  In addition, if the input so
+     far contains more open than close parentheses zcalc will prompt
+     for more input.
+
+     If arguments are given to zcalc on start up, they are used to
+     prime the first few positional parameters.  A visual indication of
+     this is given when the calculator starts.
+
+     The constants PI (3.14159...) and E (2.71828...) are provided.
+     Parameter assignment is possible, but note that all parameters
+     will be put into the global namespace unless the :local special
+     command is used.  The function creates local variables whose names
+     start with _, so users should avoid doing so.  The variables ans
+     (the last answer) and stack (the stack in RPN mode) may be
+     referred to directly; stack is an array but elements of it are
+     numeric.  Various other special variables are used locally with
+     their standard meaning, for example compcontext, match, mbegin,
+     mend, psvar.
+
+     The output base can be initialised by passing the option `-#BASE',
+     for example `zcalc -#16' (the `#' may have to be quoted, depending
+     on the globbing options set).
+
+     If the option `-e' is set, the function runs non-interactively:
+     the arguments are treated as expressions to be evaluated as if
+     entered interactively line by line.
+
+     If the option `-f' is set, all numbers are treated as floating
+     point, hence for example the expression `3/4' evaluates to 0.75
+     rather than 0.  Options must appear in separate words.
+
+     If the option `-r' is set, RPN (Reverse Polish Notation) mode is
+     entered.  This has various additional properties:
+    Stack
+          Evaluated values are maintained in a stack; this is contained
+          in an array named stack with the most recent value in
+          ${stack[1]}.
+
+    Operators and functions
+          If the line entered matches an operator (+, -, *, /, **, ^, |
+          or &) or a function supplied by the zsh/mathfunc library, the
+          bottom element or elements of the stack are popped to use as
+          the argument or arguments.  The higher elements of stack
+          (least recent) are used as earlier arguments.  The result is
+          then pushed into ${stack[1]}.
+
+    Expressions
+          Other expressions are evaluated normally, printed, and added
+          to the stack as numeric values.  The syntax within
+          expressions on a single line is normal shell arithmetic (not
+          RPN).
+
+    Stack listing
+          If an integer follows the option -r with no space, then on
+          every evaluation that many elements of the stack, where
+          available, are printed instead of just the most recent
+          result.  Hence, for example, zcalc -r4 shows $stack[4] to
+          $stack[1] each time results are printed.
+
+    Duplication: =
+          The pseudo-operator = causes the most recent element of the
+          stack to be duplicated onto the stack.
+
+    pop
+          The pseudo-function pop causes the most recent element of the
+          stack to be popped.  A `>' on its own has the same effect.
+
+    >IDENT
+          The expression > followed (with no space) by a shell
+          identifier causes the most recent element of the stack to be
+          popped and assigned to the variable with that name.  The
+          variable is local to the zcalc function.
+
+    <IDENT
+          The expression < followed (with no space) by a shell
+          identifier causes the value of the variable with that name to
+          be pushed onto the stack.  IDENT may be an integer, in which
+          case the previous result with that number (as shown before
+          the > in the standard zcalc prompt) is put on the stack.
+
+    Exchange: xy
+          The pseudo-function xy causes the most recent two elements of
+          the stack to be exchanged.  `<>' has the same effect.
+
+
+     The prompt is configurable via the parameter ZCALCPROMPT, which
+     undergoes standard prompt expansion.  The index of the current
+     entry is stored locally in the first element of the array psvar,
+     which can be referred to in ZCALCPROMPT as `%1v'.  The default
+     prompt is `%1v> '.
+
+     The variable ZCALC_ACTIVE is set within the function and can be
+     tested by nested functions; it has the value rpn if RPN mode is
+     active, else 1.
+
+     A few special commands are available; these are introduced by a
+     colon.  For backward compatibility, the colon may be omitted for
+     certain commands.  Completion is available if compinit has been
+     run.
+
+     The output precision may be specified within zcalc by special
+     commands familiar from many calculators.
+    :norm
+          The default output format.  It corresponds to the printf %g
+          specification.  Typically this shows six decimal digits.
+
+    :sci DIGITS
+          Scientific notation, corresponding to the printf %g output
+          format with the precision given by DIGITS.  This produces
+          either fixed point or exponential notation depending on the
+          value output.
+
+    :fix DIGITS
+          Fixed point notation, corresponding to the printf %f output
+          format with the precision given by DIGITS.
+
+    :eng DIGITS
+          Exponential notation, corresponding to the printf %E output
+          format with the precision given by DIGITS.
+
+    :raw
+          Raw output:  this is the default form of the output from a
+          math evaluation.  This may show more precision than the
+          number actually possesses.
+
+
+     Other special commands:
+    :!LINE...
+          Execute LINE... as a normal shell command line.  Note that it
+          is executed in the context of the function, i.e. with local
+          variables.  Space is optional after :!.
+
+    :local ARG ...
+          Declare variables local to the function.  Other variables may
+          be used, too, but they will be taken from or put into the
+          global scope.
+
+    :function NAME [ BODY ]
+          Define a mathematical function or (with no BODY) delete it.
+          :function may be abbreviated to :func or simply :f.  The NAME
+          may contain the same characters as a shell function name.
+          The function is defined using zmathfuncdef, see below.
+
+          Note that zcalc takes care of all quoting.  Hence for example:
+
+
+               :f cube $1 * $1 * $1
+
+          defines a function to cube the sole argument.  Functions so
+          defined, or indeed any functions defined directly or
+          indirectly using functions -M, are available to execute by
+          typing only the name on the line in RPN mode; this pops the
+          appropriate number of arguments off the stack to pass to the
+          function, i.e. 1 in the case of the example cube function.
+          If there are optional arguments only the mandatory arguments
+          are supplied by this means.
+
+    [#BASE]
+          This is not a special command, rather part of normal
+          arithmetic syntax; however, when this form appears on a line
+          by itself the default output radix is set to BASE.  Use, for
+          example, `[#16]' to display hexadecimal output preceded by an
+          indication of the base, or `[##16]' just to display the raw
+          number in the given base.  Bases themselves are always
+          specified in decimal. `[#]' restores the normal output format.
+          Note that setting an output base suppresses floating point
+          output; use `[#]' to return to normal operation.
+
+    $VAR
+          Print out the value of var literally; does not affect the
+          calculation.  To use the value of var, omit the leading `$'.
+
+
+     See the comments in the function for a few extra tips.
+
+min(ARG, ...)
+max(ARG, ...)
+sum(ARG, ...)
+zmathfunc
+     The function zmathfunc defines the three mathematical functions
+     min, max, and sum.  The functions min and max take one or more
+     arguments.  The function sum takes zero or more arguments.
+     Arguments can be of different types (ints and floats).
+
+     Not to be confused with the zsh/mathfunc module, described in
+     *Note The zsh/mathfunc Module::.
+
+zmathfuncdef [ MATHFUNC [ BODY ] ]
+     A convenient front end to functions -M.
+
+     With two arguments, define a mathematical function named MATHFUNC
+     which can be used in any form of arithmetic evaluation.  BODY is a
+     mathematical expression to implement the function.  It may contain
+     references to position parameters $1, $2, ...  to refer to
+     mandatory parameters and ${1:-DEFVALUE} ...  to refer to optional
+     parameters.  Note that the forms must be strictly adhered to for
+     the function to calculate the correct number of arguments.  The
+     implementation is held in a shell function named
+     zsh_math_func_MATHFUNC; usually the user will not need to refer to
+     the shell function directly.  Any existing function of the same
+     name is silently replaced.
+
+     With one argument, remove the mathematical function MATHFUNC as
+     well as the shell function implementation.
+
+     With no arguments, list all MATHFUNC functions in a form suitable
+     for restoring the definition.  The functions have not necessarily
+     been defined by zmathfuncdef.
+
+
+
+
+File: zsh.info,  Node: User Configuration Functions,  Next: Other Functions,  Prev: Mathematical Functions,  Up: User Contributions
+
+26.11 User Configuration Functions
+==================================
+
+The zsh/newuser module comes with a function to aid in configuring
+shell options for new users.  If the module is installed, this function
+can also be run by hand.  It is available even if the module's default
+behaviour, namely running the function for a new user logging in without
+startup files, is inhibited.
+
+
+zsh-newuser-install [ -f ]
+     The function presents the user with various options for customizing
+     their initialization scripts.  Currently only ~/.zshrc is handled.
+     $ZDOTDIR/.zshrc is used instead if the parameter ZDOTDIR is set;
+     this provides a way for the user to configure a file without
+     altering an existing .zshrc.
+
+     By default the function exits immediately if it finds any of the
+     files .zshenv, .zprofile, .zshrc, or .zlogin in the appropriate
+     directory.  The option -f is required in order to force the
+     function to continue.  Note this may happen even if .zshrc itself
+     does not exist.
+
+     As currently configured, the function will exit immediately if the
+     user has root privileges; this behaviour cannot be overridden.
+
+     Once activated, the function's behaviour is supposed to be
+     self-explanatory.  Menus are present allowing the user to alter
+     the value of options and parameters.  Suggestions for improvements
+     are always welcome.
+
+     When the script exits, the user is given the opportunity to save
+     the new file or not; changes are not irreversible until this
+     point.  However, the script is careful to restrict changes to the
+     file only to a group marked by the lines `# Lines configured by
+     zsh-newuser-install' and `# End of lines configured by
+     zsh-newuser-install'.  In addition, the old version of .zshrc is
+     saved to a file with the suffix .zni appended.
+
+     If the function edits an existing .zshrc, it is up to the user to
+     ensure that the changes made will take effect.  For example, if
+     control usually returns early from the existing .zshrc the lines
+     will not be executed; or a later initialization file may override
+     options or parameters, and so on.  The function itself does not
+     attempt to detect any such conflicts.
+
+
+
+
+File: zsh.info,  Node: Other Functions,  Prev: User Configuration Functions,  Up: User Contributions
+
+26.12 Other Functions
+=====================
+
+There are a large number of helpful functions in the Functions/Misc
+directory of the zsh distribution.  Most are very simple and do not
+require documentation here, but a few are worthy of special mention.
+
+
+
+26.12.1 Descriptions
+--------------------
+
+
+colors
+     This function initializes several associative arrays to map color
+     names to (and from) the ANSI standard eight-color terminal codes.
+     These are used by the prompt theme system (*Note Prompt Themes::).
+     You seldom should need to run colors more than once.
+
+     The eight base colors are: black, red, green, yellow, blue,
+     magenta, cyan, and white.  Each of these has codes for foreground
+     and background.  In addition there are seven intensity attributes:
+     bold, faint, standout, underline, blink, reverse, and conceal.
+     Finally, there are seven codes used to negate attributes: none
+     (reset all attributes to the defaults), normal (neither bold nor
+     faint), no-standout, no-underline, no-blink, no-reverse, and
+     no-conceal.
+
+     Some terminals do not support all combinations of colors and
+     intensities.
+
+     The associative arrays are:
+
+
+    color
+    colour
+          Map all the color names to their integer codes, and integer
+          codes to the color names.  The eight base names map to the
+          foreground color codes, as do names prefixed with `fg-', such
+          as `fg-red'.  Names prefixed with `bg-', such as `bg-blue',
+          refer to the background codes.  The reverse mapping from code
+          to color yields base name for foreground codes and the bg-
+          form for backgrounds.
+
+          Although it is a misnomer to call them `colors', these arrays
+          also map the other fourteen attributes from names to codes
+          and codes to names.
+
+    fg
+    fg_bold
+    fg_no_bold
+          Map the eight basic color names to ANSI terminal escape
+          sequences that set the corresponding foreground text
+          properties.  The fg sequences change the color without
+          changing the eight intensity attributes.
+
+    bg
+    bg_bold
+    bg_no_bold
+          Map the eight basic color names to ANSI terminal escape
+          sequences that set the corresponding background properties.
+          The bg sequences change the color without changing the eight
+          intensity attributes.
+
+
+     In addition, the scalar parameters reset_color and bold_color are
+     set to the ANSI terminal escapes that turn off all attributes and
+     turn on bold intensity, respectively.
+
+fned [ -x NUM ] NAME
+     Same as zed -f.  This function does not appear in the zsh
+     distribution, but can be created by linking zed to the name fned
+     in some directory in your fpath.
+
+is-at-least NEEDED [ PRESENT ]
+     Perform a greater-than-or-equal-to comparison of two strings
+     having the format of a zsh version number; that is, a string of
+     numbers and text with segments separated by dots or dashes.  If
+     the PRESENT string is not provided, $ZSH_VERSION is used.
+     Segments are paired left-to-right in the two strings with leading
+     non-number parts ignored.  If one string has fewer segments than
+     the other, the missing segments are considered zero.
+
+     This is useful in startup files to set options and other state
+     that are not available in all versions of zsh.
+
+
+          is-at-least 3.1.6-15 && setopt NO_GLOBAL_RCS
+          is-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS
+          is-at-least 2.6-17 || print "You can't use is-at-least here."
+
+nslookup [ ARG ... ]
+     This wrapper function for the nslookup command requires the
+     zsh/zpty module (see *Note The zsh/zpty Module::).  It behaves
+     exactly like the standard nslookup except that it provides
+     customizable prompts (including a right-side prompt) and
+     completion of nslookup commands, host names, etc. (if you use the
+     function-based completion system).  Completion styles may be set
+     with the context prefix `:completion:nslookup'.
+
+     See also the pager, prompt and rprompt styles below.
+
+regexp-replace VAR REGEXP REPLACE
+     Use regular expressions to perform a global search and replace
+     operation on a variable.  POSIX extended regular expressions are
+     used, unless the option RE_MATCH_PCRE has been set, in which case
+     Perl-compatible regular expressions are used (this requires the
+     shell to be linked against the pcre library).
+
+     VAR is the name of the variable containing the string to be
+     matched.  The variable will be modified directly by the function.
+     The variables MATCH, MBEGIN, MEND, match, mbegin, mend should be
+     avoided as these are used by the regular expression code.
+
+     REGEXP is the regular expression to match against the string.
+
+     REPLACE is the replacement text.  This can contain parameter,
+     command and arithmetic expressions which will be replaced:  in
+     particular, a reference to $MATCH will be replaced by the text
+     matched by the pattern.
+
+     The return status is 0 if at least one match was performed, else 1.
+
+run-help CMD
+     This function is designed to be invoked by the run-help ZLE widget,
+     in place of the default alias.  See `Accessing On-Line Help'
+     (*Note Utilities::) for setup instructions.
+
+     In the discussion which follows, if CMD is a file system path, it
+     is first reduced to its rightmost component (the file name).
+
+     Help is first sought by looking for a file named CMD in the
+     directory named by the HELPDIR parameter.  If no file is found, an
+     assistant function, alias, or command named run-help-CMD is
+     sought.  If found, the assistant is executed with the rest of the
+     current command line (everything after the command name CMD) as
+     its arguments.  When neither file nor assistant is found, the
+     external command `man CMD' is run.
+
+     An example assistant for the "ssh" command:
+
+
+          run-help-ssh() {
+              emulate -LR zsh
+              local -a args
+              # Delete the "-l username" option
+              zparseopts -D -E -a args l:
+              # Delete other options, leaving: host command
+              args=(${@:#-*})
+              if [[ ${#args} -lt 2 ]]; then
+                  man ssh
+              else
+                  run-help $args[2]
+              fi
+          }
+
+     Several of these assistants are provided in the Functions/Misc
+     directory.  These must be autoloaded, or placed as executable
+     scripts in your search path, in order to be found and used by
+     run-help.
+
+
+    run-help-git
+    run-help-ip
+    run-help-openssl
+    run-help-p4
+    run-help-sudo
+    run-help-svk
+    run-help-svn
+          Assistant functions for the git, ip, openssl, p4, sudo, svk,
+          and svn, commands.
+
+
+tetris
+     Zsh was once accused of not being as complete as Emacs, because it
+     lacked a Tetris game.  This function was written to refute this
+     vicious slander.
+
+     This function must be used as a ZLE widget:
+
+
+          autoload -U tetris
+          zle -N tetris
+          bindkey KEYS tetris
+
+     To start a game, execute the widget by typing the KEYS.  Whatever
+     command line you were editing disappears temporarily, and your
+     keymap is also temporarily replaced by the Tetris control keys.
+     The previous editor state is restored when you quit the game (by
+     pressing `q') or when you lose.
+
+     If you quit in the middle of a game, the next invocation of the
+     tetris widget will continue where you left off.  If you lost, it
+     will start a new game.
+
+tetriscurses
+     This is a port of the above to zcurses.  The input handling is
+     improved a bit so that moving a block sideways doesn't
+     automatically advance a timestep, and the graphics use unicode
+     block graphics.
+
+     This version does not save the game state between invocations, and
+     is not invoked as a widget, but rather as:
+
+
+          autoload -U tetriscurses
+          tetriscurses
+
+zargs [ OPTION ... -- ] [ INPUT ... ] [ -- COMMAND [ ARG ... ] ]
+     This function has a similar purpose to GNU xargs.  Instead of
+     reading lines of arguments from the standard input, it takes them
+     from the command line.  This is useful because zsh, especially
+     with recursive glob operators, often can construct a command line
+     for a shell function that is longer than can be accepted by an
+     external command.
+
+     The OPTION list represents options of the zargs command itself,
+     which are the same as those of xargs.  The INPUT list is the
+     collection of strings (often file names) that become the arguments
+     of the command, analogous to the standard input of xargs.
+     Finally, the ARG list consists of those arguments (usually
+     options) that are passed to the COMMAND each time it runs.  The
+     ARG list precedes the elements from the input list in each run.
+     If no COMMAND is provided, then no ARG list may be provided, and
+     in that event the default command is `print' with arguments `-r
+     --'.
+
+     For example, to get a long ls listing of all non-hidden plain files
+     in the current directory or its subdirectories:
+
+
+          autoload -U zargs
+          zargs -- **/*(.) -- ls -ld --
+
+     The first and third occurrences of `--' are used to mark the end
+     of options for zargs and ls respectively to guard against
+     filenames starting with `-', while the second is used to separate
+     the list of files from the command to run (`ls -ld -').
+
+     The first `--' would also be needed if there was a chance the list
+     might be empty as in:
+
+
+          zargs -r -- ./*.back(#qN) -- rm -f
+
+     In the event that the string `--' is or may be an INPUT, the -e
+     option may be used to change the end-of-inputs marker.  Note that
+     this does _not_ change the end-of-options marker.  For example, to
+     use `..' as the marker:
+
+
+          zargs -e.. -- **/*(.) .. ls -ld --
+
+     This is a good choice in that example because no plain file can be
+     named `..', but the best end-marker depends on the circumstances.
+
+     The options -i, -I, -l, -L, and -n differ slightly from their
+     usage in xargs.  There are no input lines for zargs to count, so
+     -l and -L count through the INPUT list, and -n counts the number
+     of arguments passed to each execution of COMMAND, _including_ any
+     ARG list.  Also, any time -i or -I is used, each INPUT is
+     processed separately as if by `-L 1'.
+
+     For details of the other zargs options, see man page xargs(1) (but
+     note the difference in function between zargs and xargs) or run
+     zargs with the --help option.
+
+zed [ -f [ -x NUM ] ] NAME
+zed -b
+     This function uses the ZLE editor to edit a file or function.
+
+     Only one NAME argument is allowed.  If the -f option is given, the
+     name is taken to be that of a function; if the function is marked
+     for autoloading, zed searches for it in the fpath and loads it.
+     Note that functions edited this way are installed into the current
+     shell, but _not_ written back to the autoload file.  In this case
+     the -x option specifies that leading tabs indenting the function
+     according to syntax should be converted into the given number of
+     spaces; `-x 2' is consistent with the layout of functions
+     distributed with the shell.
+
+     Without -f, NAME is the path name of the file to edit, which need
+     not exist; it is created on write, if necessary.
+
+     While editing, the function sets the main keymap to zed and the vi
+     command keymap to zed-vicmd.  These will be copied from the
+     existing main and vicmd keymaps if they do not exist the first
+     time zed is run.  They can be used to provide special key bindings
+     used only in zed.
+
+     If it creates the keymap, zed rebinds the return key to insert a
+     line break and `^X^W' to accept the edit in the zed keymap, and
+     binds `ZZ' to accept the edit in the zed-vicmd keymap.
+
+     The bindings alone can be installed by running `zed -b'.  This is
+     suitable for putting into a startup file.  Note that, if rerun,
+     this will overwrite the existing zed and zed-vicmd keymaps.
+
+     Completion is available, and styles may be set with the context
+     prefix `:completion:zed'.
+
+     A zle widget zed-set-file-name is available.  This can be called by
+     name from within zed using `\ex zed-set-file-name' (note, however,
+     that because of zed's rebindings you will have to type ^j at the
+     end instead of the return key), or can be bound to a key in either
+     of the zed or zed-vicmd keymaps after `zed -b' has been run.  When
+     the widget is called, it prompts for a new name for the file being
+     edited.  When zed exits the file will be written under that name
+     and the original file will be left alone.  The widget has no
+     effect with `zed -f'.
+
+     While zed-set-file-name is running, zed uses the keymap
+     zed-normal-keymap, which is linked from the main keymap in effect
+     at the time zed initialised its bindings.  (This is to make the
+     return key operate normally.)  The result is that if the main
+     keymap has been changed, the widget won't notice.  This is not a
+     concern for most users.
+
+zcp [ -finqQvwW ] SRCPAT DEST
+zln [ -finqQsvwW ] SRCPAT DEST
+     Same as zmv -C and zmv -L, respectively.  These functions do not
+     appear in the zsh distribution, but can be created by linking zmv
+     to the names zcp and zln in some directory in your fpath.
+
+zkbd
+     See `Keyboard Definition' (*Note Utilities::).
+
+zmv [ -finqQsvwW ] [ -C | -L | -M | -{p|P} PROGRAM ] [ -o OPTSTRING ]
+    SRCPAT DEST
+     Move (usually, rename) files matching the pattern SRCPAT to
+     corresponding files having names of the form given by DEST, where
+     SRCPAT contains parentheses surrounding patterns which will be
+     replaced in turn by $1, $2, ... in DEST.  For example,
+
+
+          zmv '(*).lis' '$1.txt'
+
+     renames `foo.lis' to `foo.txt', `my.old.stuff.lis' to
+     `my.old.stuff.txt', and so on.
+
+     The pattern is always treated as an EXTENDED_GLOB pattern.  Any
+     file whose name is not changed by the substitution is simply
+     ignored.  Any error (a substitution resulted in an empty string,
+     two substitutions gave the same result, the destination was an
+     existing regular file and -f was not given) causes the entire
+     function to abort without doing anything.
+
+     In addition to pattern replacement, the variable $f can be
+     referrred to in the second (replacement) argument.  This makes it
+     possible to use variable substitution to alter the argument; see
+     examples below.
+
+     Options:
+
+
+    -f
+          Force overwriting of destination files.  Not currently passed
+          down to the mv/cp/ln command due to vagaries of
+          implementations (but you can use -o-f to do that).
+
+    -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 skip it.  Note that you just need to type one
+          character.
+
+    -n
+          No execution: print what would happen, but don't do it.
+
+    -q
+          Turn bare glob qualifiers off: now assumed by default, so
+          this has no effect.
+
+    -Q
+          Force bare glob qualifiers on.  Don't turn this on unless you
+          are actually using glob qualifiers in a pattern.
+
+    -s
+          Symbolic, passed down to ln; only works with -L.
+
+    -v
+          Verbose: print each command as it's being executed.
+
+    -w
+          Pick out wildcard parts of the pattern, as described above,
+          and implicitly add parentheses for referring to them.
+
+    -W
+          Just like -w, with the addition of turning wildcards in the
+          replacement pattern into sequential ${1} .. ${N} references.
+
+    -C
+    -L
+    -M
+          Force cp, ln or mv, respectively, regardless of the name of
+          the function.
+
+    -p PROGRAM
+          Call PROGRAM instead of cp, ln or mv.  Whatever it does, it
+          should at least understand the form
+               PROGRAM -- OLDNAME NEWNAME
+          where OLDNAME and NEWNAME are filenames generated by zmv.
+          PROGRAM will be split into words, so might be e.g. the name
+          of an archive tool plus a copy or rename subcommand.
+
+    -P PROGRAM
+          As -p PROGRAM, except that PROGRAM does not accept a
+          following -- to indicate the end of options.  In this case
+          filenames must already be in a sane form for the program in
+          question.
+
+    -o OPTSTRING
+          The OPTSTRING is split into words and passed down verbatim to
+          the cp, ln or mv command called to perform the work.  It
+          should probably begin with a `-'.
+
+     Further examples:
+
+
+          zmv -v '(* *)' '${1// /_}'
+
+     For any file in the current directory with at least one space in
+     the name, replace every space by an underscore and display the
+     commands executed.
+
+
+          zmv -v '* *' '${f// /_}'
+
+     This does exactly the same by referring to the file name stored in
+     $f.
+
+     For more complete examples and other implementation details, see
+     the zmv source file, usually located in one of the directories
+     named in your fpath, or in Functions/Misc/zmv in the zsh
+     distribution.
+
+zrecompile
+     See `Recompiling Functions' (*Note Utilities::).
+
+zstyle+ CONTEXT STYLE VALUE [ + SUBCONTEXT STYLE VALUE ... ]
+     This makes defining styles a bit simpler by using a single `+' as a
+     special token that allows you to append a context name to the
+     previously used context name.  Like this:
+
+
+          zstyle+ ':foo:bar' STYLE1 VALUE1 \
+                 +':baz'     STYLE2 VALUE2 \
+                 +':frob'    STYLE3 VALUE3
+
+     This defines STYLE1 with VALUE1 for the context :foo:bar as usual,
+     but it also defines STYLE2 with VALUE2 for the context
+     :foo:bar:baz and STYLE3 with VALUE3 for :foo:bar:frob.  Any
+     SUBCONTEXT may be the empty string to re-use the first context
+     unchanged.
+
+
+
+26.12.2 Styles
+--------------
+
+
+insert-tab
+     The zed function _sets_ this style in context `:completion:zed:*'
+     to turn off completion when TAB is typed at the beginning of a
+     line.  You may override this by setting your own value for this
+     context and style.
+
+pager
+     The nslookup function looks up this style in the context
+     `:nslookup' to determine the program used to display output that
+     does not fit on a single screen.
+
+prompt
+rprompt
+     The nslookup function looks up this style in the context
+     `:nslookup' to set the prompt and the right-side prompt,
+     respectively.  The usual expansions for the PS1 and RPS1
+     parameters may be used (see *Note Prompt Expansion::).
+
+