第17章 自定义PDF输出

您可以通过更改参数设置或使用主题文件来调整PDF输出的各个方面。对于更复杂的自定义，您可以创建或安装自定义插件。

例如：

• 若要在图形下方打印文件名，请将 args.artlbl 设置为 yes。

• 若要禁用每章首页的子章节链接，请将 args.chapter.layout 设置为 BASIC。

• 若要将PDF文件名更改为输入映射名称以外的其他名称，请将 outputFile.base 设置为所需的文件名（不带 .pdf 扩展名）。

注意： 有关PDF输出的完整参数列表，请参见第88页的“PDF参数”。

自定义方法......111
生成修订条......113
PDF主题......114

PDF自定义方法

有多种方法可用于自定义DITA Open Toolkit生成的PDF输出。每种方法都有其优势和不足，在准备自定义项目时应予以考虑。

注意： 其中某些方法被认为是“反模式”，其缺点可能超过表面上的吸引力。在大多数情况下，您应创建自定义PDF插件。

为何不应直接编辑默认文件？

初次尝试PDF自定义时，新手用户常倾向于直接编辑默认的 org.dita.pdf2 文件以观察效果。

尽管这种方法看似实用，但DITA-OT项目不建议修改默认插件中的任何文件。

虽然此方法能快速见效，并帮助用户确定哪些文件和模板控制PDF输出的不同方面，但任何错误都可能导致工具包无法生成PDF输出，从而引发问题。

警告： 以这种方式进行的更改在升级到新版本DITA-OT时会被覆盖。因此，通过此方式自定义工具包安装的用户通常只能停留在旧版本工具包上，无法利用DITA-OT最新版本的改进功能。

===== 第2页 =====

配置DITA-OT

使用“Customization”文件夹

原始的Idiom插件使用其自身的扩展机制来覆盖PDF转换。通过此方法，插件内的专用文件夹用于存储自定义文件。

org.dita.pdf2/Customization 文件夹中的文件可以覆盖默认文件，允许用户在不修改插件默认文件或生成输出时指定额外参数的情况下调整PDF输出的某些方面。

重要提示： 尽管此方法略优于直接编辑默认文件，但在升级工具包到新版本时仍可能导致问题。由于“Customization”文件夹位于 org.dita.pdf2 插件的父目录中，用户在升级时必须注意保留此文件夹的内容。

尽管DITA-OT的最新版本仍支持此机制以确保向后兼容性，但此做法已弃用，建议改用自定义PDF插件。

提示： 使用“Customization”文件夹修改默认PDF输出的用户应转而创建自定义PDF插件。在许多情况下，只需将“Customization”文件夹的内容复制到 plugins 文件夹的新子文件夹中，并创建必要的 plugin.xml 文件和Ant脚本来定义转换类型即可。

指定外部自定义目录

为确保自定义文件夹中的覆盖内容在升级DITA-OT时不被覆盖，可在构建时或通过 customization.dir 参数在构建脚本中指定外部自定义目录。

此方法优于使用 org.dita.pdf2/Customization 文件夹，因为外部目录的内容在升级DITA-OT时不受影响。在分布式环境中，用户可以使用本地安装的DITA-OT，同时利用存储在团队共享位置（如网络驱动器）的通用自定义配置。

对于因企业策略、CMS权限或网络访问权限而禁止修改工具包安装的环境，此方法也很有用。

提示： 通过 customization.dir 指定外部自定义目录的用户应尽可能创建自定义PDF插件。

结合自定义插件与自定义目录

可将通用自定义插件用于存储适用于所有公司出版物的基础覆盖配置，并在构建时传递 customization.dir 参数以按需覆盖特定项目的设置。

===== 第3页 =====

在这种情况下，自定义目录中的设置将优先于自定义插件或默认 org.dita.pdf2 插件中的对应设置。

此方法允许在多个出版物或整个公司间共享单一自定义插件，而无需为每个项目创建额外的插件依赖。

然而，使用多种自定义机制可能使调试优先级级联和确定本地格式或处理覆盖的来源变得困难。

提示： 在大多数场景中，建议使用专用的PDF自定义插件。通用自定义可捆绑在一个插件中，而项目特定的覆盖可维护在单独的插件中，这些插件基于通用插件中的基础品牌或其他设置。

生成修订条

您可以通过DITAVAL <revprop> 元素的 @changebar 和 @color 属性在PDF输出中生成修订条。

