利用Pandoc转换markdown和HTML、LaTeX
- pandoc是什么？
- 如何安装
- 怎么用？
  - 参考文章
- 任务
- 这次不讨论的方法
- 在文本编辑器中使用文档标记语言编写文件
  - 标记语言简史
  - 轻量级标记语言时代
- 标记语言的评价标准
- 若干标记语言的对比
- Chapter 1
  - Section 1
- Chapter 2
  - DocBook
  - TeX/LaTeX
  - Markdown
  - reStructuredText
- 应用Markdown
  - 用Pandoc处理Markdown
  - Pandoc扩展的Markdown
  - Pandoc用于演示
- 总结
如何从零开始制作一个PDF
Try pandoc online
Examples

利用Pandoc转换markdown和HTML、LaTeX

核心提示：本文主要讲述利用Pandoc转换markdown和HTML、LaTeX相关内容：利用Pandoc转换 markdown/reStructuredTex/textile/HTML/LaTeX

pandoc是什么？

如果你需要把文件从一种标记语言格式转换到另一种格式，pandoc会是你的瑞士军刀。它可以把markdown、 reStructuredText、 textile、 HTML、或者LaTeX转换成：

HTML格式: XHTML, HTML5, 以及HTML幻灯片Slidy， S5，或者DZSlides.
文字处理软件格式： Microsoft Word docx, OpenOffice/LibreOffice ODT,OpenDocument XML
电子书： EPUB
文档格式： DocBook, GNU TexInfo, Groff man pages
TeX格式： LaTeX, ConTeXt, LaTeX Beamer slides
PDF via LaTeX
轻量级标记语言格式： Markdown, reStructuredText, AsciiDoc, MediaWiki markup, Emacs Org-Mode, Textile

如何安装

见http://johnmacfarlane.net/pandoc/installing.html。

需要注意的是，我在ubuntu下用命令sudo apt-get install pandoc安装pandoc，发现并不能编译beamer

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

后来在ubuntu的问答网站发现了答案

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

怎么用？

在官方网站的示例中找了一个例子，修改了模板文件mytemplate.tex，使它可以支持中文，然后用下面的命令编译SLIDES.md

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

示例页里还有很多别的例子，其中将markdown文件转换成网页的sldes非常吸引人

pandoc -s –mathml -i -t dzslides SLIDES -o example14a.html\ pandoc -s –webtex -i -t slidy SLIDES -oexample14b.html\ pandoc -s –webtex -t -t s5 SLIDES -o example14c.html

之前益辉就给出过一个HTML5幻灯片的例子。人生苦短啊，不要把太多的时间和精力浪费在调格式上了。

参考文章

pandoc介绍
如何用markdown写简历
如何用markdown写beamer幻灯片

任务

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

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

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

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

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

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

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

这次不讨论的方法

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

OpenOffice.org/LibreOffice
GNOME Office
KOffice
Google Docs
LyX

他们有一些问题：

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

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

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

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

标记语言有一个粗略的类型分类：

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

标记语言简史

1971，troff，Bell Labs
1978，TeX，Donald Knuth
- 1980初期，LaTeX，Leslie Lamport
1982，PostScript，John Warnock和Charles Geschke（Adobe Systems）
1986，SGML，ISO 8879:19861^
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.
Et dolore magna aliqua.
Ut enim ad minim veniam.

Chapter 2

Laboris nisi ut aliquip ex ea commodo consequat!

DocBook

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

<section id="chapter-1">
  <title>Chapter 1</title>
  <para>
    Lorem ipsum!
  </para>
  <para>
    Dolor sit amet, consectetur <emphasis>adipisicing</emphasis> elit.
  </para>
  <section id="section-1">
    <title>Section 1</title>
    <itemizedlist>
      <listitem>
        <para>
          <emphasis role="strong">Sed do eiusmod</emphasis> tempor incididunt
          ut <ulink url="http://example.org/">labore</ulink>.
        </para>
      </listitem>
      <listitem>
        <para>
          Et dolore magna aliqua.
        </para>
      </listitem>
      <listitem>
        <para>
          Ut enim ad <literal>minim veniam</literal>.
        </para>
      </listitem>
    </itemizedlist>
  </section>
</section>
<section id="chapter-2">
  <title>Chapter 2</title>
  <blockquote>
    <para>
      Laboris nisi ut aliquip ex ea commodo consequat!
    </para>
  </blockquote>
