Source Mage code commit list

[Jaka Kranjc <scm AT sourcemage.org>]

GIT changes to master bashdoc by Jaka Kranjc <lynxlynxlynx AT sourcemage.org>:

 ChangeLog             |   18 +
 bashdoc.sh            |  576 
++++++++++++++++++++++++++++++++++++--------------
 generate-smgl-docs.sh |    9 
 3 files changed, 444 insertions(+), 159 deletions(-)

New commits:
commit 7c0463a790fd9eed5671f83bb6bf958fe70a191d
Author: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>
Commit: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>

    added missing scripts to g-s-d

commit 750417bc5ec178bb00aadcaa5cf606d057d6e774
Author: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>
Commit: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>

    bashdoc: chmod +x

commit d42085ce6d9c47eeb6475b4f644af3c743fd3558
Author: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>
Commit: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>

        * generate-smgl-docs.sh: fixed long standing HTMl typo
        * started documenting changes the standard smgl way

commit 4504ee52587b7098c5aee4e3984b4ada510f2882
Author: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>
Commit: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>

    plenty of old changes from Arvid Norlander, see ChangeLog

diff --git a/ChangeLog b/ChangeLog
index 00dc3d8..33969da 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,9 +1,23 @@
-Sun Aug 13 13:08:12 PDT 2006
+2008-04-02 Jaka Kranjc <lynxlynxlynx AT sourcemage.org>
+       * generate-smgl-docs.sh: fixed long standing HTMl typo
+         added missing scripts
+       * started documenting changes the standard smgl way
+       * bashdoc: chmod +x
+
+Sun Oct 14 17:24:19 CEST 2007; Arvid Norlander
+  The last two days I have changed so much on bashdoc that I lost count of it
+  Some nice things:
+    Cleaned up code.
+    XHTML and CSS.
+    Made bashdoc able to document variables.
+    Fix many bugs.
+
+Sun Aug 13 13:08:12 PDT 2006; Paul Mahon
   Fix bug which caused either extra garbage around function links in src or
   skipped some interlinks.
   Release bashdoc-0.1.8
 
-Sun Jan 22 16:22:45 EST 2006
+Sun Jan 22 16:22:45 EST 2006; Paul Mahon
   ChangeLog: Started
   src2html: changed sed to fix the weird invalid range end erors
     Changes suggested by Jaka Kranjc
diff --git a/bashdoc.sh b/bashdoc.sh
index 9b8ef06..821f9b3 100755
--- a/bashdoc.sh
+++ b/bashdoc.sh
@@ -1,17 +1,15 @@
-#!/bin/bash
-
-VERSION="0.1.6"
-HEADER="<!-- Generated by bashdoc version $VERSION, on $(date). -->"
-
+#!/usr/bin/env bash
+# -*- coding: utf-8 -*-
 #--------------------------
 ##     @Synopsis       Reads specialy formated shell scripts and creates docs
 ##     @Copyright      Copyright 2003, Paul Mahon
+##     @Copyright      Copyright 2007, Arvid Norlander
 ##     @License        GPL v2
 ##     Parses comments between lines of '#---'
 ##     Lines to be parsed start with ##. All tags start with @.
 ##     Lines without a tag are considered simple description of the section.
 ##     If the line following the comment block doesn't start with 'function'
-##     the it's assumed that the comment is for the whole file. Only the 
first 
+##     the it's assumed that the comment is for the whole file. Only the 
first
 ##     non-function comment block will be used, the other will be ignored.
 ##     <p>
 ##     Multiple identical tags are allowed, the contents are appended and 
separated
@@ -21,18 +19,85 @@ HEADER="<!-- Generated by bashdoc version $VERSION, on 
$(date). -->"
 ##     in any bashdoc comment. It will be transformed into a link to that 
function.
 ##     Note, this will only work for functions that are defined in the same 
script.
 ##     <p><pre>
-##     Usage:  [-p project] [-o directory] [-e tag] [--] script [ script ...]
-##     '-p project'    Name of the project
-##     '-o directory'  Specifies the directory you want the 
-##             resulting html to go into
-##  '-e tag'   Only output if the block has this tag
-##     '-q'            Quiet things down
-##     '--'            No more arguments, only scripts
-##     'script'        The script you want documented
+##     Usage:  [OPTIONS] [--] script [ script ...]
+##     -p, --project project   Name of the project
+##     -o, --output directory  Specifies the directory you want the 
resulting html to go into
+##     -c, --nocss             Do not write default CSS file.
+##     -e, --exclusive tag     Only output if the block has this tag
+##     -q, --quiet             Quiet the output
+##     -h, --help              Display this help and exit
+##     -V, --version           Output version information and exit
+##     --                      No more arguments, only scripts
+##     script                  The script you want documented
 ##</pre>
 ##
 #--------------------------
 
