PATCH: manual roadmap

[Peter Stephenson <pws@xxxxxxx>]

I'd like to add an informal section to the manual with a brief
list of features a new user might want to know about, and where to find
the documentation.  It's not designed to duplicate the main
documentation itself.  Something like the following...

Index: Doc/.distfiles
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/.distfiles,v
retrieving revision 1.6
diff -u -r1.6 .distfiles
--- Doc/.distfiles	31 Jul 2005 18:04:35 -0000	1.6
+++ Doc/.distfiles	21 Oct 2005 09:20:52 -0000
@@ -4,11 +4,11 @@
     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='
Index: Doc/Makefile.in
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Makefile.in,v
retrieving revision 1.29
diff -u -r1.29 Makefile.in
--- Doc/Makefile.in	23 Aug 2005 00:37:51 -0000	1.29
+++ Doc/Makefile.in	21 Oct 2005 09:20:52 -0000
@@ -47,7 +47,8 @@
 # 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 @@
 
 zshparam.1: Zsh/params.yo
 
+zshroadmap.1: Zsh/roadmap.yo
+
 zshtcpsys.1: Zsh/tcpsys.yo
 
 zshzftpsys.1: Zsh/zftpsys.yo
Index: Doc/zsh.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/zsh.yo,v
retrieving revision 1.8
diff -u -r1.8 zsh.yo
--- Doc/zsh.yo	6 Feb 2003 12:21:51 -0000	1.8
+++ Doc/zsh.yo	21 Oct 2005 09:20:52 -0000
@@ -44,6 +44,7 @@
 )\
 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 @@
 ifzshall(\
 def(source)(1)(NOTRANS(.so )man1/ARG1NOTRANS(.)1)\
 CMT()
+source(zshroadmap)
 source(zshmisc)
 source(zshexpn)
 source(zshparam)
Index: Doc/zshroadmap.yo
===================================================================
RCS file: Doc/zshroadmap.yo
diff -N Doc/zshroadmap.yo
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ Doc/zshroadmap.yo	21 Oct 2005 09:20:52 -0000
@@ -0,0 +1,3 @@
+manpage(ZSHROADMAP)(1)(date())(zsh version())
+manpagename(zshroadmap)(informal introduction to the zsh manual)
+includefile(Zsh/roadmap.yo)

Index: Doc/Zsh/.distfiles
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/.distfiles,v
retrieving revision 1.14
diff -u -r1.14 .distfiles
--- Doc/Zsh/.distfiles	21 Jul 2005 13:45:27 -0000	1.14
+++ Doc/Zsh/.distfiles	21 Oct 2005 09:20:52 -0000
@@ -12,6 +12,7 @@
     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
 '
Index: Doc/Zsh/intro.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/intro.yo,v
retrieving revision 1.4
diff -u -r1.4 intro.yo
--- Doc/Zsh/intro.yo	9 Jan 2004 18:14:01 -0000	1.4
+++ Doc/Zsh/intro.yo	21 Oct 2005 09:20:54 -0000
@@ -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 @@
 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)
Index: Doc/Zsh/invoke.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/invoke.yo,v
retrieving revision 1.7
diff -u -r1.7 invoke.yo
--- Doc/Zsh/invoke.yo	24 Apr 2005 18:38:04 -0000	1.7
+++ Doc/Zsh/invoke.yo	21 Oct 2005 09:20:54 -0000
@@ -1,4 +1,4 @@
-texinode(Invocation)(Files)(Introduction)(Top)
+texinode(Invocation)(Files)(Roadmap)(Top)
 chapter(Invocation)
 cindex(invocation)
 sect(Invocation Options)
Index: Doc/Zsh/manual.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/manual.yo,v
retrieving revision 1.14
diff -u -r1.14 manual.yo
--- Doc/Zsh/manual.yo	6 Feb 2003 12:21:51 -0000	1.14
+++ Doc/Zsh/manual.yo	21 Oct 2005 09:20:54 -0000
@@ -14,6 +14,7 @@
 startmenu()
 menu(The Z Shell Manual)
 menu(Introduction)
+menu(Roadmap)
 menu(Invocation)
 menu(Files)
 menu(Shell Grammar)
Index: Doc/Zsh/roadmap.yo
===================================================================
RCS file: Doc/Zsh/roadmap.yo
diff -N Doc/Zsh/roadmap.yo
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ Doc/Zsh/roadmap.yo	21 Oct 2005 09:20:54 -0000
@@ -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()

-- 
Peter Stephenson <pws@xxxxxxx>                  Software Engineer
CSR PLC, Churchill House, Cambridge Business Park, Cowley Road
Cambridge, CB4 0WZ, UK                          Tel: +44 (0)1223 692070


This message has been scanned for viruses by BlackSpider MailControl - www.blackspider.com