Any XML editor will work to edit DocBook.  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 or tags in the wrong location).

The structure for OLE

docbook folder in trunk contains

• guide folders (one per module)
  • 1 chapter per module, [module name]All.xml
• images
• books
  • OLE.xml is the book for OLE

Adding a Chapter to OLE's 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.
2. Add the new chapter file to the top level book file in the books directory.
   For example: In the "books" folder, open "OLE.xml".  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. To link to the section from another place in the documentation or for the help links, be sure to include an anchor in the title

   <section>
               <title><anchor xml:id="_Statistical_Category"/>Statistical Category</title>
               <para role="Body Text">...

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

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

    

   Make sure the image is sized properly by building the webhelp and PDF versions and ensuring that they show up ok. 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>
        <alt>Statistical Category Lookup</alt>
             <imageobject>
                  <imagedata fileref="../images/DeliverNoTitlePage-133.png"/>
             </imageobject>
   </inlinemediaobject>

    -OR-

   <screenshot>
      <mediaobject>
           <alt>Patron Statistical Category Document</alt>
           <imageobject>
               <imagedata fileref="../images/DeliverNoTitlePage-176.png"
                width="100%"/>
           </imageobject>
      </mediaobject>
   </screenshot>

    

   The first example is for smaller images that would fit inline with the text.  The second is for larger images that would be on their own lines and not in line with text.  If you image is not that big but should be on its own line, do not include the "width="100%"
   FYI: The alt tag is added for accessibility.  In webhelp outputs, the tag will also be displayed in the mouse-over.

Creating Hyperlinks

Links to internal documents (i.e. another section of OLE's guide) should be entered as:

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

where the anchor exists somewhere else in the OLE.xml document (you will get validation errors when creating the chapters if the anchor is not in the same chapter however this will correct itself in the build):

 <anchor xml:id="_Editors"/>

Functionality that has not yet been used in OLE but could be:

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="topbot">
   <tgroup cols="2">
   <colspec colname="col1" colnum="1"/>
   <colspec colname="col2" colnum="2"/>
   <tbody>
   <row>...

2. Make sure that the "rowsep" and the "colsep" both equal 1.  Be sure that the entry text is wrapped in a paragraph tag.

   <row>
       <entry colname="col1" colsep="1" rowsep="1" valign="top">
           <para role="Table Cells">Title</para>
       </entry>
       <entry colname="col2" colsep="1" 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.  Several examples of the available code are below.  Note you can easily add a list within a list.

To create a bulletted list:

<itemizedlist mark="disc" spacing="normal">
            <listitem>
                <para">To add a new vendor ('parent Vendor record')</para>
            </listitem>
            <listitem>
                <para>To create a new division to an existing vendor ('child Vendor
                    record')</para>
            </listitem>
            <listitem>
                <para>To edit information about an existing vendor or division</para>
            </listitem>
        </itemizedlist>

To create steps/ a numerical list:

<orderedlist numeration="arabic" spacing="normal">
    <listitem>
       <para>Search for 'In Process' purchase orders using the Order Holding Queue or document search and click the document ID to open it. </para>
    </listitem>
    <listitem>
        <para>Complete the standard tabs as necessary.</para>
    </listitem>
    <listitem>
        <para>Complete the <emphasis role="bold">Vendor</emphasis> and other </emphasis>tabs as necessary. To add information to these sections, click the   
             <emphasis role="bold">amend</emphasis> button at the bottom of the PO.</para>
    </listitem>
    <listitem>
         <para>Click submit</para>
    </listitem>
</orderedlist>

If you need an ordered list to continue at a later point, you can simply add the enumeration value: <orderedlist numeration="arabic" continuation="continues" spacing="normal">

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 for SMEs.  Once complete, I make these changes in DocBook.

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.
   1. If you move things outside of the first section of a chapter, you will need to have the help link updated.
4. Search the chapters for JIRA tickets, the last few release numbers, the present release and future release.  Review if bugs still exist.

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
• Developing Rice DocBook Documentation - yes, some of their information was copied to this page. Thank you Rice team for paving the way!