Home → DobuDish → Global and local customization
|
I have been happy to discover that DobuDish has a well-designed hierarchy of XSL files to allow for project-specific, output-specific and also global customization. The remarks below are my interpretation of how the layer works. Please feel free to comment on and correct this. The DocbuDish manual only touches very briefly on global customization in the section "Modifiying the Customization Layer". This does not mean that the customization is not sophisticated. The more local XSL files overrride more global ones. Conversely, the more general you need the customization, the more global the stylesheet that you use. The files come from two directories: 1. the system/templates directory: The XSL files here provide for document *type* customization, e.g. sets, books, articles. 2. the system/custom-xsl directory and sub-directories: The XSL files here provide for document *output format* customization, e.g. HTML, PDF, JavaHelp, HTMLHelp When you create a new project, e.g. a book, the template files are copied from system/templates/book-tpl-dir/book-cfg to the new project custom-cfg directory. This includes templates for all output formats. Suppose you wish to make a PDF. The entry point for FO customization is custom-cfg/fo.xsl. This is where you can override any global setting. Notice that this file imports a higher level file system/custom-xsl/fo-book.xsl and also a local file common.xsl. The file common.xsl would contain XSL customization for *all books*, regardless of output format. It was copied from system/templates/book-tpl-dir/book-cfg and is imported by all output XSL files in your local custom-cfg directory. So in common.xsl we will have such *book-specific* customization which is common to both FO-based and HTML-based output. Examples would be parameters common in the files: system/docbook-xsl/fo/param.xsl system/docbook-xsl/html/param.xsl and which are book-specific. The file: system/custom-xsl/fo-book.xsl in turn imports system/custom-xsl/fo-common.xsl, which contains common FO customization. The file fo-book.xsl also contains *book-specific* FO customization, as opposed to say set-specific or article-specific FO customization. The file system/custom-xsl/fo-common.xsl is where the default DocBook XSL stylesheet is imported and also generally where the most FO customization will be done if you want a common look to all output PDFs: set, book, article, etc. It also contains the import of the cover page customization XSL (by default this is system/custom-xsl/titlepage-spec/titlepage.nv2.xsl). So if you generate your own cover page XSL for all your projects, it can replace this one. The file system/custom-xsl/common-custom.xsl is also imported. In this file, all common customization across all document types and all output formats is made. So here we have customization which is common to both FO-based and HTML-based output, for example common in the files: system/docbook-xsl/fo/param.xsl system/docbook-xsl/html/param.xsl but is really global. The nesting path (specific to general) from specific to global for *PDF book* output is: fo.xsl->fo-book.xsl+common.xsl->fo-common.xsl->common-custom.xsl If you were generating a HTML-based output such as HTML, JavaHelp, HTMLHelp and so on, there is a XSL file for such customization, called system/custom-xsl/html-derived-common.xsl. HTMLHelp in turn has its own customization file, regardless of set, book, article. This is the file system/custom-xsl/htmlhelp-common.xsl. This is also where the default DocBook XSL stylesheet for htmlhelp is imported. The nesting path of XSL files for a *HTMLHelp book* is: htmlhelp.xsl->htmlhelp-book.xsl+common.xsl->htmlhelp-common.xsl->html-derived-common.xsl->common-custom.xsl In addition, there is a shared HTML entity file: system/custom-xsl/global-entities.xml The CSS files come from the document formats in system/templates, so there is no global CSS (yet). Some duplication is therefore still needed when you modify them, but there are ways to work around this using the new and old build hooks... |
|
Etienne
| email
September 1 2008, 02:45 PM |