Chapter 10. Documentation Generation

Table of Contents

Introduction
Abridged Chapter
Commands and Commentary
Packages
Module

The module tcldumper.tcl contains all code fragments, from which Tcl/Tk sources, wrappers (Lisp for example) and the documentation are generated.

»tcldumper« is organized in »namespaces«. The first namespace is called »dumper«, this namespace contains the code fragments for the code generation. »dumper« may contain child namespaces, currently »lisp« and »docbook« . The »lisp« namespace holds the code fragments for lisp wrappers. The DocBook namespace contains the documentation fragments.

The general aspects of »tcldumper.tcl« are irrelevant for documentation and thus are not further discussed in this chapter.

Chapter 10, Documentation Generation deals with the namespace dumper::docbook alone.

Elements of namespace docbook

options

This procedure walks through a list of property names and split them into »standard« and »specific« properties. Both lists are returned to the caller.

standard

Internal used by refentry.

Generates a »varlistentry« »term« for the given standard property.

describeProperty

These prototype will be used during definig the interface .



specific

The procedure »specific« generates »varlistentry«, »term« for a non-standard property.

This procedure works contextual: It analyses the DocBook directory identified by vgfile::docbookDirectory for a XML-file named identical to the given property. Also sub-directories are searched for a description.

In cases were it was impossible to locate a property description: An undocumented section gets generated. Again describeProperty is being deployed to format this block.

describe

»describe«, extracts the description for a given command. This procedure operates with the following procedures startcommentary, endcommentary, Example 10.3, “startproc”, Example 9.8, “Proc Commentary”, Example 10.4, “endproc”.

In addition, it tries to locate examples describing the given command inside the chosen DocBook directory. The method is the same as with specific used for properties. Only, the file ending is set to the project type. Any external example is then directly embedded in the DocBook document. This is necessary to allow syntax highlighting for the example.

startproc

This procedure returns a format description, which is being used to identify the begin of a procedure commentary.

The current implementation of »startproc« parses the projects source code for commentaries following Example 9.8, “Proc Commentary”.

The returned format string contains two string substitutions: »%1$s« and »%2$s« resembling »template namespace« and »procedure name«.


endproc

»endproc« is the companion of Example 10.3, “startproc”

First startproc is used to identify where the commentary for the procedure is located; then »endproc« to find the end of the commentary.

»%1$s« and »%2$s« resemble »template namespace« and »procedure name«, as with Example 10.3, “startproc”.


startcommentary

Identifies the string preluding the description for the procedure in question. This string is »# Description : «.

After a header commentary was isolated, using Example 10.3, “startproc” and Example 10.4, “endproc”, the commentary itself is analyzed. That is the Revision history and the description is extracted from the commentary.


The procedure Example 10.5, “startcommentary” is used to search for the begin of a description. Here a word sequence is searched. Everything else is either part of the description or belongs to the revision of that procedure.

Empty lines are interpreted as separators between paragraphs. The description itself is transformed into as many paragraphs as indicated.

Entities, and the <, > and & tokens may occur inside the description. An entity is preserved as such –can be used! While the other tokens are transformed.

Some additional DocBook sequences may also appear inside a commentary.

endcommentary

identifies the string inside the Example 9.8, “Proc Commentary”, where the description, identified with: startcommentary ends.

The current endcommentary is: »Written : «. Starting with this string and everything following it inside the Example 9.8, “Proc Commentary” is interpreted as the revision history of the command.

This procedure searches for the begin of the revision history of this procedure. A simple text mark is used as the indicator. Everything after the initial revision mark to the end of the description is assumed to contain revision information. These Information is not used inside the generated document.

Revision History

The revision history is subject to change. The idea is it to generate DocBook revision informations from it.


entities

The entities procedure holds the prototype for the doctype declaration of a refentry.

The generated doctype definition is disabled, because I assumed the generated documents will belong to a master document.


refentry

refentry is the beating heart of Jeszra’s DocBook generation. This procedure uses every part, described above, and integrates it into a full refentry document. The refentry document is embedded within this procedure. Which is why I skipped it here, it would otherwise fill several pages.

When Jeszra moves to DocBook 5.0 the document will be assembled as a DOM-tree replacing the refentry procedure.

masterDocument, Container

The procedures »container« and »masterDocument« are used to tell XAE where it will find the master document and what kind (container) it is.

These two procedures do not influence the generated DocBook contents at all!

cleanseUnicodeGeometry

The unicode standard defines a series of geometric shapes. These glyphs are used to identify embedded examples inside of header comments.

The pair 0x250F (Box Drawings Heavy Down And Right), 0x2517 (Box Drawings Heavy Up And Right) generate a programlisting block encapsulated inside of an example.

The pair 0x250C (Box Drawings Light Down And Right), 0x2514 (Box Drawings Light Up And Right) generate a stand-alone programlisting block.

Other geometric shapes between these two basic shape-pairs are removed from the generated DocBook document. »cleanseUnicodeGeometry« is responsible to remove the unicode geometry shapes.

allowTags

DocBook tags can be used inside of header comments. »allowTags« controls which DocBook pairs are allowed. Embedded DocBook Tags:, lists each allowed tag.

I would have liked to also include tags for <xref/>, <link/>, <ulink/> and <link/>. This is not possible, since the closing of these tags is ambiguous.

This chapter is abridged. The full text is available in printed form or as a PDF from: www.lulu.com.