# HG changeset patch
# User Alexander 'z3ttacht' Steinböck <stone_henge@web.de>
# Date 1195391170 -3600
# Node ID 4017afb4f2568d12184b67612bc90e0fc35cf9a0
# Parent  cee7ffc1a2eabf0def6b01118d225892c758401e
Extended for the use of $(...) instead of backticks.
And it uses source code highlight filter to display shell code.
Note: source-highlight has to be installed to render the document
correctly.
Furthermore some minor corrections on formatting were done.

diff -r cee7ffc1a2ea -r 4017afb4f256 grml-policy.txt
--- a/grml-policy.txt	Fri Sep 14 09:24:38 2007 +0200
+++ b/grml-policy.txt	Sun Nov 18 14:06:10 2007 +0100
@@ -77,11 +77,14 @@ the grml-team you can checkout the accor
 the grml-team you can checkout the according repository and create a patch
 using the 'hg diff' command. Usage example:
 
-  hg clone http://hg.grml.org/grml-policy
-  cd grml-policy
-  hg diff > update_for_grml-policy-mention_foobar.diff
+[shell]
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+hg clone http://hg.grml.org/grml-policy
+cd grml-policy
+hg diff > update_for_grml-policy-mention_foobar.diff
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-and mail the resulting diff to the grml-team. The maintainer of the
+And mail the resulting diff to the grml-team. The maintainer of the
 according repository is listed in the Contact-column on
 link:http://hg.grml.org/[hg.grml.org]. You are free to
 link:http://grml.org/contact/[contact the grml-team directly via mail] or
@@ -130,12 +133,15 @@ scripts (like shellscripts handling with
 scripts (like shellscripts handling with services) and is supposed to be
 POSIX-compatible. Usage example:
 
-  % source /etc/grml/lsb-functions
-  % einfo "Starting foobar." ; /bin/true ; eend $?
-   * Starting foobar.                                  [ ok ]
-  % einfo "Starting foobar." ; /bin/false ; eend $?
-   * Starting foobar.                                  [ !! ]
-  %
+[shell]
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+% source /etc/grml/lsb-functions
+% einfo "Starting foobar." ; /bin/true ; eend $?
+ * Starting foobar.                                  [ ok ]
+% einfo "Starting foobar." ; /bin/false ; eend $?
+ * Starting foobar.                                  [ !! ]
+%
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you want to provide output on the plain console (without using an
 interface like link:http://invisible-island.net/dialog/[dialog] or
@@ -175,42 +181,78 @@ check4root function provided by /etc/grm
 * **clean up when being interrupted and on exit:** your script should not leave
 any temporary files (unless intented for debugging purposes of course).
 Usage example:
++
+[shell]
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+TMPFILE=$(mktemp ${TMP}/grml2hd.XXXXXX)
+bailout() {
+  rm -f "$TMPFILE"
+  [ -n "$1" ] && EXIT="$1" || EXIT="1"
+  exit "$EXIT"
+}
+trap bailout 1 2 3 15
+$CODE
+bailout 0
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-  TMPFILE=$(mktemp ${TMP}/grml2hd.XXXXXX)
-  bailout() {
-    rm -f "$TMPFILE"
-    [ -n "$1" ] && EXIT="$1" || EXIT="1"
-    exit "$EXIT"
-  }
-  trap bailout 1 2 3 15
-  $CODE
-  bailout 0
-
-* **use of subshells:** please use $(...) instead of `...`. (TODO: provide
-reasons...)
+* **use of subshells:** please use _$(...)_ instead of _\`...\`_.
++
+It allows nesting of commands in a more clearly and easier way.
+Therefore any shell code might appear within the parentheses, since
+the only time parentheses occur unquoted is in pairs. +
+With backquotes however any unquoted _\`_ within the form _\`...\`_
+would end the quotes immediately.
++
+Consider the following as an example on readability:
++
+[shell]
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+% echo "Tomorrow's date: `expr \`date +%d\` + 1`.`date +%m`."
+% echo "Tomorrow's date: $(expr $(date +%d) + 1).$(date +%m)."
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++
+Furthermore it can get quite tricky to get the right level of quotes
+when using backquotes.
++
+[shell]
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+% print "`echo \"hello\"`"
+hello
+% print "$(echo \"hello\")"
+"hello"
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++
+For further reading have a look at
+link:http://zsh.dotsrc.org/Guide/zshguide05.html#l11[A User's Guide to the
+Z Shell]
+and link:http://zsh.sourceforge.net/Intro/intro_7.html#SEC7[Introduction to
+the Z Shell]
 
 * **if ... then ... else ...**: you should make sure that the code is as
 easy understandable as possible. So instead of using:
++
+[shell]
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+if [ -n "$FOO" ] ; then
+   foo
+   bar
+   bla
+else
+   baz
+fi
 
-  if [ -n "$FOO" ] ; then
-     foo
-     bar
-     bla
-  else
-     baz
-  fi
+you should consider use of:
 
-  you should consider use of:
+if [ -z "$FOO" ] ; then
+   baz
+else
+   foo
+   bar
+   bla
+fi
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-  if [ -z "$FOO" ] ; then
-     baz
-  else
-     foo
-     bar
-     bla
-  fi
-
-* **indenting:* make sure you indent your code and use blank lines where
+* **indenting:** make sure you indent your code and use blank lines where
 according. Commonly accepted textwidth is 80 chars. (TODO: provide some
 more information...)
 
@@ -227,6 +269,6 @@ About this document
 About this document
 -------------------
 
-(c) Michael Prokop <mika@grml.org>; HTML version powered by link:http://www.methods.co.nz/asciidoc/[asciidoc].
+(C) Michael Prokop <mika@grml.org>; HTML version powered by link:http://www.methods.co.nz/asciidoc/[asciidoc].
 
 // vim: ft=asciidoc autoindent textwidth=75 formatoptions=tcqn