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 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

Additional steps for editing and committing documentation

• Needed 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 (Oxygen is available from iuware for those at IU, may be available through other universities also)

...

• 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, once per day run
      

      1. svn updatebe sure it is up to date

      2. mvn clean install -DskipTests=true

   2. Each time, to test 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 > pdf, html or html-multi.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.

DocBook Notes

I typically use the GUI (author mode) of oXygen to modify DocBook and I display full tags with attributes when I am editing (so that I do not accidentally put text in the wrong location).

The structure for OLE

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

Adding a Book or Article

The simplest way to add a new book or article is to look in the books folder and copy a similar file and change the pertinent information. New books or articles need to be in the books folder to be processed at build time.

Adding a Chapter to a Book

1. The simplest way to add a new chapter is to copy a chapter file in an existing book and change the pertinent information.
   For example: copy "batchAdministrativeDocuments" in the "admin-guide" folder and make modifications
2. Add the new chapter file to the top level book file in the books directory.
   For example: In the "books" folder, open "ADMIN".  Viewing the xml, add an additional "<xi:include xmlns:xi..." statement that includes the new chapter name.  Be sure to keep the new chapter in order: for OLE, we are maintaining the documentation to keep in order of the columns within each tab.

Adding Sections

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>
   <title>Section Level One</title>
      <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:

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

    

   Image Removed

   Make sure the image is sized properly by building the HTML 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 fileref="../images/EDL_Guide/example1.png" width="100%"/>

    -OR-

   <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).  The second is for any smaller images, smaller than what would fit in the pdf document.  Sometimes you really just have to test locally to see how things fit.

Creating Hyperlinks

In DocBook 5, the preference is to have xlinks for hyperlinks. If you use the oXygen GUI (author view) to add the link, you'll need to right-click on the link and add the xlink:href property with the url of your link as the value.

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

 <link xlink:href="../html/ADMIN.html#_Describe_Workbench">Describe Workbench</link>

Note: In the above example, this presumes we have the following within the CG 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 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>

Then link to it from anywhere within the same book, with the auto generated figure number and given title "My Figure" as follows:

The SOA architecture is depicted in <xref linkend="fig1"></xref>.

The above text will be rendered as (something like)

The SOA architecture is depicted in Figure 1.1, "Service Based Architecture".

(except that the figure number may be different depending upon the context, since it is dynamically generated)

Tables

Using "CALS" tables instead of "HTML" tables appears to produce better looking output if you want a table with borders.

1. Adjust the heading, frame and column data:

   <para role="TableHeading"><emphasis role="bold">Location Information tab definition</emphasis></para>

   <informaltable frame="top">

   <tgroup cols="2">

   <colspec colname="col1" colnum="1"/>

   <colspec colname="col2" colnum="2"/>

2. Make sure that the "rowsep" and the "colsep" both equal 1
   

   <row>

   <entry colname="col1" colsep="1" rowsep="1" valign="top">

   <para role="Table Cells">Title</para>

   </entry>

   <entry colname="col2" colsep="0" rowsep="1" valign="top">

   <para role="Table Cells">Description </para>

   </entry>

   </row>

3. Generate and review the PDF and webhelp output, and make any further adjustments

Lists

There are 4 types of lists available.  From Oxygen's GUI, these lists are easily created at the push of an icon - exactly the same way as Microsoft Word.

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, Rich, Jain and Megan were trained to use Oxygen to update DocBook in November 2013.

Update notes- tasks to do with each release

1. review the screens - see what links have been added or removed.  Verify they were intended to be removed and not just removed accidentally.
2. List out changes and additions that will need to be written/modified.  Use OLE Current Release Status Report and note changes when reviewing screens
3. Update docbook - menu tab images, menu lists, location of sections.  Maintenance documents will remain with their rightful DocBook.

References

...

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