next up previous
Next: Limitations Up: (doc)Tools for a new Previous: Formatting engines


Indices and Table Of Contents


Table: TOC and Index generation
#!/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.


Table: Dataflow in gendoc.sh

The flow of information inside of the script is shown in figure 8. There are three important concepts buried in these figures.


Table: Excerpt of extracted meta data
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.


next up previous
Next: Limitations Up: (doc)Tools for a new Previous: Formatting engines
[email protected]