#!/bin/sh
# Arguments: Package directory, Destination directory, optional label
src=$1 ; shift
dst=$1 ; shift
lbl=$1
if [ x$src = x -o x$dst = x ] ; then
echo 1>&2 usage: $0 source destination
exit 1
fi
if [ x$lbl = x ] ; then lbl=`basename $src` ; fi
rm -rf $dst
mkdir -p $dst
echo Find and map sources ...
dtp map -ext html -out $dst -trail 2 `find $src -type f -name '*.man' | sort` > $$.map
echo _index_ $dst/index.html >> $$.map
echo _toc_ $dst/toc.html >> $$.map
echo Fixed nagivation bars ...
dtp navbar $$.map _toc_ _toc_ 'Table Of Contents' /off _index_ 'Index' /on > $$.nb_toc
dtp navbar $$.map _index_ _toc_ 'Table Of Contents' /on _index_ 'Index' /off > $$.nb_idx
dtp navbar $$.map _index_ _toc_ 'Table Of Contents' /pass _index_ 'Index' /pass > $$.nb_page
# In the last command _index_ is a dummy, but has to be a valid symbolic filename.
echo Meta information ...
dtp meta $$.map > $$.meta
echo Table Of Contents ...
dtp toc \
-title "$lbl -- Table of Contents" \
-desc Modules \
$$.meta \
> $$.toc
dtp gen-toc \
-varfile header $$.nb_toc \
html $$.map $$.toc > $dst/toc.html
echo Index ...
dtp idx \
-title $lbl \
-desc "Keyword index" \
$$.meta \
> $$.idx
dtp gen-idx \
-varfile header $$.nb_idx \
html $$.map $$.idx > $dst/index.html
echo Pages ...
dtp gen-doc \
-varfile header $$.nb_page \
-subst header _toc_ $dst/toc.html \
-subst header _index_ $dst/index.html \
html $$.map $$.meta
rm $$.*
exit
|
In chapter 2 it was said that while documents in the doctoc and docidx formats can be written manually their generation from documents written in doctools is more likely. In figure 7 we find a shell script showing the basics for doing so. This particular script is part of the dtp application and can be extracted from it by executing dtp script. In the future this may be converted into Tcl code and become a regular method of dtp.
The flow of information inside of the script is shown in figure 8. There are three important concepts buried in these figures.
manpage {
desc {Handle text in Emacs ChangeLog format}
fid changelog
file input/tcllib/modules/doctools/changelog.man
keywords {changelog emacs doctools}
module {}
path input/tcllib/modules/doctools/changelog.man
section n
seealso {}
shortdesc {Documentation tools}
title doctools::changelog
version 0.1
}
manpage {
desc {Handle text in 'cvs log' format}
fid cvs
file input/tcllib/modules/doctools/cvs.man
keywords {cvs changelog {cvs log} log}
module {}
path input/tcllib/modules/doctools/cvs.man
section n
seealso {{}}
shortdesc {Documentation tools}
title doctools::cvs
version 0.1
}
|
For one we have the extraction of the metadata from the set of manpages, just another output format from the point of view of the engine. This format is actually a Tcl script by itself. See figure 9 for an example. Here we use it to generate the table of contents of the keyword index, first by generating them in doc*, then converting that into the final output format, here HTML.
The second concept has not been talked about before. All the references to other documents listed in either a table of contents or a keyword index are based on symbolic names and not physical ones, in conformance with the idea that these documents are independent of any output format. And embedding file names which are specific to some output format would destroy this property. This on the other hand means that a generator for a particular output format has to be told how to map from the symbolic to the actual file names. This is the second branch in the data flow, first creating the mapping and then using it anywhere a doc* document is transformed into the final output.
At last the script demonstrates the use of engine parameters. Any engine can export named parameters through which the user can influence its behaviour. In the case of the HTML engine we demonstrate there are mainly three, named meta, header, and footer. When set the engine will assume that their contents are raw HTML and inject them in specific places of the output. Here we use only the header to inject a navigation bar just before the actual contents of any document, be it table of contents, index, or manpage. Another parameter, xref, is not directly visible in figure 7, but internally used by dtp to pass in the information about command and keyword cross references, thus allowing the engine to properly create links which are between manpages, and links between manpages and the index.
At ActiveState a more fancy version of the shown script additionally inserts references to the company's stylesheet as a means of altering the visual appearance of the output without having to modify the engine, and copyright information.
The navigation bar itself also contains symbolic document references which are substituted with the correct reference while formatting each document. This is necessary because the relative position of the document containing the reference and the document referred to can change from document to document. The details of this are described in the command line help for dtp.
