jDocBook build stages

jDocBook goes through the following “build stages” :

1. translate – which is the process of taking the master language sources and the translation PO files and generating “translated XML” files.
2. profile – which is the process of applying docbook profiling
3. format – which is the process of taking the XML documents (master, as well as translated) and generating the requested outputs.

translate

Technically, the translation phase makes use of some tools/utilities from the KDE project collectively called poxml. For each of the translation languages we take its PO files along with the master language’s DocBook files and feed them to a tool called po2xml. The end result is a bunch of DocBook xml files with the translation text injected.

Inputs:

• the docbook sources. Really we just need the main xml file, and we then follow the XIncludes to determine all the source files. So in terms of “incremental build” it’s either the master language base dir or the collection of Files that is important.
• the translation base directory for the given language. Here its the directory that is important to track for “incremental build”
  Outputs:
• the translated XML; in terms of incremental builds the output base directory is enough

profile

DocBook provides a separate XSLT for performing profiling. Profiling is optional. If enabled, it is performed once per source (master/translation).

Inputs:

• profiling attribute/value (user config)
• source document (though, again, in terms of incremental builds its the full set of xincluded sources or language base directory)
  Outputs:
• the profiled XML; in terms of incremental builds the output base directory is enough

format

For each configured format, for each source language, we need to apply that format to produce the indicated output. For example, a project might want to format the docs to pdf and html. Each format is indicative of a XSLT file to produce that specified type. This XSLT might be a custom XSLT or the standard DocBook one.

Inputs:

• “format plan” (one per format)
• source document (though, again, in terms of incremental builds its the full set of xincluded sources or language base directory)
  Outputs:
• publish output – this is a series of directories indicative of format/language