DocBook as OLE help - pdf, html

1. Peri worked with Jeff to add the documents to SVN. See Developing Rice DocBook Documentation
   (Kuali OLE follows Rice and is currently using the DocBook 5 format for documentation and the docbkx-maven plugin to generate the documentation as part of our maven build.)
2. Needed to change the image file references to ../images/filename.png and reference files to ../html/linkname

3. Separated out the chapters into individual xml files and pasted the docbook document type declaration in the chapter element:

   <chapter xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" version="5.0"
       xml:lang="en-US">

4. Created an index page

The structure exists as:

docbook folder in trunk contains

• guide folders (one per module)
  
  • chapters for each submenu in OLE
  • chapters for Introductions
  • chapters for appendixes
• images
• books
  • Index
  • one book per tab/module (these books contain the links to each chapter)
  • overviews are also included

Additional steps

• Needed to complete a CLA (on the Subversion wiki page)
• Needed to complete OWASP training
• Checked out the project via Oxygen (Oxygen is available from iuware for those at IU, may be available through other universities also)

1. 1. Tools >SVN client > Repository > host: https://svn.kuali.org/repos/ole > currently, the project is in branches/kole-1.0.0-Docbook/src/site/docbook
   2. Checked out to local computer
   3. Modify
   4. Check back in through Tools > SVN client > working copy > Refresh, then right click copy and "commit"

Modifying and keeping current

To continue updating DocBook:

OLE is tagged for a release and the code along with the documentation cannot be updated.  However, SMEs continue to work on updates past this point.  SMEs are updating via Google Docs.  The instructions are listed in Documentation Templates and Guides.  Once complete, I make these changes in DocBook.  When all changes are completed, Peri and I will figure out a way to update the 1.0 material, probably by a 1.0.1 patch.

In the meantime, I will be training Rich and Jain on DocBook as back-ups.

DocBook as built-in help

Peri is working to create webhelp from DocBook.  Currently images are not displaying.  It is our intent to have the webhelp pages linked with OLE.

References

• DocBook: The Definitive Guide - clear, concise, normative reference to the DocBook DTD,the official documentation for the DocBook DTD
• docbook.org - main DocBook site
• DocBook XSL: The Complete Guide - definitive guide to DocBook stylesheets
• DocBkx Maven Plugin - reference for the plugin used to generate the DocBook docs, anything usually run as a command line option is set in maven
• DocBook Quick Reference put together by the Ubuntu community