DITA规范对 <revprop> 元素的 @changebar 属性的说明如下：

@changebar：当标志已设置时，根据目标输出格式的修订条支持指定修订条颜色、样式或字符。若未设置标志，则忽略此属性。

DITA Open Toolkit当前版本使用两个 <revprop> 属性值定义修订条：

• @changebar 属性值定义线条样式，其可能值与XSL-FO规则相同（参见 @change-bar-style）。默认值为 groove。

• @color 属性值使用XSL-FO识别的颜色值（包括常规颜色名称或十六进制颜色值）指定修订条颜色。默认值为 black。

<revprop action="flag" changebar="solid" color="green"/>  

图16：修订条配置示例

DITA-OT默认使用2毫米的偏移量将修订条置于文本栏边缘附近。偏移量、位置和宽度目前无法通过属性值配置。

XSL-FO 1.1不支持非线条的修订条（例如用数字替代线条）。Antenna House Formatter提供了专有扩展以实现此功能，但DITA-OT的PDF转换未利用此功能。

===== 第4页 =====

PDF主题

DITA-OT 4.0包含 com.elovirta.pdf 插件，该插件通过新的 --theme 参数扩展了默认的PDF2插件。--theme 选项接受主题文件路径，无需修改XSLT样式表即可更改PDF输出的样式。

主题可用于调整封面图像、页面尺寸、编号、字体属性、背景颜色和边框、间距以及页眉和页脚等运行内容。

要使用自定义主题生成PDF输出，请通过 --theme 选项将主题文件传递给 dita 命令：

dita --project=samples/project-files/pdf.xml \  
     --theme=path/to/custom-theme-file.yaml  

以下主题提供主题文件格式和受支持配置选项的详细信息。

示例主题文件

主题文件可编写为JSON或YAML格式。DITA-OT安装目录的 docsrc/samples/themes 文件夹提供了多个示例。

注意： 本文档中的示例均使用YAML格式，因其通常比JSON更简洁易读。

DITA-OT文档的PDF输出所使用的YAML主题文件位于安装目录的 dita-ot-dir/docsrc/samples/themes/dita-ot-docs-theme.yaml。

以下示例节选自该文件，展示了常见自定义配置。您可根据需求调整这些示例。

提示： 有关主题插件支持的元素和其他设置的概述，请参见第123页的“样式”、第118页的“页面设置”、第118页的“页眉和页脚”以及第131页的“变量”。

===== 第5页 =====

设置自定义颜色

与CSS或Sass类似，您可以使用 变量（第131页）定义品牌颜色和其他共享值，并通过语义引用（如 $brand-color-primary）在其他 样式（第123页）中复用这些值。

brand:  
  color:  
    inverse: '#e9ecef'  
    links: '#3563ab'  
    note:  
      background:  
        attention: '#fff3cd'  
        caution: '#f8d7da'  
        info: '#dec4f0'  
        tip: '#d16c7d'  
    primary: '#1d365d'  
    secondary: '#6c757d'  
    tertiary: '#bac8d1'  
    xml-domain: '#639'  

图17：dita-ot-docs-theme.yaml 中的颜色变量

上述定义的主品牌色和次品牌色用于第116页的“设置页眉和页脚”及第117页的“添加封面图像”示例。主题示例还定义了链接、注释背景和XML域标记的自定义品牌颜色。

定义自定义字体堆栈

您还可使用 变量（第131页）指定一个或多个字体家族的优先级列表，并通过 font-family 属性在其他样式中引用这些值。

pdf2:  
  font:  
    monospaced: 'Courier New, Courier, Arial Unicode MS, Tahoma, Batang, SimSun'  
    sans: 'Helvetica, Arial Unicode MS, Tahoma, Batang, SimSun'  
    serif: 'Times New Roman, Times, Arial Unicode MS, Tahoma, Batang, SimSun'  

图18：dita-ot-docs-theme.yaml 中的字体系列

此主题使用默认 org.dita.pdf2 插件的默认字体堆栈，但相同方法可用于定义符合企业标识的其他字体系列。

通过 pdf2 前缀定义的字体变量也可添加到 brand 键下，或通过类似 $company-font-sans 的引用在其他位置复用。

定义页面尺寸

页面设置（第118页）包括页面尺寸、方向和页边距。

page:  
  mirror-margins: true  
  size: PA4  

图19：dita-ot-docs-theme.yaml 中的页面设置

