uima-docbook-tool/HOW_TO

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
================================
= How to use the docbook tool. = 
================================

The tooling is set up assuming you put your documentation in another directory
which is parallel (has the same ancestor) as the uima-docbook-tool directory.
Furthermore, it assumes the target output directory for generated code is 
some directory (name is arbitrary) at the top level of your documentation project.
(This follows maven conventions).


Step 1: Create a project (if necessary) for your docbook documentation.

Step 2: Organize the documentation into one or more "books".  

  Directory structure to create:  
      ... (at some level) ... /your-first-book-name
      ... (at some level) ... /your-second-book-name
        etc.
        
    Within each book-name, you have subdirectories for chapters.  These
    are "xi:include-d" into a "master" file, which should be named
    the same as the book.  So, a typical book looks like:
    
      ... (at some level) ... /my-book-name/my-book-name.xml  <<-- the "master" file
      ... (at some level) ... /my-book-name/my-chapter1-name.xml  <<-- included files
      ... (at some level) ... /my-book-name/my-chapter2-name.xml  <<-- included files
                  etc.
                 
Step 3: copy the contents of the "samples" directory into your docbook project,
        in the src/styles directory.  You should end up with 
        src/styles/top and src/styles/titlepage directories.
                  
Step 4: modify the "local.docbook.properties", 
        to fit your requirements and directory layout

        For each book you want to build, create a custom copy of
        build_book-name.xml, modified to reference the book you want to build.
        
        Edit the files in the "top" directory and correct any relative path
        specifications as needed to correspond to your directory layout.
        
        (Optional) Customize the "style": Change the titlepage files, and/or
        add overrides to the xsl files in the "top" directory.  For instructions
        on how to do this, see http://www.sagehill.net/book-description.html
        (you can view this as an on-line book, or buy the book).  

Step 5: build the book using the build_book-name.xml as an ANT script.


=============
=  T I P S  =
=============

Recommended editor = XMLBuddy plugin for Eclipse.  This will read the docbook dtd, 
plus any customized Entities you might declare, and make them available for 
Eclipse auto-completion and checking.

Entities you declare can be put into shared entity files, and then
essentially included in other files.  See Chapter 22 of the DocBook XSL, the 
Complete Guide, for examples.


=============================================================
Path requirements:

The target path must be a top level path in a parallel project directory.  
The font config currently depends on this.

NOTES:

The functionality for xi:include relative linking when the thing being included was 
in a different directory from the includer was broken.  
This showed up in image fileref= attributes being improperly / inconsistently translated
to src=... attributes in the generated xml.  Work-around: give up for now
in having subdirectories - put all things into one directory.  (Note - as
of April 2007 a bug in this area has been fix and this needs to be retested)

The qandaset functionality works but the FOP processor 0.20.5 seems to have trouble
handling id= attributes; it's giving an incorrect error message about a duplicate id tag,
when, in fact, there is no duplicate.  Work-around: give up using qandaset - just use
variablelist instead. (4/2007: Needs retesting on FOP 0.93 and newer level of docbook)

Parameters for Docbook are described in the FO ref:
http://docbook.sourceforge.net/release/xsl/current/doc/fo/index.html