| | h1. Building the Reference Documentation |
| | |
| |  | The flexive reference documentation is written in [DocBook 5|http://www.docbook.org/]. The source files are stored in the flexive source tree under {{docbook/src}}. |
| | | The flexive reference documentation is written in [DocBook 5|http://www.docbook.org/]. 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}}. |
| | |
| | {toc:minlevel=2} |
| | |
| | |
| | h2. Prerequisites |
| | |
 | | * Install the DocBook stylesheets. |
| | ** On Ubuntu/Debian, use: |
| | {code} |
| | sudo apt-get install docbook docbook-xsl |
| | {code} |
| | ** On Windows, you have to install the DocBook XSL files by yourself. You might want to take a look at [http://www.dpawson.co.uk/docbook/tools.html#d994e814]. |
| | * Optional: Install xsltproc for faster XSL processing. Otherwise, a pure Java XSL processor (Saxon with Xerces) will be used. |
| | ** On Ubuntu/Debian, use: |
| | {code} |
| | sudo apt-get install xsltproc |
| | {code} |
| | ** On Windows, follow the [instructions for installing Libxml|http://www.zlatkovic.com/libxml.en.html]. |
| | * In your flexive source tree, copy {{docbook/build.properties.sample}} to {{docbook/build.properties}} and set the root directory of your DocBook XSL installation. You can ignore the {{xsltproc}} command if you don't want to use xsltproc. |
| | | * 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. |
| | {code} |
| | docbook.styles.dir=/usr/share/xml/docbook/stylesheet/nwalsh |
| | xsltproc=xsltproc |
| | {code} |
| | |
| | h3. Windows instructions |
| | Either download the respective packages from [http://www.dpawson.co.uk/docbook/tools.html#d994e814] and [http://www.zlatkovic.com/libxml.en.html]. |
| | Optionally a pre-packaged zipfile with everything needed can be downloaded [here|^docbook_windows.zip]. |
| | If you unzip [^docbook_windows.zip] in {{C:\develop\docbook}} an appropriate build.properties file would look as follows: |
| | {code} |
| | # Directory containing the standard docbook styles |
| | docbook.styles.dir=C:/develop/docbook/xsl |
| | # The xsltproc command (including the path, if necessary) |
| | xsltproc=C:/develop/docbook/xsltproc |
| | {code} |
| | |
| | |
| | h2. Generating HTML output |
| | |
| | * In your flexive directory, cd to {{docroot/}}. |
| | * Compile the documentation using: |
| | ** {{ant}} (with Saxon/Xerces - should always work, but is considerably slower than the next option) |
| | ** {{ant book-xsltproc}} (with the external xsltproc tool) |
| | * Currently, the HTML document is not packaged. It is available in the build directory under {{build/book/xhtml}}. |
| | | ** {{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) |
| | |
| | h2. Hints/tips for working with DocBook |
| | |
| | h3. 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. |
| | |
| | h3. Setup IDEA for syntax completion |
| | |
| | IntelliJ IDEA 7 provides autocompletion for all docbook tags. |
| | # Go to _File --> Settings --> Resources_. |
| | # In _Configure External Resources_ click _Add..._ |
| | # In the _URI_ field enter: {{http://docbook.org/ns/docbook}} |
| | # In the _Path_ field select the {{src/docbook5.xsd}} file in your flexive directory. |
| | # Click _OK_. |
| | # You may need to close an XML editor before the new settings take effect. |
| | |
| | h3. Using the Eclipse XML Editor |
| | |
| | # Install the [Eclipse IDE for Java Developers|http://www.eclipse.org/downloads/]. |
| | # Open Eclipse |
| | # Install [Subclipse|http://subclipse.tigris.org/install.html] for Subversion support |
| | # _File -> New Project..._ |
| | # Select _SVN -> Checkout Projects from SVN_ |
| | # Repository URL: {{http://svn.flexive.org/repositories/flexive}} |
| | # Checkout the trunk directory, select _Checkout as a project in the workspace_ |
| | # _Window -> Preferences -> Web and XML -> XML Catalog_ |
| | # Click _Add..._ |
| | ## _Location -> Work space_: Select {{docbook/docbook5.xsd}} |
| | ## _Key type:_ Namespace Name |
| | ## _Key:_ {{http://docbook.org/ns/docbook}} |
| | ## _OK_ |
| | # Open a DocBook XML file from {{docbook/src}}. |
| | # If you have docbook installed, you can generate the documentation by right-clicking on {{docbook/build.xml}} and choosing _Run As -> Ant Build_. |
| | |
| | |
| | h3. 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 |
| | {code} |
| | <!ENTITY flexive "flexive3"> |
| | {code} |
| | every time you write "{{&flexive;}}" in your XML file, it is replaced with "flexive3". |
| | |
| | h3. Adding chapters |
| | |
| | You have to create a new XML file that includes our custom entities, e.g. |
| | {code:xml|title=newchapter.xml} |
| | <?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> |
| | {code} |
| | |
| | To include the chapter in the reference documentation, you have to add it at the appropriate position in book.xml using |
| | {code:xml} |
| | <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="newchapter.xml"/> |
| | {code} |
| | |
| | |
| | h3. Useful links |
| | |
| | * [The DocBook Website|http://www.docbook.org/] |
| | * [DocBook: The Definitive Guide|http://www.docbook.org/tdg5/en/html/docbook.html] |
| | * [The KDE DocBook Authors Guide|http://l10n.kde.org/docs/markup/index.html] |
| | * [Dokumentationen mit DocBook-XML|http://www.goshaky.com/docbook-tutorial/index.html] |
| | * [Writing with DocBook elements|http://www.ibiblio.org/godoy/sgml/docbook/howto/writing-docbook.html] |
