Part II, Chapter 9. Simple customization

1. Customize the look of the (X)HTML pages generated by ditac

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

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

@import url(base.css);

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.

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;
}
```
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/.

‣ Parent topic: Chapter 9. Simple customization

2. Customizing the look of the PDF files generated by ditac

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

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 ).
```
<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/" />
```

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>

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).

‣ Parent topic: Chapter 9. Simple customization

Chapter 9. Simple customization

Child topics:

1. Customize the look of the (X)HTML pages generated by ditac

About this task

Procedure

Restriction

2. Customizing the look of the PDF files generated by ditac

About this task

Procedure