GRMLZSHRC
-May, 2009
+August, 2009
%!target: man
%!postproc(man): "^(\.TH.*) 1 " "\1 5 "
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 =
== KEYBINDINGS ==
+Apart from zsh's default key bindings, //grmlzshrc// comes with its own set of
+key bindings. Note that bindings like **ESC-e** can also be typed as **ALT-e**
+on PC keyboards.
+
+: **ESC-e**
+Edit the current command buffer in your favourite editor.
+
== SHELL FUNCTIONS ==
//grmlzshrc// comes with a wide array of defined shell functions to ease the
user's life.
-: urlencode()
+: **2html()**
+Converts plaintext files to HTML using vim. The output is written to
+<filename>.html.
+
+: **doc()**
+Takes packagename as argument. Sets current working directory to
+/usr/share/doc/<packagename> and prints out a directory listing.
+
+: **hex()**
+Prints the hexadecimal representation of the number supplied as argument
+(base ten only).
+
+: **readme()**
+Opens all README-like files in current working directory with the program
+defined in the $PAGER environment variable.
+
+: **startx()**
+Initializes an X session using startx(1) if /etc/X11/xorg.conf exists, else
+issues a Warning to use the grml-x(1) script. Can be overridden by using
+/usr/bin/startx directly.
+
+: **urlencode()**
Takes a string as its first argument and prints it RFC 2396 URL encoded to
standard out.
+: **xinit()**
+Initializes an X session using xinit(1) if /etc/X11/xorg.conf exists, else
+issues a Warning to use the grml-x(1) script. Can be overridden by using
+/usr/bin/xinit directly.
+
+
+== ALIASES ==
+//grmlzshrc// comes with a wide array of predefined aliases to ease the user's
+life.
+
+: **cmplayer** (//mplayer -vo fbdev//)
+Video player with framebuffer as video output device, so you can watch
+videos on a virtual tty. Hint: Using fbdev2 allows you to use the shell
+while watching a movie.
+
+: **da** (//du -sch//)
+Prints the summarized disk usage of the arguments as well as a grand total
+in human readable format.
+
+: **fblinks** (//links2 -driver fb//)
+A Web browser on the framebuffer device. So you can browse images and click
+links on the virtual tty.
+
+: **fbmplayer** (//mplayer -vo fbdev -fs -zoom//)
+Fullscreen Video player with the framebuffer as video output device. So you
+can watch videos on a virtual tty.
+
+: **g** (//git//)
+Revision control system by Linus Torvalds.
+
+: **http** (//python -m SimpleHTTPServer//)
+Basic HTTP server implemented in python. Listens on port 8000/tcp and
+serves current directory. Implements GET and HEAD methods.
+
+: **j** (//jobs -l//)
+Prints status of jobs in the current shell session in long format.
+
+: **md** (//mkdir -p//)
+Creates directory including parent directories, if necessary
+
+: **rw-** (//chmod 600//)
+Grants read and write permission of a file to the owner and nobody else.
+
+: **rwx** (//chmod 700//)
+Grants read, write and execute permission of a file to the owner and nobody
+else.
+
+: **r--** (//chmod 644//)
+Grants read and write permission of a file to the owner and read-only to
+anybody else.
+
+: **r-x** (//chmod 755//)
+Grants read, write and execute permission of a file to the owner and
+read-only plus execute permission to anybody else.
+
= AUXILIARY FILES =
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 =
+On Debian systems (http://www.debian.org) - and possibly Ubuntu
+(http://www.ubuntu.com) and similar systems - it is very easy to get
+//grmlzshrc// via grml's .deb repositories.
+
+On non-debian systems, that is not an option, but all is not lost:
+\
+```
+% wget -O .zshrc http://git.grml.org/f/grml-etc-core/etc/zsh/zshrc
+```
+
+If you would also like to get seperate function files (which you can put into
+your **$fpath**), you can browse and download them at:
+
+http://git.grml.org/?p=grml-etc-core.git;a=tree;f=usr_share_grml/zsh;hb=HEAD
= CONTRIBUTING =
possibly inclusion.
-= AUTHOR =
-This manpage was written by Frank Terbeck <ft@grml.org>.
+= 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.
+
+
+= AUTHORS =
+This manpage was written by Frank Terbeck <ft@grml.org> and Joerg Woelke
+<joewoe@fsmail.de>.
= COPYRIGHT =
projects / grml-etc-core.git / blobdiff