10 files changed, 175 insertions, 7 deletions
diff --git a/Doc/.distfiles b/Doc/.distfiles
index 18ac5272b..6a0c44e3d 100644
--- a/Doc/.distfiles
+++ b/Doc/.distfiles
@@ -4,11 +4,11 @@ DISTFILES_SRC='
     version.yo zmacros.yo zman.yo ztexi.yo
     zsh.yo zshbuiltins.yo zshcompctl.yo zshcompsys.yo zshcompwid.yo
     zshexpn.yo zshmisc.yo zshmodules.yo zshoptions.yo zshparam.yo
-    zshzftpsys.yo zshzle.yo zshcontrib.yo zshtcpsys.yo
+    zshroadmap.yo zshzftpsys.yo zshzle.yo zshcontrib.yo zshtcpsys.yo
     zsh.texi
     zsh.1 zshbuiltins.1 zshcompctl.1 zshcompsys.1 zshcompwid.1 zshexpn.1
-    zshmisc.1 zshmodules.1 zshoptions.1 zshparam.1 zshzle.1 zshall.1
-    zshzftpsys.1 zshcontrib.1 zshtcpsys.1
+    zshmisc.1 zshmodules.1 zshoptions.1 zshparam.1 zshroadmap.1
+    zshzle.1 zshall.1 zshzftpsys.1 zshcontrib.1 zshtcpsys.1
 '
 
 DISTFILES_DOC='
diff --git a/Doc/Makefile.in b/Doc/Makefile.in
index 414ef4b28..998085c30 100644
--- a/Doc/Makefile.in
+++ b/Doc/Makefile.in
@@ -47,7 +47,8 @@ TEXI2HTML = texi2html --output . --ifinfo --split=chapter
 # man pages to install
 MAN = zsh.1 zshbuiltins.1 zshcompctl.1 zshcompwid.1 zshcompsys.1 \
 zshcontrib.1 zshexpn.1 zshmisc.1 zshmodules.1 \
-zshoptions.1 zshparam.1 zshtcpsys.1 zshzftpsys.1 zshzle.1 zshall.1
+zshoptions.1 zshparam.1 zshroadmap.1 zshtcpsys.1 zshzftpsys.1 zshzle.1 \
+zshall.1
 
 # yodl documentation
 
@@ -194,6 +195,8 @@ zshoptions.1: Zsh/options.yo
 
 zshparam.1: Zsh/params.yo
 
+zshroadmap.1: Zsh/roadmap.yo
+
 zshtcpsys.1: Zsh/tcpsys.yo
 
 zshzftpsys.1: Zsh/zftpsys.yo
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()
diff --git a/Doc/zsh.yo b/Doc/zsh.yo
index 5258555a8..6b4076d8c 100644
--- a/Doc/zsh.yo
+++ b/Doc/zsh.yo
@@ -44,6 +44,7 @@ texiendtitlepage()
 )\
 ifnzman(includefile(Zsh/manual.yo))
 includefile(Zsh/intro.yo)
+ifnzman(includefile(Zsh/roadmap.yo))
 includefile(Zsh/invoke.yo)
 includefile(Zsh/files.yo)
 ifnzman(includefile(Zsh/grammar.yo))
@@ -69,6 +70,7 @@ ifnzman(includefile(Zsh/contrib.yo))
 ifzshall(\
 def(source)(1)(NOTRANS(.so )man1/ARG1NOTRANS(.)1)\
 CMT()
+source(zshroadmap)
 source(zshmisc)
 source(zshexpn)
 source(zshparam)
diff --git a/Doc/zshroadmap.yo b/Doc/zshroadmap.yo
new file mode 100644
index 000000000..ed34f0a4c
--- /dev/null
+++ b/Doc/zshroadmap.yo
@@ -0,0 +1,3 @@
+manpage(ZSHROADMAP)(1)(date())(zsh version())
+manpagename(zshroadmap)(informal introduction to the zsh manual)
+includefile(Zsh/roadmap.yo)