grmlzshrc.t2t: Document function linenr()
[grml-etc-core.git] / doc / grmlzshrc.t2t
index 38e6cbd..384078f 100644 (file)
@@ -1,6 +1,6 @@
 GRMLZSHRC
 
-August, 2009
+June, 2010
 
 %!target: man
 %!postproc(man): "^(\.TH.*) 1 "  "\1 5 "
@@ -43,6 +43,47 @@ Or by setting them permanently in **zshrc.pre** (See AUXILIARY FILES below).
 If set to a value greater than zero and //acpi// installed, //grmlzshrc// will
 put the battery status into the right hand side interactive prompt.
 
+: **COMMAND_NOT_FOUND**
+A non zero value activates a handler, which is called when a command can not
+be found. The handler is defined by GRML_ZSH_CNF_HANDLER (see below).
+
+: **GRML_ALWAYS_LOAD_ALL**
+Enables the whole grml setup for root, if set to a non zero value.
+
+: **GRML_ZSH_CNF_HANDLER**
+This variable contains the handler to be used by COMMAND_NOT_FOUND (see above)
+and defaults to "/usr/share/command-not-found/command-not-found".
+
+: **GRMLSMALL_SPECIFIC**
+Set this to zero to remove items in zsh config, which do not work in
+grml-small.
+
+: **MAILCHECK**
+Sets the frequency in seconds for zsh to check for new mail. Defaults to 30.
+A value of zero turns off checking.
+
+: **NOCOR**
+Non zero values deactivate automatic correction of commands.
+
+: **NOMENU**
+If set to zero (default), allows selection from a menu, if there are at least
+five possible options of completion.
+
+: **NOPRECMD**
+A non zero value disables precmd and preexec commands. These are functions
+that are run before every command (setting xterm/screen titles etc.).
+
+: **REPORTTIME**
+Show time (user, system and cpu) used by external commands, if they run longer
+than the defined number of seconds (default: 5).
+
+: **ZSH_NO_DEFAULT_LOCALE**
+Import "/etc/default/locale", if set to zero (default).
+
+: **ZSH_PROFILE_RC**
+A non zero value causes shell functions to be profiled. The results can be
+obtained with the zprof builtin command (see zshmodules(1) for details).
+
 
 = FEATURE DESCRIPTION =
 This is an in depth description of non-standard features implemented by
@@ -229,6 +270,37 @@ available via the usual history lookup widgets.
 
 
 = REFERENCE =
+== ENVIRONMENT VARIABLES ==
+//grmlzshrc// sets some environment variables, which influence the
+behaviour of applications.
+
+: **BROWSER**
+If X is running this is set to "firefox", otherwise to "w3m".
+
+: **COLORTERM**
+Set to "yes". Some applications read this to learn about properties
+of the terminal they are running in.
+
+: **EDITOR**
+If not already set, sets the default editor. Falls back to vi(1),
+if vim(1) is not available.
+
+: **MAIL**
+The mailbox file for the current user is set to /var/mail/$USER, if not
+already set otherwise.
+
+: **PAGER**
+Set less(1) as default pager, if not already set to something different.
+
+: **QTDIR**
+Holds the path to shared files for the C++ application framework QT
+(version 3 or 4).
+
+: **SHELL**
+Set explicitly to /bin/zsh, to prevent certain terminal emulators to
+default to /bin/sh or /bin/bash.
+
+
 == OPTIONS ==
 Apart from zsh's default options, //grmlzshrc// sets some options
 that change the behaviour of zsh. Options that change Z-shell's default
@@ -343,6 +415,11 @@ Converts plaintext files to HTML using vim. The output is written to
 If 915resolution is available, issues a warning to the user to run it instead
 to modify the resolution on intel graphics chipsets.
 
+: **accessed()**
+Lists files in current directory, which have been accessed within the
+last N days. N is an integer to be passed as first and only argument.
+If no argument is specified N is set to 1.
+
 : **agoogle()**
 Searches for USENET postings from authors using google groups.
 
@@ -357,6 +434,12 @@ sequences) and the colors they represent.
 Pressing the 'asdf' keys toggles between dvorak or neon and us keyboard
 layout.
 
+: **asc()**
+Login on the host provided as argument using autossh. Then reattach a GNU screen
+session if a detached session is around or detach a currently attached screen or
+else start a new screen.  This is especially useful for roadwarriors using GNU
+screen and ssh.
+
 : **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
@@ -384,10 +467,28 @@ If the original cdrecord is not installed, issues a warning to the user to
 use the wodim binary instead. Wodim is the debian fork of Joerg Schillings
 cdrecord.
 
+: **changed()**
+Lists files in current directory, which have been changed within the
+last N days. N is an integer to be passed as first and only argument.
+If no argument is specified N is set to 1.
+
+: **check_com()**
+Returns true if given command exists either as program, function, alias,
+builtin or reserved word. If the option -c is given, only returns true,
+if command is a program.
+
+: **checkhome()**
+Changes directory to $HOME on first invocation of zsh. This is neccessary on
+grml systems with autologin.
+
 : **cl()**
 Changes current directory to the one supplied by argument and lists the files
 in it, including file names starting with ".".
 
