grmlzshrc.t2t: Add customisation note about smkx and rmkx for keybindings

[grml-etc-core.git] / doc / grmlzshrc.t2t

diff --git a/doc/grmlzshrc.t2t b/doc/grmlzshrc.t2t
index 69745c4..a74e087 100644 (file)
--- a/doc/grmlzshrc.t2t
+++ b/doc/grmlzshrc.t2t
@@ -310,6 +310,50 @@ style. (The default is **true** in all contexts.)
 
 == PROMPT ==
 
+The //grmlzshrc// now supplies three prompt themes compatible with zsh's
+**promptinit** system. The three themes are called **grml**, **grml-large** and
+**grml-chroot**.
+
+By default, **grml** is used, unless //$GRMLPROMPT// is set to a value larger
+than zero, in which case **grml-large** is used. Lastly, if //$GRML_CHROOT// is
+non-empty, **grml-chroot** is used.
+
+As usual, with promtinit themes, the user may switch to a different theme using
+the //prompt// utility:
+\
+```
+    prompt grml-large
+```
+
+That will use the **grml-large** prompt theme.
+
+The themes are highly customisable. The main source of documentation about
+customisation is the main **grml** theme's doc-string, that is available via
+the following command:
+\
+```
+    prompt -h grml
+```
+
+The other themes also come with doc-strings, but the main theme's is the
+canonical reference about all of them.
+
+This feature requires version //4.3.7// of the shell. Older versions will use
+the classic grml prompt as a fallback.
+
+A note to people who like customisation: If you are **not** using a prompt
+theme for your customisation, but you're either statically setting $PS1 (or
+$PROMPT) or you're constructing one of those variables in zsh's \`precmd()'
+function, make sure you are turning the zsh's prompt theme system **off**
+before doing so. A correct example customisation could look like this:
+\
+```
+    # Turn the prompt system off:
+    prompt off
+    # Customise the prompt yourself:
+    PS1='%~ %# '
+```
+
 
 == GNU/SCREEN STATUS SETTING ==
 //grmlzshrc// sets screen's hardstatus lines to the currently running command
@@ -464,6 +508,23 @@ Display help on keybindings and zsh line editor. Press consecutively to page thr
 Brings a job, which got suspended with CTRL-z back to foreground.
 
 
+=== Customisation ===
+
+To customise keybindings, you can just use zsh's bindkey utility. However, if
+you plan to to use the `//zle-line-init//' or `//zle-line-finish//' hooks
+yourself, make sure you call the following functions in the respective hook:
+
+- **zle-line-init**: //zle-smkx//
+- **zle-line-finish**: //zle-rmkx//
+
+
+This is **required** so the keybindings set up by //grmlzshrc// work. The
+reason for this is to turn the terminal into the right mode while zsh's line
+editor (zle) is running. This enables us to query //terminfo// about escape
+sequences for special keys and thus simplify and generalise our keybinding
+section.
+
+
 == SHELL FUNCTIONS ==
 //grmlzshrc// comes with a wide array of defined shell functions to ease the
 user's life.
@@ -787,9 +848,6 @@ grep-excuses(1)).
 : **grep** (//grep --color=auto//)
 Shows grep output in nice colors, if available.
 
-: **grml-rebuildfstab** (//rebuildfstab -v -r -config//)
-Scans for new devices and updates /etc/fstab according to the findings.
-
 : **grml-version** (//cat /etc/grml_version//)
 Prints version of running grml.
 
@@ -1117,7 +1175,7 @@ Beckert <abe@deuxchevaux.org>.
 
 
 = COPYRIGHT =
-Copyright (c) 2009-2011 Grml project <http://grml.org>
+Copyright (c) 2009-2013 Grml project <http://grml.org>
 
 This manpage is distributed under the terms of the GPL version 2.