---
layout: post
title: 利用Pandoc转换markdown和HTML、LaTeX
description: 利用Pandoc转换 markdown/reStructuredTex/textile/HTML/LaTeX
keywords: Pandoc
author: admin
date: 2012-03-28 17:43
category: 网络技术
tags: pandoc
---

## pandoc是什么？

如果你需要把文件从一种标记语言格式转换到另一种格式，[pandoc](http://johnmacfarlane.net/pandoc)会是你的瑞士军刀。它可以把[markdown](http://daringfireball.net/projects/markdown/)、
[reStructuredText](http://docutils.sourceforge.net/docs/ref/rst/introduction.html)、
[textile](http://redcloth.org/textile)、
[HTML](http://www.w3.org/TR/html40/)、或者[LaTeX](http://www.latex-project.org/)转换成：

- HTML格式: XHTML, HTML5,
以及HTML幻灯片[Slidy](http://www.w3.org/Talks/Tools/Slidy)，
[S5](http://meyerweb.com/eric/tools/s5/)，或者[DZSlides](http://paulrouget.com/dzslides/).
- 文字处理软件格式： Microsoft Word
[docx](http://www.microsoft.com/interop/openup/openxml/default.aspx),
OpenOffice/LibreOffice
[ODT](http://en.wikipedia.org/wiki/OpenDocument), [OpenDocument
XML](http://opendocument.xml.org/)
- 电子书： [EPUB](http://en.wikipedia.org/wiki/EPUB)
- 文档格式： [DocBook](http://www.docbook.org/), [GNU
TexInfo](http://www.gnu.org/software/texinfo/), [Groff
man](http://www.gnu.org/software/groff/groff.html) pages
- TeX格式： [LaTeX](http://www.latex-project.org/),
[ConTeXt](http://www.pragma-ade.nl/), LaTeX Beamer slides
- [PDF](http://en.wikipedia.org/wiki/Portable_Document_Format) via
LaTeX
- 轻量级标记语言格式：
[Markdown](http://daringfireball.net/projects/markdown/),
[reStructuredText](http://docutils.sourceforge.net/docs/ref/rst/introduction.html),
[AsciiDoc](http://www.methods.co.nz/asciidoc/), [MediaWiki
markup](http://www.mediawiki.org/wiki/Help:Formatting), Emacs
[Org-Mode](http://orgmode.org),
[Textile](http://redcloth.org/textile)


## 如何安装

见[http://johnmacfarlane.net/pandoc/installing.html](http://johnmacfarlane.net/pandoc/installing.html)。

需要注意的是，我在ubuntu下用命令`sudo apt-get install pandoc`安装[pandoc](http://johnmacfarlane.net/pandoc)，发现并不能编译beamer

pandoc -t beamer talk.txt -o talk.pdf
pandoc: Unknown writer: beamer

后来在ubuntu的问答网站发现了[答案](http://askubuntu.com/questions/108138/pandoc-on-ubuntu-cant-use-beamer)

sudo apt-get autoremove pandoc
sudo apt-get install cabal-install
cabal update
cabal install pandoc

然后再把`~/.cabal`加到路径中去，在`.bashrc`里加上一句

~~~~ {.line-numbers}
1
~~~~

export PATH=/home/ypchen/.cabal/bin:$PATH

## 怎么用？

在官方网站的[示例](http://johnmacfarlane.net/pandoc/demos.html)中找了一个例子，修改了模板文件[mytemplate.tex](/cn/downloads/code/2012/03/mytemplate.tex)，使它可以支持中文，然后用下面的命令编译[SLIDES.md](/cn/downloads/code/2012/03/SLIDES.md)

pandoc -N --template=mytemplate.tex --variable version=1.9 SLIDES.md --latex-engine=xelatex --toc -o example14.pdf

[示例](http://johnmacfarlane.net/pandoc/demos.html)页里还有很多别的例子，其中将markdown文件转换成网页的sldes非常吸引人

pandoc -s –mathml -i -t dzslides
[SLIDES](http://johnmacfarlane.net/pandoc/demo/SLIDES) -o
[example14a.html](http://johnmacfarlane.net/pandoc/demo/example14a.html)\
pandoc -s –webtex -i -t slidy
[SLIDES](http://johnmacfarlane.net/pandoc/demo/SLIDES) -o
[example14b.html](http://johnmacfarlane.net/pandoc/demo/example14b.html)\
pandoc -s –webtex -t -t s5
[SLIDES](http://johnmacfarlane.net/pandoc/demo/SLIDES) -o
[example14c.html](http://johnmacfarlane.net/pandoc/demo/example14c.html)

之前益辉就给出过一个[HTML5幻灯片的例子](http://yihui.name/cn/2011/11/html5-slides/)。人生苦短啊，不要把太多的时间和精力浪费在调格式上了。

### 参考文章

- [pandoc介绍](http://stdio.tumblr.com/lightdoc)
- [如何用markdown写简历](http://sysadvent.blogspot.com/2011/12/day-14-write-your-resume-in-markdown.html)
- [如何用markdown写beamer幻灯片](http://www.music.mcgill.ca/~sinclair/content/blog/using_markdown_for_beamer_presentations)





## 任务

现在有一个任务：制作一个文件。例如：

- 报告、论文、软件手册、作业、信件、网页、演示胶片。

并且任务对这个文件有一定**但不太复杂**的样式要求。最简单的样式就是分段，长篇文字至少要分段才可以看清。一般常用的样式例如：

- 页：页眉、页脚、边距；
- 段：标题、章节、列表（缩进、间距、……）；
- 字：字体、修饰；
- 插入：表格、列表、公式。

并且可能还需要将此文件输出到不同的表现形式，例如：

- 纸张、投影仪、PDF、网页、邮件、纯文本。

需要一些方法来完成这个任务。

## 这次不讨论的方法

字处理器（文档准备系统）和/或演示程序：

- OpenOffice.org/LibreOffice
- GNOME Office
- KOffice
- Google Docs
- LyX

他们有一些问题：

- 都是专门软件。
- 都是图形界面。
- 有一些二进制的文件格式，不可读、写、改。
- OOO使用了Java虚拟机，又慢又丑，而且Java死期不远。

所以希望能够在一个文本编辑器中完成这个任务。

## 在文本编辑器中使用文档标记语言编写文件

从源代码开始，需要一个给文档内容标注样式的语言，这就是标记语言（markup
language）。

标记语言有一个粗略的类型[分类](http://en.wikipedia.org/wiki/Markup_language#Types)：

- 表现型：描述文本表现形式、产生所见即所得的效果。
- 过程型：在文本中嵌入指令，让程序进行特定处理。
- 描述型：对文件不同部分进行不同的语义标记，而相对表现形式来说是中立的。

### 标记语言简史

- 1971，troff，Bell Labs
- 1978，TeX，Donald Knuth
- 1980初期，LaTeX，Leslie Lamport

- 1982，PostScript，John Warnock和Charles Geschke（Adobe Systems）
- 1986，SGML，ISO 8879:1986^[1](#fn:sgml-example)^
- 1991，HTML，Tim Berners-Lee
- 1991，DocBook，HAL Computer Systems和O’Reilly & Associates
- 1998，XML 1.0，W3C

### 轻量级标记语言时代

- 1998，BBCode，Ultimate Bulletin Board
- 2001，txt2tags，txt2tags team
- 2002，reStructuredText，David Goodger
- 2002，AsciiDoc，Stuart Rackham
- 2004，Markdown，John Gruber

##标记语言的评价标准

在开始写作之前，需要选择一个不错的标记语言。它应该：

- 容易写；
- 容易读；
- 容易改。

这里依据的原则是：

- 高德纳：文学化编程。
- ESR概括的Unix哲学：KISS；经济原则（宁花机器一分，不花程序员一秒）。
- 本文标题表明的讨论主题：轻量级。

##若干标记语言的对比

这里举一个样例。一般情况下，我们需要得到这样一个文件：

##Chapter 1

Lorem ipsum! Dolor sit amet, consectetur *adipisicing* elit.

### Section 1

- **Sed do eiusmod** tempor incididunt ut
[labore](http://example.org/ "Example").
- Et dolore magna aliqua.
- Ut enim ad `minim veniam`.

##Chapter 2

> Laboris nisi ut aliquip ex ea commodo consequat!

### DocBook

为了生成样例文件，我们需要写这些DocBook代码：


Chapter 1

Lorem ipsum!


Dolor sit amet, consectetur adipisicing elit.


Section 1



Sed do eiusmod tempor incididunt
ut labore.




Et dolore magna aliqua.




Ut enim ad minim veniam.






Chapter 2


Laboris nisi ut aliquip ex ea commodo consequat!




> Why care about DocBook at all? There are two possibilities that make
> DocBook really interesting. One is *multi-mode rendering* and the
> other is *searchable documentation databases*. — Eric Raymond.
> *DocBook Demystification HOWTO*.

DocBook是一个描述型的标记语言。它从一开始就是面向机器的。ESR说，DocBook有两个真正有趣的用途，一个是生成其他各种格式的文件，另一个是构成可搜索的文档数据库。因为它具有了很强的格式和语义，所以可以对于机器来说进行处理可以做到很精确，也有利于检索。

这样，另一方面，它就非常重量级，[含有417个标签](http://github.com/wojdyr/fityk/wiki/DocBookVsReStructuredText)，非常繁琐冗长，手写很困难。而且XML标准规定，导致如果出现手误而产生XML[致命错误](http://www.w3.org/TR/xml/#dt-fatal)，那么整个文档就不能进行任何用途了。

因此我认为这个语言与之前确定的评价标准不符。

与其类似的HTML虽然同样繁琐，也要简单很多了：

Chapter 1


Lorem ipsum!


Dolor sit amet, consectetur adipisicing elit.



Section 1




Chapter 2



Laboris nisi ut aliquip ex ea commodo consequat!




### TeX/LaTeX

为了生成样例文件，我们需要写这些LaTeX代码：

\section{Chapter 1}

Lorem ipsum!

Dolor sit amet, consectetur \emph{adipisicing} elit.

\subsection{Section 1}

\begin{itemize}
\item
\textbf{Sed do eiusmod} tempor incididunt ut \href{http://example.org/}{labore}.
\item
Et dolore magna aliqua.
\item
Ut enim ad \verb!minim veniam!.
\end{itemize}

\section{Chapter 2}

\begin{quote}
Laboris nisi ut aliquip ex ea commodo consequat!
\end{quote}

TeX是一个排版系统，经过LaTeX的包装，产生一种过程型、但又倾向于描述型的标记语言。

LaTeX专长是数学公式排版，除此之外作为一种标记语言它并不算友好。

- 丑陋、冗长、全是反斜杠。
- 难学、难安装、难调试。
- 记号太多，但经常用的记号很少。
- 语法严格，容易出错，但出错之后调试信息令人困惑。
- 难安装问题需要通过TeX发行版来解决。

- 标记占文字太多，默认行为太多，令人无法把握。
- Unicode支持简陋。
- 有若干种在LaTeX上通过hack支持CJK的方式，但都有这种那样的问题。
- 可以使用支持Unicode的XeTeX后端、XeLaTeX和xeCJK，为较好解决方案。
- Debian有TeX Live包，为一个较好的TeX发行版。

### Markdown

为了生成样例文件，我们需要写这些Markdown代码：

# Chapter 1

Lorem ipsum!

Dolor sit amet, consectetur _adipisicing_ elit.

## Section 1

- **Sed do eiusmod** tempor incididunt ut [labore](http://example.org/ "Example").
- Et dolore magna aliqua.
- Ut enim ad `minim veniam`.

# Chapter 2

> Laboris nisi ut aliquip ex ea commodo consequat!

> A Markdown-formatted document should be publishable as-is, as plain
> text, without looking like it’s been marked up with tags or formatting
> instructions. — John Gruber. *Markdown Syntax: Philosophy*.

[Markdown](http://daringfireball.net/projects/markdown/)是这里要介绍的第一个轻量级标记语言。它面向表现，所见即所得。它非常简单，以至于简单到简陋的程度。其作者John
Gruber是一个狂热果粉，不难想象他对这个语言简约程度的强迫症程度。

Markdown在互联网上很流行，有一些大型用户，比如[Stack
Overflow](http://stackoverflow.com/)、[Reddit](http://www.reddit.com/)、[GitHub](https://github.com/)、[Posterous](http://posterous.com/)、[Tumblr](http://www.tumblr.com/)（这两个已被GFW认证）。虽然这个语言很简单，但也有人用这个语言写了一本书：《[Pro
Git](http://progit.org/2009/07/28/the-gory-details.html)》。

这个语言的问题：

- Too simple, sometimes naïve.
- 以HTML为中心。
- 不可扩展。
- [不能用于大型项目](http://adam.gomaa.us/blog/2007/oct/22/markdown-doesnt-scale/)（但*Pro
Git*仍然是反例）。
- 没有规范或标准。

### reStructuredText

为了生成样例文件，我们需要写这些rST代码：

Chapter 1
=========

Lorem ipsum!

Dolor sit amet, consectetur *adipisicing* elit.


- **Sed do eiusmod** tempor incididunt ut `labore `_.
- Et dolore magna aliqua.
- Ut enim ad ``minim veniam``.

Chapter 2
=========

Laboris nisi ut aliquip ex ea commodo consequat!

reStructuredText（rST）是一个丰富可扩展，但又易读、所见即所得的纯文本标记句法。目前正试图成为Python的文档规范（[PEP
287](http://www.python.org/dev/peps/pep-0287/)）。

rST的[设计理念](http://docutils.sourceforge.net/docs/ref/rst/introduction.html#goals)很好地概括了轻量级标记语言的一般哲学：

- 可读：要让对此标记语言完全不了解的读者也能轻易阅读，未经处理的原始代码也可以轻易直接阅读。
- 低调：应使用最常见、最自然、最简单的方式。
- 明确：一种标记只有一种解释，不能产生歧义。
- 正常：不应导致意外的处理结果。
- 直觉：要明显易记。
- 简单：要能使用普通文本编辑器轻易使用编写。
- 伸缩：要能够适用于各种规模和长度的文本。
- 强大：要提供足够多功能来生成结构丰富的文件。
- 扩展：应提供简单句法和接口以扩展其他标记。
- 语言中立：要能适用于各种自然或者人工语言，而不限于英语。
- 输出格式中立：要能用于输出各种格式，不应偏向于某一特定格式。

PEP 287还提及另一个原则：

- 程序能推导的信息就不再需要额外标记。

归结起来就是：

- 容易读、容易学、容易写、不容易错。
- 强大、但又最小（简约）。
- 通用、普适。

后两点是原始Markdown所不具有的。这些哲学也可以用于评判其他轻量级标记语言。（比如为什么我觉得asciidoc不好。）

但是我不喜欢rST，单纯因为它的链接标记比较奇怪：

Citation references, like [CIT2002]_.

.. [CIT2002] A citation
(as often used in journals).

##应用Markdown

以上介绍了两种轻量级标记语言，符合最初设想的要求。这两种算是比较常用和著名的，实际上还有其他一些轻量级标记语言，比如AsciiDoc、txt2tags。这里就我偏好的Markdown作应用的介绍。

### 用Pandoc处理Markdown

[Pandoc](http://johnmacfarlane.net/pandoc/)可以对Markdown和rST进行各种处理，号称文档处理的瑞士军刀。它可以：

- 读：Markdown，rST子集，HTML和LaTeX。
- 写：纯文本，Markdown，rST，HTML，LaTeX，ConTeXt，RTF，DocBook
XML，OpenDocument XML，ODT，GNU Texinfo，MediaWiki标记，groff man
pages，EPUB电子书，和S5以及Slidy格式的HTML幻灯片。附带脚本`markdown2pdf`可以将Markdown通过转为LaTeX而输出到PDF。

### Pandoc扩展的Markdown

经过Pandoc扩展的Markdown就足够强大，可以满足大多数样式需求了。Pandoc新增了这些[功能](http://johnmacfarlane.net/pandoc/README.html)：

- 定义列表
- 表格
- 脚注
- 引用
- 标题
- 行内TeX数学公式：`$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$`
- 行内原始HTML代码
- 行内原始TeX代码

其中包含HTML和TeX代码的功能直接为Markdown提供了极大的扩展能力，弥补了原始Markdown的主要缺陷。

当然，这些功能的组合要与rST的设计理念相比还显得有一些问题，不过对我来说够用了。

### Pandoc用于演示

我的了解中比较常见的演示手段是用LaTeX
Beamer生成若干幻灯片，然后用PDF阅读器全屏播放。

Pandoc可以将Markdown转换成Slidy和S5（HTML代码），然后用网页浏览器来播放。Slidy是[W3C推荐](http://www.w3.org/Talks/Tools/)的。跟PDF幻灯片唯一的区别是，讲义需要另外生成，不过这也很直接。

不幸的是，Debian负责给Pandoc打包的人比较懒不怎么更新，导致Pandoc这个包生成幻灯片的功能有问题。所以最后这个幻灯片还是拿Google
Docs生成的。

之前我没有考虑的Markdown和LaTeX
Beamer结合制作幻灯片也有不少[成功经验](http://www.google.com/search?q=markdown+beamer)，[这](http://www.music.mcgill.ca/~sinclair/content/blog/using_markdown_for_beamer_presentations)就是其一。不过鉴于Beamer模板的复杂性，我就暂时不折腾这个了，读者可以自行尝试。

## 总结

- 轻量级标记语言面向表现，源代码文本已所见即所得；重量级标记语言一般面向结构或者语义，难以直接阅读。
- 使用Pandoc Markdown处理轻量级文档任务可以满足需求，方便易行。
- 高级排版任务仍需使用LaTeX等重量级语言。

# 如何从零开始制作一个PDF

> 2011年5月5日

1. 安装TeXLive发行版（以此为例），包括XeTeX在内。
2. 用`pandoc -D latex >xetex-cjk.template`输出默认模板，现在还不能用中文。
3. 在`xetex-cjk.template`里修改和添加（字体自选）：

\ifxetex
\usepackage{fontspec}
\defaultfontfeatures{Mapping=tex-text}
$if(cjk)$
\usepackage[BoldFont,SlantFont,CJKchecksingle]{xeCJK}
\setCJKmainfont{Adobe Song Std}
\setCJKsansfont{Adobe Kaiti Std}
\setCJKmonofont{Adobe Fangsong Std}
\punctstyle{quanjiao}
$endif$
\else

4. `markdown2pdf --xetex --template=xetex-cjk.template -V cjk=yes Paper.markdown -o Paper.pdf`
5. 阅读`pandoc(1)`和`markdown2pdf(1)`的使用手册，了解额外的特性。
6. 阅读LaTeX语法和xeCJK配置方法，自定义模板（不能自定义怎么行！）。xeCJK的文档附带在TeXLive里了。

* * * * *




Pandoc a universal document converter

[Try pandoc online](#TOC)
=========================

You can try pandoc online [here](http://johnmacfarlane.net/pandoc/try).

[Examples](#TOC)
================

To see the output created by each of the commands below, click on the
name of the output file:

1. HTML fragment:

pandoc README -o example1.html

2. Standalone HTML file:

pandoc -s README -o example2.html

3. HTML with smart quotes, table of contents, CSS, and custom footer:

pandoc -s -S --toc -c pandoc.css -A footer.html README -o example3.html

4. LaTeX:

pandoc -s README -o example4.tex

5. From LaTeX to markdown:

pandoc -s example4.tex -o example5.text

6. reStructuredText:

pandoc -s -w rst --toc README -o example6.text

7. Rich text format (RTF):

pandoc -s README -o example7.rtf

8. Beamer slide show:

pandoc -t beamer SLIDES -o example8.pdf

9. DocBook XML:

pandoc -s -S -w docbook README -o example9.db

Chunked XHTML via DocBook and
[xmlto](http://cyberelk.net/tim/xmlto/):

xmlto xhtml -m config.xsl example9.db -o example9/

10. Man page:

pandoc -s -w man pandoc.1.md -o example10.1

11. ConTeXt:

pandoc -s -w context README -o example11.tex

PDF via pandoc and ConTeXt’s `texexec`:

texexec --pdf example11.tex # produces example11.pdf

12. Converting a web page to markdown:

pandoc -s -r html http://www.gnu.org/software/make/ -o example12.text

13. From markdown to PDF:

pandoc README -o example13.pdf

14. PDF with numbered sections and a custom LaTeX header:

pandoc -N --template=mytemplate.tex --variable version=1.9 README --latex-engine=xelatex --toc -o example14.pdf

15. A wiki program using [Happstack](http://happstack.com) and pandoc:
[gitit](http://gitit.net)

16. HTML slide shows:

pandoc -s --mathml -i -t dzslides SLIDES -o example14a.html

pandoc -s --webtex -i -t slidy SLIDES -o example14b.html

pandoc -s --webtex -i -t s5 SLIDES -o example14c.html

17. TeX math in HTML:

pandoc math.text -s -o mathDefault.html

pandoc math.text -s --mathml -o mathMathML.html

pandoc math.text -s --webtex -o mathWebTeX.html

pandoc math.text -s --mathjax -o mathMathJax.html

pandoc math.text -s --latexmathml -o mathLaTeXMathML.html

18. Syntax highlighting of delimited code blocks:

pandoc code.text -s --highlight-style pygments -o example18a.html

pandoc code.text -s --highlight-style kate -o example18b.html

pandoc code.text -s --highlight-style monochrome -o example18c.html

pandoc code.text -s --highlight-style espresso -o example18d.html

pandoc code.text -s --highlight-style haddock -o example18e.html

pandoc code.text -s --highlight-style tango -o example18f.html

19. GNU Texinfo, converted to info, HTML, and PDF formats:

pandoc README -s -o example19.texi

makeinfo example19.texi -o example19.info

makeinfo example19.texi --html -o example19

texi2pdf example19.texi # produces example19.pdf

20. OpenDocument XML:

pandoc README -s -w opendocument -o example20.xml

21. ODT (OpenDocument Text, readable by OpenOffice):

pandoc README -o example21.odt

22. MediaWiki markup:

pandoc -s -S -w mediawiki --toc README -o example22.wiki

23. EPUB ebook:

pandoc -S README -o README.epub

24. Markdown citations:

pandoc -s -S --biblio biblio.bib --csl chicago-author-date.csl CITATIONS -o example24a.html

pandoc -s -S --biblio biblio.bib --csl mhra.csl CITATIONS -o example24b.html

pandoc -s -S --biblio biblio.bib --csl ieee.csl CITATIONS -t man -o example24c.1

25. Textile writer:

pandoc -s -S README -t textile -o example25.textile

26. Textile reader:

pandoc -s -S example25.textile -f textile -t html -o example26.html

27. Org-mode:

pandoc -s -S README -o example26.org

28. AsciiDoc:

pandoc -s -S README -t asciidoc -o example27.txt

29. Word docx:

pandoc -s -S README -o example28.docx

30. LaTeX math to docx:

pandoc -s math.tex -o example29.docx