doc/grmlzshrc.t2t

   1 GRMLZSHRC
   2
   3 May, 2009
   4
   5 %!target: man
   6 %!postproc(man): "^(\.TH.*) 1 "  "\1 5 "
   7
   8
   9 = NAME =
  10 grmlzshrc - grml's zsh setup
  11
  12
  13 = SYNOPSIS =
  14 //zsh// [**options**]...
  15
  16
  17 = DESCRIPTION =
  18 The grml project provides a fairly exhaustive interactive setup (referred to
  19 as //grmlzshrc// throughout this document) for the amazing unix shell zsh
  20 (http://zsh.sourceforge.net). This is the reference manual for that
  21 setup.
  22
  23 To use //grmlzshrc//, you need at least version 3.1.7 of zsh (although not all
  24 features are enabled in every version).
  25
  26 //grmlzshrc// behaves differently depending on which user loads it. For the
  27 root user (**EUID** == 0) only a subset of features is loaded by default. This
  28 behaviour can be altered by setting the **GRML_ALWAYS_LOAD_ALL** STARTUP
  29 VARIABLE (see below).
  30
  31 = STARTUP VARIABLES =
  32 Some of the behaviour of //grmlzshrc// can be altered by setting certain shell
  33 variables. These may be set temporarily when starting zsh like this:
  34 \
  35 ``` % BATTERY=1 zsh
  36
  37 Or by setting them permanently in **zshrc.pre** (See AUXILIARY FILES below).
  38
  39 : **BATTERY**
  40 If set to a value greater than zero and //acpi// installed, //grmlzshrc// will
  41 put the battery status into the right hand side interactive prompt.
  42
  43
  44 = FEATURE DESCRIPTION =
  45 This is an in depth description of non-standard features implemented by
  46 //grmlzshrc//.
  47
  48 == DIRSTACK HANDLING ==
  49 The dirstack in //grmlzshrc// has a persistent nature. It is stored into a
  50 file each time zsh's working directory is changed. That file can be configured
  51 via the **DIRSTACKFILE** variable and it defaults to **~/.zdirs**. The
  52 **DIRSTACKSIZE** variable defaults to **20** in this setup.
  53
  54 The **DIRSTACKFILE** is loaded each time zsh starts, therefore freshly started
  55 zshs inherit the dirstack of the zsh that most recently updated
  56 **DIRSTACKFILE**.
  57
  58 == DIRECTORY BASED PROFILES ==
  59 If you want certain settings to be active in certain directories (and
  60 automatically switch back and forth between them), this is what you want.
  61 \
  62 ```
  63 zstyle ':chpwd:profiles:/usr/src/grml(|/|/*)'   profile grml
  64 zstyle ':chpwd:profiles:/usr/src/debian(|/|/*)' profile debian
  65 ```
  66
  67 When that's done and you enter a directory that matches the pattern
  68 in the third part of the context, a function called chpwd_profile_grml,
  69 for example, is called (if it exists).
  70
  71 If no pattern matches (read: no profile is detected) the profile is
  72 set to 'default', which means chpwd_profile_default is attempted to
  73 be called.
  74
  75 A word about the context (the ':chpwd:profiles:*' stuff in the zstyle
  76 command) which is used: The third part in the context is matched against
  77 **$PWD**. That's why using a pattern such as /foo/bar(|/|/*) makes sense.
  78 Because that way the profile is detected for all these values of **$PWD**:
  79 \
  80 ```
  81 /foo/bar
  82 /foo/bar/
  83 /foo/bar/baz
  84 ```
  85
  86 So, if you want to make double damn sure a profile works in /foo/bar
  87 and everywhere deeper in that tree, just use (|/|/*) and be happy.
  88
  89 The name of the detected profile will be available in a variable called
  90 'profile' in your functions. You don't need to do anything, it'll just
  91 be there.
  92
  93 Then there is the parameter **$CHPWD_PROFILE** which is set to the profile,
  94 that was active up to now. That way you can avoid running code for a
  95 profile that is already active, by running code such as the following
  96 at the start of your function:
  97 \
  98 ```
  99 function chpwd_profile_grml() {
 100     [[ ${profile} == ${CHPWD_PROFILE} ]] && return 1
 101     ...
 102 }
 103 ```
 104
 105 The initial value for **$CHPWD_PROFILE** is 'default'.
 106
 107 === Signaling availabily/profile changes ===
 108
 109 If you use this feature and need to know whether it is active in your
 110 current shell, there are several ways to do that. Here are two simple
 111 ways:
 112
 113 a) If knowing if the profiles feature is active when zsh starts is
 114    good enough for you, you can put the following snippet into your
 115    //.zshrc.local//:
 116 \
 117 ```
 118 (( ${+functions[chpwd_profiles]} )) &&
 119     print "directory profiles active"
 120 ```
 121
 122 b) If that is not good enough, and you would prefer to be notified
 123    whenever a profile changes, you can solve that by making sure you
 124    start **every** profile function you create like this:
 125 \
 126 ```
 127 function chpwd_profile_myprofilename() {
 128     [[ ${profile} == ${CHPWD_PROFILE} ]] && return 1
 129     print "chpwd(): Switching to profile: $profile"
 130   ...
 131 }
 132 ```
 133
 134 That makes sure you only get notified if a profile is **changed**,
 135 not everytime you change directory.
 136
 137 === Version requirement ===
 138 This feature requires zsh //4.3.3// or newer.
 139
 140
 141 == ACCEPTLINE WRAPPER ==
 142
 143 == PROMPT ==
 144
 145 == GNU/SCREEN STATUS SETTING ==
 146
 147 == PERSISTENT HISTORY ==
 148
 149
 150 = REFERENCE =
 151 == KEYBINDINGS ==
 152
 153 == SHELL FUNCTIONS ==
 154 //grmlzshrc// comes with a wide array of defined shell functions to ease the
 155 user's life.
 156
 157 : urlencode()
 158 Takes a string as its first argument and prints it RFC 2396 URL encoded to
 159 standard out.
 160
 161
 162 = AUXILIARY FILES =
 163 This is a set of files, that - if they exist - can be used to customize the
 164 behaviour of //grmlzshrc//.
 165
 166 : .zshrc.pre
 167 Sourced at the very beginning of //grmlzshrc//. Among other things, it can
 168 be used to permantenly change //grmlzshrc//'s STARTUP VARIABLES (see above):
 169 \
 170 ```
 171 # show battery status in RPROMPT
 172 BATTERY=1
 173 # always load the complete setup, even for root
 174 GRML_ALWAYS_LOAD_ALL=1
 175 ```
 176
 177 : .zshrc.local
 178 Sourced right before loading //grmlzshrc// is finished. There is a global
 179 version of this file (/etc/zsh/zshrc.local) which is sourced before the
 180 user-specific one.
 181
 182
 183 = INSTALLATION ON NON-DEBIAN SYSTEMS =
 184
 185
 186 = CONTRIBUTING =
 187 If you want to help to improve grml's zsh setup, clone the grml-etc-core
 188 repository from git.grml.org:
 189 \
 190 ``` % git clone git://git.grml.org/grml-etc-core.git
 191
 192 Make your changes, commit them; use '**git format-patch**' to create a series
 193 of patches and send those to the following address via '**git send-email**':
 194 \
 195 ``` grml-etc-core@grml.org
 196
 197 Doing so makes sure the right people get your patches for review and
 198 possibly inclusion.
 199
 200
 201 = STATUS =
 202 This manual page is supposed to be a **reference** manual for //grmlzshrc//.
 203 That means that in contrast to the existing refcard it should document **every**
 204 aspect of the setup. That is currently **not** the case. Not for a long time
 205 yet. Contributions are highly welcome.
 206
 207
 208 = AUTHOR =
 209 This manpage was written by Frank Terbeck <ft@grml.org>.
 210
 211
 212 = COPYRIGHT =
 213 Copyright (c) 2009, grml project <http://grml.org>
 214
 215 This manpage is distributed under the terms of the GPL version 2.
 216
 217 Most parts of grml's zshrc are distributed under the terms of GPL v2, too,
 218 except for **accept-line()** and **vcs_info()**, which are distributed under
 219 the same conditions as zsh itself (which is BSD-like).