@@ -1,5 +1,5 @@
11.\"t
2−.TH PANDOC 1 "December 27, 2017" "pandoc 2.1"
2+.TH PANDOC 1 "January 7, 2018" "pandoc 2.1"
33.SH NAME
44pandoc - general markup converter
55.SH SYNOPSIS
@@ -9,38 +9,39 @@ pandoc - general markup converter
99.PP
1010Pandoc is a Haskell library for converting from one markup format to
1111another, and a command\-line tool that uses this library.
12−It can read Markdown, CommonMark, PHP Markdown Extra, GitHub\-Flavored
13−Markdown, MultiMarkdown, and (subsets of) Textile, reStructuredText,
14−HTML, LaTeX, MediaWiki markup, TWiki markup, TikiWiki markup, Creole
15−1.0, Haddock markup, OPML, Emacs Org mode, DocBook, JATS, Muse,
16−txt2tags, Vimwiki, EPUB, ODT, and Word docx; and it can write plain
17−text, Markdown, CommonMark, PHP Markdown Extra, GitHub\-Flavored
18−Markdown, MultiMarkdown, reStructuredText, XHTML, HTML5, LaTeX
19−(including \f[C]beamer\f[] slide shows), ConTeXt, RTF, OPML, DocBook,
20−JATS, OpenDocument, ODT, Word docx, GNU Texinfo, MediaWiki markup,
21−DokuWiki markup, ZimWiki markup, Haddock markup, EPUB (v2 or v3),
22−FictionBook2, Textile, groff man, groff ms, Emacs Org mode, AsciiDoc,
23−InDesign ICML, TEI Simple, Muse, PowerPoint slide shows and Slidy,
24−Slideous, DZSlides, reveal.js or S5 HTML slide shows.
12+.PP
13+Pandoc can read Markdown, CommonMark, PHP Markdown Extra,
14+GitHub\-Flavored Markdown, MultiMarkdown, and (subsets of) Textile,
15+reStructuredText, HTML, LaTeX, MediaWiki markup, TWiki markup, TikiWiki
16+markup, Creole 1.0, Haddock markup, OPML, Emacs Org mode, DocBook, JATS,
17+Muse, txt2tags, Vimwiki, EPUB, ODT, and Word docx.
18+.PP
19+Pandoc can write plain text, Markdown, CommonMark, PHP Markdown Extra,
20+GitHub\-Flavored Markdown, MultiMarkdown, reStructuredText, XHTML,
21+HTML5, LaTeX (including \f[C]beamer\f[] slide shows), ConTeXt, RTF,
22+OPML, DocBook, JATS, OpenDocument, ODT, Word docx, GNU Texinfo,
23+MediaWiki markup, DokuWiki markup, ZimWiki markup, Haddock markup, EPUB
24+(v2 or v3), FictionBook2, Textile, groff man, groff ms, Emacs Org mode,
25+AsciiDoc, InDesign ICML, TEI Simple, Muse, PowerPoint slide shows and
26+Slidy, Slideous, DZSlides, reveal.js or S5 HTML slide shows.
2527It can also produce PDF output on systems where LaTeX, ConTeXt,
2628\f[C]pdfroff\f[], \f[C]wkhtmltopdf\f[], \f[C]prince\f[], or
2729\f[C]weasyprint\f[] is installed.
2830.PP
29−Pandoc\[aq]s enhanced version of Markdown includes syntax for footnotes,
30−tables, flexible ordered lists, definition lists, fenced code blocks,
31−superscripts and subscripts, strikeout, metadata blocks, automatic
32−tables of contents, embedded LaTeX math, citations, and Markdown inside
33−HTML block elements.
34−(These enhancements, described further under Pandoc\[aq]s Markdown, can
35−be disabled using the \f[C]markdown_strict\f[] input or output format.)
36−.PP
37−In contrast to most existing tools for converting Markdown to HTML,
38−which use regex substitutions, pandoc has a modular design: it consists
39−of a set of readers, which parse text in a given format and produce a
40−native representation of the document, and a set of writers, which
41−convert this native representation into a target format.
31+Pandoc\[aq]s enhanced version of Markdown includes syntax for tables,
32+definition lists, metadata blocks, \f[C]Div\f[] blocks, footnotes and
33+citations, embedded LaTeX (including math), Markdown inside HTML block
34+elements, and much more.
35+These enhancements, described further under Pandoc\[aq]s Markdown, can
36+be disabled using the \f[C]markdown_strict\f[] format.
37+.PP
38+Pandoc has a modular design: it consists of a set of readers, which
39+parse text in a given format and produce a native representation of the
40+document (like an \f[I]abstract syntax tree\f[] or AST), and a set of
41+writers, which convert this native representation into a target format.
4242Thus, adding an input or output format requires only adding a reader or
4343writer.
44+Users can also run custom pandoc filters to modify the intermediate AST.
4445.PP
4546Because pandoc\[aq]s intermediate representation of a document is less
4647expressive than many of the formats it converts between, one should not
@@ -54,14 +55,9 @@ perfect, conversions from formats more expressive than pandoc\[aq]s
5455Markdown can be expected to be lossy.
5556.SS Using \f[C]pandoc\f[]
5657.PP
57−If no \f[I]input\-file\f[] is specified, input is read from
58+If no \f[I]input\-files\f[] are specified, input is read from
5859\f[I]stdin\f[].
59−Otherwise, the \f[I]input\-files\f[] are concatenated (with a blank line
60−between each) and used as input.
61−Output goes to \f[I]stdout\f[] by default (though output to the terminal
62−is disabled for the \f[C]odt\f[], \f[C]docx\f[], \f[C]epub2\f[], and
63−\f[C]epub3\f[] output formats, unless it is forced using
64−\f[C]\-o\ \-\f[]).
60+Output goes to \f[I]stdout\f[] by default.
6561For output to a file, use the \f[C]\-o\f[] option:
6662.IP
6763.nf
@@ -70,10 +66,10 @@ pandoc\ \-o\ output.html\ input.txt
7066\f[]
7167.fi
7268.PP
73−By default, pandoc produces a document fragment, not a standalone
74−document with a proper header and footer.
75−To produce a standalone document, use the \f[C]\-s\f[] or
76−\f[C]\-\-standalone\f[] flag:
69+By default, pandoc produces a document fragment.
70+To produce a standalone document (e.g.
71+a valid HTML file including \f[C]<head>\f[] and \f[C]<body>\f[]), use
72+the \f[C]\-s\f[] or \f[C]\-\-standalone\f[] flag:
7773.IP
7874.nf
7975\f[C]
@@ -82,37 +78,17 @@ pandoc\ \-s\ \-o\ output.html\ input.txt
8278.fi
8379.PP
8480For more information on how standalone documents are produced, see
85−Templates, below.
86−.PP
87−Instead of a file, an absolute URI may be given.
88−In this case pandoc will fetch the content using HTTP:
89−.IP
90−.nf
91−\f[C]
92−pandoc\ \-f\ html\ \-t\ markdown\ http://www.fsf.org
93−\f[]
94−.fi
95−.PP
96−It is possible to supply a custom User\-Agent string or other header
97−when requesting a document from a URL:
98−.IP
99−.nf
100−\f[C]
101−pandoc\ \-f\ html\ \-t\ markdown\ \-\-request\-header\ User\-Agent:"Mozilla/5.0"\ \\
102−\ \ http://www.fsf.org
103−\f[]
104−.fi
81+Templates below.
10582.PP
10683If multiple input files are given, \f[C]pandoc\f[] will concatenate them
10784all (with blank lines between them) before parsing.
108−This feature is disabled for binary input formats such as \f[C]EPUB\f[],
109−\f[C]odt\f[], and \f[C]docx\f[].
85+(Use \f[C]\-\-file\-scope\f[] to parse files individually.)
86+.SS Specifying formats
11087.PP
11188The format of the input and output can be specified explicitly using
11289command\-line options.
113−The input format can be specified using the \f[C]\-r/\-\-read\f[] or
114−\f[C]\-f/\-\-from\f[] options, the output format using the
115−\f[C]\-w/\-\-write\f[] or \f[C]\-t/\-\-to\f[] options.
90+The input format can be specified using the \f[C]\-f/\-\-from\f[]
91+option, the output format using the \f[C]\-t/\-\-to\f[] option.
11692Thus, to convert \f[C]hello.txt\f[] from Markdown to LaTeX, you could
11793type:
11894.IP
@@ -130,17 +106,15 @@ pandoc\ \-f\ html\ \-t\ markdown\ hello.html
130106\f[]
131107.fi
132108.PP
133−Supported output formats are listed below under the \f[C]\-t/\-\-to\f[]
134−option.
135−Supported input formats are listed below under the \f[C]\-f/\-\-from\f[]
136−option.
137−Note that the \f[C]rst\f[], \f[C]textile\f[], \f[C]latex\f[], and
138−\f[C]html\f[] readers are not complete; there are some constructs that
139−they do not parse.
109+Supported input and output formats are listed below under Options (see
110+\f[C]\-f\f[] for input formats and \f[C]\-t\f[] for output formats).
111+You can also use \f[C]pandoc\ \-\-list\-input\-formats\f[] and
112+\f[C]pandoc\ \-\-list\-output\-formats\f[] to print lists of supported
113+formats.
140114.PP
141115If the input or output format is not specified explicitly,
142116\f[C]pandoc\f[] will attempt to guess it from the extensions of the
143−input and output filenames.
117+filenames.
144118Thus, for example,
145119.IP
146120.nf
@@ -155,7 +129,8 @@ or if the output file\[aq]s extension is unknown, the output format will
155129default to HTML.
156130If no input file is specified (so that input comes from \f[I]stdin\f[]),
157131or if the input files\[aq] extensions are unknown, the input format will
158−be assumed to be Markdown unless explicitly specified.
132+be assumed to be Markdown.
133+.SS Character encoding
159134.PP
160135Pandoc uses the UTF\-8 character encoding for both input and output.
161136If your local character encoding is not UTF\-8, you should pipe input
@@ -174,8 +149,7 @@ the \f[C]\-s/\-\-standalone\f[] option.
174149.SS Creating a PDF
175150.PP
176151To produce a PDF, specify an output file with a \f[C]\&.pdf\f[]
177−extension.
178−By default, pandoc will use LaTeX to create the PDF:
152+extension:
179153.IP
180154.nf
181155\f[C]
@@ -183,10 +157,34 @@ pandoc\ test.txt\ \-o\ test.pdf
183157\f[]
184158.fi
185159.PP
186−Production of a PDF requires that a LaTeX engine be installed (see
187−\f[C]\-\-pdf\-engine\f[], below), and assumes that the following LaTeX
188−packages are available: \f[C]amsfonts\f[], \f[C]amsmath\f[],
189−\f[C]lm\f[], \f[C]unicode\-math\f[], \f[C]ifxetex\f[],
160+By default, pandoc will use LaTeX to create the PDF, which requires that
161+a LaTeX engine be installed (see \f[C]\-\-pdf\-engine\f[] below).
162+.PP
163+Alternatively, pandoc can use ConTeXt, \f[C]pdfroff\f[], or any of the
164+following HTML/CSS\-to\-PDF\-engines, to create a PDF:
165+\f[C]wkhtmltopdf\f[], \f[C]weasyprint\f[] or \f[C]prince\f[].
166+To do this, specify an output file with a \f[C]\&.pdf\f[] extension, as
167+before, but add the \f[C]\-\-pdf\-engine\f[] option or
168+\f[C]\-t\ context\f[], \f[C]\-t\ html\f[], or \f[C]\-t\ ms\f[] to the
169+command line (\f[C]\-t\ html\f[] defaults to
170+\f[C]\-\-pdf\-engine=wkhtmltopdf\f[]).
171+.PP
172+PDF output can be controlled using variables for LaTeX (if LaTeX is
173+used) and variables for ConTeXt (if ConTeXt is used).
174+When using an HTML/CSS\-to\-PDF\-engine, \f[C]\-\-css\f[] affects the
175+output.
176+If \f[C]wkhtmltopdf\f[] is used, then the variables
177+\f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[],
178+\f[C]margin\-bottom\f[], and \f[C]papersize\f[] will affect the output.
179+.PP
180+To debug the PDF creation, it can be useful to look at the intermediate
181+representation: instead of \f[C]\-o\ test.pdf\f[], use for example
182+\f[C]\-s\ \-o\ test.tex\f[] to output the generated LaTeX.
183+You can then test it with \f[C]pdflatex\ test.tex\f[].
184+.PP
185+When using LaTeX, the following packages need to be available (they are
186+included with all recent versions of TeX Live): \f[C]amsfonts\f[],
187+\f[C]amsmath\f[], \f[C]lm\f[], \f[C]unicode\-math\f[], \f[C]ifxetex\f[],
190188\f[C]ifluatex\f[], \f[C]listings\f[] (if the \f[C]\-\-listings\f[]
191189option is used), \f[C]fancyvrb\f[], \f[C]longtable\f[],
192190\f[C]booktabs\f[], \f[C]graphicx\f[] and \f[C]grffile\f[] (if the
@@ -205,24 +203,26 @@ available, and \f[C]csquotes\f[] will be used for typography if added to
205203the template or included in any header file.
206204The \f[C]natbib\f[], \f[C]biblatex\f[], \f[C]bibtex\f[], and
207205\f[C]biber\f[] packages can optionally be used for citation rendering.
208−These are included with all recent versions of TeX Live.
206+.SS Reading from the Web
209207.PP
210−Alternatively, pandoc can use ConTeXt, \f[C]pdfroff\f[], or any of the
211−following HTML/CSS\-to\-PDF\-engines, to create a PDF:
212−\f[C]wkhtmltopdf\f[], \f[C]weasyprint\f[] or \f[C]prince\f[].
213−To do this, specify an output file with a \f[C]\&.pdf\f[] extension, as
214−before, but add the \f[C]\-\-pdf\-engine\f[] option or
215−\f[C]\-t\ context\f[], \f[C]\-t\ html\f[], or \f[C]\-t\ ms\f[] to the
216−command line (\f[C]\-t\ html\f[] defaults to
217−\f[C]\-\-pdf\-engine=wkhtmltopdf\f[]).
208+Instead of an input file, an absolute URI may be given.
209+In this case pandoc will fetch the content using HTTP:
210+.IP
211+.nf
212+\f[C]
213+pandoc\ \-f\ html\ \-t\ markdown\ http://www.fsf.org
214+\f[]
215+.fi
218216.PP
219−PDF output can be controlled using variables for LaTeX (if LaTeX is
220−used) and variables for ConTeXt (if ConTeXt is used).
221−When using an HTML/CSS\-to\-PDF\-engine, \f[C]\-\-css\f[] affects the
222−output.
223−If \f[C]wkhtmltopdf\f[] is used, then the variables
224−\f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[],
225−\f[C]margin\-bottom\f[], and \f[C]papersize\f[] will affect the output.
217+It is possible to supply a custom User\-Agent string or other header
218+when requesting a document from a URL:
219+.IP
220+.nf
221+\f[C]
222+pandoc\ \-f\ html\ \-t\ markdown\ \-\-request\-header\ User\-Agent:"Mozilla/5.0"\ \\
223+\ \ http://www.fsf.org
224+\f[]
225+.fi
226226.SH OPTIONS
227227.SS General options
228228.TP
@@ -283,9 +283,8 @@ show) or the path of a custom lua writer (see Custom writers, below).
283283(\f[C]markdown_github\f[] provides deprecated and less accurate support
284284for Github\-Flavored Markdown; please use \f[C]gfm\f[] instead, unless
285285you use extensions that do not work with \f[C]gfm\f[].) Note that
286−\f[C]odt\f[], \f[C]epub\f[], and \f[C]epub3\f[] output will not be
287−directed to \f[I]stdout\f[]; an output filename must be specified using
288−the \f[C]\-o/\-\-output\f[] option.
286+\f[C]odt\f[], \f[C]docx\f[], and \f[C]epub\f[] output will not be
287+directed to \f[I]stdout\f[] unless forced with \f[C]\-o\ \-\f[].
289288Extensions can be individually enabled or disabled by appending
290289\f[C]+EXTENSION\f[] or \f[C]\-EXTENSION\f[] to the format name.
291290See Extensions below, for a list of extensions and their names.
@@ -386,8 +385,8 @@ List supported output formats, one per line.
386385.RE
387386.TP
388387.B \f[C]\-\-list\-extensions\f[][\f[C]=\f[]\f[I]FORMAT\f[]]
389−List supported Markdown extensions, one per line, preceded by a
390−\f[C]+\f[] or \f[C]\-\f[] indicating whether it is enabled by default in
388+List supported extensions, one per line, preceded by a \f[C]+\f[] or
389+\f[C]\-\f[] indicating whether it is enabled by default in
391390\f[I]FORMAT\f[].
392391If \f[I]FORMAT\f[] is not specified, defaults for pandoc\[aq]s Markdown
393392are given.
@@ -574,6 +573,10 @@ respectively.
574573The author and time of change is included.
575574\f[C]all\f[] is useful for scripting: only accepting changes from a
576575certain reviewer, say, or before a certain date.
576+If a paragraph is inserted or deleted, \f[C]track\-changes=all\f[]
577+produces a span with the class
578+\f[C]paragraph\-insertion\f[]/\f[C]paragraph\-deletion\f[] before the
579+affected paragraph break.
577580This option only affects the docx reader.
578581.RS
579582.RE
@@ -4071,55 +4074,6 @@ Use native pandoc \f[C]Span\f[] blocks for content inside
40714074For the most part this should give the same output as \f[C]raw_html\f[],
40724075but it makes it easier to write pandoc filters to manipulate groups of
40734076inlines.
4074−.SS Extension: \f[C]fenced_divs\f[]
4075−.PP
4076−Allow special fenced syntax for native \f[C]Div\f[] blocks.
4077−A Div starts with a fence containing at least three consecutive colons
4078−plus some attributes.
4079−The attributes may optionally be followed by another string of
4080−consecutive colons.
4081−The attribute syntax is exactly as in fenced code blocks (see Extension:
4082−\f[C]fenced_code_attributes\f[]).
4083−As with fenced code blocks, one can use either attributes in curly
4084−braces or a single unbraced word, which will be treated as a class name.
4085−The Div ends with another line containing a string of at least three
4086−consecutive colons.
4087−The fenced Div should be separated by blank lines from preceding and
4088−following blocks.
4089−.PP
4090−Example:
4091−.IP
4092−.nf
4093−\f[C]
4094−:::::\ {#special\ .sidebar}
4095−Here\ is\ a\ paragraph.
4096−
4097−And\ another.
4098−:::::
4099−\f[]
4100−.fi
4101−.PP
4102−Fenced divs can be nested.
4103−Opening fences are distinguished because they \f[I]must\f[] have
4104−attributes:
4105−.IP
4106−.nf
4107−\f[C]
4108−:::\ Warning\ ::::::
4109−This\ is\ a\ warning.
4110−
4111−:::\ Danger
4112−This\ is\ a\ warning\ within\ a\ warning.
4113−:::
4114−::::::::::::::::::
4115−\f[]
4116−.fi
4117−.PP
4118−Fences without attributes are always closing fences.
4119−Unlike with fenced code blocks, the number of colons in the closing
4120−fence need not match the number in the opening fence.
4121−However, it can be helpful for visual clarity to use fences of different
4122−lengths to distinguish nested divs from their parents.
41234077.SS Extension: \f[C]raw_tex\f[]
41244078.PP
41254079In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
@@ -4467,12 +4421,67 @@ identifier (LaTeX \f[C]\\caption\f[]), or both (HTML).
44674421When no \f[C]width\f[] or \f[C]height\f[] attributes are specified, the
44684422fallback is to look at the image resolution and the dpi metadata
44694423embedded in the image file.
4470−.SS Spans
4424+.SS Divs and Spans
4425+.PP
4426+Using the \f[C]native_divs\f[] and \f[C]native_spans\f[] extensions (see
4427+above), HTML syntax can be used as part of markdown to create native
4428+\f[C]Div\f[] and \f[C]Span\f[] elements in the pandoc AST (as opposed to
4429+raw HTML).
4430+However, there is also nicer syntax available:
4431+.SS Extension: \f[C]fenced_divs\f[]
4432+.PP
4433+Allow special fenced syntax for native \f[C]Div\f[] blocks.
4434+A Div starts with a fence containing at least three consecutive colons
4435+plus some attributes.
4436+The attributes may optionally be followed by another string of
4437+consecutive colons.
4438+The attribute syntax is exactly as in fenced code blocks (see Extension:
4439+\f[C]fenced_code_attributes\f[]).
4440+As with fenced code blocks, one can use either attributes in curly
4441+braces or a single unbraced word, which will be treated as a class name.
4442+The Div ends with another line containing a string of at least three
4443+consecutive colons.
4444+The fenced Div should be separated by blank lines from preceding and
4445+following blocks.
4446+.PP
4447+Example:
4448+.IP
4449+.nf
4450+\f[C]
4451+:::::\ {#special\ .sidebar}
4452+Here\ is\ a\ paragraph.
4453+
4454+And\ another.
4455+:::::
4456+\f[]
4457+.fi
4458+.PP
4459+Fenced divs can be nested.
4460+Opening fences are distinguished because they \f[I]must\f[] have
4461+attributes:
4462+.IP
4463+.nf
4464+\f[C]
4465+:::\ Warning\ ::::::
4466+This\ is\ a\ warning.
4467+
4468+:::\ Danger
4469+This\ is\ a\ warning\ within\ a\ warning.
4470+:::
4471+::::::::::::::::::
4472+\f[]
4473+.fi
4474+.PP
4475+Fences without attributes are always closing fences.
4476+Unlike with fenced code blocks, the number of colons in the closing
4477+fence need not match the number in the opening fence.
4478+However, it can be helpful for visual clarity to use fences of different
4479+lengths to distinguish nested divs from their parents.
44714480.SS Extension: \f[C]bracketed_spans\f[]
44724481.PP
44734482A bracketed sequence of inlines, as one would use to begin a link, will
4474−be treated as a span with attributes if it is followed immediately by
4475−attributes:
4483+be treated as a \f[C]Span\f[] with attributes if it is followed
4484+immediately by attributes:
44764485.IP
44774486.nf
44784487\f[C]