<queue-voice-of-god>In the beginning there was jdocbook-styles...</queue-voice-of-god>
jDocBook styles were meant to represent common styling elements that could be developed on their own, built into bundles and used as dependencies to DocBook builds using the jDocBook plugin. The contents of the styles (css and images) were staged to a special directory within the DocBook project's target directory for use within the XSLT formatting.
Recently I have been working on extending that concept to an idea from the world of publican. For those not familiar with it, publican is the DocBook build system used by Fedora and many Red Hat related projects. The idea I was looking at including into the world of jDocBook is what publican terms brands. These brands really provide two somewhat complimentary things:
- styling
- fallback content
Much like jdocbook-styles, publican brands allow providing css and images that should be used in the output formatting. The big difference is that brands allow for them to be localized to the particular translations. The notion of 'fallback content' allows common pieces of content (DocBook XML) to be developed and then used throughout various documentation projects. For example, the publican brands generally define fallback content for things like legal notices and document conventions. Again, allows for localization to the various translations in terms of appropriate POT/PO files.
The localization aspect brings up a question wrt jdocbook-styles and the staging of those resources. Currently the resources within a jdocbook-styles are staged into the target/docbook/staging directory by the jdocbook plugin itself (the later formatting phase simply points to them from there for each translation since they are implicitly shared for all translations). Staging of the brands, however, would require that each translation have its own staging directory (ala target/docbook/staging/en-US, etc). So either the jdocbook-styles could be repeatedly exploded into each translation's staging directory or we could make the move to have localized jdocbook-styles as well.
Initially the idea was to have the jDocBook plugin itself perform all these stagings (especially since it does so already for jdocbook-styles). But today another thought crossed my mind: separate out the notions of staging. The basic principle would be to simplify jDocBook to focus on a core competency, namely taking some DocBook XML, some resources, some XSLT and generating some formatted output. This would allow projects not using styles and not using brands to have a very simple jDocBook setup; essentially it would build directly from the controlled sources. For projects with styles and/or brands we would stage everything to the staging directories and configure jDocBook itself to use the staged directories as its input.
--- Resources:
- GNU gettext if you are not familiar with POT/PO files
- poxml for the tools used to handle gettext in regards to XML files
