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).
== 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:<subcontext>'**.
+
+Where **<subcontext>** 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: <repository name>'** via zsh's vcs_info.
+
== PERSISTENT HISTORY ==
+If you got commands you consider important enough to be included in every
+shell's history, you can put them into ~/.important_commands and they will be
+available via the usual history lookup widgets.
= REFERENCE =
//grmlzshrc// comes with a wide array of defined shell functions to ease the
user's life.
-: urlencode()
+: **urlencode()**
Takes a string as its first argument and prints it RFC 2396 URL encoded to
standard out.
This is a set of files, that - if they exist - can be used to customize the
behaviour of //grmlzshrc//.
-: .zshrc.pre
+: **.zshrc.pre**
Sourced at the very beginning of //grmlzshrc//. Among other things, it can
be used to permantenly change //grmlzshrc//'s STARTUP VARIABLES (see above):
\
GRML_ALWAYS_LOAD_ALL=1
```
-: .zshrc.local
+: **.zshrc.local**
Sourced right before loading //grmlzshrc// is finished. There is a global
version of this file (/etc/zsh/zshrc.local) which is sourced before the
user-specific one.
+: **.zdirs**
+Directory listing for persistent dirstack (see above).
+
+: **.important_commands**
+List of commands, used by persistent history (see above).
+
= INSTALLATION ON NON-DEBIAN SYSTEMS =
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 <ft@grml.org>.
projects / grml-etc-core.git / blobdiff