Generguide Design

Build Executables

CGI Publishing

The generguide tools can be driven from web pages and CGI scripts.

Figure 4. CGI Publishing Flowchart

CGI Publishing Flowchart

Processing goes through the following web pages:

Config Selection

User select sections from web forms.

Target Documentation

Target documentation is dynamically built and displayed in a web page.

Command Line Publishing provides command line publishing for unix/linux/cygwin systems.

Figure 5. Command Line Publishing Objects

Command Line Publishing Objects process uses the following steps:

  1. Modules from the Generic Guide are copied into a temporary build area.

  2. Project Modules are copied into the temporary build area, sometimes overwriting Generic Modules.

  3. Merge all the Docbook modules into one document by processing all the <xi:include> tags.

  4. Publish the master Docbook document into the target format (usually html).

Build Components is a CGI script which builds the web selection form, or the target documentation.

Configuration Selection web page

This web page contains two forms:

Configuration Selection form

This form allows a user to change attributes all the <xinclude> tags from Generguide Sections. Whenever a user changes an attribute, the generconfig.xml form is updated using javascript in form.js.

generconfig.xml form

generconfig.xml is rebuilt dynamically by functions in form.js. The functions uses stripdefaults.xsl to remove any default filters from generconfig.xml.

The configuration selection web page is built by toform.xsl.


toform.xsl builds the Configuration Selection html form. It is built from Generguide sections, and a previous generconfig.xsl. The processing involves:

  1. Parse Generguide sections, selecting <xinclude> and <section> tags.

  2. Print <xinclude> and <section> titles.

  3. For <xinclude> tags, search generconfig.xml for the <xinclude> id and determine what attributes should be printed.


selectivcexinclude.xsl selectively includes <xinclude> nodes from generguide sections based on the filter rules in generconfig.xml.

It is used when publishing generguide sections.


Removes unnecessary nodes from generconfig.xsl. Used by form.js.


form.js provides functions to dynamically update the generconfig.xml form as the user updates the Configuration Selection Form. Uses stripdefaults.xsl to remove unnecessary nodes from generconfig.xml.


Sarrissa.js provides cross browser compatibility for XML javascript functions.

Generconfig Sections

Refer to section the section called “Modular documentation”.

XSLT and XSL-FO Processor

Generguide uses XSLT and XSL-FO processors to convert documents from Docbook XML to published formats. Processors easily be interchanged.


xsltproc is a XSLT processor written in C and can hence be installed and executed (on both unix and windows systems) without requiring Java. This is particularly useful for the web based processing as many ISPs do not support Java. xsltproc is the easiest XSLT processor to use if you just want to produce HTML output.


saxon is a XSLT processor written in Java. This processor should be used instead of xsltproc if you want XHTML or PDF output.


FOP is a XSL-FO processor written in Java. FOP is used to create PDF output.

Documentation Format

Initial versions of generguide support Simplified Docbook. In future other formats may be supported as well. In particular, Docbook XML.

Docbook XML

Docbook XML is a versatile, open format used by the Linux Documentation Project (among others).

According to The Software Release's Howto, Docbook is the open source format of the future, and most of the high profile open source projects have moved or are moving to Docbook as their documentation standard.

Using Docbook ensures documentation content is kept separate from presentation so content can written once and published in numerous formats and styles.

Docbook can be easily converted into numerous output formats, like HTML, PDF, etc.

Simplified Docbook

Simplified Docbook is a subset of Docbook XML, a versatile, open format used by the Linux Documentation Project (among others).

Simplified Docbook is often preferable to Docbook XML.

  • The reduced tag set ensures a short learning curve for potential editors.

  • The tag set is sufficient for the majority of technical writing tasks.

WYSIWYM Docbook Editors

There are a few What You See Is What You Mean (WYSIWYM) editors for Docbook now, however there are not any no-cost editors which support all generguide requirements yet.

The most promising editor to date is XXE. XXE is a semi-free WYSIWYM Docbook editor. Version 2.4 of XXE offers reasonable support for generguide <xi:include> tags, however generguide ENTITIES are not supported properly. XXE can read documents with ENTITIES but not write.

Conglomerate is building an open source Docbook editor which looks promising.

Modular documentation

Content of the Generic Guide is stored in numerous files which is recombined during publication.

Each file contains a Docbook node. For instance, one file might contain a section for Java Coding Standards. Files can only contain section or article tags as the master nodes. (Our XSLT doesn't support other master tags yet).

Modules can include modules from other files using <xi:include> tags. For instance, the main guide.sgml file will use numerous <xi:include> tags to include sections for the rest of the Guide.

Example 4. Including sections into a master document

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
    <title>Software Developers Guide</title>

  <section id="scope">

    <xi:include xmlns:xi=""

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
<section id="licence">

  <para>Copyright (c) 2002 Cameron Shorter. Permission is granted to copy,
  distribute and/or modify this document under the terms of the <ulink
  url="">GNU Free Documentation License</ulink>,
  Version 1.1 or any later version published by the Free Software Foundation;
  with the Invariant Sections being with no Invariant Sections, with the
  Front-Cover Texts being no Front-Cover Texts, and with the Back-Cover Texts
  being no Back-Cover Texts.</para>

Notice in the above example that <section> tags contain an id attribute. This means the URL of sections will be human readable, something like instead of

Advantages of modular documentation include:

  • Reusable content units.

  • Smaller file units to load into an editing program.

  • Distributed authoring.

  • Finer grain version control.

To do: If a file uses <xlink url="some_other_file.xml"> to reference another file, the first file will be invalid xml. This is not desirable, and we need to revisit this later.


Within a section, we need to be able to specify variable names, like "project_name", or "cvs_host_directory", etc.

Variables are currently implemented using ENTITIES. Refer to the Users Guide for implementation details.

We don't know whether ENTITIES are the best way to implement variables. ENTITIES have problems in that they are not stored as XML and hence many XML based editors have problems with them.

Configuration file

Generguide can be configured with a configuration file. The structure of the configuration file is explained in the Users Guide.

Documentation Contents

Authors of sections can be credited if the so wish using the tags:


Generguide section structure describes how sections should be structured.

Docbook References

There are a few references worth knowing: