Page Comparison

DocBook as OLE help - pdf, html, webhelp

1. Peri worked with Jeff to add the documents to SVN. See Developing Rice DocBook Documentation
   (Kuali OLE followed 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.)
   The difference between OLE and Rice documentation is that OLE has decided to use Webhelp output for our documentation whereas Rice uses only HTML.  See the plugin documentation here: http://docbkx-tools.sourceforge.net/docbkx-maven-plugin/plugin-info.html.

2. Needed to change the image

   file references to

   links.  <Inlinemediaobject> is for images that occur within text.  <screenshot><mediaobject> is for images that occur on their own line, separated from the text.
   Example:

   Code Block
   <inlinemediaobject> <alt>Location Level</alt> <imageobject> <imagedata fileref="../images/

   filename.png and reference files to ../html/linkname

   DescribeNoTitlePage-178.png"/> </imageobject> </inlinemediaobject> Or <screenshot><mediaobject> <alt>Location Level Document</alt> <imageobject> <imagedata fileref="../images/DescribeNoTitlePage-179.png" width="100%"/> </imageobject> </mediaobject> </screenshot>

3. Set up links to other webhelp space, link to the anchor like this:

   Code Block
   <link linkend:href="_searchingOLE">Searching OLE</link>

   This assumes that you have an anchor at the space

   Code Block
   <anchor xml:id="_searchingOLE"/>

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

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

5. 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)

Additional steps

...

Additional steps for editing and committing documentation

...

• Need to complete a CLA (on the Subversion the License Agreement Process (CLA/CCLA) wiki page)
• Needed to complete OWASP training
• Checked out the project via Oxygen

1. 1. Tools >SVN client > Repository > host: http://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.

• Have editing software - it is xml so you could use a simple text editor but with the images, Oxygen is recommended.
• Fork the project into your own GitHub repository and pull updates (see OLE development using Github)

• Once saved but before committing, you can view changes locally through the command line. 

1. 1. Enter your local OLE directory
      

      1. be sure it is up to date

      2. mvn clean install -DskipTests=true

   2. To test your updates, type "mvn clean pre-site -N". 

   3. To view the changes, open Windows Explorer or Finder and dig into the correct folder: your local OLE directory > target > site > reference > webhelp

DocBook as built-in help (webhelp)

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.had to do some modifications to get the webhelp to display correctly.  We had to modify images and tables to get them to display correctly.  Webhelp pages are now linked with OLE.

See the plugin documentation: http://docbkx-tools.sourceforge.net/docbkx-maven-plugin/plugin-info.html