mirror of
https://github.com/zsh-users/zsh
synced 2024-11-05 16:08:45 +00:00
23447: improve documentation for zsh/newuser
This commit is contained in:
Peter Stephenson
parent
55ca3b0d16
commit
51897d0502
6 changed files with 90 additions and 11 deletions
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)).
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
28
INSTALL
28
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.
|
||||
|
||||
|
|
|
|||
5
README
5
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
|
||||
--------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue