DocBook - Extending DocBook

From ADempiere
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.


Extending DocBook

XSL Stylesheets

Stylesheets are XSL files which define how DocBook elements are formatted.

While the XML source file merely contains markups describing what the meaning of its elements are, stylesheets translate that meaning into formatting information.

For example, the author may tag a certain passage as programlisting. The stylesheet then informs the transformation process that a programlisting should be printed in monospaced font on a dark background and that all whitespace should be preserved. Another stylesheet might use a serif font on a pink background, and a third stylesheet might drop it alltogether.

Adempiere's implementation of DocBook comes with pre-defined stylesheets for producing HTML, WIKI, and PDF output. They are located in the docbook/style directory.

These are simple text files in .xsl format and can therefore be edited with any text editor. Again, XML-aware editors are a great help

Documentation how to customize DocBook stylesheets can be found here.

To Do

Internationalization

The current stylesheets are only available for US English. For other languages, the legalNotice… parameters would have to be translated in docbook/style/common.xsl.

The stylesheets have not been tested with writing systems which are not left-to-right.

WIKI Stylesheets

While the PDF stylesheets are mature and the HTML stylesheets provide acceptable results, the WIKI stylesheets are a product of trial-and-error and leave much room for improvement.

Currently they are based on the HTML stylesheets with some tweaking to use WIKI instead of HTML markup.

But as HTML itself is well-formed XML, it might be better to have stylesheets which transform the HTML output documents to WIKI format instead of directly transforming the source XML. Translating HTML markup to WIKI markup should be fairly straightforward and much easier than transforming DocBook XML to WIKI markup using tweaked HTML stylesheets.

But for linking, WIKI uses page names, not file names, so a way would need to be found to deduct the page name from chunked HTML files.