How to write DocBook sources for UIMA Documentation

This page gathers the hints and tips on how to write Documentation using the DocBook markup, for UIMA.

Naming conventions

IDs

IDs are strings that identify parts of the markup. They are part of the XML spec, and must be globally unique. To achieve this global uniqueness, the following naming conventions are in use (but not always
followed to the letter):

• The name is multi-part, with each part separated from others with a period (like Java namespaces).
• all lower case. multi-part names spelled with underscore where useful, e.g. "name_spaces".
• The initial parts (other than the last) are often short, abbreviations.
• Parts:
  • first: "ugr" - for the set of books called "Users Guide and Reference". Could be something else for other sets of books
  • second: (a shortened version of the) book-name within the set of books. So far, we have:
    • ovv - overview_and_setup
    • ref - reference
    • tools - tools
    • tug - tutorials_and_users_guides
  • third: (a shortened version of the) chapter-name. For instance: in the Reference book, we have a "jcas" and a "cas" chapters. For some chapters, we have 2 part names. For example, xml.cd (component descriptor xml reference), and xml.cpe (cpe xml reference).
  • last: a potentially longer name often a short form of the <title> or <titleabbrev> of the section the id is attached to. For instance, the section titled "Name Spaces" in the JCas reference chapter in the Reference book of the book set for User's Guide and Reference has an id: "ugr.ref.jcas.name_spaces".

How To:

• Shorten titles (addressing most common cause of FOP message about text overflowing a static area): follow <title>a loooonnnnnggggg title</title> with <titleabbrev>a short form</titleabbrev>. The styles are set up to use the abbreviated version in the static areas (the headers).

Things to avoid

• Don't write <programlisting> or </programlisting> on separate lines - the new line that follows or preceeds them will cause extra white space in the output.

Things to cleanup

• If you don't include an "id" attribute on a section, docbook will produce a warning. If you see these, just add an appropriate id. It's good to get rid of these warnings, to make the other errors / warnings stand out.