@@ -1,14 +1,14 @@
11% Pandoc User's Guide
22% John MacFarlane
3−% January 8, 2008
3+% March 24, 2008
44
55Pandoc is a [Haskell] library for converting from one markup format to
66another, and a command-line tool that uses this library. It can read
77[markdown] and (subsets of) [reStructuredText], [HTML], and [LaTeX], and
88it can write [markdown], [reStructuredText], [HTML], [LaTeX], [ConTeXt],
9−[RTF], [DocBook XML], [GNU Texinfo], [groff man] pages, and [S5] HTML
10−slide shows. Pandoc's version of markdown contains some enhancements,
11−like footnotes and embedded LaTeX.
9+[RTF], [DocBook XML], [OpenDocument XML], [GNU Texinfo], [groff man]
10+pages, and [S5] HTML slide shows. Pandoc's version of markdown contains
11+some enhancements, like footnotes and embedded LaTeX.
1212
1313In contrast to existing tools for converting markdown to HTML, which
1414use regex substitutions, Pandoc has a modular design: it consists of a
@@ -25,6 +25,7 @@ or output format requires only adding a reader or writer.
2525[ConTeXt]: http://www.pragma-ade.nl/
2626[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
2727[DocBook XML]: http://www.docbook.org/
28+[OpenDocument XML]: http://opendocument.xml.org/
2829[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html
2930[Haskell]: http://www.haskell.org/
3031[GNU Texinfo]: http://www.gnu.org/software/texinfo/
@@ -37,41 +38,6 @@ scripts), Peter Wang (Texinfo writer), Andrea Rossato (OpenDocument writer).
3738
3839[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"
3940
40−Requirements
41−============
42−
43−The `pandoc` program itself does not depend on any external libraries
44−or programs.
45−
46−The wrapper script `html2markdown` requires
47−
48− - `pandoc` (which must be in the PATH)
49− - a POSIX-compliant shell (installed by default on all linux and unix
50− systems, including Mac OS X, and in [Cygwin] for Windows),
51− - `HTML Tidy`
52− - `iconv` (for character encoding conversion). (If `iconv` is absent,
53− `html2markdown` will still work, but it will treat everything as UTF-8.)
54−
55−The wrapper script `markdown2pdf` requires
56−
57− - `pandoc` (which must be in the PATH)
58− - a POSIX-compliant shell
59− - `pdflatex`, which should be part of any [LaTeX] distribution
60− - the following LaTeX packages (available from [CTAN], if they
61− are not already included in your LaTeX distribution):
62− + `unicode`
63− + `fancyhdr` (if you have verbatim text in footnotes)
64− + `graphicx` (if you use images)
65− + `array` (if you use tables)
66− + `ulem` (if you use strikeout text)
67−
68−The wrapper script `hsmarkdown` requires only a POSIX-compliant shell.
69−
70−[Cygwin]: http://www.cygwin.com/
71−[HTML Tidy]: http://tidy.sourceforge.net/
72−[`iconv`]: http://www.gnu.org/software/libiconv/
73−[CTAN]: http://www.ctan.org "Comprehensive TeX Archive Network"
74−
7541Using Pandoc
7642============
7743
@@ -151,10 +117,10 @@ then convert the output back to the local encoding.
151117Shell scripts
152118=============
153119
154−Three shell scripts, `markdown2pdf`, `html2markdown`, and `hsmarkdown`,
155−are included in the standard Pandoc installation. (They are not included
156−in the Windows binary package, as they require a POSIX shell, but they
157−may be used in Windows under Cygwin.)
120+Four shell scripts, `markdown2pdf`, `markdown2odt`, `html2markdown`, and
121+`hsmarkdown`, are included in the standard Pandoc installation. (They
122+are not included in the Windows binary package, as they require a POSIX
123+shell, but they may be used in Windows under Cygwin.)
158124
1591251. `markdown2pdf` produces a PDF file from markdown-formatted
160126 text, using `pandoc` and `pdflatex`. The default
@@ -173,7 +139,35 @@ may be used in Windows under Cygwin.)
173139 If no input file is specified, input will be taken from STDIN.
174140 All of `pandoc`'s options will work with `markdown2pdf` as well.
175141
176−2. `html2markdown` grabs a web page from a file or URL and converts
142+ `markdown2pdf` assumes that `pdflatex` is in the path. It also
143+ assumes that the following LaTeX packages are available:
144+ `unicode`, `fancyhdr` (if you have verbatim text in footnotes),
145+ `graphicx` (if you use images), `array` (if you use tables),
146+ and `ulem` (if you use strikeout text). If they are not already
147+ included in your LaTeX distribution, you can get them from
148+ [CTAN].
149+
150+2. `markdown2odt` produces an ODT file from markdown-formatted
151+ text, using `pandoc` and `pdflatex`. (ODT is "OpenDocument
152+ Text," the default format for the OpenOffice.org Writer.)
153+ The default behavior of `markdown2odt` is to create a file with the
154+ same base name as the first argument and the extension `odt`; thus,
155+ for example,
156+
157+ markdown2odt sample.txt endnotes.txt
158+
159+ will produce `sample.odt`. (If `sample.odt` exists already,
160+ it will be backed up before being overwritten.) An output file
161+ name can be specified explicitly using the `-o` option:
162+
163+ markdown2odt -o book.odt chap1 chap2
164+
165+ If no input file is specified, input will be taken from STDIN.
166+ All of `pandoc`'s options will work with `markdown2odt` as well.
167+
168+ `markdown2odt` requires `zip`, which must be in the path.
169+
170+3. `html2markdown` grabs a web page from a file or URL and converts
177171 it to markdown-formatted text, using `tidy` and `pandoc`.
178172
179173 All of `pandoc`'s options will work with `html2markdown` as well.
@@ -198,7 +192,11 @@ may be used in Windows under Cygwin.)
198192 available program (`wget`, `curl`, or a text-mode browser) to fetch
199193 the contents of a URL.
200194
201−3. `hsmarkdown` is designed to be used as a drop-in replacement for
195+ `html2markdown` requires [HTML Tidy], which must be in the path.
196+ It uses [`iconv`] for character encoding conversions; if `iconv`
197+ is absent, it will still work, but it will treat everything as UTF-8.
198+
199+4. `hsmarkdown` is designed to be used as a drop-in replacement for
202200 `Markdown.pl`. It forces `pandoc` to convert from markdown to
203201 HTML, and to use the `--strict` flag for maximal compliance with
204202 official markdown syntax. (All of Pandoc's syntax extensions and
@@ -214,6 +212,11 @@ may be used in Windows under Cygwin.)
214212 under Cygwin, due to problems with its simulation of symbolic
215213 links.
216214
215+[Cygwin]: http://www.cygwin.com/
216+[HTML Tidy]: http://tidy.sourceforge.net/
217+[`iconv`]: http://www.gnu.org/software/libiconv/
218+[CTAN]: http://www.ctan.org "Comprehensive TeX Archive Network"
219+
217220Command-line options
218221====================
219222