23447: improve documentation for zsh/newuser

3 files changed, 62 insertions, 2 deletions

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)