#!/bin/bash
Version=2.05
Myname="${0##*/}"
shopt -s extglob
doc=$(cat \
<<'DOC'
= gendoc - convert inline documentation to man, html or pdf
= Synopsis
gendoc [options] script
= Options
-h,--help print this help and exit
-H,--Help print full documentation via less and exit
-V,--version print version and exit
-m,--man generate a man page
-n,--noindex do not (re)generate an index
-p,--pdf generate a PDF file
-v,--verbose print some intermediate messages
-w,--web generate a web page
= Description
gendoc is a Bash script that looks for gendoc-formatted documentation in a
/script/. If the argument is an absolute path, that path is followed to
find the script; otherwise it is searched in your PATH; if the search fails,
the script is supposed to be in the current directory.
It creates three kinds of documentation for the script:
- a web page; it is placed in a directory |html|, next to the directory in
which the script resides. So if the script is |/local/bin/test|, the html
documentation will be |/local/html/test.html|.
- a pdf document; it is placed in |/local/pdf/test.pdf|.
- a man page; it is placed in |/local/man/man1/test.1|.
If you do not want all three documents, you can specify the ones you
want with the |--web|, |--pdf| and |--man| options respectively.
The documentation directories, |/local/{html,pdf,man/man1}| will be created
if they do not exist, but your permission will be asked.
In the |html| directory, a file |index.html| is generated, unless the
|--noindex| option was used. That option may be useful is you use gendoc
repeatedly, because index generation is slow. If you use the
|--noindex| option, be sure to run gendoc once again without it, or
your index will not be up to date.
= The gendoc format
== Global layout
gendoc documentation is mostly normal text, with some characters having a
special meaning. It must be placed between a line containing nothing but
the string |:<<'DOC'| (for bash of bourne shell scripts) or |<<'DOC'| (for
perl, ruby or python scripts) and another line, containing nothing but the
string |DOC|. For python, each such fragment of documentation must be
commented out with lines containing |"""| only.
You can have more than one piece of such documentation. So you may want
to have documentation for each of your functions separately.
== Special character sequences
Some special commands are defined in order to keep markup as simple as
possible. Currently these are:
|...| prints the |...| as code in light blue typewriter
font. If you need to typeset a bar (|), enclose it in
parentheses; those are also typeset.
*...* prints the |...| in bold; if you need asterisks, offer them in
verbatim text, either between vertical bars or
space-prefixed lines.
/.../ prints the |...| italic; if you need slashes, offer them in
verbatim text, either between vertical bars or
space-prefixed lines.
[...](...) prints first argument and links it to url in the second
argument. In the latter, don´t use |mailto:|, |http://|
or |https://| prefixes. If the link contains an @ character,
|mailto:| will automatically be added, otherwise, |http://|
will automatically be inserted. So you can simply write:
|[mail me](bc@def.com)| or |[Google](www.google.com)|.
If the first argument is empty, it will be replaced with
the link, after stripping any prefix. so you can write:
|See [](www.google.com)|.
Red{...} prints its argument in Red{red} color
Green{...} prints its argument in Green{green} color
Blue{...} prints its argument in Blue{blue} color
- The name of the script will automatically be printed in bold face,
it wil be linked to the script, and characters will be escaped if
needed.
- A line starting with a single |=| is typeset as a main heading.
- A line starting with a |==| is typeset as a smaller subheading.
- The first main heading should be of the form:
= scriptname - description
It will be typeset larger than other main headers.
- A line starting with |- | (a hyphen and one space) is the first item
of a bulleted list, which ends when a line without a starting |- |
or | | (two spaces) is met. Lines starting with more
than 2 whitespace characters are typeset as code, like in the next
item:
- Outside bulleted lists, lines starting with spaces are typeset
verbatim, like this:
#!/bin/bash
# Start of my script
In such lines, pairs of vertical bars (|), asterisks (*) and slashes
(/) are typeset literally, that is: they will not influence the
typeface of the surrounded text.
- Lines containing a tab character are typeset as two-column tables,
with left-aligned cells. The first column will be typeset verbatim.
Also, lines in second column will be typeset verbatim if they start
with at least one space. If the first line of the table has an
empty second field, that is: ends with a tab, all lines are supposed to
have only one non-empty field and non-empty first fields are typeset
over two columns, while empty first fields wil have a small fixed
width: 10% for HTML output, 10mm for PDF output.
= Version, type and short description
The script´s type, version and short description are displayed in the
documentation. If any of these cannot be found, gendoc dies with a message
telling which ones are missing. The type is taken from the shebang line.
The version is captured from the script by looking for a line starting with
|Version|, |version| or |$version|, followed by |=n.mx|, where the |=| may
be surrounded by whitespace, |n| and |m| are one or more digits, and |x|
stands for zero or more lowercase letters. The short description is taken
from the first heading.
= Recreate all docs
If for some reason a |pdf| subdirectory needs to be regenerated, then
cd to the directory containing the scripts and run:
for i in $(grep -d skip -l "^:<<'DOC'" *); do
gendoc ./$i
done
= Author
[Wybo Dekker](wybodekker@me.com).
= Copyright
Released under the [GNU General Public License](www.gnu.org/copyleft/gpl.html)
= See also
instscript(1), scriptinfo(1)
DOC
)
set -f # no globbing
# --- colors, help from embedded doc, die and warn ---
[ -t 1 ] && { Red=$'\e[1;31m' Mag=$'\e[1;35m' Nor=$'\e[0m'; } || Red='' Mag='' Nor=''
nv="-$Myname-${Version/./\\.} (press h for help, q to quit)"
helpsrt() { sed -n '/^= Synopsis/,/^= Desc/{//d;p}' <<<"$doc"; exit; }
helpall() { less -P"$nv" <<<"$doc"; exit; }
die() { printf "%s$Nor\n" "${@/#/$Myname: $Red}" >&2; exit 1; }
Warn() { printf "%s$Nor\n" "${@/#/$Myname: $Mag}" >&2; }
warn() { $verbose && Warn "$@"; }
:<<'DOC' #----------------------------------------------------------------------
= excheck
synopsis: excheck executable1 [executable2...]
description: check if all needed execs are there and getopt is GNU
DOC
#-------------------------------------------------------------------------------
excheck() {
local ok=true i
for i; do
command -v "$i" > /dev/null && continue
Warn "Missing executable: $i"
ok=false
done
$ok || die
getopt -T
[[ $? -ne 4 ]] && die "Your getopt is not GNU"
i=$(unzip -h|head -1|cut -c7-10)
[[ ${i:0:1} -ge 6 ]] ||tv die "Your unzip is too old (version $i)"
}
:<<'DOC' #----------------------------------------------------------------------
= handle_options
synopsis: handle_options "$@"
description: handle the options.
globals used: Myname Version
globals set args verbose index outext
returns: the number of remaining arguments
DOC
#-------------------------------------------------------------------------------
handle_options() {
local options
options=$(getopt \
-n "$Myname" \
-o hHVIvwpgim \
-l help,Help,verbose,version,html,pdf,index,man -- "$@"
) ||exit 1
eval set -- "$options"
index=false
verbose=false
outext=()
while [ $# -gt 0 ]; do
case $1 in
(-h|--help) # print this help and exit
helpsrt
;;
(-H|--Help) # print full documentation via less and exit
helpall
;;
(-V|--version) # print version and exit
echo $Version
exit
;;
(-m|--man) # generate a man page
outext+=(1)
shift
;;
(-i|--index) # do (re)generate an index in the html directory
index=true
shift
;;
(-p|--pdf) # generate a PDF file
outext+=(pdf)
shift
;;
(-v|--verbose) # print some intermediate messages
verbose=true
shift
;;
(-w|--web) # generate a web page
outext+=(html)
shift
;;
(-I) instscript "$0" ||
die 'the -I option is for developers only'
exit
;;
(--) shift
break
;;
(*) break
;;
esac
done
args=( "$@" )
}
:<<'DOC' #----------------------------------------------------------------------
= verb
synopsis: verb string [string...]
description: Prints the argument to stderr, but only if |verbose=true|
globals used: verbose
DOC
#-------------------------------------------------------------------------------
verb() {
$verbose && printf '%s\n' "$@" 1>&2
}
:<<'DOC' #----------------------------------------------------------------------
= info
synopsis: info script
description: Find script's type, version, short description.
See /scriptinfo/ for more information.
Dies if any if these cannot be found.
globals set: scriptversion type short progorscript
globals used: -
returns: 0
DOC
#-------------------------------------------------------------------------------
info() {
scriptversion='' type='' short='' progorscript='script'
local missing='' i
declare -A vars=(
[short]='short description'
[scriptversion]='version'
[type]='shebang line'
)
for i in short type scriptversion; do
read -r "${i?}"
test "$(eval "echo \$$i")" == '' && missing+="${vars[$i]}, "
done < <(scriptinfo --brief "$1")
[[ -n $missing ]] && die "missing in $1: ${missing%, }"
[[ $type == C ]] && progorscript=program
}
:<<'DOC' #----------------------------------------------------------------------
= indx
description: make new index in html directory
globals set: (via /scriptinfo/) type short scriptversion
globals used: type short bindir
DOC
#-------------------------------------------------------------------------------
indx() {
local i script
verb "creating index.html in $PWD"
set +f
( printf '
gendoc index
'
for i in *.html; do
[[ $i =~ ^index.html$ ]] && continue
script="$bindir/${i%.html}"
# just in case somebody removed a script, but not its html file:
[[ -e $script ]] || { rm "$i"; continue; }
info "$script"
printf '
 |
%s |
 |
%s |
\n' "$type" "$type" "$script" "${i%.html}" "$i" "$short"
done
printf '
'
ecode=""
bcompact=''
edoc='