抠丁客 抠丁客
项目
编辑 (2024/8/5)

Org-mode 的功能与差异

Pandoc 处理 org 文件的方式与 Emacs org-mode 类似。本文档旨在突出那些无法实现或尚未实现的情况。

导出选项

以下导出关键字得到支持。（由于它们填充元数据字段，除非使用 -s/--standalone 选项来生成包含元数据的独立文档，否则通常不会影响输出。）

  • AUTHOR: 作者列表（以逗号分隔）；完全支持。
  • CREATOR: 输出生成器；作为纯文本元数据条目 creator 插入，但默认模板不使用它。
  • DATE: 创建或发布日期；Pandoc 支持良好。
  • EMAIL: 作者的电子邮件地址；作为纯文本元数据字段 email 插入，但默认模板不使用它。
  • LANGUAGE: 文档语言；作为纯文本元数据字段 lang 插入。其值应为 BCP47 语言标签。
  • SELECT_TAGS: 用于选择导出树的标签。
  • EXCLUDE_TAGS: 阻止子树被导出的标签。完全支持。
  • TITLE: 文档标题；完全支持。
  • EXPORT_FILE_NAME: 目标文件名；不支持，输出默认为标准输出，除非命令行选项中指定了目标。

Pandoc 尝试在导出 org 文档时与 org-mode 兼容。如果某些行为令人困惑，请参考 org-mode 的 Export-Settings 文档。例如，常见的困惑是处理大于 3 级的标题不同（如 #3214、#5169"、#6145 和 #7236），这是因为 org-mode 默认设置 org-export-headline-levels（可通过 #+OPTIONS: H:3 配置）为 3。

特定格式选项

Emacs Org-mode 支持适用于特定导出格式的额外导出选项。这些选项的行为在 Org-mode 中可能根据输出格式而有所不同，而 Pandoc 在解析时对格式无关，其中的差异会在出现的地方注明。

  • DESCRIPTION: 文档描述；Pandoc 解析此选项为带有标记的文本，并将其插入到 description 元数据字段中。该字段未在默认模板中使用。

    Pandoc 跟随 LaTeX 导出器的做法，允许在描述中使用标记。相比之下，Org-mode 的 HTML 导出器将描述视为纯文本。

  • LATEX_HEADER 和 LATEX_HEADER_EXTRA: 向文档前言中添加任意行。与 Org-mode 不同，这些行不是在超链接设置之前插入，而是接近前言的末尾。

    此选项的内容存储为 header-includes 元数据字段中的原始 LaTeX 行列表。

  • LATEX_CLASS: LaTeX 文档类；与 Org-mode 一样，Pandoc 使用 article 作为默认类。

    此选项的内容存储为纯文本元数据字段 documentclass。

  • LATEX_CLASS_OPTIONS: LaTeX 文档类的选项；完全支持。

    此选项的内容存储为纯文本元数据字段 classoption。

  • SUBTITLE: 文档副标题；完全支持。

    此选项的内容存储为 subtitle 元数据字段中的内联元素。

  • HTML_HEAD 和 HTML_HEAD_EXTRA: 向 HTML 文档的头部添加任意行；完全支持。

    这些选项的内容存储为 header-includes 元数据字段中的原始 HTML 行列表。

Pandoc 特定选项

Pandoc 认识一些 Emacs Org 不使用的导出选项。

  • NOCITE: 该字段将列出的引用添加到参考文献中，无需在文本中提及它们。特殊值 @* 会导致所有可用的参考文献都被添加到参考文献中。
  • HEADER-INCLUDES: 类似于 HTML_HEAD 和 LATEX_HEADER，但将选项的值视为带有标记的正常文本。
  • INSTITUTE: 作者的隶属机构；将其视为带有标记的文本，并存储在 institute 元数据字段中。默认情况下，该字段会包含在 Beamer 演示文稿的标题幻灯片中。

其他选项

任何未在上面列出的导出选项或指令，在使用 Pandoc 解析时没有效果。然而，这些信息被保留为 原始块。可以通过 过滤器 访问它，并且将在 org 输出中包括。

指令作为元数据 例如，我们将恢复 Pandoc 2.10 之前的旧行为。未知的关键字被视为变量定义，并添加到文档的元数据中。在 org 文件中键入 #+key: value 与使用 --metadata key=value 选项运行 Pandoc 具有相同的效果。

从 Pandoc 2.10 开始，每个以 #+ 开头的未处理行都作为格式为 org 的原始块内部保存。此块可以由过滤器检查和处理。下面是一个 Lua 过滤器，它可以将这些未处理的行转换为元数据键值对。

