Collapse AllExpand All

Chapter 9. Simple customization Previous topic Parent topic Child topic Next topic

1. Customize the look of the HTML pages generated by ditac Previous topic Parent topic Child topic Next topic

We'll explain how to customize the look of the HTML pages generated by ditac by using an example. Let's suppose we want to render topic titles in a nice dark blue color rather than in black.
Restriction
Restriction
The customization method described below will not work for formats for which the generated HTML pages are automatically compiled or archived. This is the case for HTML Help, Java™ Help and EPUB.

About this task

The easiest way to customize the look of the HTML pages generated by ditac is to use a custom CSS stylesheet rather than the stock one.

Procedure

  1. Create a custom CSS stylesheet importing the stock CSS stylesheet.
    The stock CSS stylesheet is found in:
    ditac_install_dir/xsl/xhtml/resources/basic.css
    Used for the XHTML 1.0, XHTML 1.1, HTML 4.01 and XHTML 5 output formats.
    ditac_install_dir/xsl/webhelp/resources/webhelp.css
    Used for the Web Help output format.
    ditac_install_dir/xsl/htmlhelp/resources/basic.css
    Used for the HTML Help output format.
    ditac_install_dir/xsl/eclipsehelp/resources/basic.css
    Used for the Eclipse Help output format.
    ditac_install_dir/xsl/javahelp/resources/javahelp.css
    Used for the Java™ Help output format.
    ditac_install_dir/xsl/epub/resources/basic.css
    Used for the EPUB output format.
    Initial contents of the custom CSS stylesheet (a copy of this file is found in customize/custom.css Opens in new window).
    @import url(basic.css);
  2. Add one or more rules to the custom CSS stylesheet.
    The XSLT stylesheets generating XHTML/HTML pages make extensive use of the class attribute. Generally the XHTML element generated for a DITA element has a class attribute bearing the name of the DITA element. Example: a DITA <p> is converted to a XHTML <div class="p">.
    For more information, you'll have to refer to the stock CSS stylesheet or even to the HTML pages generated by ditac.
    @import url(basic.css);
    
    .part-title,
    .chapter-title,
    .appendix-title,
    .section1-title,
    .section2-title,
    .section3-title,
    .section4-title,
    .section5-title,
    .section6-title,
    .section7-title,
    .section8-title,
    .section9-title,
    .topic-title {
        color: #403480;
        border-bottom: 1px solid #403480;
    }
  3. Specify the "-p css res/custom.css" option when running ditac.
    $ ditac -images img -p xsl-resources-directory res \
        -p css res/custom.css \
        out/manual/_.html manual.ditamap
  4. Last but not least, do not forget to copy custom.css to the resources subdirectory of the output directory (out/manual/res/ in the case of the above example). The ditac command-line cannot do that automatically for you.
    $ cp customize/custom.css out/manual/res

2. Customizing the look of the PDF files generated by ditac Previous topic Parent topic Child topic Next topic

We'll explain how to customize the look of the PDF files generated by ditac by using an example. Let's suppose we want to render topic titles in a nice dark blue color rather than in black.

About this task

A PDF file is created by converting the XSL-FO file generated by the ditac XSLT 2.0 stylesheet by the means of an XSL-FO processor such as Apache FOP, RenderX XEP or Antenna House Formatter. Therefore we need to generate a custom XSL-FO file. This is done by creating a very simple variant of the stock XSLT stylesheet which generates XSL-FO.

Procedure

  1. Create a custom XSLT stylesheet importing the stock one.
    This stock XSLT stylesheet is found in ditac_install_dir/xsl/fo/fo.xsl. It is used to generate an intermediate XSL-FO file. After that, the XSL-FO file is converted to PDF , PostScript , RTF , WordprocessingML , Office Open XML (.docx) or OpenOffice/LibreOffice (.odt) by the means of an XSL-FO processor.
    Initial contents of the custom XSLT stylesheet (a copy of this file is found in customize/custom_fo.xsl Opens in new window).
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                    xmlns:fo="http://www.w3.org/1999/XSL/Format"
                    version="2.0">
    
      <xsl:import href="ditac-xsl:fo/fo.xsl"/>
    
    </xsl:stylesheet>
    Notice the funny looking URI "ditac-xsl:fo/fo.xsl". "ditac-xsl:" is an easy way to refer to ditac_install_dir/xsl/. This works because the XML catalog used by the ditac command-line utility (found in ditac_install_dir/schema/catalog.xml) contains:
    <rewriteURI uriStartString="ditac-xsl:" rewritePrefix="../xsl/" />
  2. Redefine one or more named xsl:attribute-sets in your custom XSLT stylesheet.
    Named xsl:attribute-sets are not documented yet. For more information, you'll have to refer to the XSLT stylesheets found in ditac_install_dir/xsl/fo/.
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                    xmlns:fo="http://www.w3.org/1999/XSL/Format"
                    version="2.0">
    
      <xsl:import href="ditac-xsl:fo/fo.xsl"/>
    
      <xsl:attribute-set name="topic-title" use-attribute-sets="topic-title">
        <xsl:attribute name="color">#403480</xsl:attribute>
        <xsl:attribute name="font-size">160%</xsl:attribute>
        <xsl:attribute name="padding-bottom">0.05em</xsl:attribute>
        <xsl:attribute name="border-bottom">0.5pt solid #403480</xsl:attribute>
        <xsl:attribute name="space-before.optimum">1.5em</xsl:attribute>
        <xsl:attribute name="space-before.minimum">1.2em</xsl:attribute>
        <xsl:attribute name="space-before.maximum">1.8em</xsl:attribute>
      </xsl:attribute-set>
    
    </xsl:stylesheet>
  3. Specify the "-t customize/custom_fo.xsl" option when running ditac.
    $ ditac -t customize/custom_fo.xsl \
        out/manual.pdf manual.ditamap
    Alternatively, package your custom XSLT stylesheet as a plug-in and then specify the name of this plug-in using the -plugin command-line option. By doing this, your custom XSLT stylesheet will be automatically used whatever the output format which uses XSL-FO as its intermediate format (PDF, RTF, .odt, .docx, etc).