22057: don't use zsh/newuser in emulation

22058: tweak docs for release

2 files changed, 22 insertions, 9 deletions

diff --git a/Doc/Zsh/mod_newuser.yo b/Doc/Zsh/mod_newuser.yo
index 202fb90e8..d21e633c2 100644
--- a/Doc/Zsh/mod_newuser.yo
+++ b/Doc/Zsh/mod_newuser.yo
@@ -12,7 +12,9 @@ removed from tt($MODULE_PATH) by the administrator if it is not required.
 On loading, the module tests if any of the start-up files tt(.zshenv),
 tt(.zprofile), tt(.zshrc) or tt(.zlogin) exist in the directory given by
 the environment variable tt(ZDOTDIR), or the user's home directory if that
-is not set.
+is not set.  The test is not performed and the module halts processing if
+the shell was in an emulation mode (i.e. had been invoked as some other
+shell than zsh).
 
 If none of the start-up files were found, the module then looks for the
 file tt(newuser) first in a sitewide directory, usually the parent
diff --git a/Doc/Zsh/roadmap.yo b/Doc/Zsh/roadmap.yo
index 547f7e20b..1e529c6f6 100644
--- a/Doc/Zsh/roadmap.yo
+++ b/Doc/Zsh/roadmap.yo
@@ -14,6 +14,12 @@ be created or edited to customize the shell.  See ifzman(the section
 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 @@ 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
+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 @@ 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))\
+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 @@ 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)).
+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 @@ 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.
+a command for renaming files by means of shell patterns.
 )
 enditem()