-- 用于存储变量及其值的中间存储
local variables = {}

-- 用于每个原始块元素的函数
function RawBlock(raw)
  -- 如果该块不包含 *org* 标记，则不做任何操作
  if raw.format ~= 'org' then return nil end

  -- 提取变量名称和值
  local name, value = raw.text:match'^#%+(%w+):%s*(.+)$'
  if name and value then
    variables[name] = value
  end
end

-- 将提取的变量添加到文档的元数据中
function Meta(meta)
  for name, value in pairs(variables) do
    meta[name] = value
  end
  return meta
end

表格

Pandoc 支持普通的 org 表格（有时称为“管道表格”）和网格表格（由 table.el 创建的表格）。

列宽

Org-mode 表格不允许单元格内的换行符，含有文本的行可能会非常长。这通常会导致表格在导出时超出页面边界，尤其是在通过 LaTeX 导出到 PDF 时。源文本中的过长行通常通过设置 列宽 来隐藏，但默认的 Emacs 导出器忽略该设置。Pandoc 与 Emacs 的行为不同，它使用这些信息在导出时调整表格列宽。

限制

目前还不支持跨越多个列或行的单元格。table.el 网格表格允许行跨和列跨，Pandoc 自 2.10 版本以来的内部结构也支持这些特性，但解析器尚未更新。

强调规则

Org-mode 使用复杂的规则来决定字符串是否代表强调文本。在 Emacs 中，这可以通过变量 org-emphasis-regexp-components 自定义。像这样的变量与 Pandoc 的模型不太匹配。相反，可以使用特殊行来更改这些值：

#+pandoc-emphasis-pre: "-\t ('\"{\x200B"
#+pandoc-emphasis-post: "-\t\n .,:!?;'\")}[\x200B"

以上描述了这些变量的默认值。参数必须是有效的（Haskell）字符串。如果解释参数为字符串失败，则恢复默认值。

更改强调规则仅会影响特殊行之后的部分文档。它们必须是一些最早的行之一，才能改变整个文档的解析行为。也可以临时更改选定部分的值。以下代码片段中的字符串 test 将作为强调文本读取，而文档的其余部分将使用默认的强调规则进行解析：

#+pandoc-emphasis-pre: "["
#+pandoc-emphasis-post: "]"
[/test/]
#+pandoc-emphasis-pre:
#+pandoc-emphasis-post:

smart 扩展

Org-mode 允许通过特殊字符序列插入某些字符。例如，可以使用三个点 ... 替代手动输入 Unicode /水平省略号/ 字符 …。破折号和长破折号可以分别写为 -- 和 ---。此外，引号 (") 和撇号引号 (') 可以以“智能”的方式处理，可能用适当的、语言特有的 Unicode 引号字符替换它们。

与 Markdown 类似，可以通过启用 smart 扩展一次性开启所有这些行为。但是，禁用 smart（默认设置）并不一定会禁用智能引号和特殊字符串。相反，它只会导致默认的 Org-mode 行为。

特殊字符串功能可以通过 #+OPTIONS: -:nil 导出设置 关闭。目前没有控制这些特性的命令行标志。作为变通方案，可以使用过程替换，这是大多数 shell 支持的功能。它允许在命令行上提供选项行：

pandoc -f org <(printf "#+OPTIONS: -:nil\n")

fancy_lists 扩展

Org-mode 有一个变量 org-list-allow-alphabetical，当设置为 t 时，允许使用单个字母标记的有序列表。由于此变量默认为 nil，可以通过启用 fancy_lists 扩展在 Pandoc 中可选地启用字母标记。

当 fancy_lists 被启用时，Pandoc 还会解析以一个小写或大写字母开头的列表标记，例如 a. 和 D)。与 Markdown 中使用此扩展的情况不同，不能使用罗马数字或 # 占位符作为标记，因为它们在 Org-mode 中不允许。

通过 fancy_lists 扩展启用的另一个行为是 Pandoc 会区分列表标记的 . 和 ) 分隔符。本质上，这意味着在将 Org 转换为 LaTeX 等格式时，Pandoc 会尊重你在 Org 文件中使用的分隔符类型，而不是总是使用导出格式的默认分隔符。

当前不支持的功能

Library Of Babel

The library of babel 在各种编程语言之间进行互译。这对于 Pandoc 超出了范围。请使用 Emacs 运行代码，然后将结果的 org 文件传递给 Pandoc。

在本文档中