</section>

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个标签，非常繁琐冗长，手写很困难。而且XML标准规定，导致如果出现手误而产生XML致命错误，那么整个文档就不能进行任何用途了。

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

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

<h1>Chapter 1</h1>
<p>Lorem ipsum!</p>
<p>Dolor sit amet, consectetur <em>adipisicing</em> elit.</p>
<h2>Section 1</h2>
<ul>
  <li>
    <strong>Sed do eiusmod</strong> tempor incididunt ut
    <a target="_blank" rel="external nofollow" href="http://example.org/" title="Example">labore</a>.
  </li>
  <li>
    Et dolore magna aliqua.
  </li>
  <li>
    Ut enim ad <code>minim veniam</code>.
  </li>
</ul>
<h1>Chapter 2</h1>
<blockquote>
  <p>Laboris nisi ut aliquip ex ea commodo consequat!</p>
</blockquote>

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是这里要介绍的第一个轻量级标记语言。它面向表现，所见即所得。它非常简单，以至于简单到简陋的程度。其作者John Gruber是一个狂热果粉，不难想象他对这个语言简约程度的强迫症程度。

Markdown在互联网上很流行，有一些大型用户，比如Stack Overflow、Reddit、GitHub、Posterous、Tumblr（这两个已被GFW认证）。虽然这个语言很简单，但也有人用这个语言写了一本书：《Pro Git》。

这个语言的问题：

Too simple, sometimes naïve.
以HTML为中心。
不可扩展。
不能用于大型项目（但Pro Git仍然是反例）。
没有规范或标准。

reStructuredText

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

Chapter 1
=========
Lorem ipsum!
Dolor sit amet, consectetur *adipisicing* elit.
-  **Sed do eiusmod** tempor incididunt ut `labore <http://example.org/>`_.
-  Et dolore magna aliqua.
-  Ut enim ad ``minim veniam``.
Chapter 2
=========
    Laboris nisi ut aliquip ex ea commodo consequat!

reStructuredText（rST）是一个丰富可扩展，但又易读、所见即所得的纯文本标记句法。目前正试图成为Python的文档规范（PEP 287）。

rST的设计理念很好地概括了轻量级标记语言的一般哲学：

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

PEP 287还提及另一个原则：

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

归结起来就是：

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

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

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

    Citation references, like [CIT2002]_.
    .. [CIT2002] A citation
       (as often used in journals).

应用Markdown

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

用Pandoc处理Markdown

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新增了这些功能：

定义列表
表格
脚注
引用
标题
行内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推荐的。跟PDF幻灯片唯一的区别是，讲义需要另外生成，不过这也很直接。

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

之前我没有考虑的Markdown和LaTeX Beamer结合制作幻灯片也有不少成功经验，这就是其一。不过鉴于Beamer模板的复杂性，我就暂时不折腾这个了，读者可以自行尝试。

总结

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

如何从零开始制作一个PDF

2011年5月5日

安装TeXLive发行版（以此为例），包括XeTeX在内。
用pandoc -D latex >xetex-cjk.template输出默认模板，现在还不能用中文。
在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

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

Pandoc a universal document converter

Try pandoc online

You can try pandoc online here.

Examples

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

HTML fragment:

pandoc README -o example1.html

Standalone HTML file:

pandoc -s README -o example2.html

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

LaTeX:

pandoc -s README -o example4.tex

From LaTeX to markdown:

pandoc -s example4.tex -o example5.text

reStructuredText:

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

Rich text format (RTF):

pandoc -s README -o example7.rtf

Beamer slide show:

pandoc -t beamer SLIDES -o example8.pdf

DocBook XML:

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

Chunked XHTML via DocBook and xmlto:

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

Man page:

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

ConTeXt:

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

PDF via pandoc and ConTeXt’s texexec:

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

Converting a web page to markdown:

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

From markdown to PDF:

pandoc README -o example13.pdf

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

A wiki program using Happstack and pandoc: gitit
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

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

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

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

OpenDocument XML:

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

ODT (OpenDocument Text, readable by OpenOffice):

pandoc README -o example21.odt

MediaWiki markup:

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

EPUB ebook:

pandoc -S README -o README.epub

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

Textile writer:

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

Textile reader:

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

Org-mode:

pandoc -s -S README -o example26.org

AsciiDoc:

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

Word docx:

pandoc -s -S README -o example28.docx

LaTeX math to docx:

pandoc -s math.tex -o example29.docx

Pandoc 转换 markdown 和 HTML、LaTeX