Building the Reference Documentation

The flexive reference documentation is written in DocBook 5. The source files are stored in the flexive source tree under docbook/src. The stylesheets are stored in the source tree under docbook/resources/docbook-xsl.zip.

Prerequisites

• Optional: Install xsltproc for faster XSL processing. Otherwise, a pure Java XSL processor (Saxon with Xerces) will be used.
  • On Ubuntu/Debian, use:

    sudo apt-get install xsltproc

  • On Windows, follow the instructions for installing Libxml.
• In your flexive source tree, copy docbook/build.properties.sample to docbook/build.properties. You can ignore the xsltproc command if you don't want to use xsltproc.

  xsltproc=xsltproc

Generating HTML output

• In your flexive directory, cd to docroot/.
• Compile the documentation using:
  • ant (builds all documentation packages with Saxon/Xerces - useful for distribution, but may be too slow for development)
  • ant book-xsltproc (compiles only the single-page XHTML file with xsltproc)

Hints/tips for working with DocBook

Overall structure

All source files reside in docbook/src. The main book file is book.xml which includes all chapters using XInclude. For example, intro.xml contains the introduction.

Setup IDEA for syntax completion

IntelliJ IDEA 7 provides autocompletion for all docbook tags.

1. Go to File --> Settings --> Resources.
2. In Configure External Resources click Add...
3. In the URI field enter: http://docbook.org/ns/docbook
4. In the Path field select the src/docbook5.xsd file in your flexive directory.
5. Click OK.
6. You may need to close an XML editor before the new settings take effect.

Using the Eclipse XML Editor

1. Install the Eclipse IDE for Java Developers.
2. Open Eclipse
3. Install Subclipse for Subversion support
4. File -> New Project...
5. Select SVN -> Checkout Projects from SVN
6. Repository URL: http://svn.flexive.org/repositories/flexive
7. Checkout the trunk directory, select Checkout as a project in the workspace
8. Window -> Preferences -> Web and XML -> XML Catalog
9. Click Add...
   1. Location -> Work space: Select docbook/docbook5.xsd
   2. Key type: Namespace Name
   3. Key: http://docbook.org/ns/docbook
   4. OK
10. Open a DocBook XML file from docbook/src.
11. If you have docbook installed, you can generate the documentation by right-clicking on docbook/build.xml and choosing Run As -> Ant Build.

Custom Entities

Custom entities are useful for defining global text blocks, e.g. the exact product name. The definitions are stored in docbook/src/global.ent. For example, by defining

<!ENTITY flexive "flexive3">

every time you write "&flexive;" in your XML file, it is replaced with "flexive3".

Adding chapters

You have to create a new XML file that includes our custom entities, e.g.

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE chapter [
        <!ENTITY % global_entities SYSTEM "global.ent">
        %global_entities;
        ]>
<chapter id="newchapter" xmlns="http://docbook.org/ns/docbook">

</chapter>

To include the chapter in the reference documentation, you have to add it at the appropriate position in book.xml using

<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="newchapter.xml"/>

Useful links

• The DocBook Website
• DocBook: The Definitive Guide
• The KDE DocBook Authors Guide
• Dokumentationen mit DocBook-XML
• Writing with DocBook elements