+: **d()**
+Presents a numbered listing of the directory stack. Then changes current
+working directory to the one chosen by the user.
+
 : **debbug()**
 Searches the Debian bug tracking system (bugs.debian.org) for Bug numbers,
 email addresses of submitters or any string given on the command line.
@@ -410,6 +511,9 @@ Translates C source code to assembly and ouputs both.
 Takes packagename as argument. Sets current working directory to
 /usr/share/doc/<packagename> and prints out a directory listing.
 
+: **exirename()**
+Renames image files based on date/time informations in their exif headers.
+
 : **fir()**
 Opens given URL with Firefox (Iceweasel on Debian). If there is already an
 instance of firefox running, attaches to the first window found and opens the
@@ -444,20 +548,6 @@ Downloads and installs newer version of Skype.
 Tries to download and unpack X-lite (VoIP software) from counterpath.com into
 ~/tmp.
 
-: **git-get-diff()**
-Opens a specific git commitdiff from kernel.org in default browser. Tree is
-chosen by the environment variable GITTREE which defaults to Linus Torvalds'
-kernel tree.
-
-: **git-get-commit()**
-Opens a specific git commit from kernel.org in default browser. The tree to
-fetch from is controlled by the environment variable GITTREE which defaults
-to Linus Torvalds' kernel tree.
-
-: **git-get-plaindiff()**
-Fetches specific git diff from kernel.org. The tree is controlled by the
-environment variable GITTREE which defaults to Linus Torvalds' kernel tree.
-
 : **greph()**
 Searches the zsh command history for a regular expression.
 
@@ -468,6 +558,14 @@ Prints the hexadecimal representation of the number supplied as argument
 : **hidiff()**
 Outputs highlighted diff; needs highstring(1).
 
+: **hl()**
+Shows source files in less(1) with syntax highlighting. Run "hl -h"
+for detailed usage information.
+
+: **ic_get()**
+Queries IMAP server (first parameter) for its capabilities. Takes
+port number as optional second argument.
+
 : **is4()**
 Returns true, if zsh version is equal or greater than 4, else false.
 
@@ -498,6 +596,10 @@ Returns true, if running on a grml system from a live cd, else false.
 : **isgrmlsmall()**
 Returns true, if run on grml-small, else false.
 
+: **iso2utf()**
+Changes every occurrence of the string iso885915 or ISO885915 in
+environment variables to UTF-8.
+
 : **isutfenv()**
 Returns true, if run within an utf environment, else false.
 
@@ -509,13 +611,31 @@ parameter.
 Lists images (i. e. files ending with ".jpg", ".gif" or ".png") in current
 directory.
 
+: **linenr()**
+Prints specified range of (numbered) lines of a file.
+Usage: linenr <start>[,<end>] <file>
+
+: **makereadable()**
+Creates a PostScript and a PDF file (basename as first argument) from
+source code files.
+
+: **man2()**
+Displays manpage in a streched style.
+
 : **mcd()**
 Creates directory including parent directories, if necessary. Then changes
 current working directory to it.
 
+: **mdiff()**
+Diffs the two arguments recursively and writes the
+output (unified format) to a timestamped file.
+
+: **memusage()**
+Prints the summarized memory usage in bytes.
+
 : **minimal-shell()**
-Spawns a absolute minimal Korn shell. It references no files in /usr, so
-that file system can be unmounted.
+Spawns a minimally set up MirBSD Korn shell. It references no files in /usr,
+so that file system can be unmounted.
 
 : **mkaudiocd()**
 Renames all mp3 files in ~/ripps (see audiorip above) to lowercase and
@@ -527,10 +647,19 @@ Creates an iso9660 filesystem image with Rockridge and Joliet extensions
 enabled using mkisofs(8). Prompts the user for volume name, filename and
 target directory.
 
+: **mkmaildir()**
+Creates a directory with first parameter as name inside $MAILDIR_ROOT
+(defaults to $HOME/Mail) and subdirectories cur, new and tmp.
+
 : **mmake()**
 Runs "make install" and logs the output under ~/.errorlogs/; useful for
 a clean deinstall later.
 
+: **modified()**
+Lists files in current directory, which have been modified within the
+last N days. N is an integer to be passed as first and only argument.
+If no argument is specified N is set to 1.
+
 : **ogg2mp3_192()**
 Recodes an ogg file to mp3 with a bitrate of 192.
 
@@ -557,6 +686,10 @@ Reloads functions given as parameters.
 Checks whether a regular expression (first parameter) matches a string
 (second parameter) using perl.
 
+: **salias()**
+Creates an alias whith sudo prepended, if $EUID is not zero. Run "salias -h"
+for details. See also xunfunction() below.
+
 : **selhist()**
 Greps the history for the string provided as parameter and shows the numbered
 findings in default pager. On exit of the pager the user is prompted for a
