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

Directory and File names for Docbook Sources

Docbook sources are kept in the uima-docbooks project, under the directory src/docbook. The folder and file names under this (usually) follow these conventions:

  • book name: an easy to understand, short folder name for the book, not to abbreviated, e.g. "references"
    • an "images" directory holding all the imbedded images for that book
    • a "master" file, named the same as the directory, but followed with .xml. This file should xi:include the chapters or other parts of the book, as well as have the book identification information, and include the common boiler plate.
    • the xi:included parts of the book - these are usually the chapters. Names for this are compound:
      • First: an abbreviation of the book directory name: e.g. for "references", we're using "ref"
      • Second: one or two names describing the chapter: e.g. "jcas" or "xml.cpe_descriptor"
      • Third: ".xml"

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.
  • No labels