Document How to Use Your Own Stylesheets

[tomschr]

Problem

Currently, we don't have a dedicated section which deals about how to use your own XSLT stylesheets for your project.
Although we have 9.3 Customizing the DocBook Stylesheets, but this doesn't give readers instructions. It only links to my DoCookBook project.

Solution

I would recommend to enhance section 9.3 Customizing the DocBook Stylesheets (ID=sec.daps.user.layout.styleheets) with the following information:

• Reasons to use a customization layer
  Why does someone want this? Well, it's the usual suspects: change the original DocBook XSL stylesheet output, adapt the behaviour how an element is processed, need for a corporate style, etc.

• Correct (sub)structure for your customization stylesheets
  It's probably a good idea to use xslt insde your project as the top-level root directory for all the stylesheets (although this is just a recommendation and not mandatory) . Depending on which formats are supported, this top-level directory should/could be integrated into your project directory like this:

YOUR_DOC_DIR/
 |
 +-- DC-files
 +-- xml/
      +--- your XML files...
 +-- xslt/
      +-- fo/
           +-- docbook.xsl
      +-- html/
           +-- docbook.xsl
           +-- chunk.xsl
       +-- [additional formats, supported by DB XSL]
           +-- docbook.xsl

• Your XSLT customization layer
  Use Example 2.1. General Customization Layer as a basis. The main entry file has to be named docbook.xsl. For HTML or XHTML, you need an additional chunk.xsl file which is needed for "chunking" (splitting the result transformation into different HTML files).
  It is allowed (and recommended!) to split the stylesheets into different sub-stylesheets which are included/imported into the main entry file.

• DC file(s) changes
  The DC file must include the STYLEROOT variable, pointing to the xslt directory (see above). It is recommended to set also the FALLBACK_STYLEROOT variable. For openSUSE, it points to /usr/share/xml/docbook/stylesheet/nwalsh.

• Include references
  Add references to the DocBook XSL Stylesheets: Reference Documentation and my DoCookBook project.

• XSLT knowledge needed
  The reader should be aware of that he or she needs to know about XSLT (at least a little bit). Basic customizations like parameter changes can be done by simple adding a line with <xsl:param name="PARAMETER_NAME" select="VALUE"/>. The available parameters are format dependent and are listed in the "XSL Stylesheets Reference Documentation".

Recommendations

• Use a <procedure> tag to give the reader instructions on how to setup his project to support his own stylesheets.
• It's probably easier to explain it with an example instead of being abstract.

In the long run this maybe a topic for a Developer Guide, but for the time being I think we should document it in the User Guide.