[SM-Commit] GIT changes to master bashdoc by Jaka Kranjc (7c0463a790fd9eed5671f83bb6bf958fe70a191d)

Jaka Kranjc scm at sourcemage.org
Wed Apr 2 06:25:03 EDT 2008


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



More information about the SM-Commit mailing list