Публикация DITA в PDF с использованием DITA Open Toolkit

Всем привет! Недавно начал пользоваться DITA. Как единственный технический писатель в компании, в общем-то, являюсь первопроходцем в данной технологии.

Пишу в DITA. В качестве редакторов попробовал Adobe FrameMaker и oXygen. В качестве выходного формата использую PDF. В целом, базовый шаблон вполне удовлетворяет. Однако, есть желание доработать его, например, под требования ГОСТ. В связи с этим начал изучать технологию публикации DITA в PDF. Своими изысканиями решил поделиться с коллегами по цеху в данной и в дальнейших статьях. Итак…

Публикация

Публикация DITA в PDF осуществляется в два этапа (см. рисунок):

1. Преобразование DITA в XSL-FO документ в соответствии с XSLT-шаблоном.
2. Формирование файла PDF на основе XSL-FO документа.

Рисунок взят из книги: Dave Pawson, XSL-FO. Making XML Look Good in Print, 2002.



На первом этапе содержимое (поток, flow) исходного документа (текст, картинки, таблицы и т.д.) распределяются по блокам будущего PDF документа. Фактически происходит XSLT преобразование из XML разметки, используемой в DITA, в XML разметку, используемую в XSL-FO.

XSL-FO (eXtensible Stylesheet Language Formatting Objects) – язык разметки предпечатных макетов, предназначенных для получения печатаемых документов в формате PDF, PostScript или RTF.

XSL-FO полностью описывает будущий документ – начиная от разметки страниц (поля, колонтитулы и т.п.) заканчивая стилями абзацев, текста, таблиц и т.п. Он позволяет описать для одного документа разные типы страниц (обложка, титульный лист, аннотация, основная часть документа, концевой титульный лист, задняя обложка и т.д.)

На втором этапе сформированный макет документа (XSL-FO документ) преобразовывается в печатаемый документ. Обычно это PDF.

Где искать DITA-OT в редакторе

Разработка XSLT-шаблона представляет собой достаточно сложную задачу. Для этого требуется знать особенности XSL-FO разметки, языки XSLT и XPath. В DITA-OT уже есть встроенный шаблон публикации DITA в PDF. Он расположен в каталоге «DITA-OT/plugins/org.dita.pdf2».

В зависимости от используемого XML редактора каталог DITA-OT может располагаться, например:

• «%Oxygen install dir%/frameworks/dita» для редактора oXygen;
• «%AdobeFrameMaker install dir%/fminit/ditafm» для редактора Adobe FrameMaker;
• «%Serna install dir%/plugins/dita» для редактора Serna.

В общем, для любого редактора, поддерживающего DITA-OT, в его каталоге установки необходимо искать папку «DITA-OT/plugins/org.dita.pdf2».

Есть также шаблон org.dita.pdf. Это базовая версия, разработанная группой OASIS DITA. Она не поддерживает некоторые возможности PDF. org.dita.pdf2 – более полная версия шаблона, OASIS DITA рекомендует использовать его.

Какие в DITA-OT есть папки с настройками

В каталоге шаблона интересны две папки:

1. cfg – содержит две подпапки:
   
   • common – содержит настройки локализации (папки index, properties и vars) и графические фрагменты, автоматически помещаемые в документ (папка artwork).
   • fo – содержит файл разметки документа (layout-masters.xsl) и настройки стиля (размер страницы, полей, шрифтов, выравнивание и т.д.) в папке attrs.
2. xsl – содержит набор шаблонов XSLT преобразования DITA в XSL-FO в папке fo.

Для начала нам будет интересна папка /cfg/fo/attrs. В ней, не касаясь XSLT преобразований, можно задать некоторые параметры документа (например, изменить размер шрифта), если нас не устраивают базовые настройки.

Файл basic-settings.xsl содержит основные настройки страницы. Например, ее размеры:

<!-- 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>

Или размер шрифта основного текста:

<xsl:variable name="default-font-size">10pt</xsl:variable>

Файл common-attr.xsl содержит некоторые общие настройки стилей.

Например, стили заголовков. Они прописаны для шести уровней. Для первого уровня используется следующий набор атрибутов:

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

Для заголовков к рисункам используется следующий набор атрибутов:

<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

Можно изменять состав атрибутов и их значения. Для этого рекомендуется использовать файл custom.xsl, расположенный в этой же папке. Можно просто скопировать требуемый набор атрибутов (attribute-set) в этот файл, и уже там внести изменения. Никто не запрещает вносить изменения непосредственно в исходные файлы, но все-таки в одном файле хранить их удобнее.

При формировании документа параметры, содержащиеся в файле custom.xsl, имеют приоритет. Если в файле custom.xsl отсутствуют какие-либо атрибуты, то используются значения, указанные в других файлах. Т.е., если требуется изменить только размер шрифта заголовка, то нет необходимости копировать все атрибуты набора. Можно указать набор с одним атрибутом – font-size.

Названия атрибутов, в целом, не сильно отличаются от атрибутов каскадных таблиц стилей. Так что, для владеющих базовыми представлениями в этой области найти требуемый атрибут не составит труда.

Файлы с атрибутами разделены по элементам документа. Некоторые из них:

• basic-settings.xsl и common-attr.xsl я уже упоминал;
• front-matter-attr.xsl – атрибуты обложки документа (титульного листа);
• glossary-attr.xsl –атрибуты глоссариев;
• index-attr.xsl – атрибуты индексов;
• layout-masters-attr.xsl – атрибуты разметки шаблона документа;
• links-attr.xsl – атрибуты ссылок;
• lists-attr.xsl – атрибуты списков;
• static-content-attr.xsl – атрибуты так называемого статичного содержимого (например, номера страниц);
• tables-attr.xsl – атрибуты таблиц;
• task-elements-attr.xsl – атрибуты топиков типа task;
• toc-attr.xsl – атрибуты оглавления.

Описание каждого файла с атрибутами — это предмет отдельной статьи.

Примеры

В завершение несколько примеров. В примерах указано конкретно, что нужно указать в файле custom.xsl.

Чтобы установить формат страницы А4:

<xsl:variable name="page-width">210.0mm</xsl:variable>
<xsl:variable name="page-height">297.0mm</xsl:variable>

Чтобы установить размер шрифта для заголовка 4 уровня:

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

Чтобы установить количество уровней заголовков, собираемых в оглавлении, равное 4. В параметре указывается число на 1 большее требуемого (установлено опытным путем).

<xsl:param name="tocMaximumLevel" select="5"/>

Чтобы установить поля страницы:

Внутреннее поле (у переплета)

<xsl:variable name="page-margin-inside">15mm</xsl:variable>

Внешнее поле

<xsl:variable name="page-margin-outside">15mm</xsl:variable>

Верхнее поле

<xsl:variable name="page-margin-top">20mm</xsl:variable>

Нижнее поле

<xsl:variable name="page-margin-bottom">10mm</xsl:variable>

Чтобы установить выравнивание текста в абзацах по ширине:

<xsl:attribute-set name="p" use-attribute-sets="common.block">
    <xsl:attribute name="text-align">justify</xsl:attribute>
</xsl:attribute-set>

Чтобы установить выравнивание подписей иллюстраций по центру:

<xsl:attribute-set name="fig.title" use-attribute-sets="base-font common.title">
    <xsl:attribute name="text-align">center</xsl:attribute>
</xsl:attribute-set>