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 to DITA. I tried Adobe FrameMaker and oXygen as editors. As an output format I use PDF. In general, the basic template is quite satisfying. 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. He decided to share his research with his colleagues in this and in future articles. So…
Publishing DITA to PDF is carried out in two stages (see figure):
Picture taken from the book: Dave Pawson, XSL-FO. Making XML Look Good in Print, 2002.
')
At the first stage, the contents (flow, flow) of the original document (text, images, tables, etc.) are distributed into blocks of a future PDF document. XSLT actually takes place 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 preprinted layouts designed to produce printable documents in PDF, PostScript or RTF format.
XSL-FO fully describes the future document - from the layout of pages (fields, footers, etc.) to paragraph styles, text, tables, etc. It allows you to describe different types of pages for a single document (cover, title page, abstract, main part of the document, title page, 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 quite a challenge. This requires knowing the features of XSL-FO markup, XSLT and XPath languages. DITA-OT already has a built-in DITA PDF publication 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 a template org.dita.pdf . This is a basic version developed by the OASIS DITA group. It does not support some PDF features. org.dita.pdf2 is a more complete version of the template, OASIS DITA recommends using it.
There are two interesting folders in the template directory:
For a start, we will be interested in the folder / cfg / fo / attrs . In it, without touching the 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 main page settings. For example, its dimensions:
Or the font size of the main text:
The common-attr.xsl file contains some common style settings.
For example, header styles. They are prescribed for six levels. For the first level, the following set of attributes is used:
For captions to pictures, the following set of attributes is used:
You can change the composition of the attributes and their values. For this, it is recommended to use the custom.xsl file located in the same folder. You can simply copy the desired set of attributes ( attribute-set ) to this file and make changes there. Nobody forbids making changes directly to the source files, but still it is 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, the values specified in other files are used. That is, if you only need to change the font size of the header, you do not need to copy all the attributes of the set. You can specify a set with one attribute - font-size .
Attribute names, in general, are not very different from cascading style sheet attributes. So, for those who have basic ideas in this area, it is easy to find the required attribute.
Files with attributes are divided into document elements. Some of them:
The description of each attribute file is the subject of a separate article.
In conclusion, a few examples. The examples specifically indicate what needs to be specified in the custom.xsl file.
To set A4 page format:
To set the font size for level 4 headings:
To set the number of levels of headings collected in the table of contents, equal to 4. The parameter specifies a number 1 higher than the required one (set experimentally).
To set page margins:
Inner margin (with binding)
External field
Top field
Bottom field
To set text alignment in paragraphs for width:
To set the alignment of the captions of the illustrations in the center:
I am writing to DITA. I tried Adobe FrameMaker and oXygen as editors. As an output format I use PDF. In general, the basic template is quite satisfying. 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. He decided to share his research with his colleagues in this and in future articles. So…
Publication
Publishing DITA to PDF is carried out in two stages (see figure):
- Convert DITA to XSL-FO document according to the XSLT template.
- Generate a PDF file based on the XSL-FO document.
Picture taken from the book: Dave Pawson, XSL-FO. Making XML Look Good in Print, 2002.
')
At the first stage, the contents (flow, flow) of the original document (text, images, tables, etc.) are distributed into blocks of a future PDF document. XSLT actually takes place 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 preprinted layouts designed to produce printable documents in PDF, PostScript or RTF format.
XSL-FO fully describes the future document - from the layout of pages (fields, footers, etc.) to paragraph styles, text, tables, etc. It allows you to describe different types of pages for a single document (cover, title page, abstract, main part of the document, title page, 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 find DITA-OT in the editor
Developing an XSLT template is quite a challenge. This requires knowing the features of XSL-FO markup, XSLT and XPath languages. DITA-OT already has a built-in DITA PDF publication 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 the oXygen editor;
- “ % AdobeFrameMaker install dir% / fminit / ditafm ” for Adobe FrameMaker;
- " % 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 a template org.dita.pdf . This is a basic version developed by the OASIS DITA group. It does not support some PDF features. org.dita.pdf2 is a more complete version of the template, OASIS DITA recommends using it.
What are the settings folders in DITA-OT
There are two interesting folders in the template directory:
- cfg - contains two subfolders:
- common - contains localization settings ( index , properties and vars folders ) and graphic fragments automatically placed in a document ( artwork folder).
- fo - contains a document markup file ( layout-masters.xsl ) and style settings (page size, margins, fonts, alignment, etc.) in the attrs folder.
- xsl - contains a set of XSLT DITA to XSL-FO conversion templates in the fo folder.
For a start, we will be interested in the folder / cfg / fo / attrs . In it, without touching the 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 main page settings. For example, its dimensions:
<!-- The default of 215.9mm x 279.4mm is US Letter size (8.5x11in) --> <xsl:variable name="page-width">215.9mm</xsl:variable> <xsl:variable name="page-height">279.4mm</xsl:variable> Or the font size of the main text:
<xsl:variable name="default-font-size">10pt</xsl:variable> The common-attr.xsl file contains some common style settings.
For example, header styles. They are prescribed for six levels. For the first level, the following set of attributes is used:
<xsl:attribute-set name="topic.title" use-attribute-sets="common.title"> <xsl:attribute name="border-bottom">3pt solid black</xsl:attribute> <xsl:attribute name="space-before">0pt</xsl:attribute> <xsl:attribute name="space-after">16.8pt</xsl:attribute> <xsl:attribute name="font-size">18pt</xsl:attribute> <xsl:attribute name="font-weight">bold</xsl:attribute> <xsl:attribute name="padding-top">16.8pt</xsl:attribute> <xsl:attribute name="keep-with-next.within-column">always</xsl:attribute> </xsl:attribute-set> For captions to pictures, the following set of attributes is used:
<xsl:attribute-set name="fig.title" use-attribute-sets="base-font common.title"> <xsl:attribute name="font-weight">bold</xsl:attribute> <xsl:attribute name="space-before">5pt</xsl:attribute> <xsl:attribute name="space-after">10pt</xsl:attribute> <xsl:attribute name="keep-with-previous.within-page">always</xsl:attribute> </xsl:attribute-set> Custom.xsl file
You can change the composition of the attributes and their values. For this, it is recommended to use the custom.xsl file located in the same folder. You can simply copy the desired set of attributes ( attribute-set ) to this file and make changes there. Nobody forbids making changes directly to the source files, but still it is 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, the values specified in other files are used. That is, if you only need to change the font size of the header, you do not need to copy all the attributes of the set. You can specify a set with one attribute - font-size .
Attribute names, in general, are not very different from cascading style sheet attributes. So, for those who have basic ideas in this area, it is easy to find the required attribute.
Files with attributes are divided into document elements. Some of them:
- I mentioned basic-settings.xsl and common-attr.xsl ;
- front-matter-attr.xsl - attributes of the cover of the document (title page);
- glossary-attr.xsl - glossary attributes ;
- index-attr.xsl - index attributes;
- layout-masters-attr.xsl - markup attributes 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 - task type attributes;
- toc-attr.xsl - table of contents attributes.
The description of each attribute file is the subject of a separate article.
Examples
In conclusion, a few examples. The examples specifically indicate what needs to be specified in the custom.xsl file.
To set A4 page format:
<xsl:variable name="page-width">210.0mm</xsl:variable> <xsl:variable name="page-height">297.0mm</xsl:variable> To set the font size for level 4 headings:
<xsl:attribute-set name="topic.topic.topic.topic.title" use-attribute-sets="base-font common.title"> <xsl:attribute name="font-size">12pt</xsl:attribute> </xsl:attribute-set> To set the number of levels of headings collected in the table of contents, equal to 4. The parameter specifies a number 1 higher than the required one (set experimentally).
<xsl:param name="tocMaximumLevel" select="5"/> To set page margins:
Inner margin (with binding)
<xsl:variable name="page-margin-inside">15mm</xsl:variable> External field
<xsl:variable name="page-margin-outside">15mm</xsl:variable> Top field
<xsl:variable name="page-margin-top">20mm</xsl:variable> Bottom field
<xsl:variable name="page-margin-bottom">10mm</xsl:variable> To set text alignment in paragraphs for width:
<xsl:attribute-set name="p" use-attribute-sets="common.block"> <xsl:attribute name="text-align">justify</xsl:attribute> </xsl:attribute-set> To set the alignment of the captions of the illustrations in the center:
<xsl:attribute-set name="fig.title" use-attribute-sets="base-font common.title"> <xsl:attribute name="text-align">center</xsl:attribute> </xsl:attribute-set> Source: https://habr.com/ru/post/266021/
All Articles