Publish DITA to PDF using the DITA Open Toolkit
Hello! Recently started using DITA. As the only technical writer in the company, in general, I am a pioneer in this technology.
I am writing in DITA. I tried Adobe FrameMaker and oXygen as editors. I use PDF as the output format. In general, the basic template is quite satisfactory. However, there is a desire to modify it, for example, under the requirements of GOST. In this regard, he began to study the technology of publishing DITA in PDF. I decided to share my research with my colleagues in this and in future articles. So…
The publication of DITA in PDF is carried out in two stages (see figure):
Drawing taken from book: Dave Pawson, XSL-FO. Making XML Look Good in Print, 2002.
At the first stage, the contents (stream, flow) of the source document (text, pictures, tables, etc.) are distributed in blocks of the future PDF document. In fact, XSLT is being converted from the XML markup used in DITA to the XML markup used in XSL-FO.
XSL-FO (eXtensible Stylesheet Language Formatting Objects) is a markup language for prepress layouts designed to receive printed documents in PDF, PostScript or RTF format.
XSL-FO fully describes the future document - from the layout of pages (margins, footers, etc.) to the styles of paragraphs, text, tables, etc. It allows you to describe different types of pages for a single document (cover, cover page, abstract, main part of the document, end cover sheet, back cover, etc.)
At the second stage, the generated document layout (XSL-FO document) is converted into a printed document. This is usually a PDF.
Developing an XSLT template is a fairly complex task. This requires knowing the features of XSL-FO markup, XSLT and XPath languages. DITA-OT already has a built-in DITA PDF publishing template. It is located in the DITA-OT / plugins / org.dita.pdf2 directory .
Depending on the XML editor used, the DITA-OT directory may be located, for example:
In general, for any editor that supports DITA-OT, in its installation directory, you must look for the folder " DITA-OT / plugins / org.dita.pdf2 ".
There is also an org.dita.pdf template . This is the basic version developed by the OASIS DITA team. It does not support some PDF features. org.dita.pdf2 - a more complete version of the template, OASIS DITA recommends using it.
Two folders are interesting in the template directory:
To begin with, we will be interested in the / cfg / fo / attrs folder . In it, without touching XSLT transformations, you can set some parameters of the document (for example, change the font size) if we are not satisfied with the basic settings.
The basic-settings.xsl file contains the basic settings of the page. For example, its dimensions:
Or the font size of the main text:
The common-attr.xsl file contains some general style settings.
For example, heading styles. They are prescribed for six levels. For the first level, the following set of attributes is used:
The following set of attributes is used for captions to the pictures:
You can change the composition of attributes and their values. To do this, it is recommended to use the custom.xsl file located in the same folder. You can simply copy the required set of attributes ( attribute-set ) into this file, and there you can make changes. No one forbids making changes directly to the source files, but still it’s more convenient to store them in one file.
When forming a document, the parameters contained in the custom.xsl file take precedence. If any attributes are missing in the custom.xsl file , then the values specified in other files are used. That is, if you want to change only the font size of the header, then there is no need to copy all the attributes of the set. You can specify a set with one attribute -font-size .
The names of the attributes, in general, are not much different from the attributes of cascading style sheets. So, for those who have basic ideas in this area, it is not difficult to find the required attribute.
Files with attributes are separated by document elements. Some of them:
The description of each file with attributes is the subject of a separate article.
In conclusion, a few examples. The examples indicate specifically what needs to be specified in the custom.xsl file .
To set the A4 page format:
To set the font size for a level 4 heading:
To set the number of levels of headings collected in the table of contents to 4. The parameter indicates a number 1 greater than the required value (established experimentally).
To set page margins:
Inner margin (at binding)
External field
Top field
Bottom field
To set the alignment of text in paragraphs in width:
To center the captions of illustrations:
I am writing in DITA. I tried Adobe FrameMaker and oXygen as editors. I use PDF as the output format. In general, the basic template is quite satisfactory. However, there is a desire to modify it, for example, under the requirements of GOST. In this regard, he began to study the technology of publishing DITA in PDF. I decided to share my research with my colleagues in this and in future articles. So…
Publication
The publication of DITA in PDF is carried out in two stages (see figure):
- Convert DITA to XSL-FO document in accordance with the XSLT template.
- Generating a PDF file based on an XSL-FO document.
Drawing taken from book: Dave Pawson, XSL-FO. Making XML Look Good in Print, 2002.
At the first stage, the contents (stream, flow) of the source document (text, pictures, tables, etc.) are distributed in blocks of the future PDF document. In fact, XSLT is being converted from the XML markup used in DITA to the XML markup used in XSL-FO.
XSL-FO (eXtensible Stylesheet Language Formatting Objects) is a markup language for prepress layouts designed to receive printed documents in PDF, PostScript or RTF format.
XSL-FO fully describes the future document - from the layout of pages (margins, footers, etc.) to the styles of paragraphs, text, tables, etc. It allows you to describe different types of pages for a single document (cover, cover page, abstract, main part of the document, end cover sheet, back cover, etc.)
At the second stage, the generated document layout (XSL-FO document) is converted into a printed document. This is usually a PDF.
Where to look for DITA-OT in the editor
Developing an XSLT template is a fairly complex task. This requires knowing the features of XSL-FO markup, XSLT and XPath languages. DITA-OT already has a built-in DITA PDF publishing template. It is located in the DITA-OT / plugins / org.dita.pdf2 directory .
Depending on the XML editor used, the DITA-OT directory may be located, for example:
- “ % Oxygen install dir% / frameworks / dita ” for oXygen editor;
- " % AdobeFrameMaker install dir% / fminit / ditafm " for the Adobe FrameMaker editor;
- " % Serna install dir% / plugins / dita " for the Serna editor.
In general, for any editor that supports DITA-OT, in its installation directory, you must look for the folder " DITA-OT / plugins / org.dita.pdf2 ".
There is also an org.dita.pdf template . This is the basic version developed by the OASIS DITA team. It does not support some PDF features. org.dita.pdf2 - a more complete version of the template, OASIS DITA recommends using it.
What are the settings folders in DITA-OT?
Two folders are interesting in the template directory:
- cfg - contains two subfolders:
- common - contains localization settings ( index , properties and vars folders ) and graphic fragments that are automatically placed in the document ( artwork folder ).
- fo - contains the document layout file ( layout-masters.xsl ) and style settings (page size, margins, fonts, alignment, etc.) in the attrs folder .
- xsl - contains a set of XSLT templates for converting DITA to XSL-FO in the fo folder .
To begin with, we will be interested in the / cfg / fo / attrs folder . In it, without touching XSLT transformations, you can set some parameters of the document (for example, change the font size) if we are not satisfied with the basic settings.
The basic-settings.xsl file contains the basic settings of the page. For example, its dimensions:
215.9mm 279.4mm Or the font size of the main text:
10pt The common-attr.xsl file contains some general style settings.
For example, heading styles. They are prescribed for six levels. For the first level, the following set of attributes is used:
3pt solid black 0pt 16.8pt 18pt bold 16.8pt always The following set of attributes is used for captions to the pictures:
bold 5pt 10pt always Custom.xsl file
You can change the composition of attributes and their values. To do this, it is recommended to use the custom.xsl file located in the same folder. You can simply copy the required set of attributes ( attribute-set ) into this file, and there you can make changes. No one forbids making changes directly to the source files, but still it’s more convenient to store them in one file.
When forming a document, the parameters contained in the custom.xsl file take precedence. If any attributes are missing in the custom.xsl file , then the values specified in other files are used. That is, if you want to change only the font size of the header, then there is no need to copy all the attributes of the set. You can specify a set with one attribute -font-size .
The names of the attributes, in general, are not much different from the attributes of cascading style sheets. So, for those who have basic ideas in this area, it is not difficult to find the required attribute.
Files with attributes are separated by document elements. Some of them:
- basic-settings.xsl and common-attr.xsl I already mentioned;
- front-matter-attr.xsl - attributes of the document cover (title page);
- glossary-attr.xsl — glossary attributes ;
- index-attr.xsl - attributes of indexes;
- layout-masters-attr.xsl - attributes of the layout of the document template;
- links-attr.xsl - link attributes;
- lists-attr.xsl - list attributes;
- static-content-attr.xsl - attributes of the so-called static content (for example, page numbers);
- tables-attr.xsl - table attributes;
- task-elements-attr.xsl - attributes of topics of type task;
- toc-attr.xsl - table of contents attributes.
The description of each file with attributes is the subject of a separate article.
Examples
In conclusion, a few examples. The examples indicate specifically what needs to be specified in the custom.xsl file .
To set the A4 page format:
210.0mm 297.0mm To set the font size for a level 4 heading:
12pt To set the number of levels of headings collected in the table of contents to 4. The parameter indicates a number 1 greater than the required value (established experimentally).
To set page margins:
Inner margin (at binding)
15mm External field
15mm Top field
20mm Bottom field
10mm To set the alignment of text in paragraphs in width:
justify To center the captions of illustrations:
center 
