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

The argument script must be a script containing gendoc-formatted (see below) documentation. 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.

Description

gendoc is a Bash script that looks for gendoc-formatted documentation in a script, and converts it to three kinds of documentation:

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: they will be removed and replaced. 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 color
Green{...}	prints its argument in green color
Blue{...}	prints its argument in 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

Copyright

Released under the GNU General Public License

Functions used:

excheck

synopsis:	excheck executable1 [executable2...]
description:	check if all needed execs are there and getopt is GNU

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

verb

synopsis:	verb string [string...]
description:	Prints the argument to stderr, but only if `verbose=true`
globals used:	verbose

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	scriptversion type short progorscript
globals used:	-
returns:	0

indx

description:	make new index in html directory
globals	(via scriptinfo) type short scriptversion
globals used:	type short bindir

fnd

synopsis:	fnd scriptname
description:	Find the script and set some globals, telling the
	directory where the script is in, the basename of the supposed to be in the current directory.
globals set:	bindir base type

rline

description:	if repeat = false, read a line into variable line, if
	it´s true, leave the previous value in line.
globals	line lineno eof repeat
globals used:	repeat
returns:	1 on EOF

prverb

synopsis:	prverb string
description:	print the string verbatim
globals used:	sedverb

tabrow

description:	Prints the two tab separated cells in `line`.
	If cell 2 is empty, cell 1 is printed over 2 cols. If cell 2 starts with whitespace, print it verbatim.
globals used:	line brow mrow erow bRow eRow bverb everb ext

printout

synopsis:	printout string
description:	Prints the string, with items between bars in verbatim
globals used:	sedtext sedcode

cpurl

synopsis:	cpurl string
description:	Prints the argument with converted/protected links.
	URL's are of the form `[X](Y)`. This function finds them in a string and converts them in advance, protecting `/`'s, `<`'s, `>`'s and `\`'s with U+2620, U+2621, U+2622 and U+2623 respectively. The `X` is the representation of the link. If empty, the link itself is used, without any prefix like `http://`. The `Y` is the link. It may be an email address (possibly prefixed with `mailto:`) or a URL like `x.y.z/a/b`, possibly prefixed with `http://` or `https://`. For html and pdf, the final link will then replace the `[...](...)` version, proctecting special characters as described. For man pages, `http://` and `mailto:` prefixes are not needed, and `[X](Y)` will be replaced with `Y␣(X)` or, if `X` and `Y` are identical, with just `X`.
globals used:	ext

do_presets

synopsis:	do_presets extension
description:	Preset many global variables, depending on the output
	extension (html, pdf or 1)
globals	too many to report here
globals used:	base type progorscript scriptversion bindir