4.8.2. Customizing the DocBook stylesheets

The DocBook stylesheets are located in the docbook-xsl folder of the Docmenta web application. The current Docmenta version includes an adapted version of the v1.76.1 DocBook stylesheets. The original content of the adapted files are included with suffix "_original". For example, the file fo/pagesetup.xsl includes Docmenta-specific modifications. The original content of the file (as of version 1.76.1) is included in the same folder, but with filename pagesetup_original.xsl. This way, the Docmenta-specific adaptions of the stylesheet can be determined by comparing the file pagesetup.xsl with pagesetup_original.xsl. However, the files with suffix "_original" are not used by Docmenta. But if the DocBook stylesheets are updated to a newer version than 1.76.1, then the modifications need to be integrated in the new version again.
Besides these adaptions of the existing DocBook stylesheets, Docmenta adds additional XSL code to the DocBook stylesheets. In the terminology of the DocBook stylesheets such XSL code is called a "customization layer". In Docmenta the customization layer consists of the files listed in Table 4.8.2, “Pre-defined Docmenta customization layer files”. The files are located in the sub-folder docma of the web application.
Table 4.8.2. Pre-defined Docmenta customization layer files
FileDescription
customlayer.xsl Customization layer used for all DocBook-based exports (DocBook, PDF, static HTML, WebHelp V1 and EPUB).
customlayer_pdf.xsl Additional XSL code included only for PDF output.
customlayer_html.xsl Additional XSL code included only for HTML-based output formats that utilize the DocBook stylesheets (static HTML, WebHelp V1 and EPUB).
coverpage_pdf.xsl XSL code used for generating cover pages in PDF output.
custom_header_footer_pdf.xsl XSL code used for the creation of customized page headers/footers in PDF output.
tocline_template_pdf.xsl XSL code used for the creation customized ToC lines in PDF output.
Be aware that further XSL code is generated dynamically and added to the customization layer. Therefore, to have a complete view of the generated customization layer, the Docmenta source code has to be considered as well. The generation of the customization layer is done by the createDocBookXSLCustomLayer method in the org.docma.app.FormattingEngine class.
Besides the XSL-files listed above, a plug-in can add further XSL code to the customization layer, by adding files with one of the prefixes listed in the following table.
Table 4.8.3. Filename prefixes for customization layer plug-in files
File PrefixDescription
custom- Files with this prefix are added to the customization layer of all DocBook-based exports (DocBook, PDF, static HTML, WebHelp V1 and EPUB).
custom_print- Files with this prefix are added to the customization layer for print output, but not for HTML-based output. Currently the only supported print format is PDF.
custom_pdf- Files with this prefix are only added to the customization layer for PDF output.
custom_html- Files with this prefix are only added to the customization layer for HTML-based output formats that utilize the DocBook stylesheets (static HTML, WebHelp V1 and EPUB).
Note: WebHelp V2
The WebHelp V2 format is not based on DocBook. Therefore, none of these customization files have impact on the WebHelp V2 output. To adapt the output of WebHelp V2, AutoFormat styles can be used (see Chapter 4.6, AutoFormat plug-ins).
As an example, we set the DocBook XSL parameters "sidebar.float.type" and "sidebar.float.width", which define the alignment and width of side floats (see the example given in Section 4.8.1, “Customizing the transformation to DocBook”). Therefore, we add a file named custom_print-aside.xsl with following content to the docma folder of the Docmenta web-application:
<xsl:param name="sidebar.float.type">start</xsl:param>
<xsl:param name="sidebar.float.width">150pt</xsl:param>
 
<xsl:attribute-set name="sidebar.properties"
use-attribute-sets="formal.object.properties">
<!--style:aside-->
</xsl:attribute-set>

Listing 4.8.2. custom_print-aside.xsl

In our example, side floats shall be supported for print output only. Therefore, the file prefix "custom_print-" is used. In 4.8.2: custom_print-aside.xsl, the "sidebar.float.type" parameter is set to "start" and the "sidebar.float.width" parameter is set to "150pt". Therefore, side floats are left-aligned and have a default width of 150pt.
Furthermore, an attribute-set with name "sidebar.properties" is added to the customization layer. This attribute-set defines the FO formatting properties of the side float. Within the customization layer files, the placeholder <!--style:id--> can be used to insert the CSS properties of the Docmenta style with identifier id. In the example given above, the CSS properties of the style "aside" are inserted.
To add the customization layer files to a Docmenta installation, a plug-in package has to be created. This is described in the following section.
More information on adapting the Docbook stylesheets by customization layers, can be found in the book "DocBook XSL: The Complete Guide" by Bob Stayton.