DITA-OT文档主题使用PA4页面尺寸（21×28厘米），这是一种适用于A4和US Letter纸张打印的过渡格式。

===== 第6页 =====

mirror-margins 键为双面文档设置对称页边距，使左页边距与右页边距镜像对称。

扩展和覆盖主题

您可以通过一个主题扩展另一个主题。DITA-OT安装目录中的示例包含其他主题文件，可用于将文档主题的PA4页面尺寸覆盖为A4或Letter。

# 将页面尺寸改为A4的示例主题文件  
extends: ./dita-ot-docs-theme.yaml  
page:  
  size: A4  

图20：通过 dita-ot-docs_A4.yaml 切换为A4尺寸

# 将页面尺寸改为US Letter的示例主题文件  
extends: ./dita-ot-docs-theme.yaml  
page:  
  size: Letter  

图21：通过 dita-ot-docs_Letter.yaml 切换为Letter尺寸

当通过 --theme 选项将此类扩展主题传递给 dita 命令时，扩展主题中的 page-size 值将优先于原始 dita-ot-docs-theme.yaml 中的值。

若在扩展主题中添加新键，这些键将覆盖被扩展主题中的对应键。

设置页眉和页脚

文档主题包含调整页眉和页脚内容的示例配置：

header:  
  color: $brand-color-secondary  
  display-align: before  
  end-indent: 10mm  
  even:  
    content: '{part-title}'  
    text-align: start  
  font-family: $pdf2-font-sans  
  odd:  
    content: '{chapter-title}'  
    text-align: end  
  padding-after: 6pt  
  padding-before: 12pt  
  start-indent: 10mm  

图22：dita-ot-docs-theme.yaml 中的页眉设置

===== 第7页 =====

这些设置使用次品牌色（见第115页“设置自定义颜色”）和Sans-serif字体（见第115页“定义自定义字体堆栈”），并通过缩进和填充定位内容。

footer:  
  color: $brand-color-secondary  
  end-indent: 10mm  
  even:  
    content: '{folio}'  
    font-weight: bold  
    text-align: start  
  font-family: $pdf2-font-sans  
  odd:  
    content: '{folio}'  
    font-weight: bold  
    text-align: end  
  padding-after: 12pt  
  padding-before: 6pt  
  start-indent: 10mm  

图23：dita-ot-docs-theme.yaml 中的页脚设置

这些设置使用 {folio} 字段将当前页码置于页脚外侧。content 键可包含静态文本或使用花括号引用的变量。有关可用选项的详细信息，请参见第118页的“页眉和页脚”及第131页的“变量”。

添加封面图像

通过 cover 和 cover-title 样式键（第123页）可添加背景图像并调整文档标题的格式和位置。

cover:  
  background-image: dita-ot-logo-inverse.svg  
  background-repeat: no-repeat  
  height: 25.7cm  
cover-title:  
  color: $brand-color-primary  
  font-size: 36pt  
  font-weight: bold  
  line-height: 1.5  
  space-before: 195mm  

图24：dita-ot-docs-theme.yaml 中的封面设置

DITA-OT文档主题引用了与主题文件同目录的背景图像，并通过设置 cover-title 的 space-before 属性将标题置于页面底部。

提示： 文档主题的最新版本可在GitHub上获取：dita-ot-docs-theme.yaml。

===== 第8页 =====

页面设置

页面尺寸和方向可通过 size 和 orientation 键设置。页边距通过 top、outside、bottom 和 inside 键设置。

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

size 键支持以下值：

• A3

• A4

• A5

• Executive

• JIS B5

• Tabloid

• Legal

• Letter

• PA4

若需使用不支持的页面尺寸，可通过 height 和 width 键自定义。

mirror-margins 键用于设置双面文档的对称页边距。当此键设为 true 时，左页的页边距是右页的镜像。左右页的内部边距相同，外部边距也相同。默认值为 false。

页眉和页脚

页眉或页脚的 content 键可用于添加文本。内容可包含静态文本或通过花括号引用的变量。

当前支持的变量字段包括：

• {title}：地图标题

• {chapter-or-part-or-appendix}：章节、部分或附录编号及标题

• {chapter-title}：章节标题

• {folio}：当前页码

• {year}：当前年份

header:  
  content: '{title} - {chapter}'  
  border-bottom: solid 1pt black  

页眉和页脚尺寸与对齐

