Previous: , Up: OpenDocument Text Export   [Contents][Index]

13.12.12 Advanced topics in ODT export

ODT 导出后端提供丰富功能，适用于高级用户与高频 ODT 格式使用场景。

Configuring a document converter

ODT 导出后端可直接适配主流转换工具，几乎无需额外配置（见 Extending ODT export）。 以下内容适用于不被支持的转换工具或调整默认配置的场景。

注册转换工具

将转换工具名称添加到变量 org-odt-convert-processes ， 同时需指定该工具的命令行调用方式，详见该变量文档字符串。

配置工具支持格式

通过自定义变量 org-odt-convert-capabilities 指定转换工具可处理的格式， 可参考该变量默认值配置新工具，详情见其文档字符串。

选择转换工具

通过自定义选项 org-odt-convert-process ，将新添加的转换工具设为首选工具。

Working with OpenDocument style files

本节介绍 ODT 导出工具的内部实现：生成带样式文档的方式，以及自动样式与自定义开放文档样式的使用。

ODT 导出工具生成输出依赖两个文件， 这些文件随发行版一同分发，存放路径由变量 org-odt-styles-dir 指定。两个文件分别为：

‘OrgOdtStyles.xml’

该文件内容会并入最终 ODT 文档的 =styles.xml=， 会在以下场景被修改：

  1. 根据用户设置控制大纲编号；
  2. 添加 ‘htmlfontify.el’ 为代码块语法高亮生成的样式。
‘OrgOdtContentTemplate.xml’

该文件内容会并入最终 ODT 文档的 ‘content.xml’ ， Org 大纲内容会插入到文件的 ‘<office:text>’ … ‘</office:text>’ 元素之间。

除作为最终 ‘content.xml’ 的模板外，该文件还用于：

  1. 包含导出工具引用的、用于表格格式化的自动样式；
  2. 包含 ‘<text:sequence-decl>’ … ‘</text:sequence-decl>’ 元素， 控制表格、图片、公式等对象的编号。

以下两个变量控制 ODT 导出工具读取自定义样式与内容模板文件的路径， 自定义这些变量可覆盖导出工具的默认样式。

org-odt-styles-file

ODT 导出后端使用该变量指向的文件（如 ‘styles.xml’ ）生成最终输出， 可接受以下取值：

‘FILE.xml’

使用该文件替代默认 ‘styles.xml’ 。

‘FILE.odt’ 或 ‘FILE.ott’

使用指定开放文档文本或模板文件中包含的 ‘styles.xml’ 。

‘FILE.odt’ 或 ‘FILE.ott’ 及部分内嵌文件

使用指定开放文档文本或模板文件中的 ‘styles.xml’ ， 同时提取指定成员文件并嵌入最终 ODT 文档。

当 ‘styles.xml’ 引用页眉、页脚图片等附加文件时适用此选项。

nil

使用默认 ‘styles.xml’ 。

org-odt-content-template-file

使用该变量指定最终输出中使用的空白 ‘content.xml’ 。

Creating one-off styles

ODT 导出后端可读取 Org 文件中嵌入的原生开放文档 XML 代码， 此类直接格式化方式适用于临时单次使用场景。

在普通文本中嵌入 ODT 标签

使用 ‘@@odt:...@@’ 包裹开放文档语法实现行内标记。 例如高亮一段文本： 

@@odt:<text:span text:style-name="Highlight">This is highlighted
text</text:span>@@. 但这段为普通文本。

提示： 如需查看示例效果，编辑 ‘styles.xml’ （见 默认样式）， 添加如下自定义 Highlight 样式： 

<style:style style:name="Highlight" style:family="text">
  <style:text-properties fo:background-color="#ff0000"/>
</style:style>
嵌入单行开放文档 XML

ODT 导出后端可读取 Org 文件中以 ‘#+ODT:’ 开头的单行配置。 例如强制分页： 

#+ODT: <text:p text:style-name="PageBreak"/>

提示： 如需查看示例效果，编辑 ‘styles.xml’ （见 默认样式）， 添加如下自定义 ‘PageBreak’ 样式。 

<style:style style:name="PageBreak" style:family="paragraph"
             style:parent-style-name="Text_20_body">
  <style:paragraph-properties fo:break-before="page"/>
</style:style>
嵌入整块开放文档 XML

ODT 导出后端支持读取 ODT 导出块形式的开放文档 XML， 此类块使用 ‘#+BEGIN_EXPORT odt’ … ‘#+END_EXPORT’ 结构。

例如创建一段使用粗体的临时段落： 

#+BEGIN_EXPORT odt
  <text:p text:style-name="Text_20_body_20_bold">
  This paragraph is specially formatted and uses bold text.
  </text:p>
#+END_EXPORT

Customizing tables in ODT export

通过 ‘#+ATTR_ODT’ 行指定自定义表格样式，覆盖默认表格格式。 关于表格默认格式的说明，见 Tables in ODT export。

该功能高度模拟开放文档 v1.2 规范147 中表格模板的定义方式。

如需快速预览该功能，安装以下配置后导出后续表格： 

