6 files changed, 163 insertions, 3 deletions
diff --git a/Doc/Zsh/.distfiles b/Doc/Zsh/.distfiles
index 9b529885d..5961f6201 100644
--- a/Doc/Zsh/.distfiles
+++ b/Doc/Zsh/.distfiles
@@ -12,6 +12,7 @@ DISTFILES_SRC='
     mod_terminfo.yo mod_zftp.yo mod_zle.yo mod_zleparameter.yo
     mod_zselect.yo mod_zutil.yo mod_zprof.yo mod_zpty.yo
     modules.yo modlist.yo modmenu.yo manmodmenu.yo
-    options.yo params.yo prompt.yo redirect.yo restricted.yo seealso.yo
+    options.yo params.yo prompt.yo redirect.yo restricted.yo
+    roadmap.yo seealso.yo
     zftpsys.yo zle.yo contrib.yo tcpsys.yo
 '
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 9baee7a1b..71980180e 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -671,6 +671,13 @@ 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 tt(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,
+tt(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 tt(--enable-multibyte)); however, the function
 works for the limited range of characters available in single-byte
diff --git a/Doc/Zsh/intro.yo b/Doc/Zsh/intro.yo
index be2bd6acf..065f53b0e 100644
--- a/Doc/Zsh/intro.yo
+++ b/Doc/Zsh/intro.yo
@@ -1,4 +1,4 @@
-texinode(Introduction)(Invocation)(The Z Shell Manual)(Top)
+texinode(Introduction)(Roadmap)(The Z Shell Manual)(Top)
 chapter(Introduction)
 cindex(introduction)
 ifzman(\
@@ -15,6 +15,7 @@ startlist()
 ifzshone(\
 list(em(zsh)          Zsh overview (this section))
 )\
+list(em(zshroadmap)   Informal introduction to the manual)
 list(em(zshmisc)      Anything not fitting into the other sections)
 list(em(zshexpn)      Zsh command and parameter expansion)
 list(em(zshparam)     Zsh parameters)
diff --git a/Doc/Zsh/invoke.yo b/Doc/Zsh/invoke.yo
index 1701c4149..01e9b00e6 100644
--- a/Doc/Zsh/invoke.yo
+++ b/Doc/Zsh/invoke.yo
@@ -1,4 +1,4 @@
-texinode(Invocation)(Files)(Introduction)(Top)
+texinode(Invocation)(Files)(Roadmap)(Top)
 chapter(Invocation)
 cindex(invocation)
 sect(Invocation Options)
diff --git a/Doc/Zsh/manual.yo b/Doc/Zsh/manual.yo
index 9fb81d99a..9820f1f23 100644
--- a/Doc/Zsh/manual.yo
+++ b/Doc/Zsh/manual.yo
@@ -14,6 +14,7 @@ Version version(), last updated date().
 startmenu()
 menu(The Z Shell Manual)
 menu(Introduction)
+menu(Roadmap)
 menu(Invocation)
 menu(Files)
 menu(Shell Grammar)
diff --git a/Doc/Zsh/roadmap.yo b/Doc/Zsh/roadmap.yo
new file mode 100644
index 000000000..ad4c679e1
--- /dev/null
+++ b/Doc/Zsh/roadmap.yo
@@ -0,0 +1,150 @@
+texinode(Roadmap)(Invocation)(Introduction)(Top)
+chapter(Roadmap)
+cindex(roadmap)
+
+The Zsh Manual, like the shell itself, is large and often complicated.
+This section of the manual provides some pointers to areas of the shell
+that are likely to be of particular interest to new users, and indicates
+where in the rest of the manual the documentation is to found.
+
+sect(When the shell starts)
+
+When it starts, the shell reads commands from various files.  These can
+be created or edited to customize the shell.  See ifzman(the section
+Startup/Shutdown Files in zmanref(zsh))\
+ifnzman(noderef(Files)).
+
+sect(Interactive use)
+
+Interaction with the shell uses the builtin Zsh Line Editor, ZLE.  This is
+described in detail in ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor)).
+
+The first decision a user must make is whether to use the Emacs or Vi
+editing mode as the keys for editing are substantially different.  Emacs
+editing mode is probably more natural for beginners and can be selected
+explicitly with the command tt(bindkey -e).
+
+A history mechanism for retrieving previously typed lines (most simply with
+the Up or Down arrow keys) is available; note that, unlike other shells,
+zsh will not save these lines when the shell exits unless you set
+appropriate variables.  See the description of the shell variables
+(referred to in the documentation as parameters) tt(HISTFILE), tt(HISTSIZE)
+and tt(SAVEHIST) in ifzman(zmanref(zshparams))\
+ifnzman(noderef(Parameters Used By The Shell)).
+
+The line editor provides an extensive completion system and the shell
+is supplied for completions with many commonly used commands.  Note
+that the new completion system referred to as tt(compsys) is preferred
+over the older tt(compctl) system.  The completion system must be enabled
+explicitly when the shell starts.  For more information see
+ifzman(zmanref(zshcompssy))\
+ifnzman(noderef(Completion System)).
+
+Apart from completion, the line editor is highly extensible by means of
+shell functions.  Some useful functions are provided with the shell; they
+provide facilities such as:
+
+startitem()
+item(tt(insert-composed-char))(
+composing characters not found on the keyboard
+)
+item(tt(match-words-by-style))(
+configuring what the line editor considers a word when moving or
+deleting by word
+)
+item(tt(history-beginning-search-backward-end), etc.)(
+alternative ways of searching the shell history
+)
+item(tt(replace-string), tt(replace-pattern))(
+functions for replacing strings or patterns globally in the command line.
+)
+enditem()
+
+See ifzman(the section `ZLE Functions' in zmanref(zshcontrib))\
+ifnzman(noderef(ZLE Functions)) for descriptions of these.
+
+sect(Options)
+
+The shell has a large number of options for changing its behaviour.
+These cover all aspects of the shell; browsing the full documentation is
+the only good way to become acquainted with the many possibilities.  See
+ifzman(zmanref(zshoptions))\
+ifnzman(noderef(Options)).
+
+sect(Pattern matching)
+
+The shell has a rich set of patterns which are available for file matching
+(described in the documentation as `filename generation' and also known for
+historical reasons as `globbing') and for use when programming.  These are
+described in ifzman(the section `Filename Generation' in zmanref(zshexpn))\
+ifnzman(noderef(Filename Generation)).
+
+Of particular interest are the following patterns that are not commonly
+supported by other systems of pattern matching:
+
+startitem()
+item(tt(**))(
+for matching over multiple directories
+)
+item(tt(~), tt(^))(
+the ability to exclude patterns from matching when the tt(EXTENDED_GLOB)
+option is set
+)
+item(tt(LPAR())var(...)tt(RPAR()))(
+glob qualifiers, included in parentheses at the end of the pattern,
+which select files by type (such as directories) or attribute (such as
+size).
+)
+enditem()
+
+sect(General Comments on Syntax)
+
+Although the syntax of zsh is in ways similar to the Korn shell, and
+therefore more remotely to the original UNIX shell, the Bourne shell,
+its default behaviour does not entirely correspond to those shells.
+General shell syntax is introduced in ifzman(the section `Shell Grammar' in
+zmanref(zshmisc))\
+ifnzman(noderef(Shell Grammar)).
+
+One commonly encountered difference is that variables (other than arrays, a
+particular type of variable) substituted onto the command line are not
+split into words.  See the description of the shell option
+tt(SH_WORD_SPLIT) in ifzman(the section `Parameter Expansion' in
+zmanref(zshexpn))\
+ifnzman(noderef(Parameter Expansion)).
+
+sect(Programming)
+
+The most convenient way of adding enhancements to the shell is typically
+by writing a shell function and arranging for it to be autoloaded.
+Functions are described in ifzman(the section `Functions' in
+zmanref(zshmisc))\
+ifnzman(noderef(Functions)).
+
+A few general functions, other than those for the line editor described
+above, are provided with the shell and are described in
+ifzman(zmanref(zshcontrib))\
+ifnzman(noderef(User Contributions)).  Features include:
+
+startitem()
+item(tt(promptinit))(
+a prompt theme system for changing prompts easily, see ifzman(the section
+`Prompt Themes'
+)\
+ifnzman(noderef(Prompt Themes))
+)
+item(tt(zsh-mime-setup))(
+a MIME-handling system which dispatches commands according to the suffix of
+a file as done by graphical file managers
+)
+item(tt(zcalc))(
+a calculator
+)
+item(tt(zargs))(
+a version of tt(xargs) that makes the tt(find) command redundant
+)
+item(tt(zmv))(
+a command for renaming files with patterns.
+)
+enditem()