21498: Add zsh/newuser module

2 files changed, 39 insertions, 1 deletions

diff --git a/Doc/Makefile.in b/Doc/Makefile.in
index 72cf0f5f5..f1cbb3d8b 100644
--- a/Doc/Makefile.in
+++ b/Doc/Makefile.in
@@ -59,7 +59,8 @@ Zsh/mod_compctl.yo Zsh/mod_complete.yo Zsh/mod_complist.yo \
 Zsh/mod_computil.yo \
 Zsh/mod_datetime.yo Zsh/mod_deltochar.yo \
 Zsh/mod_example.yo Zsh/mod_files.yo \
-Zsh/mod_mapfile.yo Zsh/mod_mathfunc.yo Zsh/mod_parameter.yo Zsh/mod_pcre.yo \
+Zsh/mod_mapfile.yo Zsh/mod_mathfunc.yo Zsh/mod_newuser.yo \
+Zsh/mod_parameter.yo Zsh/mod_pcre.yo \
 Zsh/mod_sched.yo Zsh/mod_socket.yo \
 Zsh/mod_stat.yo  Zsh/mod_system.yo Zsh/mod_tcp.yo \
 Zsh/mod_termcap.yo Zsh/mod_terminfo.yo \
diff --git a/Doc/Zsh/mod_newuser.yo b/Doc/Zsh/mod_newuser.yo
new file mode 100644
index 000000000..202fb90e8
--- /dev/null
+++ b/Doc/Zsh/mod_newuser.yo
@@ -0,0 +1,37 @@
+COMMENT(!MOD!zsh/newuser
+Arrange for files for new users to be installed.
+!MOD!)
+The tt(zsh/newuser) module is loaded at boot if it is
+available, the tt(RCS) option is set, and the tt(PRIVILEGED) option is not
+set (all three are true by default).  This takes
+place immediately after commands in the global tt(zshenv) file (typically
+tt(/etc/zshenv)), if any, have been executed.  If the module is not
+available it is silently ignored by the shell; the module may safely be
+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.
+
+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
+directory of the tt(site-functions) directory, and if that is not found the
+module searches in a version-specific directory, usually the parent of the
+tt(functions) directory containing version-specific functions.  (These
+directories can be configured when zsh is built using the
+tt(--enable-site-scriptdir=)var(dir) and tt(--enable-scriptdir=)var(dir)
+flags to tt(configure), respectively; the defaults are
+var(prefix)tt(/share/zsh) and var(prefix)tt(/share/zsh/$ZSH_VERSION) where
+the default var(prefix) is tt(/usr/local).)
+
+If the file tt(newuser) is found, it is then sourced in the same manner as
+a start-up file.  The file is expected to contain code to install start-up
+files for the user, however any valid shell code will be executed.
+
+The tt(zsh/newuser) module is then unconditionally unloaded.
+
+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.