PATCH: minor documentation stuff

[Peter Stephenson <pws@xxxxxxx>]

I read through the documentation again and tweaked a few little things.
I'll make a test release shortly.

Index: NEWS
===================================================================
RCS file: /cvsroot/zsh/zsh/NEWS,v
retrieving revision 1.8
diff -u -r1.8 NEWS
--- NEWS	23 Nov 2005 11:29:20 -0000	1.8
+++ NEWS	9 Dec 2005 12:25:04 -0000
@@ -12,6 +12,10 @@
   (one with no .zshrc, .zshenv, .zprofile or .zlogin file) without
   any additional setting up by the administrator.
 
+- The manual now has a Roadmap section (manual page zshroadmap) to
+  give new users an indication of the most interesting parts of the
+  manual.
+
 - New option PROMPT_SP, on by default, to work around the problem that the
   line editor can overwrite output with no newline at the end.
 
@@ -20,11 +24,8 @@
 
 - New redirection syntax e.g. {myfd}>file opens a new file descriptor
   and stores the number in $myfd, so that >&$myfd will work.  Chosen
-  not to break existing code.
-
-- The manual now has a Roadmap section (manual page zshroadmap) to
-  give new users an indication of the most interesting parts of the
-  manual.
+  not to break existing code (and to be compatible with proposals for the
+  Korn shell).
 
 - New Posix-style zsh-specific tests [[:IDENT:]], [[:IFS:]],
   [[:IFSSPACE:]], [[:WORD:]] test if character can appear in identifier,
@@ -35,7 +36,16 @@
 - The idiom =(<<<...) is optimised so that the shell internally turns
   the ... into the contents of a file whose name is then substituted.
 
-- As always, many enhancements to completion functions.
+- Supplied functions catch and throw provide limited support for
+  exception handling using the `{ ... } always { ... }' syntax.
+
+- Signals now accept the SIG as part of the name for compatibility with
+  other shells.
+
+- Editor function argument-base allows non-decimal arguments for
+  editor widgets.
+
+- As always, there are many enhancements to completion functions.
 
 Changes in 4.2 since version 4.2.0
 ----------------------------------
@@ -67,7 +77,7 @@
   in the event of an error.  It also runs after a break, continue, or
   return, including a return forced by the ERR_RETURN option
   (but not an exit, which is immediate).  The syntax is:
-    `{'  try-block-list `}' `always' `{' always-block-list `}'
+    `{' try-block-list `}' `always' `{' always-block-list `}'
   where no newline or semicolon may appear between `}' and `always'.
   This is compatible with all previous valid zsh syntax as an `always'
   at that point used to be a syntax error.  For example,
@@ -101,8 +111,8 @@
 
 - New WIDGETSTYLE, WIDGETFUNC parameters in ZLE.
 
-- Glob qualifiers (+func) is shorthand for (e:func:) (calls command,
-  typically shell function, with no argument).
+- Glob qualifier (+func) is shorthand for (e:func:) (calls a command,
+  typically a shell function, with no argument).
 
 New features between zsh versions 4.0 and 4.2
 ---------------------------------------------
Index: Doc/Zsh/roadmap.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/roadmap.yo,v
retrieving revision 1.4
diff -u -r1.4 roadmap.yo
--- Doc/Zsh/roadmap.yo	7 Nov 2005 09:37:34 -0000	1.4
+++ Doc/Zsh/roadmap.yo	9 Dec 2005 12:25:06 -0000
@@ -14,6 +14,12 @@
 Startup/Shutdown Files in zmanref(zsh))\
 ifnzman(noderef(Files)).
 
+If no personal intialization files exist for the current user, a function
+is run to help you change some of the most common settings.  It won't
+appear if your administrator has disabled the tt(zsh/newuser) module.
+The function is designed to be self-explanatory.  You can run it by hand
+with `tt(autoload -Uz zsh-newuser-install; zsh-newuser-install -f)'.
+
 sect(Interactive Use)
 
 Interaction with the shell uses the builtin Zsh Line Editor, ZLE.  This is
@@ -35,7 +41,7 @@
 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
+is supplied with completions for 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
@@ -111,12 +117,15 @@
 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))\
+One commonly encountered difference is that variables 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)).
+In zsh, you should use arrays when you want variables to expand to more
+than one word.  See
+ifzman(the section `Array Parameters' in zmanref(zshparam))\
+ifnzman(noderef(Array Parameters)).
 
 sect(Programming)
 
@@ -124,7 +133,9 @@
 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)).
+ifnzman(noderef(Functions)).  Users changing from the C shell and its
+relatives should notice that aliases are less used in zsh as they don't
+perform argument substitution, only simple text replacement.
 
 A few general functions, other than those for the line editor described
 above, are provided with the shell and are described in
@@ -149,6 +160,6 @@
 a version of tt(xargs) that makes the tt(find) command redundant
 )
 item(tt(zmv))(
-a command for renaming files with patterns.
+a command for renaming files by means of shell 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