@@ -585,7 +718,7 @@ Compresses/archives the file given as first parameter. Takes an optional
 second argument, which denotes the compression/archive type as typical
 filename extension; defaults to "tar.gz".
 
-: **smartindent()**
+: **smart-indent()**
 Indents C source code files given; uses Kernighan & Ritchie style.
 
 : **sshot()**
@@ -595,6 +728,24 @@ 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.
 
+: **ssl-cert-fingerprints**
+Prints the SHA512, SHA256, SHA1 and MD5 digest of a x509 certificate.
+First and only parameter must be a file containing a certificate. Use
+/dev/stdin as file if you want to pipe a certificate to these
+functions.
+
+: **ssl-cert-info**
+Prints all information of a x509 certificate including the SHA512,
+SHA256, SHA1 and MD5 digests. First and only parameter must be a file
+containing a certificate. Use /dev/stdin as file if you want to pipe a
+certificate to this function.
+
+: **ssl-cert-sha512(), ssl-cert-sha256(), ssl-cert-sha1(), ssl-cert-md5()**
+Prints the SHA512, SHA256, SHA1 respective MD5 digest of a x509
+certificate. First and only parameter must be a file containing a
+certificate. Use /dev/stdin as file if you want to pipe a certificate
+to this function.
+
 : **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
@@ -603,15 +754,33 @@ issues a Warning to use the grml-x(1) script. Can be overridden by using
 : **status()**
 Shows some information about current system status.
 
+: **swspeak()**
+Sets up software synthesizer by calling swspeak-setup(8). Kernel boot option
+swspeak must be set for this to work.
+
+: **trans()**
+Translates a word from german to english (-D) or vice versa (-E).
+
 : **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.
 
+: **uopen()**
+Downloads and displays a file using a suitable program for its
+Content-Type.
+
+: **uprint()**
+Works around the "print -l ${(u)foo}"-limitation on zsh older than 4.2.
+
 : **urlencode()**
 Takes a string as its first argument and prints it RFC 2396 URL encoded to
 standard out.
 
+: **utf2iso()**
+Changes every occurrence of the string UTF-8 or utf-8 in environment
+variables to iso885915.
+
 : **viless()**
 Vim as pager.
 
@@ -623,17 +792,43 @@ line options, she always wants, in her .zshrc.local.
 : **vman()**
 Use vim(1) as manpage reader.
 
+: **xcat()**
+Tries to cat(1) file(s) given as parameter(s). Always returns true.
+See also xunfunction() below.
+
 : **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.
 
+: **xsource()**
+Tries to source the file(s) given as parameter(s). Always returns true.
+See zshbuiltins(1) for a detailed description of the source command.
+See also xunfunction() below.
+
+: **xtrename()**
+Changes the title of xterm window from within screen(1). Run without
+arguments for details.
+
+: **xunfunction()**
+Removes the functions salias, xcat, xsource, xunfunction and zrcautoload.
+
 : **zg()**
 Search for patterns in grml's zshrc using perl. zg takes no or exactly one
 option plus a non empty pattern. Run zg without any arguments for a listing
 of available command line switches. For a zshrc not in /etc/zsh, set the
 GRML_ZSHRC environment variable.
 
+: **zrcautoload()**
+Wrapper around the autoload builtin. Loads the definitions of functions
+from the file given as argument. Searches $fpath for the file. See also
+xunfunction() above.
+
+: **zrclocal()**
+Sources /etc/zsh/zshrc.local and ${HOME}/.zshrc.local. These are the files
+where own modifications should go. See also zshbuiltins(1) for a description
+of the source command.
+
 
 == ALIASES ==
 //grmlzshrc// comes with a wide array of predefined aliases to ease the user's
@@ -1063,19 +1258,29 @@ possibly inclusion.
 
 
 = STATUS =
-This manual page is supposed to be a **reference** manual for //grmlzshrc//.
+This manual page is the **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.
+aspect of the setup.
+
+This manual is currently not complete. If you want to help improving it, visit
+the following pages:
+
+http://wiki.grml.org/doku.php?id=zshrcmanual
+
+http://lists.mur.at/pipermail/grml/2009-August/004609.html
+
+Contributions are highly welcome.
 
 
 = AUTHORS =
-This manpage was written by Frank Terbeck <ft@grml.org> and Joerg Woelke
-<joewoe@fsmail.de>.
+This manpage was written by Frank Terbeck <ft@grml.org>, Joerg Woelke
+<joewoe@fsmail.de>, Maurice McCarthy <manselton@googlemail.com> and Axel
+Beckert <abe@deuxchevaux.org>.
 
 
 = COPYRIGHT =
-Copyright (c) 2009, grml project <http://grml.org>
+Copyright (c) 2009-2010 grml project <http://grml.org>
 
 This manpage is distributed under the terms of the GPL version 2.