+# Make env sane
+unset LC_CTYPE LC_NUMERIC LC_TIME LC_COLLATE LC_MONETARY
+unset LC_MESSAGES LC_PAPER LC_NAME LC_ADDRESS
+unset LC_TELEPHONE LC_MEASUREMENT LC_IDENTIFICATION
+export LC_ALL=C
+export LANG=C
+
+# Check bash version. We need at least 3.2.x
+# Lets not use anything like =~ here because
+# that may not work on old bash versions.
+if [[ "$(awk -F. '{print $1 $2}' <<< $BASH_VERSION)" -lt 32 ]]; then
+       echo "Sorry your bash version is too old!"
+       echo "You need at least version 3.2 of bash"
+       echo "Please install a newer version:"
+       echo " * Either use your distro's packages"
+       echo " * Or see http://www.gnu.org/software/bash/";
+       exit 2
+fi
+
+# To make set -x more usable
+export PS4='(${BASH_SOURCE}:${LINENO}): ${FUNCNAME[0]} : '
+
+VERSION="0.1.8"
+HEADERS="<!-- Generated by bashdoc version $VERSION, on $(date +'%Y-%m-%d'). 
-->
+<link rel=\"stylesheet\" href=\"style.css\" type=\"text/css\" />
+<meta http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\" />"
+
+GOOD=$'\e[32;01m'
+WARN=$'\e[33;01m'
+BAD=$'\e[31;01m'
+NORMAL=$'\e[0m'
+
+#--------------------------
+##     Output error message
+##     @param  Message
+##     @Stderr Formated message
+#--------------------------
+print_error () {
+       echo -e " ${BAD}*${NORMAL} $*" >&2
+}
+#--------------------------
+##     Output warning message
+##     @param  Message
+##     @Stderr Formated message
+#--------------------------
+print_warn () {
+       echo -e " ${WARN}*${NORMAL} $*" >&2
+}
+#--------------------------
+##     Output info message
+##     @param  Message
+##     @Stderr Formated message
+#--------------------------
+print_info () {
+       echo -e " ${GOOD}*${NORMAL} $*" >&2
+}
+#--------------------------
+##     Output debug message
+##     @param  Message
+##     @Stderr Formated message
+#--------------------------
+print_debug () {
+    echo -e "   $*" >&2
+}
+
 #--------------------------
 ##     @Arguments      -r: recursive, -o [directory]: output html
 ##     Parses arguments for this script
@@ -43,53 +108,102 @@ function args()
        local retVal=0
        QUIET=0
        while true ; do
-               case $1 in 
-                       -p)     PROJECT="$2"
-                               let retVal+=2
-                               shift 2                 ;;
-                       -o)     OUT_DIR=$2
-                               let retVal+=2
-                               shift 2                 ;;
-                       --help|-h)      usage
-                               exit 0                  ;;
-                       --exclusive|-e)
+               case $1 in
+                       -p|--project)
+                               PROJECT="$2"
+                               (( retVal+=2 ))
+                               shift 2
+                               ;;
+                       -o|--output)
+                               OUT_DIR="$2"
+                               (( retVal+=2 ))
+                               shift 2
+                               ;;
+                       -c|--nocss)
+                               NOCSS="1"
+                               (( retVal+=2 ))
+                               shift 1
+                               ;;
+                       -h|--help)
+                               usage
+                               exit 0
+                               ;;
+                       -V|--version)
+                               version
+                               exit 0
+                               ;;
+                       -e|--exclusive)
                                EXCLUSIVE="${2%%=*}"
                                EXCLUSIVE_VAL="${2#*=}"
-                               let retVal+=2
-                               shift 2                 ;;
+                               (( retVal+=2 ))
+                               shift 2
+                               ;;
                        -q|--quiet)
-                               let QUIET+=1
-                               let retVal+=1
-                               shift 1                 ;;
-                       --)     let retVal++
-                               return $retVal  ;;
-                       -*)     usage
-                               exit 0                  ;;
-                       *)      [ -e $1 ] && return $retVal
+                               (( QUIET+=1 ))
+                               (( retVal+=1 ))
+                               shift 1
+                               ;;
+                       --)
+                               (( retVal++ ))
+                               return $retVal
+                               ;;
+                       -*)
+                               usage
+                               exit 0
+                               ;;
+                       *)
+                               [[ -e $1 ]] && return $retVal
                                echo "$1 doesn't exist."
                                usage
-                               exit 1                  ;;
+                               exit 1
+                               ;;
                esac
        done
 }
 
 #-------------------------
