@@ -1,477 +0,0 @@
1−% PANDOC(1) Pandoc User Manuals
2−% John MacFarlane
3−% January 8, 2008
4−
5−# NAME
6−
7−pandoc - general markup converter
8−
9−# SYNOPSIS
10−
11−pandoc [*options*] [*input-file*]...
12−
13−# DESCRIPTION
14−
15−Pandoc converts files from one markup format to another. It can
16−read markdown and (subsets of) Textile, reStructuredText, HTML, and LaTeX,
17−and it can write plain text, markdown, reStructuredText, HTML, LaTeX,
18−ConTeXt, Texinfo, groff man, MediaWiki markup, Textile, RTF,
19−OpenDocument XML, ODT, DocBook XML, EPUB, Emacs Org-Mode, and
20−Slidy or S5 HTML slide shows.
21−
22−If no *input-file* is specified, input is read from *stdin*.
23−Otherwise, the *input-files* are concatenated (with a blank
24−line between each) and used as input. Output goes to *stdout* by
25−default (though output to *stdout* is disabled for the `odt` and
26−`epub` output formats). For output to a file, use the `-o` option:
27−
28− pandoc -o output.html input.txt
29−
30−Instead of a file, an absolute URI may be given. In this case
31−pandoc will fetch the content using HTTP:
32−
33− pandoc -f html -t markdown http://www.fsf.org
34−
35−The input and output formats may be specified using command-line options
36−(see **OPTIONS**, below, for details). If these formats are not
37−specified explicitly, Pandoc will attempt to determine them
38−from the extensions of the input and output filenames. If input comes
39−from *stdin* or from a file with an unknown extension, the input is assumed
40−to be markdown. If no output filename is specified using the `-o`
41−option, or if a filename is specified but its extension is unknown,
42−the output will default to HTML. Thus, for example,
43−
44− pandoc -o chap1.tex chap1.txt
45−
46−converts *chap1.txt* from markdown to LaTeX. And
47−
48− pandoc README
49−
50−converts *README* from markdown to HTML.
51−
52−Pandoc's version of markdown is an extended variant of standard
53−markdown: the differences are described in the *README* file in
54−the user documentation. If standard markdown syntax is desired, the
55−`--strict` option may be used.
56−
57−Pandoc uses the UTF-8 character encoding for both input and output.
58−If your local character encoding is not UTF-8, you
59−should pipe input and output through `iconv`:
60−
61− iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
62−
63−# OPTIONS
64−
65−`-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
66−: Specify input format. *FORMAT* can be
67− `native` (native Haskell), `markdown` (markdown or plain text),
68− `textile` (Textile), `rst` (reStructuredText), `html` (HTML),
69− or `latex` (LaTeX). If `+lhs` is appended to `markdown`, `rst`,
70− or `latex`, the input will be treated as literate Haskell source:
71− see [Literate Haskell support](#literate-haskell-support),
72− below.
73−
74−`-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT*
75−: Specify output format. *FORMAT* can be `native` (native Haskell),
76− `plain` (plain text), `markdown` (markdown), `rst` (reStructuredText),
77− `html` (HTML), `latex` (LaTeX), `context` (ConTeXt), `man` (groff man),
78− `mediawiki` (MediaWiki markup), `textile` (Textile), `org` (Emacs
79− Org-Mode), `texinfo` (GNU Texinfo), `docbook` (DocBook XML),
80− `opendocument` (OpenDocument XML), `odt` (OpenOffice text document),
81− `epub` (EPUB book), `slidy` (Slidy HTML and javascript slide show),
82− `s5` (S5 HTML and javascript slide show), or `rtf` (rich text
83− format). Note that `odt` and `epub` output will not be directed to
84− *stdout*; an output filename must be specified using the `-o/--output`
85− option. If `+lhs` is appended to `markdown`, `rst`, `latex`, or `html`,
86− the output will be rendered as literate Haskell source:
87− see [Literate Haskell support](#literate-haskell-support),
88− below.
89−
90−`-s`, `--standalone`
91−: Produce output with an appropriate header and footer (e.g. a
92− standalone HTML, LaTeX, or RTF file, not a fragment).
93−
94−`-o` *FILE*, `--output=`*FILE*
95−: Write output to *FILE* instead of *stdout*. If *FILE* is
96− `-`, output will go to *stdout*. (Exception: if the output
97− format is `odt` or `epub`, output to stdout is disabled.)
98−
99−`-p`, `--preserve-tabs`
100−: Preserve tabs instead of converting them to spaces (the default).
101−
102−`--tab-stop=`*TABSTOP*
103−: Specify the number of spaces per tab (default is 4).
104−
105−`--strict`
106−: Use strict markdown syntax, with no pandoc extensions or variants.
107− When the input format is HTML, this means that constructs that have no
108− equivalents in standard markdown (e.g. definition lists or strikeout
109− text) will be parsed as raw HTML.
110−
111−`--reference-links`
112−: Use reference-style links, rather than inline links, in writing markdown
113− or reStructuredText. By default inline links are used.
114−
115−`-R`, `--parse-raw`
116−: Parse untranslatable HTML codes and LaTeX environments as raw HTML
117− or LaTeX, instead of ignoring them. Affects only HTML and LaTeX
118− input. Raw HTML can be printed in markdown, reStructuredText, HTML, Slidy,
119− and S5 output; raw LaTeX can be printed in markdown, reStructuredText,
120− LaTeX, and ConTeXt output. The default is for the readers to omit
121− untranslatable HTML codes and LaTeX environments. (The LaTeX reader
122− does pass through untranslatable LaTeX *commands*, even if `-R` is not
123− specified.)
124−
125−`-S`, `--smart`
126−: Produce typographically correct output, converting straight quotes
127− to curly quotes, `---` and `--` to dashes, ande `...` to ellipses.
128− Nonbreaking spaces are inserted after certain abbreviations, such
129− as "Mr." (Note: This option is significant only when the input format is
130− `markdown` or `textile`. It is selected automatically when the input
131− format is `textile` or the output format is `latex` or `context`.)
132−
133−`-m` *URL*, `--latexmathml=`*URL*
134−: Use the [LaTeXMathML] script to display embedded TeX math in HTML output.
135− To insert a link to a local copy of the `LaTeXMathML.js` script,
136− provide a *URL*. If no *URL* is provided, the contents of the
137− script will be inserted directly into the HTML header, preserving
138− portability at the price of efficiency. If you plan to use math on
139− several pages, it is much better to link to a copy of the script,
140− so it can be cached.
141−
142−`--mathml`
143−: Convert TeX math to MathML. In standalone mode, a small javascript
144− will be inserted that allows the MathML to be viewed on some browsers.
145−
146−`--jsmath=`*URL*
147−: Use [jsMath] to display embedded TeX math in HTML output.
148− The *URL* should point to the jsMath load script (e.g.
149− `jsMath/easy/load.js`); if provided, it will be linked to in
150− the header of standalone HTML documents.
151−
152−`--mathjax=`*URL*
153−: Use [MathJax] to display embedded TeX math in HTML output.
154− The *URL* should point to the `MathJax.js` load script.
155−
156−`--gladtex`
157−: Enclose TeX math in `<eq>` tags in HTML output. These can then
158− be processed by [gladTeX] to produce links to images of the typeset
159− formulas.
160−
161−`--mimetex=`*URL*
162−: Render TeX math using the [mimeTeX] CGI script. If *URL* is not
163− specified, it is assumed that the script is at `/cgi-bin/mimetex.cgi`.
164−
165−`--webtex=`*URL*
166−: Render TeX formulas using an external script that converts TeX
167− formulas to images. The formula will be concatenated with the URL
168− provided. If *URL* is not specified, the Google Chart API will be used.
169−
170−`-i`, `--incremental`
171−: Make list items in Slidy or S5 display incrementally (one by one).
172− The default is for lists to be displayed all at once.
173−
174−`--offline`
175−: Include all the CSS and javascript needed for a Slidy or S5 slide
176− show in the output, so that the slide show will work even when no
177− internet connection is available.
178−
179−`--xetex`
180−: Create LaTeX outut suitable for processing by XeTeX.
181−
182−`-N`, `--number-sections`
183−: Number section headings in LaTeX, ConTeXt, or HTML output.
184− By default, sections are not numbered.
185−
186−`--section-divs`
187−: Wrap sections in `<div>` tags, and attach identifiers to the
188− enclosing `<div>` rather than the header itself.
189− See [Section identifiers](#header-identifiers-in-html), below.
190−
191−`--no-wrap`
192−: Disable text wrapping in output. By default, text is wrapped
193− appropriately for the output format.
194−
195−`--sanitize-html`
196−: Sanitizes HTML (in markdown or HTML input) using a whitelist.
197− Unsafe tags are replaced by HTML comments; unsafe attributes
198− are omitted. URIs in links and images are also checked against a
199− whitelist of URI schemes.
200−
201−`--email-obfuscation=`*none|javascript|references*
202−: Specify a method for obfuscating `mailto:` links in HTML documents.
203− *none* leaves `mailto:` links as they are. *javascript* obfuscates
204− them using javascript. *references* obfuscates them by printing their
205− letters as decimal or hexadecimal character references.
206− If `--strict` is specified, *references* is used regardless of the
207− presence of this option.
208−
209−`--id-prefix`=*STRING*
210−: Specify a prefix to be added to all automatically generated identifiers
211− in HTML output. This is useful for preventing duplicate identifiers
212− when generating fragments to be included in other pages.
213−
214−`--indented-code-classes=`*CLASSES*
215−: Specify classes to use for indented code blocks--for example,
216− `perl,numberLines` or `haskell`. Multiple classes may be separated
217− by spaces or commas.
218−
219−`--toc`, `--table-of-contents`
220−: Include an automatically generated table of contents (or, in
221− the case of `latex`, `context`, and `rst`, an instruction to create
222− one) in the output document. This option has no effect on `man`,
223− `docbook`, `slidy`, or `s5` output.
224−
225−`--base-header-level=`*LEVEL*
226−: Specify the base level for headers (defaults to 1).
227−
228−`--template=`*FILE*
229−: Use *FILE* as a custom template for the generated document. Implies
230− `--standalone`. See [Templates](#templates) below for a description
231− of template syntax. If this option is not used, a default
232− template appropriate for the output format will be used. See also
233− `-D/--print-default-template`.
234−
235−`-V` *KEY=VAL*, `--variable=`*KEY:VAL*
236−: Set the template variable *KEY* to the value *VAL* when rendering the
237− document in standalone mode. This is only useful when the
238− `--template` option is used to specify a custom template, since
239− pandoc automatically sets the variables used in the default
240− templates.
241−
242−`-c` *URL*, `--css=`*URL*
243−: Link to a CSS style sheet.
244−
245−`-H` *FILE*, `--include-in-header=`*FILE*
246−: Include contents of *FILE*, verbatim, at the end of the header.
247− This can be used, for example, to include special
248− CSS or javascript in HTML documents. This option can be used
249− repeatedly to include multiple files in the header. They will be
250− included in the order specified. Implies `--standalone`.
251−
252−`-B` *FILE*, `--include-before-body=`*FILE*
253−: Include contents of *FILE*, verbatim, at the beginning of the
254− document body (e.g. after the `<body>` tag in HTML, or the
255− `\begin{document}` command in LaTeX). This can be used to include
256− navigation bars or banners in HTML documents. This option can be
257− used repeatedly to include multiple files. They will be included in
258− the order specified. Implies `--standalone`.
259−
260−`-A` *FILE*, `--include-after-body=`*FILE*
261−: Include contents of *FILE*, verbatim, at the end of the document
262− body (before the `</body>` tag in HTML, or the
263− `\end{document}` command in LaTeX). This option can be be used
264− repeatedly to include multiple files. They will be included in the
265− order specified. Implies `--standalone`.
266−
267−`-C` *FILE*, `--custom-header=`*FILE*
268−: Use contents of *FILE* as the document header. Implies `--standalone`.
269− *Note: This option is deprecated. Users should transition to using
270− `--template` instead.*
271−
272−`--reference-odt=`*FILE*
273−: Use the specified file as a style reference in producing an ODT.
274− For best results, the reference ODT should be a modified version
275− of an ODT produced using pandoc. The contents of the reference ODT
276− are ignored, but its stylesheets are used in the new ODT. If no
277− reference ODT is specified on the command line, pandoc will look
278− for a file `reference.odt` in the user data directory (see
279− `--data-dir`). If this is not found either, sensible defaults will be
280− used.
281−
282−`--epub-stylesheet=`*FILE*
283−: Use the specified CSS file to style the EPUB. If no stylesheet
284− is specified, pandoc will look for a file `epub.css` in the
285− user data directory (see `--data-dir`, below). If it is not
286− found there, sensible defaults will be used.
287−
288−`--epub-metadata=`*FILE*
289−: Look in the specified XML file for metadata for the EPUB.
290− The file should contain a series of Dublin Core elements,
291− as documented at <http://dublincore.org/documents/dces/>.
292− For example:
293−
294− <dc:rights>Creative Commons</dc:rights>
295− <dc:language>es-AR</dc:language>
296−
297− By default, pandoc will include the following metadata elements:
298− `<dc:title>` (from the document title), `<dc:creator>` (from the
299− document authors), `<dc:language>` (from the locale), and
300− `<dc:identifier id="BookId">` (a randomly generated UUID). Any of
301− these may be overridden by elements in the metadata file.
302−
303−`-D` *FORMAT*, `--print-default-template=`*FORMAT*
304−: Print the default template for an output *FORMAT*. (See `-t`
305− for a list of possible *FORMAT*s.)
306−
307−`-T` *STRING*, `--title-prefix=*STRING*
308−: Specify *STRING* as a prefix at the beginning of the title
309− that appears in the HTML header (but not in the title as it
310− appears at the beginning of the HTML body). Implies
311− `--standalone`.
312−
313−`--bibliography=`*FILE*
314−: Specify bibliography database to be used in resolving
315− citations. The database type will be determined from the
316− extension of *FILE*, which may be `.mods` (MODS format),
317− `.bib` (BibTeX format), `.bbx` (BibLaTeX format),
318− `.ris` (RIS format), `.enl` (EndNote format),
319− `.xml` (EndNote XML format), `.wos` (ISI format),
320− `.medline` (MEDLINE format), `.copac` (Copac format),
321− or `.json` (citeproc JSON). If you want to use multiple
322− bibliographies, just use this option repeatedly.
323−
324−`--csl=`*FILE*
325−: Specify [CSL] style to be used in formatting citations and
326− the bibliography. If *FILE* is not found, pandoc will look
327− for it in
328−
329− $HOME/.csl
330−
331− in unix and
332−
333− C:\Documents And Settings\USERNAME\Application Data\csl
334−
335− in Windows. If the `--csl` option is not specified, pandoc
336− will use a default style: either `default.csl` in the
337− user data directory (see `--data-dir`), or, if that is
338− not present, the Chicago author-date style.
339−
340−`--data-dir=`*DIRECTORY*
341−: Specify the user data directory to search for pandoc data files.
342− If this option is not specified, the default user data directory
343− will be used:
344−
345− $HOME/.pandoc
346−
347− in unix and
348−
349− C:\Documents And Settings\USERNAME\Application Data\pandoc
350−
351− in Windows. A `reference.odt`, `epub.css`, `templates` directory,
352− or `s5` directory placed in this directory will override pandoc's
353− normal defaults.
354−
355−`--dump-args`
356−: Print information about command-line arguments to *stdout*, then exit.
357− This option is intended primarily for use in wrapper scripts.
358− The first line of output contains the name of the output file specified
359− with the `-o` option, or `-` (for *stdout*) if no output file was
360− specified. The remaining lines contain the command-line arguments,
361− one per line, in the order they appear. These do not include regular
362− Pandoc options and their arguments, but do include any options appearing
363− after a `--` separator at the end of the line.
364−
365−`--ignore-args`
366−: Ignore command-line arguments (for use in wrapper scripts).
367− Regular Pandoc options are not ignored. Thus, for example,
368−
369− pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
370−
371− is equivalent to
372−
373− pandoc -o foo.html -s
374−
375−`-v`, `--version`
376−: Print version.
377−
378−`-h`, `--help`
379−: Show usage message.
380−
381−[LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/
382−[jsMath]: http://www.math.union.edu/~dpvc/jsmath/
383−[MathJax]: http://www.mathjax.org/
384−[gladTeX]: http://www.math.uio.no/~martingu/gladtex/index.html
385−[mimeTeX]: http://www.forkosh.com/mimetex.html
386−[CSL]: http://CitationStyles.org
387−
388−# TEMPLATES
389−
390−When the `-s/--standalone` option is used, pandoc uses a template to
391−add header and footer material that is needed for a self-standing
392−document. To see the default template that is used, just type
393−
394− pandoc --print-default-template=FORMAT
395−
396−where `FORMAT` is the name of the output format. A custom template
397−can be specified using the `--template` option. You can also override
398−the system default templates for a given output format `FORMAT`
399−by putting a file `templates/FORMAT.template` in the user data
400−directory (see `--data-dir`, below).
401−
402−Templates may contain *variables*. Variable names are sequences of
403−alphanumerics, `-`, and `_`, starting with a letter. A variable name
404−surrounded by `$` signs will be replaced by its value. For example,
405−the string `$title$` in
406−
407− <title>$title$</title>
408−
409−will be replaced by the document title.
410−
411−To write a literal `$` in a template, use `$$`.
412−
413−Some variables are set automatically by pandoc. These vary somewhat
414−depending on the output format, but include:
415−
416−`legacy-header`
417−: contents specified by `-C/--custom-header`
418−`header-includes`
419−: contents specified by `-H/--include-in-header` (may have multiple
420− values)
421−`toc`
422−: non-null value if `--toc/--table-of-contents` was specified
423−`include-before`
424−: contents specified by `-B/--include-before-body` (may have
425− multiple values)
426−`include-after`
427−: contents specified by `-A/--include-after-body` (may have
428− multiple values)
429−`body`
430−: body of document
431−`title`
432−: title of document, as specified in title block
433−`author`
434−: author of document, as specified in title block (may have
435− multiple values)
436−`date`
437−: date of document, as specified in title block
438−
439−Variables may be set at the command line using the `-V/--variable`
440−option. This allows users to include custom variables in their
441−templates.
442−
443−Templates may contain conditionals. The syntax is as follows:
444−
445− $if(variable)$
446− X
447− $else$
448− Y
449− $endif$
450−
451−This will include `X` in the template if `variable` has a non-null
452−value; otherwise it will include `Y`. `X` and `Y` are placeholders for
453−any valid template text, and may include interpolated variables or other
454−conditionals. The `$else$` section may be omitted.
455−
456−When variables can have multiple values (for example, `author` in
457−a multi-author document), you can use the `$for$` keyword:
458−
459− $for(author)$
460− <meta name="author" content="$author$" />
461− $endfor$
462−
463−You can optionally specify a separator to be used between
464−consecutive items:
465−
466− $for(author)$$author$$sep$, $endfor$
467−
468−# SEE ALSO
469−
470−`markdown2pdf` (1).
471−The *README* file distributed with Pandoc contains full documentation.
472−
473−The Pandoc source code and all documentation may be downloaded from
474−<http://johnmacfarlane.net/pandoc/>.
475−
476−[CSL]: CitationStyles.org
477−