请帮助乌克兰!
赞助商
Pandoc   一个通用文档转换器

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 导出设置文档。例如,一个常见的困惑(#3214#5169#6145#7236)是对级别大于 3 的标题的不同处理,因为 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 相反,这些行不是在 hyperref 设置之前插入,而是在导言区接近末尾的位置。

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

  • LATEX_CLASS: LaTeX 文档类;与 Org-mode 类似,Pandoc 使用 article 作为默认类。

    此选项的内容以纯文本形式存储在 documentclass 元数据字段中。

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

    此选项的内容以纯文本形式存储在 classoption 元数据字段中。

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

    此选项的内容以内联形式存储在 subtitle 元数据字段中。

  • HTML_HEAD 和 HTML_HEAD_EXTRA: 要添加到 HTML 文档 head 部分的任意行;完全支持。

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

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 过滤器,它将这些未处理的行转换为元数据键值对。

-- intermediate store for variables and their values
local variables = {}

--- Function called for each raw block element.
function RawBlock (raw)
  -- Don't do anything unless the block contains *org* markup.
  if raw.format ~= 'org' then return nil end

  -- extract variable name and value
  local name, value = raw.text:match '#%+(%w+):%s*(.+)$'
  if name and value then
    variables[name] = value
  end
end

-- Add the extracted variables to the document's metadata.
function Meta (meta)
  for name, value in pairs(variables) do
    meta[name] = value
  end
  return meta
end

表格

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

列宽

Org 模式表格不允许单元格内换行,并且包含文本的行可能会变得非常长。这通常导致导出时表格超出页面,尤其是在通过 LaTeX 导出到 PDF 时。源文本中过长的行通常通过设置列宽来隐藏,但默认的 Emacs 导出器会忽略该设置。Pandoc 偏离了 Emacs 的行为,并使用此信息在导出时调整表格列的宽度。

限制

目前尚不支持跨多列或多行的单元格。table.el 网格表允许行合并和列合并,自 2.10 版以来 Pandoc 的内部结构也支持,但解析器尚未更新。

强调规则

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 /HORIZONTAL ELLISPIS/ 字符 ,而是可以键入三个点 ...。en 短破折号和 em 短破折号可以分别写为 -----。此外,引号 (") 和撇号引号 (') 可以通过“智能”方式处理,可能会将其替换为适当的、特定于语言的 Unicode 引号字符。

与 Markdown 中一样,通过启用 smart 扩展可以一次性打开这些行为。但是,禁用 smart(默认设置)一定会禁用智能引号和特殊字符串。相反,它只会导致默认的 Org 模式行为。

特殊字符串功能可以通过 #+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 文件中使用的分隔符类型,而不是始终使用导出格式的默认分隔符。

当前不支持的功能

巴别塔库

巴别塔库在各种编程语言之间进行翻译。这超出了 Pandoc 的范围。请使用 Emacs 运行代码,然后将生成的 Org 文件输入给 Pandoc。