+##     Version for this script
+##     @Stdout Version information
+#-------------------------
+function version()
+{
+       echo "bashdoc $VERSION - Generate HTML documentation from bash 
scripts"
+       echo ''
+       echo 'Copyright (C) 2003 Paul Mahon'
+       echo 'Copyright (C) 2007 Arvid Norlander'
+       echo 'This is free software; see the source for copying conditions.  
There is NO'
+       echo 'warranty; not even for MERCHANTABILITY or FITNESS FOR A 
PARTICULAR PURPOSE.'
+       echo ''
+       echo 'Written by Paul Mahon and modified by Arvid Norlander'
+}
+
+#-------------------------
 ##     Usage for this script
 ##     @Stdout Usage information
 #-------------------------
 function usage()
 {
 cat <<- EOF
-Usage: $(basename $0) [-p project] [-o directory] [--] script [ script ...]
-       '-p project'    Name of the project
-       '-o directory'  Specifies the directory you want the 
-               resulting html to go into
-       '-e tag'        Only output if the block has this tag
-       '-q'            Quiet the output
-       '--'            No more arguments, only scripts
-       'script'        The script you want documented
-       
-       Example: bash2doc.sh -p smgl -o docs/ 
/home/user/p4/sgl/devel/sorcery/var/lib/sorcery/modules/lib{misc,codex} 
bash2doc.sh
+bashdoc generates HTML documentation from bash scripts.
+
+Usage: $(basename $0) [OPTIONS] [--] script [script ...]
+
+Options:
+  -p, --project project   Name of the project
+  -o, --output directory  Specifies the directory you want the resulting 
html to go into
+  -c, --nocss             Do not write default CSS file.
+  -e, --exclusive tag     Only output if the block has this tag
+  -q, --quiet             Quiet the output
+  -h, --help              Display this help and exit
+  -V, --version           Output version information and exit
+  --                      No more arguments, only scripts
+  script                  The script you want documented
+
+Examples:
+  bashdoc.sh -p bashdoc -o docs/ bashdoc.sh              Generate 
documentation for this program.
+  bashdoc.sh -p appname -o docs/ -e Type=API someapp.sh  Generate 
documentation for someapp.sh,
+                                                         exclude items that 
do not include the tag
+                                                         @Type API
 EOF
 }
 
@@ -99,7 +213,7 @@ EOF
 ##     <br><pre>#---</pre></br>
 ##     Alone on a line, and continues until the next
 ##     <br><pre>#---</pre></br>
-##     All comment lines inside should have ## at the start or they 
+##     All comment lines inside should have ## at the start or they
 ##     will be ignored.
 ##
 ##     @return 0 Possibly more blocks
@@ -107,33 +221,35 @@ EOF
 ##     @return 2 Expected end of file, no more blocks
 ##     @Stdin  Reads a chunk
 ##     @Stdout Block with starting '##' removed
