From 1e1c69600ec7ef3f57b273b7fdae14bfb5fb9af5 Mon Sep 17 00:00:00 2001
From: Pierre Neidhardt <ambrevar@gmail.com>
Date: Mon, 21 Jan 2013 15:33:01 +0100
Subject: [PATCH] Shell: printhelp fixes plus some more.

---
 .shell.d/funs_pacman    | 103 +++++++++++++++++++++------------------
 .shell.d/funs_rc        | 105 +++++++++++++++++++++-------------------
 .shell.d/funs_transcode |  23 +++++----
 3 files changed, 124 insertions(+), 107 deletions(-)

diff --git a/.shell.d/funs_pacman b/.shell.d/funs_pacman
index 468d9eef..3f8eaf5c 100644
--- a/.shell.d/funs_pacman
+++ b/.shell.d/funs_pacman
@@ -42,13 +42,14 @@ pacman-files()
 {
     _printhelp()
     {
-        echo "Synopsis:"
-        echo -e "  $1 [-n] PACKAGES"
-        echo
-        echo "Usage:"
-        echo -e "  default:\tDisplay size of files in PACKAGES."
-        echo -e "  -h:\t\tDisplay this help."
-        echo -e "  -n:\t\tSort by size."
+        cat <<EOF
+Usage: $1 [OPTIONS] PACKAGES
+
+Display size of files in PACKAGES.
+
+  -h:  Display this help.
+  -n:  Sort by size.
+EOF
     }
 
     local OPTION_SORT="cat"
@@ -99,15 +100,16 @@ pacman-diff()
 {
     _printhelp()
     {
-        echo "Synopsis:"
-        echo -e "  $1 [-m|-e] [-q] FILE"
-        echo
-        echo "Usage:"
-        echo -e "  default:\tDisplay packages included in FILE but not installed."
-        echo -e "  -e:\t\tCompare FILE to explicitly installed packages."
-        echo -e "  -h:\t\tDisplay this help."
-        echo -e "  -m:\t\tCompare FILE to foreign installed packages."
-        echo -e "  -q:\t\tDisplay installed packages not included in FILE."
+        cat <<EOF
+Usage: $1 [-m|-e] [-q] FILE
+        
+Display packages included in FILE but not installed.
+
+  -e:  Compare FILE to explicitly installed packages.
+  -h:  Display this help.
+  -m:  Compare FILE to foreign installed packages.
+  -q:  Display installed packages not included in FILE.
+EOF
     }
 
     local OPTION_EXPLICIT=""
@@ -158,15 +160,17 @@ pacman-size()
 {
     _printhelp()
     {
-        echo "Synopsis:"
-        echo -e "  $1 [-a|-h|-n|-q] PACKAGES"
-        echo -e "  Arguments MUST be set before package list."
-        echo
-        echo "Usage:"
-        echo -e "  default:\tDisplay package size. Output contains no double and is alphabetically sorted. A grand total is printed at the end. It will only work for repos packages by default."
-        echo -e "  -h:\t\tShow this help."
-        echo -e "  -n:\t\tOutput is sorted by size."
-        echo -e "  -q:\t\tUses installed packages database instead of repos database. It speeds up queries and allows displaying size of local packages not available in repos."
+        cat <<EOF
+Usage: $1 [OPTIONS] PACKAGES
+
+Display package size. Output contains no double and is alphabetically sorted. A
+grand total is printed at the end. It will only work for repos packages by
+default.
+
+  -h:  Show this help.
+  -n:  Output is sorted by size.
+  -q:  Uses installed packages database instead of repos database. It speeds up queries and allows displaying size of local packages not available in repos.
+EOF
     }
 
     local CMD="pacman -Si"
@@ -233,16 +237,18 @@ pacman-deps()
 {
     _printhelp()
     {
-        echo "Synopsis:"
-        echo -e "  $1 [-a|-h|-q] [-r] PACKAGES"
-        echo -e "  Arguments MUST be set before package list."
-        echo
-        echo "Usage:"
-        echo -e "  default:\tDisplay package dependencies. Output contains no double and is alphabetically sorted. It will only work for repos packages by default."
-        echo -e "  -a:\t\tUses Yaourt queries instead of repos database. It slows down query but allow displaying size of any packages not available in repos."
-        echo -e "  -h:\t\tShow this help."
-        echo -e "  -r:\t\tCall function recursively."
-        echo -e "  -q:\t\tUses installed packages database instead of repos database. It speeds up queries and allows displaying size of local packages not available in repos."
+
+        cat <<EOF
+Usage: $1 [-a|-h|-q] [-r] PACKAGES
+
+Display package dependencies. Output contains no double and is alphabetically
+sorted. It will only work for repos packages by default.
+
+  -a:  Uses Yaourt queries instead of repos database. It slows down query but allow displaying size of any packages not available in repos.
+  -h:  Show this help.
+  -r:  Call function recursively.
+  -q:  Uses installed packages database instead of repos database. It speeds up queries and allows displaying size of local packages not available in repos.
+EOF
     }
 
     local CMD="pacman -Si"
@@ -355,19 +361,20 @@ abs-fetch ()
 {
     _printhelp ()
     {
-        echo "Synopsis:"
-        echo -e "  $1 [-hfy] PACKAGES"
-        echo
-        echo "Usage:"
-        echo -e "  default:\tFetch PKGBUILDs from ABS-tree"
-        echo -e "  -f:\t\tOverwrite folder if it exists."
-        echo -e "  -h:\t\tDisplay this help."
-        echo -e "  -y:\t\tUse 'yaourt' to fetch data."
-        echo 
-        echo 'Noteworthy parameters:'
-        echo '* $(pacman-official)'
-        echo '* $(pacman -Qmq)'
-        echo '* $(pacman -Qq)'
+        cat <<EOF
+Usage: $1 [-hfy] PACKAGES
+
+Fetch PKGBUILDs from ABS-tree.
+
+  -f:\t\tOverwrite folder if it exists.
+  -h:\t\tDisplay this help.
+  -y:\t\tUse 'yaourt' to fetch data.
+
+Noteworthy parameters:
+  \$(pacman-official)
+  \$(pacman -Qmq)
+  \$(pacman -Qq)
+EOF
     }
 
     local DL_AGENT=0
diff --git a/.shell.d/funs_rc b/.shell.d/funs_rc
index 26bcaf9d..aca9ed81 100644
--- a/.shell.d/funs_rc
+++ b/.shell.d/funs_rc
@@ -231,20 +231,18 @@ sanitize()
 
 asciify()
 {
-    asciify_help()
+    _printhelp()
     {
-        echo
-        echo "Usage:"
-        echo -e "\t$1 FILES"
-        echo
-        echo "Synopsis:"
-        echo -e "\tConvert non-ASCII characters to their ASCII equivalent."
-        echo
+        cat <<EOF
+Usage: $1 FILES
+
+Convert non-ASCII characters to their ASCII equivalent.
+EOF
     }
 
     if [ $# -eq 0 ]; then
         echo "Missing arguments."
-        asciify_help $0
+        _printhelp $0
         return
     fi 
 
@@ -305,22 +303,23 @@ asciify()
 
 blind-append()
 {
-    blind_help()
+    _printhelp()
     {
-        echo
-        echo "Usage:"
-        echo -e "\t$1 FILE [STRING]"
-        echo
-        echo "Synopsis:"
-        echo -e "\tAppend to all STRING found in FILE a secret phrase being prompted."
-        echo -e "\tIf STRING is omitted, secret phrase will be appended to the end of the file."
-        echo -e "\tIf FILE does not exist, it will be created and secret phrase will be inserted. STRING will be ignored."
-        echo
+        cat <<EOF
+Usage: $1 FILE [STRING]
+
+Append to all STRING found in FILE a secret phrase being prompted.  If STRING is
+omitted, secret phrase will be appended to the end of the file.  If FILE does
+not exist, it will be created and secret phrase will be inserted. STRING will be
+ignored.
+
+This requires 'read -s'. It will not work for Bourne Shell.
+EOF
     }
 
     if [ $# -gt 2 ] || [ $# -lt 1 ]; then
         echo "Wrong number of arguments."
-        blind_help $0
+        _printhelp $0
         return
     fi 
 
@@ -363,6 +362,7 @@ termcolors256()
     done
 }
 
+## Will not work for Bourne Shell.
 termcolors()
 {
     # The test text. Must be 3 letters.
@@ -396,43 +396,47 @@ termsupport()
     done | sort -nk2
 }
 
-## Highlight themes viewer for 256-colors terminals.
 if [ -n "$(command -v highlight)" ] ; then
     hlt-viewer ()
     {
-        print_help()
+        _printhelp()
         {
-            echo "Synopsis:"
-            echo -e "  $1"
-            echo
-            echo "This script displays a preview for every highlight's theme."
-            echo "Press ENTER to display next preview. Press anything else then ENTER to quit."
+            cat<<EOF
+Usage: $1
+
+Highlight themes viewer for 256-colors terminals.
+
+highlight is a tool for listing printing. This script displays a preview for
+every highlight's theme.  Press ENTER to display next preview. Press anything
+else then ENTER to quit.
+EOF
         }
         
         if [ $# -gt 0 ]; then
-            print_help "$0"
+            _printhelp "$0"
             return
         fi
 
-
-        local LIST=$(highlight -w | grep -v "\s\|^$")
-        local SAMPLE="void function(char* pointer, int &ref)
+        local SAMPLE="$(cat <<EOF 
+void function(char* pointer, int &ref)
 {
   int integer=3;
-  char* string=\"Hello!\";
+  char* string="Hello!";
 
   // Line comment
   for ( i=0; i<10; i++)
   {
-    printf(\"Sum: %d\\\n\", i*( integer+14 ) );
+    printf("Sum: %d\n", i*( integer+14 ) );
   }
-}"
+}
+EOF
+)"
 
         unset DUMMY
         for i in $(highlight -w | grep -v "\s\|^$"); do
             echo "******************** $i ********************"
-            highlight -S c -O xterm256 <(echo $SAMPLE) -s "$i" 
-            read -s DUMMY
+            highlight -S c -O xterm256 <(echo "$SAMPLE") -s "$i" 
+            read DUMMY
             if [ -n "$DUMMY" ]; then
                 return
             fi 
@@ -519,21 +523,21 @@ pdfresize ()
     gs  -q -o $2 -sDEVICE=pdfwrite -sPAPERSIZE=a4 -dFIXEDMEDIA -dPDFFitPage -dCompatibilityLevel=1.4 $1
 }
 
-## Create an archive from a single or multiples files/folders.
 archive ()
 {
-    printhelp()
+    _printhelp()
     {
-        echo "Synopsis:"
-        echo -e "  $1 [-m METHOD] [-v] FILES|FOLDERS"
-        echo
-        echo "Usage:"
-        echo -e "  default:\tCreate an archive of specified FILES and/or FOLDERS."
-        echo -e "  -h:\t\tDisplay this help."
-        echo -e "  -m:\t\tChoose compression method."
-        echo -e "    gz\t\tgzip (default)."
-        echo -e "    xz\t\tLZMA."
-        echo -e "  -v:\t\tExclude VCS data. (GNU tar only)."
+        cat <<EOF
+Usage: $1 [-m METHOD] [-v] FILES|FOLDERS
+
+Create an archive from a single or multiples files/folders.
+
+  -h:  Display this help.
+  -m:  Choose compression method.
+         * gz:  gzip (default).
+         * xz:  LZMA.
+  -v:  Exclude VCS data. (GNU tar only).
+EOF
     }
 
     local OPTION_VCS=""
@@ -542,7 +546,7 @@ archive ()
     while getopts ":hm:v" opt; do
         case $opt in
             h)
-                printhelp "$0"
+                _printhelp "$0"
                 return 1
                 ;;
             m)
@@ -552,7 +556,7 @@ archive ()
                 OPTION_VCS="--exclude-vcs"
                 ;;
             ?) 
-                printhelp "$0"
+                _printhelp "$0"
                 return 1
                 ;;
             :)
@@ -668,6 +672,7 @@ vcsclean()
     fi
     
     local CHOICE
+    unset CHOICE
     echo "This will clean current folder from all VCS control files."
     echo -n "Proceed ? [y/N] "
     while [ -z "$CHOICE" ];
diff --git a/.shell.d/funs_transcode b/.shell.d/funs_transcode
index e36bc24c..13fe11d2 100644
--- a/.shell.d/funs_transcode
+++ b/.shell.d/funs_transcode
@@ -125,14 +125,17 @@ tc_transcode()
 {
     _printhelp()
     {
-        echo "Synopsis:"
-        echo -e "  $1 [-f|-h|-s] FILES"
-        echo
-        echo "Usage:"
-        echo -e "  default:\tTranscode FILES to .mkv with x264 and ogg. Output files are the same as the original, with time appended. You can customize encoding with the TC_* variables."
-        echo -e "  -f:\t\tOverwrite existing file if any."
-        echo -e "  -h:\t\tDisplay this help."
-        echo -e "  -s:\t\tSample of ten minutes."
+        cat <<EOF
+Usage: $1 [OPTIONS] FILES|FOLDERS
+
+Transcode FILES or files found in FOLDERS to .mkv with x264 and ogg. Output
+files are the same as the original, with time appended. You can customize
+encoding with the TC_* variables.
+
+  -f:  Overwrite existing file if any.
+  -h:  Display this help.
+  -s:  Sample of ten minutes.
+EOF
     }
 
     ## What to do if file exists:
@@ -176,10 +179,12 @@ tc_transcode()
         return
     fi
 
+    ## The IFS trick will let us use an array of file that can have spaces. Real arrays are much better at it, but in this case the trick is not excessive, and works on all sh shells.
     local OLDIFS
     OLDIFS=$IFS
 
-    ## Zsh compatibility
+    ## Zsh compatibility. We need it otherwise word splitting of parameter like
+    ## TC_SAMPLE will not work.
     local STATUS
     STATUS="$(set -o | grep 'shwordsplit' | awk '{print $2}')"
     [ "$STATUS" = "off" ] && set -o shwordsplit