X-Git-Url: http://git.grml.org/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fgrmlzshrc.t2t;h=2ff2cc9cde13f413bdf1e4653ce909bc8e31a174;hb=ccabb9b26127441a2aff38571bfdbe901cf3a644;hp=82809b2dabacb9da7c4fcb8b831298a29ca1f98c;hpb=fc9a21f45058063dd2ff8161d01fdc0d832d708f;p=grml-etc-core.git diff --git a/doc/grmlzshrc.t2t b/doc/grmlzshrc.t2t index 82809b2..2ff2cc9 100644 --- a/doc/grmlzshrc.t2t +++ b/doc/grmlzshrc.t2t @@ -1,6 +1,6 @@ GRMLZSHRC -May, 2009 +August, 2009 %!target: man %!postproc(man): "^(\.TH.*) 1 " "\1 5 " @@ -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). @@ -56,33 +56,429 @@ 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 == +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 +.html. + +: **audioburn()** +Burns the files in ~/ripps (see audiorip() below) to an audio CD. +Then prompts the user if she wants to remove that directory. You might need +to tell audioburn which cdrom device to use like: +"DEVICE=/dev/cdrom audioburn" + +: **audiorip()** +Creates directory ~/ripps, if it does not exist. Then rips audio CD into +it. Then prompts the user if she wants to burn a audio CD with audioburn() +(see above). You might need to tell audiorip which cdrom device to use like: +"DEVICE=/dev/cdrom audioburn" + +: **cl()** +Changes current directory to the one supplied by argument and lists the files +in it, including file names starting with ".". + +: **doc()** +Takes packagename as argument. Sets current working directory to +/usr/share/doc/ and prints out a directory listing. + +: **greph()** +Searches the zsh command history for a regular expression. + +: **hex()** +Prints the hexadecimal representation of the number supplied as argument +(base ten only). + +: **is4()** +Returns true, if zsh version is equal or greater than 4, else false. + +: **is41()** +Returns true, if zsh version is equal or greater than 4.1, else false. + +: **is42()** +Returns true, if zsh version is equal or greater than 4.2, else false. + +: **is425()** +Returns true, if zsh version is equal or greater than 4.2.5, else false. + +: **is43()** +Returns true, if zsh version is equal or greater than 4.3, else false. + +: **is433()** +Returns true, if zsh version is equal or greater than 4.3.3, else false. + +: **isdarwin()** +Returns true, if running on darwin, else false. + +: **isgrml()** +Returns true, if running on a grml system, else false. + +: **isgrmlcd()** +Returns true, if running on a grml system from a live cd, else false. + +: **isgrmlsmall()** +Returns true, if run on grml-small, else false. + +: **isutfenv()** +Returns true, if run within an utf environment, else false. + +: **limg()** +Lists images (i. e. files ending with ".jpg", ".gif" or ".png") in current +directory. + +: **mcd()** +Creates directory including parent directories, if necessary. Then changes +current working directory to it. + +: **mkiso()** +Creates an iso9660 filesystem image with Rockridge and Joliet extensions +enabled using mkisofs(8). Prompts the user for volume name, filename and +target directory. + +: **readme()** +Opens all README-like files in current working directory with the program +defined in the $PAGER environment variable. + +: **shtar()** +Lists the content of a gzipped tar archive in default pager. + +: **shzip()** +Shows the content of a zip archive in default pager. + +: **slow_print()** +Prints the arguments slowly by sleeping 0.08 seconds between each character. + +: **sshot()** +Creates directory named shots in user's home directory, if it does not yet +exist and changes current working directory to it. Then sleeps 5 seconds, +so you have plenty of time to switch desktops/windows. Then makes a screenshot +of the current desktop. The result is stored in ~/shots to a timestamped +jpg file. + +: **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. + +: **status()** +Shows some information about current system status. + +: **udiff()** +Makes a unified diff of the command line arguments trying hard to find a +smaller set of changes. Descends recursively into subdirectories. Ignores +hows some information about current status. + +: **urlencode()** Takes a string as its first argument and prints it RFC 2396 URL encoded to standard out. +: **viless()** +Vim as pager. + +: **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. A few aliases (like those involving //grep// or //ls//) use the option +//--color=auto// for colourizing output. That option is part of **GNU** +implementations of these tools, and will only be used if such an implementation +is detected. + +: **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. + +: **grep** (//grep --color=auto//) +Shows grep output in nice colors, if available. + +: **GREP** (//grep -i --color=auto//) +Case insensitive grep with colored output. + +: **http** (//python -m SimpleHTTPServer//) +Basic HTTP server implemented in python. Listens on port 8000/tcp and +serves current directory. Implements GET and HEAD methods. + +: **l** (//ls -lF --color=auto//) +Lists files in long output format with indicator for filetype appended +to filename. If the terminal supports it, with colored output. + +: **la** (//ls -la --color=auto//) +Lists files in long colored output format. Including file names +starting with ".". + +: **lh** (//ls -hAl --color=auto//) +Lists files in long and human readable output format in nice colors, +if available. Includes file names starting with "." except "." and +"..". + +: **ll** (//ls -l --color=auto//) +Lists files in long colored output format. + +: **j** (//jobs -l//) +Prints status of jobs in the current shell session in long format. + +: **ls** (//ls -b -CF --color=auto//) +Lists directory printing octal escapes for nongraphic characters. +Entries are listed by columns and an indicator for file type is appended +to each file name. Additionally the output is colored, if the terminal +supports it. + +: **lsbig** (//ls -flh *(.OL[1,10])//) +Displays the ten biggest files (long and human readable output format). + +: **lsd** (//ls -d *(/)//) +Shows directories. + +: **lse** (//ls -d *(/^F)//) +Shows empty directories. + +: **lsnew** (//ls -rl *(D.om[1,10])//) +Displays the ten newest files (long output format). + +: **lsold** (//ls -rtlh *(D.om[1,10])//) +Displays the ten oldest files (long output format). + +: **lssmall** (//ls -Srl *(.oL[1,10])//) +Displays the ten smallest files (long output format). + +: **lsw** (//ls -ld *(R,W,X.^ND/)//) +Displays all files which are world readable and/or world writable and/or +world executable (long output format). + +: **lsx** (//ls -l *(*)//) +Lists only executable files. + +: **md** (//mkdir -p//) +Creates directory including parent directories, if necessary + +: **screen** (///usr/bin/screen -c ${HOME}/.screenrc//) +If invoking user is root, starts screen session with /etc/grml/screenrc +as config file. If invoked by a regular user, start a screen session +with users .screenrc config if it exists, else use /etc/grml/screenrc_grml +as configuration. + +: **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): \ @@ -93,13 +489,33 @@ BATTERY=1 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 = @@ -117,8 +533,16 @@ Doing so makes sure the right people get your patches for review and possibly inclusion. -= AUTHOR = -This manpage was written by Frank Terbeck . += 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 and Joerg Woelke +. = COPYRIGHT =