From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 13085 invoked from network); 21 May 2007 11:28:54 -0000 X-Spam-Checker-Version: SpamAssassin 3.2.0 (2007-05-01) on f.primenet.com.au X-Spam-Level: X-Spam-Status: No, score=-2.5 required=5.0 tests=AWL,BAYES_00 autolearn=no version=3.2.0 Received: from news.dotsrc.org (HELO a.mx.sunsite.dk) (130.225.247.88) by ns1.primenet.com.au with SMTP; 21 May 2007 11:28:54 -0000 Received-SPF: none (ns1.primenet.com.au: domain at sunsite.dk does not designate permitted sender hosts) Received: (qmail 89930 invoked from network); 21 May 2007 11:28:48 -0000 Received: from sunsite.dk (130.225.247.90) by a.mx.sunsite.dk with SMTP; 21 May 2007 11:28:48 -0000 Received: (qmail 27813 invoked by alias); 21 May 2007 11:28:45 -0000 Mailing-List: contact zsh-workers-help@sunsite.dk; run by ezmlm Precedence: bulk X-No-Archive: yes X-Seq: 23447 Received: (qmail 27804 invoked from network); 21 May 2007 11:28:45 -0000 Received: from news.dotsrc.org (HELO a.mx.sunsite.dk) (130.225.247.88) by sunsite.dk with SMTP; 21 May 2007 11:28:45 -0000 Received: (qmail 89772 invoked from network); 21 May 2007 11:28:45 -0000 Received: from cluster-c.mailcontrol.com (168.143.177.190) by a.mx.sunsite.dk with SMTP; 21 May 2007 11:28:41 -0000 Received: from cameurexb01.EUROPE.ROOT.PRI ([62.189.241.200]) by rly27c.srv.mailcontrol.com (MailControl) with ESMTP id l4LBQo9F028388 for ; Mon, 21 May 2007 12:28:16 +0100 Received: from news01.csr.com ([10.103.143.38]) by cameurexb01.EUROPE.ROOT.PRI with Microsoft SMTPSVC(6.0.3790.1830); Mon, 21 May 2007 12:26:49 +0100 Received: from news01.csr.com (localhost.localdomain [127.0.0.1]) by news01.csr.com (8.13.8/8.13.4) with ESMTP id l4LBQnCB007085 for ; Mon, 21 May 2007 12:26:49 +0100 Received: from csr.com (pws@localhost) by news01.csr.com (8.13.8/8.13.8/Submit) with ESMTP id l4LBQnaD007082 for ; Mon, 21 May 2007 12:26:49 +0100 Message-Id: <200705211126.l4LBQnaD007082@news01.csr.com> X-Authentication-Warning: news01.csr.com: pws owned process doing -bs To: zsh-workers@sunsite.dk (Zsh hackers list) Subject: PATCH: improved zsh/newuser doc Date: Mon, 21 May 2007 12:26:48 +0100 From: Peter Stephenson X-OriginalArrivalTime: 21 May 2007 11:26:49.0609 (UTC) FILETIME=[EC5C4F90:01C79B9A] Content-Type: text/plain MIME-Version: 1.0 X-Scanned-By: MailControl A-06-00-00 (www.mailcontrol.com) on 10.67.0.137 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//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 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