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

  ...

  • • 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.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 "ADMINOLE.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:

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

     Code Block
     <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:

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

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

      -OR-

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

      

     The first example is for larger images (anything that looks like it will be wider than a 1/2 sheet of 8.5x11 sheet of paper).  The second is for any really small images.  You really just have to test locally to see how things fit.

     Screenshots are labeled as such:

     Code Block
     <alt>Statistical Category Lookup</alt> <imageobject> <para>  <imagedata fileref="../images/DeliverNoTitlePage-133.png"/> <screenshot> </imageobject> </inlinemediaobject>

      -OR-

     Code Block
     <screenshot> <mediaobject> <alt>Patron Statistical <alt>E-Resource Note Tab</alt> Category Document</alt> <imageobject> <imagedata  <imagedata fileref="../images/eresourceDeliverNoTitlePage-42176.png" width="100%"/> width="100%"/> </imageobject> </mediaobject> </screenshot> </para>

     Again, if they are small enough

     </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 the webhelp and HTML outputs, the tag will also be displayed in the mouse-over.

  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

  Code Block
  <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 BASICS books:

  Code Block
  <section xml:id="_Describe_Workbench">

   

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

  Code Block
  <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):

  Code Block
  <section <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:

  ...

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

     Code Block
     <para role="TableHeading"><emphasis role="bold">Location Information tab definition</emphasis></para> <informaltable frame="toptopbot"> <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.

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

  ...

  Code Block

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

  ...

  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!

  ...