sebersole edited this page Sep 14, 2010 · 4 revisions
Clone this wiki locally

jDocBook is a means to incorporate processing of DocBook-based documentation into your build process.

What is DocBook?

DocBook is, in part, “an XML vocabulary that lets you create documents in a presentation-neutral form that captures the logical structure of your content”. Another aspect of DocBook is the rendering of that content into various formats using DocBook-supplied (or custom) XSLT stylesheets. Basically, DocBook allows you to write and maintain a single source for documentation, and to then render that single source into multiple formats such as PDF or HTML.

Why jDocBook?

The aim of the jDocBook is to allow these DocBook transformations to occur as a natural part of your build process. The main difficulty with this has always been the fact that DocBook transformations were usually very closely tied to the user’s local environment. The design goal, then, of jDocBook was to utilize the notion of a “central artifact repository” (see Maven, Ivy, et al.) to bring all the pieces together “on demand”. Those pieces are:

  1. the DocBook distribution
  2. custom XSLT
  3. custom fonts
  4. custom images
  5. custom css

These are the ingredients that when mixed with the source file(s) and stirred with an XSLT transformer produce the desired output(s).

XLST, fonts, images and css collectively define a “style”. The concept of a style allows creation of shareable and extendable documentation skinning reusable across any number of projects. See jDocBook Styles for more information.