Apache UIMA™ Docbook Bookshelf

To facilitate cross referencing among UIMA docbooks, we ask users when downloading these books to place the downloaded files in a common directory, which we refer to as the UIMA bookshelf.

When this is done, the user will be able to follow cross reference linkages within the downloaded books, without needing an internet connection.

Docbook Conventions used

The build tooling expects the following conventions to be followed:
Docbook source(s) should be put in the directory src/docbook/. The existance of this directory is what causes the normal parent pom chain to notice that docbook processing is needed during the build.

Currently, the docbooks are written to the 4.4 version of Docbook; begin your files with the standard boilerplate (best to copy from another docbook in the "set".

There is one designated file specified in project's POM as the property "<bookNameRoot>" which must have as its value the name of the docbook source file to process, minus the ".xml". This supports breaking large docbooks into multiple parts, perhaps one per "chapter"; you have one top-level docbook which xincludes the other parts. See the file uima-docbook-overview-and-setup/src/docbook/overview-and-setup.xml for an example of using this technique.
The bookNameRoot name serves also as the book "name" and must be unique among all the docbooks in the UIMA bookshelf.
The first part of the top docbook source must include the line:
<xi:include xmlns:xi="https://www.w3.org/2001/XInclude"
  href="../../target/docbook-shared/common_book_info.xml"/>
This allows it to pick up the standard license, disclaimers, and copyright notices. Please set the POM element <inceptionYear>; this is used in the copyright notice.
Xinclude support is automatically provided by the docbkx toolchain; you do not have to set XML entities for this at the top of your file.

Images to be included are by convention expected be located in a folder named "images/[bookNameRoot]", which is located in the same parent directory as the top docbook source file. The [bookNameRoot] is the name of the top docbook source file, less the ".xml". The "extra" directory under "images" is used to separate images from the different docbooks in the uima bookshelf.
Standard entities may be included, using the form:
<!ENTITY imgroot
  "images/insert-booknameroot-here/optional-sub-dir/">
<!ENTITY % uimaents SYSTEM 
  "../../target/docbook-shared/entities.ent">  
%uimaents;
The docbook-shared/entities... are common shared entities you can use; please see the source for the list, located here: here.

Cross Referencing among UIMA Docbooks

Docbooks support an enhanced cross-referencing among docbook collections, using a link style called "olink". Olinks allow cross-referencing and hyperlinking among documents, using extra saved information about the target document (being linked to, as contrasted with plain href style links, which only have the link url). For instance, in PDFs, there's extra info enabling the referring doc to say "page 123 in document abc". For PDF and HTML, olinks allow the referring text to include a hyperlink which includes target document's element title, and maybe a number (if it has numbered items - such as our chapter / section numbers in the main UIMA documentation). So you can get a link that looks like this:
see Section 1.5.1, ?Annotator Methods?
where the 1.5.1 was generated by docbook processing, and the "Annotator Methods" was the title of that section.

To make olinks work, each time a docbook is processed, an extra database of info for that docbook is created, containing just the things needed for this. This database, together with some other data about how the multiple interlinking docbooks are arranged, is then used when processing a docbook.

Olink data for all UIMA docbooks is stored in one additional project, uima-docbook-olink, that has an attached artifact: a zip file of all olink data.

This project is at the level 1-SNAPSHOT, and will stay there. Because it's a snapshot, it is updated whenever it is "deployed". Each docbook processing run updates that docbook's olink data. Committers should deploy the snapshot to share updates of olink data with others.

Creating a new Docbook

Add a src/docbook directory, and put an images directory there for new images (if you have images), and one or more XML files containing docbook source.

Put the name of the top docbook xml file in the project's docbookNameRoot property

Add this docbook to the UIMA bookshelf - modifying the uima-docbook-olink project's src/main/docbook-olink/{html, htmlsingle, and pdf}/site.xml files.
Add a stanza to the site-map, and

add an entity for the docbookNameRoot at the top of the site file.