DITA-OT 4.0新特性 - PDF themes，定制PDF样式的新方法

随着DITA-OT 4.0的发布，它提供了一种新的定制PDF样式方法，这种方法就是PDF theme。这篇文章来聊一聊这种定制PDF输出的新方法和实验结果。 

在进入PDF theme细节之前，为各位读者梳理一下DITA-OT将DITA和Markdown发布成PDF的几种方法。

- 1 -

DITA-OT发布PDF的几种方法

DITA-OT是优秀的结构化内容发布工具，是开源产品并得到广泛应用。很多公司将DITA-OT集成到自家的产品中，还有公司在DITA-OT的基础上做了扩展。

现在，在DITA-OT的基础上，出现了多种发布PDF文档的方法。下边是其中两种，请点开图看细节。  

1. 使用PDF2插件

开源版DITA-OT将DITA和Markdown发布成PDF时，使用的是上图中”1. 使用PDF2插件“的方法，它使用的是XSLT/XSL-FO技术。

XSL-FO技术是DITA-OT用来发布PDF的技术，目前也还有广泛的应用。当我们运行以下命令，它使用的就是这种方法:

dita -i book.ditamap -f pdf -o out/pdf

此命令调用DITA-OT的PDF2插件，将DITA内容转换成PDF。

在Oxygen XML Editor中选择”DITA Map PDF - based on XSL-FO"发布文档时，调用的也是这个插件：

2. 使用pdf-css-html5

在2018年W3C发布了“CSS页面媒体模块级别3”标准，用于支持使用CSS来将HTML页面发布成基于纸面的输出，如：PDF。这种方法得到了几个主流发布引擎厂商的支持，比如：Antenna House，PrinceXML和SyncRO Soft (也就是生产Oxygen XML Editor那家公司）。

pdf-css-html5是SyncRO Soft基于DITA-OT开发的插件，用于使用CSS技术来将DITA发布成PDF。这个插件只存在Oxygen XML Editor和Oxygen Publish Engine中，是商用软件。

在Oxygen XML Editor中选择”DITA Map PDF - based on HTML & CSS"发布文档时，调用的则是这个插件：

如果使用开源版DITA-OT（不包含商业插件），在DITA-OT 4.0之前定制PDF样式需要使用XSLT/XSL-FO语言，这对于TW来说有挑战。 

“我是写文档的，XSLT/XSL-FO？什么鬼？不想了解”

就算对于专业做样式定制的，使用XSL-FO开发和维护成本总体较高。原因请见我之前文章的分析：将CSS用于PDF发布

为了降低XSLT/XSL-FO定制PDF输出样式的难度和成本，DITA-OT 4.0提供DITA theme来尝试降低定制PDF的难度和成本。

DITA-OT 4.0包括com.elovirta.pdf插件，它通过提供theme参数扩展了默认的PDF2插件功能，在不需要更改XSLT样式表的情况下更改PDF输出的样式。

- 2 -

DITA Theme概要

DITA theme可用于调整PDF输出的基本设置，如：封面图片、页面大小、编号、字体属性、背景色和边框、间距以及页眉和页脚等动态内容。

要使用自定义theme生成PDF输出，dita调用命令如下：

dita -i book.ditamap -f pdf -o out/pdf --theme=path/to/custom-theme-file.yaml

theme文件可以用YAML或JSON格式编写，DITA-OT安装目录中的docsrc/samples/themes文件夹提供了几个示例。

通过theme文件可以定制以下PDF选项：

• 页面设置

• 页眉和页脚

• 内容元素的样式

1. 页面设置示例

page:
  size: A4
  orientation: portrait
  top: 20mm
  outside: 20mm
  bottom: 20mm
  inside: 30mm
  mirror-margins: true

2. 页眉和页脚示例：

header:
  border-after: solid 1pt black
  odd:
    content: '{title}'
    text-align: end
  even:
    content: '{chapter}'
    text-align: start

3. 内容元素的样式示例：

style:
  body:
    font-family: serif
    font-size: 12pt
    space-after: 6pt
    space-before: 6pt
    start-indent: 25pt
  topic:
    font-family: sans-serif
    font-size: 26pt
  link:
    color: blue
    text-decoration: underline

DITA-OT的PDF theme文档在这里：

https://www.dita-ot.org/dev/topics/pdf-themes

- 3 -

实验

在DITA-OT提供的示例theme基础上做以下调整：

1）整体和首页

• 设置中文字体
• 加logo并居中

2）页眉页脚

• 加分割线
• 内容设置为：文档标题 + 章节标题
• 页脚中的页码居中显示
• 加公司logo

3）表格

• 表格标题居中显示
• 表格序号自动生成
• 标题行自动粗体并使用灰色背景

4）图形

• 图形标题居中显示
• 图形序号自动生成

5）代码块和注

• 灰色背景
• 适合代码的字体

- 4 -

总结

说一说使用DITA theme来定制PDF的感受：

1. 语法简单，类似于CSS，容易掌握

2. 能够做一些简单的定制，目前无法做到对输出的完全控制，可以预测后续版本会有更多的增强

3. 此方法是通过配置文件来控制XSL-FO的生成，要理解配置的参数意义需要了解XSL-FO

点这里查看代码和生成的PDF文件。