XMLmind logo

XMLmind DITA Converter Manual

  

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

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

We'll explain how to customize the look of the (X)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.

About this task

The easiest way to customize the look of the (X)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/base.css
    Used for the XHTML 1.0, XHTML 1.1, HTML 4.01 and XHTML 5 output formats.
    ditac_install_dir/xsl/webhelp/resources/base.css
    Used for the Web Help output format.
    ditac_install_dir/xsl/htmlhelp/resources/base.css
    Used for the HTML Help output format.
    ditac_install_dir/xsl/eclipsehelp/resources/base.css
    Used for the Eclipse Help output format.
    ditac_install_dir/xsl/epub/resources/base.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(base.css);
    Restriction
    Restriction
    Microsoft HTML Help viewer hh.exe does not support @import. Therefore you must copy base.css into your custom CSS stylesheet if you generate HTML Help.
  2. Add one or more rules to the custom CSS stylesheet.
    The XSLT stylesheets generating (X)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 (X)HTML pages generated by ditac.
    @import url(base.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: 2px solid #403480;
}
  3. Specify the "-p custom-css customize/custom.css" option when running ditac.
    $ ditac -images img -p xsl-resources-directory res \
    -p custom-css customize/custom.css \
    out/manual/_.html manual.ditamap
    The above command gives the expected results because:
    1. "-p xsl-resources-directory res" copies all stock resources, including base.css, to subdirectory out/manual/res/.
    2. "-p custom-css customize/custom.css" copies custom.css to subdirectory 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).