通过定义 页面设置 并使用 extent 和 display-align 键调整页眉和页脚的位置。

===== 第9页 =====

page:  
  size: A4  
  top: 30mm  
  outside: 20mm  
  bottom: 30mm  
  inside: 20mm  
header:  
  content: '{title}'  
  extent: 20mm  
  start-indent: 20mm  
  display-align: after  
footer:  
  content: '{folio-with-total}'  
  extent: 20mm  
  start-indent: 20mm  
  display-align: before  

若未设置 extent，默认值将根据页面的顶部（页眉）或底部（页脚）自动调整。

简单页眉和页脚

所有页面可使用相同的页眉和页脚：

header:  
  content: '{title}'  
  start-indent: 10mm  
  end-indent: 10mm  
  border-bottom: solid 1pt black  
  text-align: center  
footer:  
  content: '{folio-with-total}'  
  start-indent: 10mm  
  end-indent: 10mm  
  border-top: solid 1pt black  
  text-align: center  

双面页眉和页脚

mirror-page-margins: true  
header:  
  start-indent: 10mm  
  end-indent: 10mm  
  padding-after: 6pt  
  border-bottom: solid 1pt black  
  odd:  
    content: '{title}'  
    text-align: end  
  even:  
    content: '{chapter}'  
    text-align: start  
footer:  
  start-indent: 10mm  
  end-indent: 10mm  
  padding-after: 6pt  
  border-bottom: solid 1pt black  
  odd:  
    content: '{folio-with-total}'  
    text-align: end  
  even:  
    content: '{folio-with-total}'  
    text-align: start  

===== 第10页 =====

页眉图像

通过 background-image 键添加图像，并通过填充、缩进等调整位置：

header:  
  content: 'DITA-OT'  
  start-indent: 25mm  
  space-before: 10mm  
  line-height: 10mm  
  padding-left: 15mm  
  text-align: start  
  font-family: Helvetica  
  dominant-baseline: middle  
  background-image: dita-ot-logo.svg  
  background-repeat: no-repeat  

样式

通过设置样式键可调整块级和内联元素的呈现。样式键使用XSL-FO属性而非CSS属性。

例如：

• 使用 padding-before 替代 padding-top

• 使用 start-indent 替代 margin-left

默认主题定义了扩展PDF2默认样式的基础键值。要创建共享配置，可编写基础主题文件，并通过 extends 键在其他主题中复用。

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  

XSL-FO扩展属性

主题支持XSL格式化程序实现的扩展属性，例如 background-size。

===== 第11页 =====

块级样式键

块级元素可通过以下键调整样式：

• appendix：附录标题

• codeblock：代码块（支持行号显示）

• fig：图形（可配置标题位置）

• table：表格（支持跨页续表标记）

示例：

style:  
  codeblock:  
    line-numbering: 'true'  
    show-whitespace: 'false'  
  fig:  
    caption-position: 'before'  
  table:  
    table-continued: 'true'  

内联样式键

内联元素可通过以下键调整样式：

• b：粗体

• i：斜体

• link：链接（可配置URL显示）

• uicontrol：用户界面控件

示例：

style:  
  link:  
    link-url: 'true'  
  uicontrol:  
    separator-content: '→'  

变量

主题键值可通过以 $ 开头的变量引用其他键的值。变量声明为普通键，其名称由连字符分隔的扁平化键名组成。

示例：

brand:  
  primary-color: orange  
font:  
  header: Helvetica  
style:  
  topic:  
    color: $brand-primary-color  
    font-family: $brand-font-header  

扩展主题

通过 extends 键可扩展其他主题。若值为 default，则扩展至内置默认主题；否则为相对路径。

# base.yaml  
brand:  
  primary-color: orange  
page:  
  size: A4  

# product/theme.yaml  
extends: ../base.yaml  
page:  
  size: Letter  
style:  
  topic:  
    color: $brand-primary-color  

===== 第12页 =====

语法糖

主题文件可通过语法糖提升可读性。例如：

• content 键支持混合变量和字段引用的DSL。

• 页面尺寸 size 自动转换为 width 和 height。

• 页眉和页脚的奇偶页设置自动合并。

示例：

header:  
  color: silver  
  odd:  
    font-weight: bold  

将解析为：

header:  
  odd:  
    font-weight: bold  
    color: silver  
  even:  
    color: silver  

提示： 完整的主题配置示例和高级用法请参考DITA-OT官方文档。