PATCH: improved zsh/newuser doc

[Peter Stephenson <pws@xxxxxxx>]

This improves the documentation for zsh/newuser by indicating more
about how the bits work together, flagging it early in README, and
documenting the function that can be called by the user.  As standalone
shell functions are usually documented in contrib.yo I've put it there,
though that's decreasingly aptly named.

Index: INSTALL
===================================================================
RCS file: /cvsroot/zsh/zsh/INSTALL,v
retrieving revision 1.29
diff -u -r1.29 INSTALL
--- INSTALL	29 Mar 2007 21:35:39 -0000	1.29
+++ INSTALL	21 May 2007 11:24:29 -0000
@@ -242,17 +242,27 @@
 .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.
 
Index: README
===================================================================
RCS file: /cvsroot/zsh/zsh/README,v
retrieving revision 1.45
diff -u -r1.45 README
--- README	21 May 2007 09:30:25 -0000	1.45
+++ README	21 May 2007 11:24:30 -0000
@@ -17,6 +17,11 @@
 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
 --------
 
Index: Doc/Zsh/contrib.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/contrib.yo,v
retrieving revision 1.68
diff -u -r1.68 contrib.yo
--- Doc/Zsh/contrib.yo	1 May 2007 12:42:24 -0000	1.68
+++ Doc/Zsh/contrib.yo	21 May 2007 11:24:32 -0000
@@ -16,6 +16,7 @@
 menu(Exception Handling)
 menu(MIME Functions)
 menu(Mathematical Functions)
+menu(User Configuration Functions)
 menu(Other Functions)
 endmenu()
 
@@ -1696,7 +1697,7 @@
 )
 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 @@
 )
 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 overrides
+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)
Index: Doc/Zsh/mod_newuser.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/mod_newuser.yo,v
retrieving revision 1.2
diff -u -r1.2 mod_newuser.yo
--- Doc/Zsh/mod_newuser.yo	9 Dec 2005 12:49:30 -0000	1.2
+++ Doc/Zsh/mod_newuser.yo	21 May 2007 11:24:32 -0000
@@ -37,3 +37,11 @@
 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)).
Index: Doc/Zsh/roadmap.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/roadmap.yo,v
retrieving revision 1.8
diff -u -r1.8 roadmap.yo
--- Doc/Zsh/roadmap.yo	21 Sep 2006 19:54:32 -0000	1.8
+++ Doc/Zsh/roadmap.yo	21 May 2007 11:24:32 -0000
@@ -19,6 +19,10 @@
 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)
 
-- 
Peter Stephenson <pws@xxxxxxx>                  Software Engineer
CSR PLC, Churchill House, Cambridge Business Park, Cowley Road
Cambridge, CB4 0WZ, UK                          Tel: +44 (0)1223 692070


To access the latest news from CSR copy this link into a web browser:  http://www.csr.com/email_sig.php

To get further information regarding CSR, please visit our Investor Relations page at http://ir.csr.com/csr/about/overview