厚缊

Pandoc 用户手册(一)

厚缊[译] / 2018-08-29


概要

pandoc [选项][输入文件]…

简介

pandoc是通过命令行工具,把一种标记语言转换为另一种的Haskell库。

pandoc能实现多种标记语言和文字处理格式之间的转换,包括但不限于,各种风格的markdown、HTML、LaTeX、docx格式。关于完整的输入、输出格式列表,请查看后文的--from--to选项部分。pandoc也能生成PDF格式的输出,参见后文如何创建PDF文档的部分。

pandoc增强版本的markdown包含了关于表格、定义列表、元数据块、脚注、引用、数学公式等语法。详细内容参见后文pandoc markdown。

pandoc有一个标准的设计:一组在给定格式下解析文本,并转换为原生表述(绝对语法树,AST)的读取设备(readers);一组把原生表述转为目标格式的输出设备(writers)。因此,增加一种输入或输出格式仅仅需要增加一个读取设备或输出设备。用户也可自定义pandoc过滤器来修改中间AST。

由于pandoc关于文件的中间表述比它能转换的许多格式都缺少表现力,所以不能期待pandoc能实现每种格式间的完美转换。pandoc尝试保留文档的结构元素,但不是格式化细节,例如页边距。一些文档元素,如复杂的表格,可能不符合pandoc 简单的文档模式。尽管希望从pandoc markdown到其它格式的转化是完美的,但是从比pandoc markdown更复杂的格式转换会存在一定的损耗。

pandoc用法

若没有指定输入文件,将通过标准输入(stdin)读取。若不指定输出文件,默认是标准输出(stdout)。若输出到一个指定文件,使用 -o 选项:

pandoc -o output.html input.txt 

pandoc默认生成文档片段。若输出独立的文档(例如有效的HTML文档要包含<head><body>),使用 -s 或者 --standalone 标记:

pandoc -s -o output.html input.txt

关于生成独立文档的更多信息请查阅后面的模板部分。

如果是多个输入文件,在解析之前,pandoc把所有的文件合并成一个文件(文件之间用空行分隔)。(使用--file-scope选项来单独解析文件)。

指定格式

输入和输出格式可以通过命令行选项明确指定。输入格式可使用 -r/--read-f/--from选项指定,输出格式可使用 -w/--write-t/--to选项指定。因此,为了把 hello.txt从markdown转为LaTeX 格式,可以输入如下命令:

pandoc -f markdown -t latex hello.txt

要把 hello.html从HTML转为markdown格式:

pandoc -f html -t markdown hello.html

支持的输入、输出格式列表在后文选项部分(-f输入格式和-t输出格式)。你也可使用pandoc --list-input-formatspandoc --list-output-formats查看所有支持的格式。

如果输入输出格式没有明确指定,pandoc尝试依据输入输出文件的扩展名推测它的格式。例如

pandoc -o hello.tet hello.txt

会把 hello.txt从markdown转为LaTeX格式。若不指定输出文件(结果输出到标准输出),或者输出文件的扩展名未知,默认输出格式为HTML。如果没有指定输入文件(输入从标准输入读取),或者输入文件扩展名未知,输入格式默认为markdown。

字符串编码

pandoc使用UTF-8对输入输出进行编码。如果本地字符编码不是UTF-8,应该通过iconv来转换输入输出格式:

iconv -t utf-8 input.txt | pandoc | iconv -f utf-8

注意,在一些格式(如HTML、LaTeX、ConTeXt、RTF、OPML、DocBook 和Texinfo )中,字符编码信息已经包含在文档头中了,但仅当你使用 -s/--stanalone选项时,文档头才包含在输出文件中。

创建PDF文档

为了生成PDF 文档,需要指定扩展名为a.pdf的输出文件。

pandoc test.txt -o test.pdf

pandoc默认使用LaTeX生成PDF文档,这需要安装LaTeX引擎(参见后文 --latex-engine)。

此外,pandoc也可以使用ConTeXt、pdfroff,或者以下任何HTML/CSS-to-PDF-engines来创建PDF:wkhtmltopdf、weasyprint或者prince。为了实现这个,如前文所述,须指定带有PDF扩展名的输出文件,但是要添加--pdf-engine选项或-t context-t html-t ms到命令行中(-t html默认等价于--pdf-engine=wkhtmltopdf)。

PDF输出可以通过LaTeX变量(若使用LaTeX)或者ConTeXt变量(若使用ConTeXt)进行控制。当使用HTML/CSS-to-PDF-engines--css影响输出。如果使用wkhtmltopdf,margin-leftmargin-rightmargin-topmargin-bottomfooter-htmlheader-htmlpapersize会影响输出。

当使用LaTeX时,需要以下宏包(所有最新的TeX发行版均包含了这些宏包):amsfontsamsmathlmifxetexifluatexeurosymlistings(若文档使用了--listings选项)、fancyvrblongtablebooktabsgraphicxgrffile(若文档包含图片)、hyperrefxcolor (colorlinks)、ulemgeometry(geometry)、setspace (linestretch)和babel(lang)。使用用xelatex或lualatex作为LaTeX引擎时,需要fontspec宏包;xelatex需要mathspecpolyglossia(lang)、xecjkbididir变量设定)。若mathspec变量设定了,xelatex将使用mathspec替代unicode-mathupquotemicrotype宏包若可用,则会被使用。若\usepackage{csquotes}已经包含在模板中,或通过/H/--include-in-header选项包含在模板中,csquotes宏包将会被用来排版。natbibbiblatexbibtexbiber可选择性用来渲染参考文献。

从网页进行读取

作为替代,我们可以使用绝对URI地址作为输入文件。这种情况下,pandoc将会通过HTTP获取内容:

pandoc -f html -t markdown http://www.fsf.org

当向URL请求文档数据时,我们可以提供自定义的User-Agent字段或者其它头信息:

pandoc -f html -t markdown --request-header  User-Agent:"Mozilla/5.0" http://www.fsf.org