The generguide tools can be driven from web pages and CGI scripts.
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.
generpublish.sh provides command line publishing for unix/linux/cygwin systems.
generpublish.sh process uses the following steps:
Modules from the Generic Guide are copied into a temporary build area.
Project Modules are copied into the temporary build area, sometimes overwriting Generic Modules.
Merge all the Docbook modules into one document by processing all the <xi:include> tags.
Publish the master Docbook document into the target format (usually html).
processconfig.pl is a CGI script which builds the web selection form, or the target documentation.
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:
Parse Generguide sections, selecting <xinclude> and <section> tags.
Print <xinclude> and <section> titles.
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.
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.
Refer to section the section called “Modular documentation”.
Generguide uses XSLT and XSL-FO processors to convert documents from Docbook XML to published formats. Processors easily be interchanged.
- xsltproc
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
saxon is a XSLT processor written in Java. This processor should be used instead of xsltproc if you want XHTML or PDF output.
- FOP
FOP is a XSL-FO processor written in Java. FOP is used to create PDF output.
Initial versions of generguide support Simplified Docbook. In future other formats may be supported as well. In particular, 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 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.
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.
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
- guide.sgml
<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN" "http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd"> <article id="guide"> <articleinfo> <title>Software Developers Guide</title> </articleinfo> <section id="scope"> <title>Scope</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="doclicense.sgml"/> </section> </article>- doclicense.sgml
<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE section PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN" "http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd"> <section id="licence"> <title>License.</title> <para>Copyright (c) 2002 Cameron Shorter. Permission is granted to copy, distribute and/or modify this document under the terms of the <ulink url="http://www.fsf.org/copyleft/fdl.html">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> </section>
Notice in the above example that <section> tags contain an id attribute. This means the URL of sections will be human readable, something like http://geotools.org/gt2docs/design.html#licence instead of http://geotools.org/gt2docs/design.html#id2754172.
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.
Generguide can be configured with a configuration file. The structure of the configuration file is explained in the Users Guide.
Authors of sections can be credited if the so wish using the tags:
<section>
<sectioninfo>
<authorgroups
<author>...</author>
</authorgroup>
</sectioninfo>
...
</section>Generguide section structure describes how sections should be structured.
There are a few references worth knowing:
The Linux Documentation Project Author Guide provides an introduction to Docbook and some of the key tags. Don't worry about the sections on tools for converting Docbook as geotools uses the maven build process instead. Note that the geotools uses Simplified Docbook which is XML based. There are various versions of Docbook which makes things confusing.
The Simplified Docbook Summary provides a list of all the XML tags you can use, and the dependency between these tags.
Simplified Docbook, the Definitive Guide provides comprehensive documentation about all the Simplified Docbook tags.
Using the Docbook XSL Stylesheets, in particular, the section on writing modular docbook files.
Xincluder is a Java open source project for processing xinlcude tags, which might be able to be used to by maven to publish modular Docbook documents.