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 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 (for html)
   Example:

   Code Block
   <link xlink:href="../html/releaseNotes.html">HTML</link> <link xlink:href="../pdf/releaseNotes.pdf">PDF</link>

   For webhelp, when linking FROM the index page (which follows the html format), links appear the same way

   Code Block
   <link xlink:href="../webhelp/ADMIN/index.html">Webhelp</link>

   However IF you are inserting a link from webhelp back to the index page or to another webhelp space, format is

   Code Block
   <link xlink:href="../../../html/Index.html"> <link xlink:href="../../../webhelp/BASICS/index.html">OLE Basic Functionality and Key Concepts</link>

3. 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">

4. Created an index page

...

1. 1. Enter your local OLE directory, once per day run

      1. svn update

      2. mvn clean install -DskipTests=true

   2. Each time, to test type "mvn clean pre-site -N". 

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

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

DocBook Notes

...

1. Sections are added with the <section> tag.
2. Sections can be nested within sections.

3. Each section has a title. The structure is as follows:

   <section>

   Code Block
   <section> <title>Section Level One</title>

   
      <section>
      <title>Section Level Two</title>
      </section>
   

   <section> <title>Section Level Two</title> </section> </section>

4. Depending on the level, sections will usually appear in the table of contents.

5. To prevent a section from appearing in the table of contents, use this construct:

   Code Block

   <section

   <section role="NotInToc"><title>Do Not Show In TOC</title>

Adding an Image File

1. Create the image file and add to the images directory.

2. Use oXygen to link to the image file and you should be able to navigate to the image file in the GUI and the path will be generated for you. Image paths should be relative, i.e. "../images/image_name.png" and use underscores instead of spaces since they are more web friendly.

    

   Make sure the image is sized properly by building the HTML webhelp and PDF versions and ensuring that they show up ok (I mentally calculate the depth for approximately 50% of the image's original size but do not state any width). Improperly sized images can look pretty bad, especially in the PDF output. Tools like Gimp are free and can be used to do the resizing.

3. Image files are inserted this ways into docbooks.

    <inlinemediaobject><imageobject><imagedata

   Code Block
   <inlinemediaobject><imageobject><imagedata fileref="../images/EDL_Guide/example1.png" width="100%"/>

    -OR-

   <inlinemediaobject><imageobject><imagedata

   Code Block
   <inlinemediaobject><imageobject><imagedata fileref="../images/EDL_Guide/example1.png"/>

    

   The first example is for larger images (anything that looks like it will be too big to fit in a pdf document (8.5 x 11) comfortably)wider than a 1/2 sheet of 8.5x11 sheet of paper).  The second is for any smaller images, smaller than what would fit in the pdf document.  Sometimes you really small images.  You really just have to test locally to see how things fit.

...

Links to external documents (in a different module) within a release should be entered like this :

...

<link xlink:href="../../

...

../webhelp/BASICS/content/ch02s04.html#_Describe_

...

Workbench>OLE Search Workbench</link>

Note: In the above example, this presumes we have the following anchor within the CG BASICS books:

<section xml:id="_Describe_Workbench">

Links to internal documents (i.e. another section of the same module/chapter) should be entered as:

 <link linkend="_Editors">MARC Editor</link>

where elsewhere the anchor exists somewhere else in the document there exists:

 <section xml:id="_Editors">

...

To link to a figure, set up the figure to have an xml id as follows:

 <figure xml:id="fig1"><title>Service Based Architecture</title>

...