grmlzshrc.t2t: Document function linenr()
[grml-etc-core.git] / doc / grmlzshrc.t2t
index 3fc7c20..384078f 100644 (file)
@@ -1,6 +1,6 @@
 GRMLZSHRC
 
-August, 2009
+June, 2010
 
 %!target: man
 %!postproc(man): "^(\.TH.*) 1 "  "\1 5 "
@@ -26,7 +26,10 @@ features are enabled in every version).
 //grmlzshrc// behaves differently depending on which user loads it. For the
 root user (**EUID** == 0) only a subset of features is loaded by default. This
 behaviour can be altered by setting the **GRML_ALWAYS_LOAD_ALL** STARTUP
-VARIABLE (see below).
+VARIABLE (see below). Also the umask(1) for the root user is set to 022,
+while for regular users it is set to 002. So read/write permissions
+for the regular user and her group are set for new files (keep that
+in mind on systems, where regular users share a common group).
 
 = STARTUP VARIABLES =
 Some of the behaviour of //grmlzshrc// can be altered by setting certain shell
@@ -40,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
@@ -226,6 +270,118 @@ 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
+settings are marked by <grml>. But note, that zsh's defaults vary depending
+on its emulation mode (csh, ksh, sh, or zsh). For details, see zshoptions(1).
+
+: **append_history**
+Zsh sessions, that use //grmlzshrc//, will append their history list to the
+history file, rather than replace it. Thus, multiple parallel zsh sessions
+will all have the new entries from their history lists added to the history
+file, in the order that they exit. The file will still be periodically
+re-written to trim it when the number of lines grows 20% beyond the value
+specified by $SAVEHIST.
+
+: **auto_cd** <grml>
+If a command is issued that can't be executed as a normal command, and the
+command is the name of a directory, perform the cd command to that directory.
+
+: **auto_pushd** <grml>
+Make cd push the old directory onto the directory stack.
+
+: **completeinword** <grml>
+If the cursor is inside a word, completion is done from both ends;
+instead of moving the cursor to the end of the word first and starting
+from there.
+
+: **extended_glob** <grml>
+Treat the '#', '~' and '^' characters as active globbing pattern characters.
+
+: **extended_history** <grml>
+Save each command's beginning timestamp (in seconds since the epoch) and the
+duration (in seconds) to the history file.
+
+: **hash_list_all**
+Whenever a command completion is attempted, make sure the entire command
+path is hashed first. This makes the first completion slower.
+
+: **histignorealldups** <grml>
+If a new command line being added to the history list duplicates an
+older one, the older command is removed from the list, even if it is
+not the previous event.
+
+: **histignorespace** <grml>
+Remove command lines from the history list when the first character on
+the line is a space, or when one of the expanded aliases contains a
+leading space. Note that the command lingers in the internal history
+until the next command is entered before it vanishes.
+
+: **longlistjobs** <grml>
+List jobs in long format by default.
+
+: **nobeep** <grml>
+Avoid to beep on errors in zsh command line editing (zle).
+
+: **noglobdots**
+A wildcard character never matches a leading '.'.
+
+: **nohup** <grml>
+Do not send the hangup signal (HUP:1) to running jobs when the shell exits.
+
+: **nonomatch** <grml>
+If a pattern for filename generation has no matches, do not print an error
+and leave it unchanged in the argument list. This also applies to file
+expansion of an initial `~' or `='.
+
+: **notify**
+Report the status of background jobs immediately, rather than waiting until
+just before printing a prompt.
+
+: **pushd_ignore_dups** <grml>
+Don't push multiple copies of the same directory onto the directory stack.
+
+: **share_history** <grml>
+As each line is added to the history file, it is checked to see if anything
+else was written out by another shell, and if so it is included in the
+history of the current shell too. Using !-style history, the commands from
+the other sessions will not appear in the history list unless you explicitly
+type the "history" command. This option is activated for zsh versions >= 4,
+only.
+
+
 == 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**
@@ -259,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.
 
@@ -273,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
@@ -300,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.
@@ -326,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
@@ -360,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.
 
@@ -384,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.
 
@@ -414,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.
 
@@ -425,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
@@ -443,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.
 
@@ -473,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
@@ -501,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()**
@@ -511,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
@@ -519,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.
 
@@ -539,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
@@ -979,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.