Download and uncompress the latest download from the Sourceforge download area.
Download and install xsltproc if it is not already installed. See installing xsltproc for more information.
If you want to run the command line interface under windows you will need to download and install cygwin, a unix emulator for windows.
If you want to create PDF output, you will need to install a Java Virtual Machine or the Java Software Developers Kit.
The CVS repository does not contain all the required library so you need to download them separately. We have made this easier by providing a simple script which will download and uncompress the libraries for you.
# Check out the code from CVS # press <enter> when prompted for a password cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/generguide co generguide # Download required libraries generguide/bin/install-libs.sh
We have written a CGI interface to Generguide so that it can be driven from a web interface. See http://www.gisontheweb.com:8080/~cameron/cgi-bin/processconfig.pl for an example.
To install generguide for the web, you need to uncompress the generguide.zip into a web viewable directory, then copy the executables into a web executable (cgi-bin) directory.
On unix, you will need to do something like the following:
Example 2. Installing Generguide CGI
cp generguide.zip /var/www/html cd /var/www/html unzip generguide.zip cp /var/www/html/generguide/bin/processconfig.pl /var/www/cgi-bin cp /var/www/html/generguide/bin/generparam.pl /var/www/cgi-bin
You will then need to update the parameters within /var/www/cgi-bin/generparam.pl to set up the relative directories of the generguide URLs.
You may also need to change the execute permissions of processconfig.pl so that it will execute from the web.
If you are running unix or cygwin, you can run generguide from the command line. The scripts are quite simple, so if you are a programmer you may be interested in translating them to windows.
The command line interface is executed by:
generguide/bin/generpublish.sh
This will create a generic guide at generguide/target/developersguide.html.
However you will probably want to tailor the output using a configuration file and output format options. This is what you can do:
Usage: generpublish.sh [-l dir] [-f file] [-t dir] [-o file] [-g dir]
[-p file] [-j] [-d dir] [-C] [-K] [-v] [-V] [-F format]
-f: name of the main file, defaults to developersguide.xml
-h: print this message
-l: local directory of sdocbook files which will overwrite the generic files
-c: the generconfig.xml file which specifies which sections to include
-o: output filename, defaults to the same as main file but with html extension
-t: target directory for published docs, defaults to generguide/target
-g: alternative location of generguide documents
-p: project specific XSL output parameters
-j: use java tools for files processing
-d: directory containing jar libraries necessary for processing with java tools.
-v: be verbose and display what is happening
-V: display version info and exit
-C: do NOT process generconfig files
-F: output file format, default 'html', supported are: 'html pdf xhtml fo',
you can use them together: 'html,pdf,xhtml'
-K: do NOT use local 'CATALOGS' to access DTDs and MODs, environment variable
must keep path to catalogs files i.e.:
SGML_CATALOG_FILES=/etc/xml/catalog:/home/cameron/sgml/catalog
by default CATALOGS are used and local project catalog is included,
containing definition of xinclude.mod
The CGI interface is the easiest way to drive generguide, however it doesn't have all the command line features yet. Hopefully using the CGI Interface is reasonably self explanatory.
See http://www.gisontheweb.com:8080/~cameron/cgi-bin/processconfig.pl for an example.
All the settings for a Guide are stored in an XML configuration file, usually called generconfig.xml. The generconfig.xml file should look something like:
Example 3. Configuration File
<generconfig>
<nodeset href="http://genericdevelopersguide.org/guide/master.xml">
<node id="intro" href="/home/generguide/guide/intro.xml"/>
<node id="code" href="http://gnucodingstandards.org/generguide/code.xml/>
<node id="refactor" filter="EXCLUDE"/>
</nodeset>
<varset>
<var name="projectname" value="My Project"/>
</varset>
</generconfig>Each <node> represents a <section> within the a Generguide section. They are linked with each other by the id attribute. Different properties within the configuration <node> specify how the <section> should be incorporated in the main document.
The <node> id attribute is used to match the corresponding module id tag in the source documentation.
The <node> href attribute is used to replace modules within the source documentation with a different file.
The <node> href attribute over-rides the corresponding href attribute within the <xinclude> tag in the source documentation.
The filter attribute within the <nodeset> and <node> tags determine whether the corresponding module should be incorporated in the target document.
Table 3. Effects of the Filter attribute
| Filter | Meaning |
|---|---|
| BLACK | This section and all child sections with DEFAULT filters will be included in the target documentation. (Child sections need to be BLACK listed with an EXCLUDE filter to be removed.) |
| WHITE | This section will be included but all child sections with DEFAULT filters will be excluded from the target documentation. (Child sections need to be WHITE listed in order to be included in the resultant documentation.) |
| EXCLUDE | This section and child sections will be excluded from target documentation. |
| DEFAULT or not specified | This section will inherit it's filter settings from it's parent. Ie, it will be included if it's parent's filter=BLACK. |
Variables like "project_name", or "cvs_host_directory" can be inserted into source documentation.
In version 0.2 of generguide, variables are implemented using ENTITIES. ENTITIES have deficiencies and we are considering alternative implementations for future releases.
Variables are inserted in documentation using:
<<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE para PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
"http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd"
[
<!ENTITY % xinclude
PUBLIC http://www.ga.gov.au/education/facts/mapproj/se_3_3.htm#map "-//GenerGuide//ELEMENTS XInclude for SDocBook V1.0//EN"
"http://generguide.sourceforge.net/xinclude/1.0/xinclude.mod">
%xinclude;
<!ENTITY % entities
PUBLIC "-//GenerGuide//ENTITIES Customization for GenerGuide//EN"
"resources/entities.ent">
%entities;
]>
<para>This project name is &projectname; </para>
Variables can be stored in entities.ent using something like the following:
<!-- The name of this project -->
<!ENTITY projectname "Generguide">
The chosen format for Generguide Documents is XML that conform to the Simplified Docbook DTD. As such documents are inherently open and standards based in accordance with the recommendations of the World Wide Web Consortium (W3C) and the OASIS Technical Committees.
From an Editor or Authoring Tool perspective this means that Generguide Documents can be created and modified using any XML aware Editor. With no proprietary lock-in at the Editor level, documents are extremely portable and can be freely inter-changed between authors using different XML Editors on different computing platforms.
In general there are two types of XML Editor, those that provide a source-view and those that provide a WYSIWYM editing environment.
Source View Editors provide an environment suited to editing both document and data orientated XML. They come in all shapes and sizes. The more powerful and multi-functional editors are akin to Integrated Development Environments (IDE's). They provide all the support required for editing in range of programming languages, including XML. The editor environment is also hooked or integrated with compilers and other tools. Simpler XML Editors are usually plain text editors with optional plugins that extend the editing functionality but very rarely integrate with compilers and other tools.
Regardless of the editor size and functionality, majority provide a common set of editing aids that make XML source editing easier and faster, like:
Syntax code-coloring
Intelligent code-insight
Auto Tag Completion
There are a number of Open Source XML Editors in the Source View category. All of which should be more than adequate for editing Generguide Documents on any Operating System. The most common and editor for editing document orientated XML is Emacs. When combined with psgmls a helper library, this editor provides powerful XML editing features.
WYSIWYM Editors provide an environment suited to editing document orientated XML. The editor main distinguishing feature between Source View editors and WYSIWYM editors is in the editing space. Where, Source View editors show XML elements and data, WYSIWYM editors use technologies like CSS and XSLT to dynamically display and format text into one rendition of What You See Is What You May Get when the document is transformed to a browser format like HTML. While the presence of the XML source is hidden from view, the document still remains as XML and can be opened and modified either type of editor.
Authors who have traditionally come from a WYSIWYG editing environment, generally find WYSIWYM easier to work with than Source View.
The problem with WYSIWYM is that there are very few editors capable of editing documents in a manner that does not automatically write changes to the XML file structure in order to accommodate deficiencies in the editor. At time of writing, three WYSIWYM Editors where identified as nearly meeting the requirement:
XXE is currently our prefered WYSIWYM editor. It can be downloaded at no cost, has an impressive WYSIWYM interface, is java based and hence cross platform and handles Modular Documents.
Version 2.4 of XXE does not handle Generguide's use of ENTITIES for variables. To work around this problem, we have written a script called comment_ent.sh which comments/uncomments ENTITIES. You can run the script before and after editing a file.
Another java XML editor. Version 3.1.3 is not as polished as XXE.
This is built on top of Gnome, and hence is a linux based docbook editor. At the time of writing, Conglomerate was still in alpha development but looks promising.