(setq org-export-odt-table-styles
      (append org-export-odt-table-styles
              '(("TableWithHeaderRowAndColumn" "Custom"
                 ((use-first-row-styles . t)
                  (use-first-column-styles . t)))
                ("TableWithFirstRowandLastRow" "Custom"
                 ((use-first-row-styles . t)
                  (use-last-row-styles . t))))))

#+ATTR_ODT: :style TableWithHeaderRowAndColumn
| Name  | Phone | Age |
| Peter |  1234 |  17 |
| Anna  |  4321 |  25 |

上例使用 ‘Custom’ 模板，并定义了两种表格样式 ‘TableWithHeaderRowAndColumn’ 与 ‘TableWithFirstRowandLastRow’ 。 重要： 实现该模板所需的开放文档样式已预先定义， 可在 ‘OrgOdtContentTemplate.xml’ （见 默认样式）的 ‘Custom Table Template’ 部分找到。 添加新模板需在此处定义新样式。

使用该功能的步骤：

  1. 创建表格模板148。

    表格模板是针对以下表格单元格类别的 ‘table-cell’ 与 ‘paragraph’ 样式集合：

    • Body(主体单元格)
    • First column(首列)
    • Last column(末列)
    • First row(首行)
    • Last row(末行)
    • Even row(偶数行)
    • Odd row(奇数行)
    • Even column(偶数列)
    • Odd Column(奇数列)

    上述样式名称需根据表格模板名称按固定规则命名。

    以名为 ‘Custom’ 的表格模板为例，所需样式名称如下表：

    单元格类型单元格样式段落样式
    Body‘CustomTableCell’‘CustomTableParagraph’
    First column‘CustomFirstColumnTableCell’‘CustomFirstColumnTableParagraph’
    Last column‘CustomLastColumnTableCell’‘CustomLastColumnTableParagraph’
    First row‘CustomFirstRowTableCell’‘CustomFirstRowTableParagraph’
    Last row‘CustomLastRowTableCell’‘CustomLastRowTableParagraph’
    Even row‘CustomEvenRowTableCell’‘CustomEvenRowTableParagraph’
    Odd row‘CustomOddRowTableCell’‘CustomOddRowTableParagraph’
    Even column‘CustomEvenColumnTableCell’‘CustomEvenColumnTableParagraph’
    Odd column‘CustomOddColumnTableCell’‘CustomOddColumnTableParagraph’

    创建名为 ‘Custom’ 的表格模板，需在内容模板文件（见 默认样式） 的 ‘<office:automatic-styles>’ … ‘</office:automatic-styles>’ 元素中定义上述样式。

  2. 定义表格样式149。

    定义表格样式需在变量 org-odt-table-styles 中添加条目，并指定：

    • 步骤 (1) 中创建的表格模板名称；
    • 该模板中需要启用的单元格样式集合。

    例如下方条目基于同一模板 ‘Custom’ 定义了两种表格样式 ‘TableWithHeaderRowAndColumn’ 与 ‘TableWithFirstRowandLastRow’ ，通过选择性启用模板中的单元格样式实现不同效果。 

    (setq org-export-odt-table-styles
      (append org-export-odt-table-styles
              '(("TableWithHeaderRowAndColumn" "Custom"
                 ((use-first-row-styles . t)
                  (use-first-column-styles . t)))
                ("TableWithFirstRowandLastRow" "Custom"
                 ((use-first-row-styles . t)
                  (use-last-row-styles . t))))))
  3. 将表格与表格样式关联。

    在 ‘ATTR_ODT’ 行中指定步骤 (2) 中创建的表格样式，示例如下： 

    #+ATTR_ODT: :style TableWithHeaderRowAndColumn
| Name  | Phone | Age |
| Peter |  1234 |  17 |
| Anna  |  4321 |  25 |

Validating OpenDocument XML

有时 ODT 文件因损坏无法打开，可通过开放文档 Relax NG Compact（RNC）语法模式验证文件是否损坏。 验证前需先用 ‘zip’ 解压 ‘.odt’ 文件，注意 ‘.odt’ 文件本质是 ZIP 压缩包：(emacs)File Archives。 ODT 文件内容为 XML 格式，XML 文件验证与模式敏感编辑的通用帮助见 (nxml-mode)Introduction。

自定义 org-odt-schema-dir 指向存放开放文档 RNC 文件与模式定位规则的目录， ODT 导出后端会自动更新 rng-schema-locating-files 。

Footnotes

(147)

OpenDocument-v1.2 Specification

(148)

见开放文档 v1.2 规范中的 ‘<table:table-template>’ 元素。

(149)

见开放文档 v1.2 规范中 ‘<table:table>’ 元素的 ‘table:template-name’ 、 ‘table:use-first-row-styles’ 、 ‘table:use-last-row-styles’ 、 ‘table:use-first-column-styles’ 、 ‘table:use-last-column-styles’ 、 ‘table:use-banding-rows-styles’ 、 ‘table:use-banding-column-styles’ 属性。

Previous: Literal examples in ODT export, Up: OpenDocument Text Export   [Contents][Index]