X-Git-Url: https://git.grml.org/?a=blobdiff_plain;f=doc%2Fgrmlzshrc.t2t;h=c9031facc6473665b0b9133942e013b80cf5359b;hb=464093627312e7be6e3afb6a2c42a5e468d21f16;hp=a6b1d9210d504e1bde79a0d902a45f34dba183c6;hpb=bfc77e17e04977e0e132916be5db626a726b87aa;p=grml-etc-core.git diff --git a/doc/grmlzshrc.t2t b/doc/grmlzshrc.t2t index a6b1d92..c9031fa 100644 --- a/doc/grmlzshrc.t2t +++ b/doc/grmlzshrc.t2t @@ -18,7 +18,7 @@ grmlzshrc - grml's zsh setup The grml project provides a fairly exhaustive interactive setup (referred to as //grmlzshrc// throughout this document) for the amazing unix shell zsh (http://zsh.sourceforge.net). This is the reference manual for that -setup (which is currently vastly incomplete; patches welcome). +setup. To use //grmlzshrc//, you need at least version 3.1.7 of zsh (although not all features are enabled in every version). @@ -46,14 +46,178 @@ This is an in depth description of non-standard features implemented by //grmlzshrc//. == DIRSTACK HANDLING == +The dirstack in //grmlzshrc// has a persistent nature. It is stored into a +file each time zsh's working directory is changed. That file can be configured +via the **DIRSTACKFILE** variable and it defaults to **~/.zdirs**. The +**DIRSTACKSIZE** variable defaults to **20** in this setup. + +The **DIRSTACKFILE** is loaded each time zsh starts, therefore freshly started +zshs inherit the dirstack of the zsh that most recently updated +**DIRSTACKFILE**. == DIRECTORY BASED PROFILES == +If you want certain settings to be active in certain directories (and +automatically switch back and forth between them), this is what you want. +\ +``` +zstyle ':chpwd:profiles:/usr/src/grml(|/|/*)' profile grml +zstyle ':chpwd:profiles:/usr/src/debian(|/|/*)' profile debian +``` + +When that's done and you enter a directory that matches the pattern +in the third part of the context, a function called chpwd_profile_grml, +for example, is called (if it exists). + +If no pattern matches (read: no profile is detected) the profile is +set to 'default', which means chpwd_profile_default is attempted to +be called. + +A word about the context (the ':chpwd:profiles:*' stuff in the zstyle +command) which is used: The third part in the context is matched against +**$PWD**. That's why using a pattern such as /foo/bar(|/|/*) makes sense. +Because that way the profile is detected for all these values of **$PWD**: +\ +``` +/foo/bar +/foo/bar/ +/foo/bar/baz +``` + +So, if you want to make double damn sure a profile works in /foo/bar +and everywhere deeper in that tree, just use (|/|/*) and be happy. + +The name of the detected profile will be available in a variable called +'profile' in your functions. You don't need to do anything, it'll just +be there. + +Then there is the parameter **$CHPWD_PROFILE** which is set to the profile, +that was active up to now. That way you can avoid running code for a +profile that is already active, by running code such as the following +at the start of your function: +\ +``` +function chpwd_profile_grml() { + [[ ${profile} == ${CHPWD_PROFILE} ]] && return 1 + ... +} +``` + +The initial value for **$CHPWD_PROFILE** is 'default'. + +=== Signaling availabily/profile changes === + +If you use this feature and need to know whether it is active in your +current shell, there are several ways to do that. Here are two simple +ways: + +a) If knowing if the profiles feature is active when zsh starts is + good enough for you, you can put the following snippet into your + //.zshrc.local//: +\ +``` +(( ${+functions[chpwd_profiles]} )) && + print "directory profiles active" +``` + +b) If that is not good enough, and you would prefer to be notified + whenever a profile changes, you can solve that by making sure you + start **every** profile function you create like this: +\ +``` +function chpwd_profile_myprofilename() { + [[ ${profile} == ${CHPWD_PROFILE} ]] && return 1 + print "chpwd(): Switching to profile: $profile" + ... +} +``` + +That makes sure you only get notified if a profile is **changed**, +not everytime you change directory. + +=== Version requirement === +This feature requires zsh //4.3.3// or newer. + == ACCEPTLINE WRAPPER == +The //accept-line// wiget is the one that is taking action when the **return** +key is hit. //grmlzshrc// uses a wrapper around that widget, which adds new +functionality. + +This wrapper is configured via styles. That means, you issue commands, that look +like: +\ +``` +zstyle 'context' style value +``` + +The context namespace, that we are using is 'acceptline'. That means, the actual +context for your commands look like: **':acceptline:'**. + +Where **** is one of: **default**, **normal**, **force**, **misc** +or **empty**. + + +=== Recognized Contexts === +: **default** +This is the value, the context is initialized with. +The //compwarnfmt and //rehash// styles are looked up in this context. + +: **normal** +If the first word in the command line is either a command, alias, function, +builtin or reserved word, you are in this context. + +: **force** +This is the context, that is used if you hit enter again, after being warned +about the existence of a _completion for the non-existing command you +entered. + +: **empty** +This is the context, you are in if the command line is empty or only +consists of whitespace. + +: **misc** +This context is in effect, if you entered something that does not match any +of the above. (e.g.: variable assignments). + + +=== Available Styles === +: **nocompwarn** +If you set this style to true, the warning about non existent commands, +for which completions exist will not be issued. (Default: **false**) + +: **compwarnfmt** +The message, that is displayed to warn about the _completion issue. +(default: **'%c will not execute and completion %f exists.'**) +'%c' is replaced by the command name, '%f' by the completion's name. + +: **rehash** +If this is set, we'll force rehashing, if appropriate. (Defaults to +**true** in //grmlzshrc//). + +: **actions** +This can be a list of wigdets to call in a given context. If you need a +specific order for these to be called, name them accordingly. The default value +is an **empty list**. + +: **default_action** +The name of a widget, that is called after the widgets from 'actions'. +By default, this will be '.accept-line' (which is the built-in accept-line +widget). + +: **call_default** +If true in the current context, call the widget in the 'default_action' +style. (The default is **true** in all contexts.) + == PROMPT == + == GNU/SCREEN STATUS SETTING == +//grmlzshrc// sets screen's hardstatus lines to the currently running command +or **'zsh'** if the shell is idling at its prompt. If the current working +directory is inside a repository unter version control, screen status is set +to: **'zsh: '** via zsh's vcs_info. + == PERSISTENT HISTORY == @@ -91,6 +255,7 @@ version of this file (/etc/zsh/zshrc.local) which is sourced before the user-specific one. + = INSTALLATION ON NON-DEBIAN SYSTEMS = @@ -109,6 +274,13 @@ Doing so makes sure the right people get your patches for review and possibly inclusion. += STATUS = +This manual page is supposed to be a **reference** manual for //grmlzshrc//. +That means that in contrast to the existing refcard it should document **every** +aspect of the setup. That is currently **not** the case. Not for a long time +yet. Contributions are highly welcome. + + = AUTHOR = This manpage was written by Frank Terbeck .