-##     @Globals        paramDesc, retDesc, desc, block, split
+##     @Globals        paramDesc, retDesc, desc, block, split, 
out_comment_block
 #--------------------------
 function get_comment_block()
 {
        local inComment commentBlock lastLine=""
        commentBlock=""
        while read LINE ; do
-               let srcLine++
+               (( srcLine++ ))
                if [[ ${LINE:0:4} == '#---' ]] ; then
                        if [[ $inComment ]] ; then
-                               echo "$commentBlock"
+                               out_comment_block="$commentBlock"
+                               # I'm not sure why this is needed but it 
fixes incorrect line number
+                               (( srcLine++ ))
                                return 0
                        else
                                inComment=yes
                        fi
                elif [[ ${LINE:0:2} != '##' ]] && [[ $inComment ]] ; then
-                               [[ $QUIET -lt 1 ]] && echo "Line $srcLine of 
$FILE isn't a doc comment! Ignoring." >&2
+                               [[ $QUIET -lt 1 ]] && print_warn "Line 
$srcLine of $FILE isn't a doc comment! Ignoring."
+                               [[ $QUIET -lt 1 ]] && print_warn "Line in 
question is: $LINE"
                elif [[ $inComment ]] ; then
                        commentBlock="$commentBlock"$'\n'${LINE####}
                fi
        done
-       
        #If we make it out here, we hit the end of the file
        if [[ $commentBlock ]] ; then
                #If there is a comment block started, then it never ended
-               [[ $QUIET -lt 2 ]] && echo "Unfinished comment block:"
-               [[ $QUIET -lt 2 ]] && echo "$commentBlock"
+               [[ $QUIET -lt 2 ]] && print_error "Unfinished comment block:"
+               [[ $QUIET -lt 2 ]] && print_error "$commentBlock"
                return 1
        else
                return 2
@@ -146,13 +262,13 @@ function get_comment_block()
 ##     function name. Mostly uses <@function parse_block> and
 ##     <@function output_parsed_block> to do the read work.
 ##     @Stdin  Reads line after comment block
-##     @Globals        paramDesc, retDesc, desc, block, split
+##     @Globals        paramDesc, retDesc, desc, block, split, 
out_comment_block
 #-----------------------
 function parse_comments()
 {
 
        #We use a lot of $( echo ... ) in here to trim the blanks
-       
+
        local funcLine funcName
        paramDesc=()
        retDesc=()
@@ -160,14 +276,21 @@ function parse_comments()
        local skipRead
        local outBlock=""
        local lastOutBlock=""
+       srcLine=0
+       # 1 = function
+       # 2 = variable
+       itemtype=0
        while true ; do
                paramNames=()
                paramDesc=()
                split=()
                retDesc=()
                desc=""
-               block=$( get_comment_block )
-               [ $? -gt 0 ] && break
+               itemtype=0
+               unset out_comment_block
+               get_comment_block
+               [[ $? -gt 0 ]] && break
+               block="$out_comment_block"
 
                if [[ $skipRead ]] ; then
                        skipRead=""
@@ -175,103 +298,143 @@ function parse_comments()
                        funcLine=""
                        funcName=""
                        read funcLine
-               fi              
-               if [[ ${funcLine%%[[:blank:]]*} == function ]] ; then
+               fi
+               # Is it a (global) variable?
+               # Check before function to catch arrays.
+               if [[ ${funcLine} =~ ^(declare -r 
+)?([a-zA-Z_][a-zA-Z0-9_]*)=.+$ ]]; then
+                       varName="${BASH_REMATCH[@]: -1}"
+                       itemtype=2
+               # Is it a function?
+               elif [[ ${funcLine%%[[:blank:]]*} == function ]] || [[ 
${funcLine} =~ ^[^\ ]+\ *\(\)\ *\{?$ ]]; then
                        funcName=$( echo ${funcLine#function} )
                        funcName=$( echo ${funcName%%()*} )
+                       itemtype=1
                fi
-               if [[ $funcName ]] || [[ $FIRST_BLOCK ]] ; then               
  
+               if [[ $funcName ]] || [[ $varName ]] || [[ $FIRST_BLOCK ]] ; 
then
                        # Only bother with this block if it is a function 
block or
                        #  the first script block
-                       
+
                        #This fills in paramDesc[*], tag_*, retDesc
                        parse_block
                        lastOutBlock="$outBlock"
                        outBlock=$(output_parsed_block)
-                       for i in ${!tag_*} ; do
-                               unset $i
-                       done
-                       
-                       if [[ $FIRST_BLOCK ]] && [[ ! $funcName ]] ; then
+
+                       if [[ $FIRST_BLOCK ]] && [[ ! $funcName ]] && [[ ! 
$varName ]]; then
                                FIRST_BLOCK=""
                        fi
-                       
+
                        if [[ $EXCLUSIVE ]] ; then
-                               local i="tag_${EXCLUSIVE}"
-                               if [[ ${!i} != $EXCLUSIVE_VAL ]] ; then
-                                       echo "$funcName block ignored, no 
$EXCLUSIVE=$EXCLUSIVE_VAL tag." >&2
-                                       for i in ${!tag_*} ; do
-                                               unset $i
-                                       done
-                                       continue
+                               # If this is first block, include it anyway.
+                               if [[ $funcName ]] || [[ $varName ]]; then
+                                       local i="tag_${EXCLUSIVE}"
+                                       if [[ ${!i} != $EXCLUSIVE_VAL ]] ; 
then
+                                               if [[ $itemtype = 2 ]]; then
+                                                       funcName="$varName"
+                                               fi
+                                               print_debug "$funcName block 
ignored, no $EXCLUSIVE=$EXCLUSIVE_VAL tag."
+                                               # Code duplication but hard 
to avoid
+                                               for i in ${!tag_*} ; do
+                                                       unset $i
+                                               done
+                                               continue
+                                       fi
                                fi
                        fi
-                       
-                       FUNC_LIST="$FUNC_LIST $funcName"
+
+                       for i in ${!tag_*} ; do
+                               unset $i
+                       done
+
+                       if [[ $funcName ]]; then
+                               FUNC_LIST="$FUNC_LIST $funcName"
+                       elif [[ $varName ]]; then
+                               VAR_LIST="$VAR_LIST $varName"
+                       fi
+                       unset funcName varName
                        echo "$outBlock"
-                       
+
                else
-                       [[ $QUIET -lt 2 ]] && echo "Ignoring non-first 
non-function comment block" >&2
-                       [[ $QUIET -lt 1 ]] && echo "$block" >&2
+                       [[ $QUIET -lt 2 ]] && print_warn "Ignoring non-first 
non-function/variable comment block"
+                       [[ $QUIET -lt 1 ]] && print_warn "$block"
                fi
        done
 }
 
 #---------------------
+##     Create HTML from the non-special tags
+##     @param  var or func (is this for a variable or function)
+##     @Stdout HTMLized tags
+#---------------------
+function output_parsed_tags() {
+       local i
+       for i in ${!tag_*} ; do
+               # Convert _ in tags to space. Looks better.
+               echo "  <h3 class=\"othertag ${1}othertag 
${i/tag_/tag-}\">$(sed 's/_/ /g' <<< "${i#tag_}")</h3>"
+               # This may be fun, allow special formatting by tag.
+               echo "  <p class=\"othertag ${1}othertag ${i/tag_/tag-}\">"
+               echo "  ${!i}"
+               echo "  </p>"
+               unset $i
+       done
+}
+
+#---------------------
 ##     Outputs the parsed information in a nice pretty format.
 ##     @Stdout formated documentation
 ##     @Globals        paramDesc, retDesc, desc, block, split
-#---------------------         
+#---------------------
 function output_parsed_block()
 {
-       echo -e "<hr>"
-       if [[ $funcName ]] ; then
+       echo "<hr />"
+       if [[ $itemtype -eq 1 ]] && [[ $funcName ]]; then
                echo "<!-- Block for $funcName -->"
-               echo "<dl>"
-               echo "  <dt><a name='$funcName'><h2>function 
<strong>$funcName</strong>()</h2></a></dt>"
-               echo "  <dd><ul>"
-               for(( i=0; i<"${#paramDesc[@]}"; i++ )) ; do
-                       echo "          <li>\$$[i+1]: ${paramDesc[i]}</li>"
-               done
-               echo "  </ul></dd>"
+               echo "  <h2 id=\"$funcName\" class=\"function\">function 
<strong>$funcName</strong>()</h2>"
+               echo "  <h3>Parameters:</h3>"
+               echo "  <ul class=\"paramerters\">"
+               if [[ ${#paramDesc[*]} -gt 0 ]] ; then
+                       for(( i=0; i<"${#paramDesc[@]}"; i++ )) ; do
+                               echo "          <li 
class=\"paramerters\">\$$[i+1]: ${paramDesc[i]}</li>"
+                       done
+               else
+                       echo "<li>None</li>"
+               fi
+               echo "  </ul>"
                if [[ ${#retDesc[*]} -gt 0 ]] ; then
-                       echo "  <dt><h3>Returns:</h3></dt>"
+                       echo "  <h3>Returns:</h3>"
+                       echo "  <ul class=\"returns\">"
                        for(( i=0; i<"${#retDesc[@]}"; i++ )) ; do
-                               echo "          <li>${retDesc[i]}</li>"
+                               echo "          <li 
class=\"returns\">${retDesc[i]}</li>"
                        done
+                       echo "  </ul>"
                fi
-               
-               for i in ${!tag_*} ; do
-                       echo "  <dt><h3>${i#tag_}</h3></dt>"
-                       echo "  <dd>${!i}</dd>"
-                       eval "unset $i"
-               done
-               [[ $desc ]] && echo "   
<dt><h3>Description</h3></dt><dd>$desc</dd>"
-               echo "</dl>"
+
+               output_parsed_tags func
+               [[ $desc ]] && echo "<h3>Description</h3><p 
class=\"description funcdescription\">$desc</p>"
+       elif [[ $itemtype -eq 2 ]]; then
+               echo "<!-- Block for $varName -->"
+               echo "  <h2 id=\"$varName\" class=\"variable\">variable 
<strong>$varName</strong></h2>"
+               output_parsed_tags var
+               [[ $desc ]] && echo "<h3>Description</h3><p 
class=\"description vardescription\">$desc</p>"
        else
                echo '<!-- Header for whole script -->'
-               echo "<dl>"
-               echo "  <dt><h1><strong>$FILE</strong></h1></dt>"
-               echo "  <dd>$desc</dd>"
+               echo "<h1>$FILE</h1>"
+               echo "  <p class=\"filedescription\">$desc</p>"
                echo "$desc" >> $SCRIPT_DESC
 
                for i in ${!tag_*} ; do
-                       echo "  <dt><h3>${i#tag_}</h3></dt>"
-                       echo "  <dd>${!i}</dd>"
+                       echo "  <h3 class=\"fileothertag 
${i/tag_/tag-}\">${i#tag_}</h3>"
+                       echo "  <p class=\"fileothertag 
${i/tag_/tag-}\">${!i}</p>"
                        unset $i
                done
-               echo "</dl>"
        fi
 
 }
 
 #---------------
 ##     Does the real work of the parsing. Tags start with @. Special
-##     tags are @return and @param. Doc lines without a tag are 
+##     tags are @return and @param. Doc lines without a tag are
 ##     considered description.
 ##     @Globals        paramDesc, retDesc, desc, block, split
-##     @Test   many line
-##     @Test   test tag
 #---------------
 function parse_block()
 {
@@ -284,28 +447,32 @@ function parse_block()
                if [[ ${LINE:0:1} == '@' ]] ; then
                        split_tag split $LINE
                        case ${split} in
-                               @param)         
#paramNames[${#paramNames[*]}]=${split[1]}
+                               @param)
+                                       
#paramNames[${#paramNames[*]}]=${split[1]}
                                        paramDesc=( "${paramDesc[@]}" 
"${split[1]}" )
                                        ;;
-                               @return)        
+                               @return)
                                        retDesc=( "${retDesc[@]}" 
"${split[1]}" )
                                        ;;
-                               @*) tag=${split[0]#@}
+                               @*)
+                                       tag=${split[0]#@}
                                        local i="tag_${tag}"
-                                       if [[ ${!i} ]] ; then 
-                                               eval 
"tag_${tag}=\"\${tag_${tag}}"$'\n'"${split[1]}\""
+                                       if [[ ${!i} ]] ; then
+                                               local varname="tag_${tag}"
+                                               eval 
"tag_${tag}=\"\${!varname}"$'\n'"\${split[1]}\""
                                        else
-                                               eval 
"tag_${tag}=\"${split[1]}\""
+                                               eval 
"tag_${tag}=\"\${split[1]}\""
                                        fi
                                        ;;
-                               *)      echo "We shouldn't get here... it was 
a tag, but not a tag?" >&2
+                               *)
+                                       print_error "We shouldn't get here... 
it was a tag, but not a tag?"
                                        ;;
                        esac
                else
                        desc="$desc"$'\n'"$LINE"
                fi
        done
-       IFS="$backIFS"  
+       IFS="$backIFS"
 }
 
 #----------------
@@ -321,7 +488,7 @@ function split_tag()
        local tag=$( echo ${1} )        ;       shift
 #      local key=$( echo ${1} )        ;       shift
        local value=$( echo $* )
-       eval "$out=( \"$tag\" \"${value}\" )"
+       eval "$out=( \"\$tag\" \"\${value}\" )"
 }
 
 #--------------------
@@ -332,50 +499,134 @@ function split_tag()
 function script_header()
 {
 cat <<- EOF > $OUT_FILE
-       <html>
-       $HEADER
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml"; lang="en" xml:lang="en">
        <head>
+               $HEADERS
                <title>$1 - $PROJECT</title>
        </head>
        <body>
-       <p align=right>
-       <a href="script_list.html">Script Index</a>
-       </p>
+               <p class="right">
+                       <a href="script_list.html">Script Index</a>
+               </p>
 EOF
 }
 
 # Initialise project variables
 OUT_DIR=$( dirname $0 )
+NOCSS=0
 args "$@"
 shift $?
 [[ $OUT_DIR ]] || OUT_DIR="."
 
+# Create output directory in case it doesn't exist
+mkdir -p "$OUT_DIR" || {
+       print_error "Failed to create output directory."
+       exit 1
+}
+
+if [[ $NOCSS = 0 ]]; then
+       print_info "Writing CSS"
+       # Copy stylesheet to output directory.
+       cat <<- EOF > "${OUT_DIR}/style.css"
+       /* Based on Trac CSS */
+       body {
+               background: #fff;
+               color: #000;
+               margin: 10px;
+               padding: 0;
+       }
+       body, th, td {
+               font: normal 13px verdana,arial,'Bitstream Vera 
Sans',helvetica,sans-serif;
+       }
+       h1, h2, h3, h4 {
+               font-family: arial,verdana,'Bitstream Vera 
Sans',helvetica,sans-serif;
+               font-weight: bold;
+               letter-spacing: -0.018em;
+       }
+       h1 { font-size: 19px; margin: .15em 1em 0 0 }
+       h2 { font-size: 16px; font-weight: normal; }
+       h3 { font-size: 14px }
+       hr { border: none;  border-top: 1px solid #ccb; margin: 2em 0 }
+       address { font-style: normal }
+       img { border: none }
+       tt { white-space: pre }
+       :link, :visited {
+               text-decoration: none;
+               color: #b00;
+               border-bottom: 1px dotted #bbb;
+       }
+       :link:hover, :visited:hover {
+               background-color: #eee;
+               color: #555;
+       }
+       h1 :link, h1 :visited ,h2 :link, h2 :visited, h3 :link, h3 :visited,
+       h4 :link, h4 :visited, h5 :link, h5 :visited, h6 :link, h6 :visited {
+       color: inherit;
+       }
+       /* Partly own stuff: */
+       .nav body {
+               margin: 0;
+               padding: 0;
+               background: inherit;
+               color: inherit;
+       }
+       .nav ul { font-size: 11px; list-style: none; margin: 0; padding: 0; 
text-align: left }
+       .nav li {
+       display: block;
+       padding: 0;
+       margin: 0;
+       white-space: nowrap;
+       }
+       /* Own stuff */
+       .nav-header {
+               font-weight: bold;
+       }
+       .right { text-align: right }
+       .tag-Deprecated { color: #e00; }
+       EOF
+else
+       print_warn "Not writing a stylesheet. You will need to add your own 
by hand afterwards."
+fi
 
-while [ $# -gt 0 ] ; do
+while [[ $# -gt 0 ]] ; do
 
-       echo "Parsing $FILE" >&2
        #Initialise vars for this src
        FILE=$1
+       [[ ! -f $FILE ]] || [[ ! -r $FILE ]] &&  {
+               print_error "$FILE is not a file or is not readable, 
skipping."
+               shift
+               continue
+       }
+       print_info "Parsing $FILE"
        shift
        OUT_FILE=${FILE#/}                                                    
                  #Remove leading /
        OUT_FILE="$OUT_DIR/${OUT_FILE//\//.}.html"
        FUNC_FILE="${OUT_FILE%.html}.funcs"
+       VAR_FILE="${OUT_FILE%.html}.vars"
        SCRIPT_DESC="${OUT_FILE%.html}.desc"
+       # Store real name (reuse in script list)
+       REAL_NAME_FILE="${OUT_FILE%.html}.name"
+       echo -n "${FILE#/}" > "$REAL_NAME_FILE"
+
        FUNC_LIST=""
+       VAR_LIST=""
 
        #Start this src's html file
-       script_header "$1"
+       script_header "$FILE"
 
        # Parse and write out function list
        {
-               parse_comments < $FILE 
+               parse_comments < $FILE
                echo "$FUNC_LIST" > $FUNC_FILE
-       } | sed -e 's!<@[[:blank:]]*function \([^,>]*\)[[:blank:]]*>!<a 
href="#\1">\1</a>!g' \
-                       -e 's!<@[[:blank:]]*function 
\([^,>]*\),[[:blank:]]*\([^>]*\)[[:blank:]]*>!<a href="\1#\2">\1</a>!g' >> 
$OUT_FILE
+               echo "$VAR_LIST" > $VAR_FILE
+       # Convert references like <@function file,functioname> into links
+       } | sed -e 's!<@[[:blank:]]*function \([^,>]*\)[[:blank:]]*>!<a 
href="#\1">\1</a>!g' \
+               -e 's!<@[[:blank:]]*function 
\([^,>]*\),[[:blank:]]*\([^>]*\)[[:blank:]]*>!<a href="\1#\2">\1</a>!g' >> 
$OUT_FILE
        #Close off the html for this src
        cat <<- EOF >> $OUT_FILE
                </body>
-               </html>
+       </html>
        EOF
 
 done #Go on to next src
@@ -383,76 +634,93 @@ done #Go on to next src
 #Now for tying the scripts all together
 pushd $OUT_DIR >/dev/null
 
+print_info "Writing function list"
 # Start page that will have all the function calls
 cat <<- EOF > function_list.html
-       <html>
-       $HEADER
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml"; lang="en" xml:lang="en">
        <head>
+               $HEADERS
                <title>Functions of $PROJECT</title>
        </head>
-       <body>
+       <body class="nav">
+               <ul class="nav">
 EOF
 
+echo "<li class=\"nav nav-header\">Functions</li>" >> function_list.html
 # Merge function lists of all sources, sort by function name
 for i in *.funcs ; do
        for f in $( cat $i ) ; do
-               echo "$f <a href=\"${i%.funcs}.html#$f\" 
target=main>$f</a><br>"
+               echo "$f <li class=\"nav nav-function\"><a 
href=\"${i%.funcs}.html#$f\" target=\"main\">$f</a></li>"
+       done
+done | sort | cut -d' ' -f2- >> function_list.html
+
+echo "<li class=\"nav nav-header\">Variables</li>" >> function_list.html
+for i in *.vars ; do
+       for v in $( cat $i ) ; do
+               echo "$v <li class=\"nav nav-variable\"><a 
href=\"${i%.vars}.html#$v\" target=\"main\">$v</a></li>"
        done
 done | sort | cut -d' ' -f2- >> function_list.html
 
 # Close off the html for the global function list
 cat <<-        EOF >> function_list.html
-</body>
+               </ul>
+       </body>
 </html>
 EOF
 
+print_info "Writing script list"
 # Start the list of scripts
 TITLE="Scripts"
 [[ $PROJECT ]] && TITLE="$PROJECT Script Documentation"
 cat <<- EOF > script_list.html
-       <html>
-       $HEADER
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml"; lang="en" xml:lang="en">
        <head>
+               $HEADERS
                <title>Scripts of $PROJECT</title>
        </head>
        <body>
-       <h1>$TITLE</h1>
-       <hr>
-       <dl>
+               <h1>$TITLE</h1>
+               <hr />
+               <dl>
 EOF
 
 # List all the sources + descriptions, sort by script dir/name
-for i in *.funcs ; do
-       name=${i%.funcs}
-       echo "${name}"
-done | sort | while read LINE ; do
-       echo "<dt><a href=\"${LINE}.html\">$LINE</a></dt>"
+for i in *.name ; do
+       name=${i%.name}
+       echo "${name} $(cat "$i")"
+done | sort | while read LINE realname; do
+       echo "<dt><a href=\"${LINE}.html\">$realname</a></dt>"
        echo "<dd>"
-       cat ${LINE}.desc 2>/dev/null || { [[ $QUIET -lt 2 ]] && echo "$LINE 
has no description." >&2; }
+       cat ${LINE}.desc 2>/dev/null || { [[ $QUIET -lt 2 ]] && print_warn 
"$LINE has no description."; }
        echo "</dd>"
 done >> script_list.html
 
 # Close off the html for the global script list
 cat <<-        EOF >> script_list.html
-       </dl>
+               </dl>
        </body>
-       </html>
+</html>
 EOF
 
+print_info "Writing index file"
 # Create the index file for the whole shbang
 cat <<- EOF > index.html
-       <html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml"; lang="en" xml:lang="en">
        <head>
-       $HEADER
+               $HEADERS
                <title>BashDoc - $PROJECT</title>
        </head>
-       <frameset COLS="20%,*">
-               <frame src=function_list.html name=function_list>
-               <frame src=script_list.html name=main>
+       <frameset cols="25%,*">
+               <frame src="function_list.html" name="function_list" />
+               <frame src="script_list.html" name="main" />
        </frameset>
-       </html>
+</html>
 EOF
 
-# Remove the temporary .desc files, leave the .func files, someone may want 
them later.
+# Remove the temporary .desc and .name files, leave the .func and .vars 
files, someone may want them later.
 rm *.desc
+rm *.name
 popd >/dev/null
diff --git a/generate-smgl-docs.sh b/generate-smgl-docs.sh
old mode 100644
new mode 100755
index 70c5a7e..a0933d8
--- a/generate-smgl-docs.sh
+++ b/generate-smgl-docs.sh
@@ -11,10 +11,13 @@ FLOW=$BIN/flow.sh
 SRC2HTML=$BIN/src2html.sh
 PROJECT=SourceMageDocs
 
-
 QUIET=${QUIET:--q -q}
 
-SCRIPTS="/var/lib/sorcery/modules/lib* 
/var/lib/sorcery/modules/url_handlers/url_* /usr/sbin/cast /usr/sbin/sorcery 
/usr/sbin/dispel /usr/sbin/gaze /usr/sbin/invoke /usr/sbin/scribbler 
/usr/sbin/scribe /usr/sbin/summon /usr/sbin/vcast /usr/sbin/xsorcery"
+SCRIPTS="/var/lib/sorcery/modules/lib* 
/var/lib/sorcery/modules/url_handlers/url_* \
+/var/lib/sorcery/modules/build_api/{api2,api1,common} 
/var/lib/sorcery/modules/dl_handlers/dl_* \
+/usr/sbin/cast /usr/sbin/sorcery /usr/sbin/dispel /usr/sbin/gaze 
/usr/sbin/invoke \
+/usr/sbin/cleanse /usr/sbin/confmeld /usr/sbin/alter /usr/sbin/delve 
/usr/sbin/cabal \
+/usr/sbin/scribbler /usr/sbin/scribe /usr/sbin/summon /usr/sbin/vcast 
/usr/sbin/xsorcery"
 #exclude non-sorcery files, like backups~ or numbered versions
 for FILE in $SCRIPTS
 do
@@ -45,7 +48,7 @@ else
        echo "The bashdoc tools are not installed, please cast bashdoc!"
 fi
 
-${SRC2HTMl} --funcs $DOCDIR $SCRIPTS
+${SRC2HTML} --funcs $DOCDIR $SCRIPTS
 if which dot >/dev/null 2>&1 ; then
        ${FLOW} --funcs $DOCDIR --exclude debug --exclude message \
                --exclude query $SCRIPTS