6 files changed, 90 insertions, 11 deletions
diff --git a/ChangeLog b/ChangeLog
index ba1faa4d1..bb2617400 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2007-05-21  Peter Stephenson  <pws@csr.com>
 
+	* 23447: INSTALL, README, Doc/Zsh/contrib.yo,
+	Doc/Zsh/mod_newuser.yo, Doc/Zsh/roadmap.yo: improve documentation
+	for the zsh/newuser module and zsh-newuser-install function.
+
 	* 23446: Src/Modules/parameter.c: a typo meant scanning
 	alias parameters returned a value the same as the key.
 
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 50965bfc4..729c4f0fe 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -16,6 +16,7 @@ menu(ZLE Functions)
 menu(Exception Handling)
 menu(MIME Functions)
 menu(Mathematical Functions)
+menu(User Configuration Functions)
 menu(Other Functions)
 endmenu()
 
@@ -1696,7 +1697,7 @@ Konqueror, tt(firefox -new-tab %u) for Firefox and tt(%b -remote
 )
 enditem()
 
-texinode(Mathematical Functions)(Other Functions)(MIME Functions)(User Contributions)
+texinode(Mathematical Functions)(User Configuration Functions)(MIME Functions)(User Contributions)
 sect(Mathematical Functions)
 
 startitem()
@@ -1814,7 +1815,54 @@ as well as the shell function implementation.
 )
 enditem()
 
-texinode(Other Functions)()(Mathematical Functions)(User Contributions)
+texinode(User Configuration Functions)(Other Functions)(Mathematical Functions)(User Contributions)
+
+The tt(zsh/newuser) module comes with a function to aid in configuring
+shell options for new users.  If the module is installed, this function can
+also be run by hand.  It is available even if the module's default
+behaviour, namely running the function for a new user logging in without
+startup files, is inhibited.
+
+startitem()
+item(tt(zsh-newuser-install) [ tt(-f) ])(
+The function presents the user with various options for customizing
+their initialization scripts.  Currently only tt(~/.zshrc) is handled.
+tt($ZDOTDIR/.zshrc) is used instead if the parameter tt(ZDOTDIR) is
+set; this provides a way for the user to configure a file without
+altering an existing tt(.zshrc).
+
+By default the function exits immediately if it finds any of the files
+tt(.zshenv), tt(.zprofile), tt(.zshrc), or tt(.zlogin) in the appropriate
+directory.  The option tt(-f) is required in order to force the function
+to continue.  Note this may happen even if tt(.zshrc) itself does not
+exist.
+
+As currently configured, the function will exit immediately if the
+user has root privileges; this behaviour cannot be overridden.
+
+Once activated, the function's behaviour is supposed to be
+self-explanatory.  Menus are present allowing the user to alter
+the value of options and parameters.  Suggestions for improvements are
+always welcome.
+
+When the script exits, the user is given the opportunity to save the new
+file or not; changes are not irreversible until this point.  However,
+the script is careful to restrict changes to the file only to a group
+marked by the lines `tt(# Lines configured by zsh-newuser-install)' and
+`tt(# End of lines configured by zsh-newuser-install)'.  In addition,
+the old version of tt(.zshrc) is saved to a file with the suffix
+tt(.zni) appended.
+
+If the function edits an existing tt(.zshrc), it is up to the user
+to ensure that the changes made will take effect.  For example, if
+control usually returns early from the existing tt(.zshrc) the lines
+will not be executed; or a later initialization file may override
+options or parameters, and so on.  The function itself does not attempt to
+detect any such conflicts.
+)
+enditem()
+
+texinode(Other Functions)()(User Configuration Functions)(User Contributions)
 sect(Other Functions)
 
 There are a large number of helpful functions in the tt(Functions/Misc)
diff --git a/Doc/Zsh/mod_newuser.yo b/Doc/Zsh/mod_newuser.yo
index d21e633c2..5da66a9f2 100644
--- a/Doc/Zsh/mod_newuser.yo
+++ b/Doc/Zsh/mod_newuser.yo
@@ -37,3 +37,11 @@ Note that it is possible to achieve exactly the same effect as the
 tt(zsh/newuser) module by adding code to tt(/etc/zshenv).  The module
 exists simply to allow the shell to make arrangements for new users without
 the need for invervention by package maintainers and system administrators.
+
+The script supplied with the module invokes the shell function
+tt(zsh-newuser-install).  This may be invoked directly by the user
+even if the tt(zsh/newuser) module is disabled.  Note, however, that
+if the module is not installed the function will not be installed either.
+The function is documented in
+ifnzman(noderef(User Configuration Functions))\
+ifzman(the section User Configuration Functions in zmanref(zshcontrib)).
diff --git a/Doc/Zsh/roadmap.yo b/Doc/Zsh/roadmap.yo
index 17f005b9b..38697adc7 100644
--- a/Doc/Zsh/roadmap.yo
+++ b/Doc/Zsh/roadmap.yo
@@ -19,6 +19,10 @@ 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)'.
+See also
+ifnzman(noderef(User Configuration Functions))\
+ifzman(the section User Configuration Functions in zmanref(zshcontrib)).
+
 
 sect(Interactive Use)
 
diff --git a/INSTALL b/INSTALL
index 783aea57c..ab5bc3760 100644
--- a/INSTALL
+++ b/INSTALL
@@ -242,17 +242,27 @@ shell interactively and has no initialisation files (.zshenv, .zshrc,
 .zprofile or .zlogin).  The shell then executes code in the file
 scripts/newuser in the shared library area (by default
 /usr/local/share/zsh/<VERSION>/scripts/newuser).  This feature can be
-turned off simply by removing this script.  The module can be removed
-entirely from the configured shell by editing the line starting
-"name=zsh/newuser" in the config.modules file, which is generated in the
-top level distribution directory during configuration: change the line to
-include "link=no auto=no".
+turned off simply by removing or renaming this script.  This is the
+recommended way of disabling the features as the function
+zsh-newuser-install (see below) remains available for users who
+wish to run it.
+
+The module can be removed entirely from the configured shell by editing the
+line starting "name=zsh/newuser" in the config.modules file, which is
+generated in the top level distribution directory during configuration:
+change the line to include "link=no auto=no".
 
 The supplied script executes the function supplied as
-Functions/Newuser/zsh-newuser-install.  This function is currently under
-development.  It is probably preferable for administrators who wish to
-customize the system their own way to edit the newuser script in
-scripts/newuser.  Also, as there is currently no internationalization
+Functions/Newuser/zsh-newuser-install, which is installed to the user's
+function path when the module is installed.  The function can be run by
+hand after being marked for autoload.  This is documented in the zshcontrib
+manual or in the info node `User Configuration Functions'.
+
+zsh-newuser-install is currently under development.  It is probably
+preferable for administrators who wish to customize the system their own
+way to edit the newuser script in scripts/newuser; for example, this script
+could copy skeleton files into place safe in the knowledge that the files
+don't yet exist.  Also, as there is currently no internationalization
 support, administrators of sites with users who mostly do not speak English
 may wish not to install the zsh/newuser module.
 
diff --git a/README b/README
index e80b6fbfb..3c4254b16 100644
--- a/README
+++ b/README
@@ -17,6 +17,11 @@ The instructions for compiling zsh are in the file INSTALL.  You should
 also check the file MACHINES in the top directory to see if there
 are any special instructions for your particular architecture.
 
+Note in particular the zsh/newuser module that guides new users through
+setting basic shell options without the administrator's intervention.  This
+is turned on by default.  See the section AUTOMATIC NEW USER CONFIGURATION
+in INSTALL for configuration information.
+
 Features
 --------