@@ -1,20 +1,20 @@
11.\"t
2−.TH PANDOC 1 "November 25, 2018" "pandoc 2.5"
2+.TH PANDOC 1 "January 30, 2019" "pandoc 2.6"
33.SH NAME
44pandoc - general markup converter
55.SH SYNOPSIS
66.PP
7−\f[C]pandoc\f[R] [\f[I]options\f[R]] [\f[I]input\-file\f[R]]...
7+\f[C]pandoc\f[R] [\f[I]options\f[R]] [\f[I]input-file\f[R]]...
88.SH DESCRIPTION
99.PP
1010Pandoc is a Haskell library for converting from one markup format to
11−another, and a command\-line tool that uses this library.
11+another, and a command-line tool that uses this library.
1212.PP
1313Pandoc can convert between numerous markup and word processing formats,
1414including, but not limited to, various flavors of Markdown, HTML, LaTeX
1515and Word docx.
16−For the full lists of input and output formats, see the
17−\f[C]\-\-from\f[R] and \f[C]\-\-to\f[R] options below.
16+For the full lists of input and output formats, see the \f[C]--from\f[R]
17+and \f[C]--to\f[R] options below.
1818Pandoc can also produce PDF output: see creating a PDF, below.
1919.PP
2020Pandoc\[aq]s enhanced version of Markdown includes syntax for tables,
@@ -42,25 +42,25 @@ perfect, conversions from formats more expressive than pandoc\[aq]s
4242Markdown can be expected to be lossy.
4343.SS Using pandoc
4444.PP
45−If no \f[I]input\-files\f[R] are specified, input is read from
45+If no \f[I]input-files\f[R] are specified, input is read from
4646\f[I]stdin\f[R].
4747Output goes to \f[I]stdout\f[R] by default.
48−For output to a file, use the \f[C]\-o\f[R] option:
48+For output to a file, use the \f[C]-o\f[R] option:
4949.IP
5050.nf
5151\f[C]
52−pandoc \-o output.html input.txt
52+pandoc -o output.html input.txt
5353\f[R]
5454.fi
5555.PP
5656By default, pandoc produces a document fragment.
5757To produce a standalone document (e.g.
5858a valid HTML file including \f[C]<head>\f[R] and \f[C]<body>\f[R]), use
59−the \f[C]\-s\f[R] or \f[C]\-\-standalone\f[R] flag:
59+the \f[C]-s\f[R] or \f[C]--standalone\f[R] flag:
6060.IP
6161.nf
6262\f[C]
63−pandoc \-s \-o output.html input.txt
63+pandoc -s -o output.html input.txt
6464\f[R]
6565.fi
6666.PP
@@ -69,19 +69,19 @@ Templates below.
6969.PP
7070If multiple input files are given, \f[C]pandoc\f[R] will concatenate
7171them all (with blank lines between them) before parsing.
72−(Use \f[C]\-\-file\-scope\f[R] to parse files individually.)
72+(Use \f[C]--file-scope\f[R] to parse files individually.)
7373.SS Specifying formats
7474.PP
7575The format of the input and output can be specified explicitly using
76−command\-line options.
77−The input format can be specified using the \f[C]\-f/\-\-from\f[R]
78−option, the output format using the \f[C]\-t/\-\-to\f[R] option.
76+command-line options.
77+The input format can be specified using the \f[C]-f/--from\f[R] option,
78+the output format using the \f[C]-t/--to\f[R] option.
7979Thus, to convert \f[C]hello.txt\f[R] from Markdown to LaTeX, you could
8080type:
8181.IP
8282.nf
8383\f[C]
84−pandoc \-f markdown \-t latex hello.txt
84+pandoc -f markdown -t latex hello.txt
8585\f[R]
8686.fi
8787.PP
@@ -89,14 +89,14 @@ To convert \f[C]hello.html\f[R] from HTML to Markdown:
8989.IP
9090.nf
9191\f[C]
92−pandoc \-f html \-t markdown hello.html
92+pandoc -f html -t markdown hello.html
9393\f[R]
9494.fi
9595.PP
9696Supported input and output formats are listed below under Options (see
97−\f[C]\-f\f[R] for input formats and \f[C]\-t\f[R] for output formats).
98−You can also use \f[C]pandoc \-\-list\-input\-formats\f[R] and
99−\f[C]pandoc \-\-list\-output\-formats\f[R] to print lists of supported
97+\f[C]-f\f[R] for input formats and \f[C]-t\f[R] for output formats).
98+You can also use \f[C]pandoc --list-input-formats\f[R] and
99+\f[C]pandoc --list-output-formats\f[R] to print lists of supported
100100formats.
101101.PP
102102If the input or output format is not specified explicitly,
@@ -106,7 +106,7 @@ Thus, for example,
106106.IP
107107.nf
108108\f[C]
109−pandoc \-o hello.tex hello.txt
109+pandoc -o hello.tex hello.txt
110110\f[R]
111111.fi
112112.PP
@@ -119,20 +119,20 @@ If no input file is specified (so that input comes from
119119input format will be assumed to be Markdown.
120120.SS Character encoding
121121.PP
122−Pandoc uses the UTF\-8 character encoding for both input and output.
123−If your local character encoding is not UTF\-8, you should pipe input
124−and output through \f[C]iconv\f[R]:
122+Pandoc uses the UTF-8 character encoding for both input and output.
123+If your local character encoding is not UTF-8, you should pipe input and
124+output through \f[C]iconv\f[R]:
125125.IP
126126.nf
127127\f[C]
128−iconv \-t utf\-8 input.txt | pandoc | iconv \-f utf\-8
128+iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
129129\f[R]
130130.fi
131131.PP
132132Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF,
133133OPML, DocBook, and Texinfo), information about the character encoding is
134134included in the document header, which will only be included if you use
135−the \f[C]\-s/\-\-standalone\f[R] option.
135+the \f[C]-s/--standalone\f[R] option.
136136.SS Creating a PDF
137137.PP
138138To produce a PDF, specify an output file with a \f[C].pdf\f[R]
@@ -140,60 +140,62 @@ extension:
140140.IP
141141.nf
142142\f[C]
143−pandoc test.txt \-o test.pdf
143+pandoc test.txt -o test.pdf
144144\f[R]
145145.fi
146146.PP
147147By default, pandoc will use LaTeX to create the PDF, which requires that
148−a LaTeX engine be installed (see \f[C]\-\-pdf\-engine\f[R] below).
148+a LaTeX engine be installed (see \f[C]--pdf-engine\f[R] below).
149149.PP
150150Alternatively, pandoc can use ConTeXt, \f[C]pdfroff\f[R], or any of the
151−following HTML/CSS\-to\-PDF\-engines, to create a PDF:
151+following HTML/CSS-to-PDF-engines, to create a PDF:
152152\f[C]wkhtmltopdf\f[R], \f[C]weasyprint\f[R] or \f[C]prince\f[R].
153153To do this, specify an output file with a \f[C].pdf\f[R] extension, as
154−before, but add the \f[C]\-\-pdf\-engine\f[R] option or
155−\f[C]\-t context\f[R], \f[C]\-t html\f[R], or \f[C]\-t ms\f[R] to the
156−command line (\f[C]\-t html\f[R] defaults to
157−\f[C]\-\-pdf\-engine=wkhtmltopdf\f[R]).
158−.PP
159−PDF output can be controlled using variables for LaTeX (if LaTeX is
160−used) and variables for ConTeXt (if ConTeXt is used).
161−When using an HTML/CSS\-to\-PDF\-engine, \f[C]\-\-css\f[R] affects the
162−output.
163−If \f[C]wkhtmltopdf\f[R] is used, then the variables
164−\f[C]margin\-left\f[R], \f[C]margin\-right\f[R], \f[C]margin\-top\f[R],
165−\f[C]margin\-bottom\f[R], \f[C]footer\-html\f[R], \f[C]header\-html\f[R]
166−and \f[C]papersize\f[R] will affect the output.
154+before, but add the \f[C]--pdf-engine\f[R] option or
155+\f[C]-t context\f[R], \f[C]-t html\f[R], or \f[C]-t ms\f[R] to the
156+command line (\f[C]-t html\f[R] defaults to
157+\f[C]--pdf-engine=wkhtmltopdf\f[R]).
158+.PP
159+PDF output uses variables for LaTeX (with a LaTeX engine); variables for
160+ConTeXt (with ConTeXt); or variables for \f[C]wkhtmltopdf\f[R] (an
161+HTML/CSS-to-PDF engine; \f[C]--css\f[R] also affects the output).
167162.PP
168163To debug the PDF creation, it can be useful to look at the intermediate
169−representation: instead of \f[C]\-o test.pdf\f[R], use for example
170−\f[C]\-s \-o test.tex\f[R] to output the generated LaTeX.
164+representation: instead of \f[C]-o test.pdf\f[R], use for example
165+\f[C]-s -o test.tex\f[R] to output the generated LaTeX.
171166You can then test it with \f[C]pdflatex test.tex\f[R].
172167.PP
173168When using LaTeX, the following packages need to be available (they are
174169included with all recent versions of TeX Live): \f[C]amsfonts\f[R],
175−\f[C]amsmath\f[R], \f[C]lm\f[R], \f[C]unicode\-math\f[R],
170+\f[C]amsmath\f[R], \f[C]lm\f[R], \f[C]unicode-math\f[R],
176171\f[C]ifxetex\f[R], \f[C]ifluatex\f[R], \f[C]listings\f[R] (if the
177−\f[C]\-\-listings\f[R] option is used), \f[C]fancyvrb\f[R],
172+\f[C]--listings\f[R] option is used), \f[C]fancyvrb\f[R],
178173\f[C]longtable\f[R], \f[C]booktabs\f[R], \f[C]graphicx\f[R] and
179174\f[C]grffile\f[R] (if the document contains images), \f[C]hyperref\f[R],
180−\f[C]xcolor\f[R] (with \f[C]colorlinks\f[R]), \f[C]ulem\f[R],
181−\f[C]geometry\f[R] (with the \f[C]geometry\f[R] variable set),
182−\f[C]setspace\f[R] (with \f[C]linestretch\f[R]), and \f[C]babel\f[R]
183−(with \f[C]lang\f[R]).
184−The use of \f[C]xelatex\f[R] or \f[C]lualatex\f[R] as the LaTeX engine
175+\f[C]xcolor\f[R], \f[C]ulem\f[R], \f[C]geometry\f[R] (with the
176+\f[C]geometry\f[R] variable set), \f[C]setspace\f[R] (with
177+\f[C]linestretch\f[R]), and \f[C]babel\f[R] (with \f[C]lang\f[R]).
178+The use of \f[C]xelatex\f[R] or \f[C]lualatex\f[R] as the PDF engine
185179requires \f[C]fontspec\f[R].
186180\f[C]xelatex\f[R] uses \f[C]polyglossia\f[R] (with \f[C]lang\f[R]),
187181\f[C]xecjk\f[R], and \f[C]bidi\f[R] (with the \f[C]dir\f[R] variable
188182set).
189183If the \f[C]mathspec\f[R] variable is set, \f[C]xelatex\f[R] will use
190−\f[C]mathspec\f[R] instead of \f[C]unicode\-math\f[R].
184+\f[C]mathspec\f[R] instead of \f[C]unicode-math\f[R].
191185The \f[C]upquote\f[R] and \f[C]microtype\f[R] packages are used if
192186available, and \f[C]csquotes\f[R] will be used for typography if
193187\f[C]\[rs]usepackage{csquotes}\f[R] is present in the template or
194−included via \f[C]/H/\-\-include\-in\-header\f[R].
188+included via \f[C]/H/--include-in-header\f[R].
195189The \f[C]natbib\f[R], \f[C]biblatex\f[R], \f[C]bibtex\f[R], and
196190\f[C]biber\f[R] packages can optionally be used for citation rendering.
191+The following packages will be used to improve output quality if
192+present, but pandoc does not require them to be present:
193+\f[C]upquote\f[R] (for straight quotes in verbatim environments),
194+\f[C]microtype\f[R] (for better spacing adjustments), \f[C]parskip\f[R]
195+(for better inter-paragraph spaces), \f[C]xurl\f[R] (for better line
196+breaks in URLs), \f[C]bookmark\f[R] (for better PDF bookmarks), and
197+\f[C]footnotehyper\f[R] or \f[C]footnote\f[R] (to allow footnotes in
198+tables).
197199.SS Reading from the Web
198200.PP
199201Instead of an input file, an absolute URI may be given.
@@ -201,23 +203,23 @@ In this case pandoc will fetch the content using HTTP:
201203.IP
202204.nf
203205\f[C]
204−pandoc \-f html \-t markdown http://www.fsf.org
206+pandoc -f html -t markdown http://www.fsf.org
205207\f[R]
206208.fi
207209.PP
208−It is possible to supply a custom User\-Agent string or other header
209−when requesting a document from a URL:
210+It is possible to supply a custom User-Agent string or other header when
211+requesting a document from a URL:
210212.IP
211213.nf
212214\f[C]
213−pandoc \-f html \-t markdown \-\-request\-header User\-Agent:\[dq]Mozilla/5.0\[dq] \[rs]
215+pandoc -f html -t markdown --request-header User-Agent:\[dq]Mozilla/5.0\[dq] \[rs]
214216 http://www.fsf.org
215217\f[R]
216218.fi
217219.SH OPTIONS
218220.SS General options
219221.TP
220−.B \f[C]\-f\f[R] \f[I]FORMAT\f[R], \f[C]\-r\f[R] \f[I]FORMAT\f[R], \f[C]\-\-from=\f[R]\f[I]FORMAT\f[R], \f[C]\-\-read=\f[R]\f[I]FORMAT\f[R]
222+.B \f[C]-f\f[R] \f[I]FORMAT\f[R], \f[C]-r\f[R] \f[I]FORMAT\f[R], \f[C]--from=\f[R]\f[I]FORMAT\f[R], \f[C]--read=\f[R]\f[I]FORMAT\f[R]
221223Specify input format.
222224\f[I]FORMAT\f[R] can be:
223225.RS
@@ -230,11 +232,13 @@ Specify input format.
230232.IP \[bu] 2
231233\f[C]docx\f[R] (Word docx)
232234.IP \[bu] 2
235+\f[C]dokuwiki\f[R] (DokuWiki markup)
236+.IP \[bu] 2
233237\f[C]epub\f[R] (EPUB)
234238.IP \[bu] 2
235−\f[C]fb2\f[R] (FictionBook2 e\-book)
239+\f[C]fb2\f[R] (FictionBook2 e-book)
236240.IP \[bu] 2
237−\f[C]gfm\f[R] (GitHub\-Flavored Markdown), or the deprecated and less
241+\f[C]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less
238242accurate \f[C]markdown_github\f[R]; use \f[C]markdown_github\f[R] only
239243if you need extensions not supported in \f[C]gfm\f[R].
240244.IP \[bu] 2
@@ -242,6 +246,8 @@ if you need extensions not supported in \f[C]gfm\f[R].
242246.IP \[bu] 2
243247\f[C]html\f[R] (HTML)
244248.IP \[bu] 2
249+\f[C]ipynb\f[R] (Jupyter notebook)
250+.IP \[bu] 2
245251\f[C]jats\f[R] (JATS XML)
246252.IP \[bu] 2
247253\f[C]json\f[R] (JSON version of native AST)
@@ -283,13 +289,13 @@ if you need extensions not supported in \f[C]gfm\f[R].
283289\f[C]vimwiki\f[R] (Vimwiki)
284290.PP
285291Extensions can be individually enabled or disabled by appending
286−\f[C]+EXTENSION\f[R] or \f[C]\-EXTENSION\f[R] to the format name.
292+\f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name.
287293See Extensions below, for a list of extensions and their names.
288−See \f[C]\-\-list\-input\-formats\f[R] and
289−\f[C]\-\-list\-extensions\f[R], below.
294+See \f[C]--list-input-formats\f[R] and \f[C]--list-extensions\f[R],
295+below.
290296.RE
291297.TP
292−.B \f[C]\-t\f[R] \f[I]FORMAT\f[R], \f[C]\-w\f[R] \f[I]FORMAT\f[R], \f[C]\-\-to=\f[R]\f[I]FORMAT\f[R], \f[C]\-\-write=\f[R]\f[I]FORMAT\f[R]
298+.B \f[C]-t\f[R] \f[I]FORMAT\f[R], \f[C]-w\f[R] \f[I]FORMAT\f[R], \f[C]--to=\f[R]\f[I]FORMAT\f[R], \f[C]--write=\f[R]\f[I]FORMAT\f[R]
293299Specify output format.
294300\f[I]FORMAT\f[R] can be:
295301.RS
@@ -314,9 +320,9 @@ Specify output format.
314320.IP \[bu] 2
315321\f[C]epub2\f[R] (EPUB v2)
316322.IP \[bu] 2
317−\f[C]fb2\f[R] (FictionBook2 e\-book)
323+\f[C]fb2\f[R] (FictionBook2 e-book)
318324.IP \[bu] 2
319−\f[C]gfm\f[R] (GitHub\-Flavored Markdown), or the deprecated and less
325+\f[C]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less
320326accurate \f[C]markdown_github\f[R]; use \f[C]markdown_github\f[R] only
321327if you need extensions not supported in \f[C]gfm\f[R].
322328.IP \[bu] 2
@@ -329,6 +335,8 @@ HTML5/XHTML polyglot markup)
329335.IP \[bu] 2
330336\f[C]icml\f[R] (InDesign ICML)
331337.IP \[bu] 2
338+\f[C]ipynb\f[R] (Jupyter notebook)
339+.IP \[bu] 2
332340\f[C]jats\f[R] (JATS XML)
333341.IP \[bu] 2
334342\f[C]json\f[R] (JSON version of native AST)
@@ -390,22 +398,22 @@ HTML5/XHTML polyglot markup)
390398the path of a custom lua writer, see Custom writers below
391399.PP
392400Note that \f[C]odt\f[R], \f[C]docx\f[R], and \f[C]epub\f[R] output will
393−not be directed to \f[I]stdout\f[R] unless forced with \f[C]\-o \-\f[R].
401+not be directed to \f[I]stdout\f[R] unless forced with \f[C]-o -\f[R].
394402.PP
395403Extensions can be individually enabled or disabled by appending
396−\f[C]+EXTENSION\f[R] or \f[C]\-EXTENSION\f[R] to the format name.
404+\f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name.
397405See Extensions below, for a list of extensions and their names.
398−See \f[C]\-\-list\-output\-formats\f[R] and
399−\f[C]\-\-list\-extensions\f[R], below.
406+See \f[C]--list-output-formats\f[R] and \f[C]--list-extensions\f[R],
407+below.
400408.RE
401409.TP
402−.B \f[C]\-o\f[R] \f[I]FILE\f[R], \f[C]\-\-output=\f[R]\f[I]FILE\f[R]
410+.B \f[C]-o\f[R] \f[I]FILE\f[R], \f[C]--output=\f[R]\f[I]FILE\f[R]
403411Write output to \f[I]FILE\f[R] instead of \f[I]stdout\f[R].
404−If \f[I]FILE\f[R] is \f[C]\-\f[R], output will go to \f[I]stdout\f[R],
405−even if a non\-textual format (\f[C]docx\f[R], \f[C]odt\f[R],
412+If \f[I]FILE\f[R] is \f[C]-\f[R], output will go to \f[I]stdout\f[R],
413+even if a non-textual format (\f[C]docx\f[R], \f[C]odt\f[R],
406414\f[C]epub2\f[R], \f[C]epub3\f[R]) is specified.
407415.TP
408−.B \f[C]\-\-data\-dir=\f[R]\f[I]DIRECTORY\f[R]
416+.B \f[C]--data-dir=\f[R]\f[I]DIRECTORY\f[R]
409417Specify the user data directory to search for pandoc data files.
410418If this option is not specified, the default user data directory will be
411419used.
@@ -435,14 +443,14 @@ C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc
435443.fi
436444.PP
437445You can find the default user data directory on your system by looking
438−at the output of \f[C]pandoc \-\-version\f[R].
446+at the output of \f[C]pandoc --version\f[R].
439447A \f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
440448\f[C]templates\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R], or
441449\f[C]s5\f[R] directory placed in this directory will override
442450pandoc\[aq]s normal defaults.
443451.RE
444452.TP
445−.B \f[C]\-\-bash\-completion\f[R]
453+.B \f[C]--bash-completion\f[R]
446454Generate a bash completion script.
447455To enable bash completion with pandoc, add this to your
448456\f[C].bashrc\f[R]:
@@ -450,83 +458,82 @@ To enable bash completion with pandoc, add this to your
450458.IP
451459.nf
452460\f[C]
453−eval \[dq]$(pandoc \-\-bash\-completion)\[dq]
461+eval \[dq]$(pandoc --bash-completion)\[dq]
454462\f[R]
455463.fi
456464.RE
457465.TP
458−.B \f[C]\-\-verbose\f[R]
466+.B \f[C]--verbose\f[R]
459467Give verbose debugging output.
460468Currently this only has an effect with PDF output.
461469.TP
462−.B \f[C]\-\-quiet\f[R]
470+.B \f[C]--quiet\f[R]
463471Suppress warning messages.
464472.TP
465−.B \f[C]\-\-fail\-if\-warnings\f[R]
473+.B \f[C]--fail-if-warnings\f[R]
466474Exit with error status if there are any warnings.
467475.TP
468−.B \f[C]\-\-log=\f[R]\f[I]FILE\f[R]
469−Write log messages in machine\-readable JSON format to \f[I]FILE\f[R].
476+.B \f[C]--log=\f[R]\f[I]FILE\f[R]
477+Write log messages in machine-readable JSON format to \f[I]FILE\f[R].
470478All messages above DEBUG level will be written, regardless of verbosity
471−settings (\f[C]\-\-verbose\f[R], \f[C]\-\-quiet\f[R]).
479+settings (\f[C]--verbose\f[R], \f[C]--quiet\f[R]).
472480.TP
473−.B \f[C]\-\-list\-input\-formats\f[R]
481+.B \f[C]--list-input-formats\f[R]
474482List supported input formats, one per line.
475483.TP
476−.B \f[C]\-\-list\-output\-formats\f[R]
484+.B \f[C]--list-output-formats\f[R]
477485List supported output formats, one per line.
478486.TP
479−.B \f[C]\-\-list\-extensions\f[R][\f[C]=\f[R]\f[I]FORMAT\f[R]]
487+.B \f[C]--list-extensions\f[R][\f[C]=\f[R]\f[I]FORMAT\f[R]]
480488List supported extensions, one per line, preceded by a \f[C]+\f[R] or
481−\f[C]\-\f[R] indicating whether it is enabled by default in
489+\f[C]-\f[R] indicating whether it is enabled by default in
482490\f[I]FORMAT\f[R].
483491If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[aq]s Markdown
484492are given.
485493.TP
486−.B \f[C]\-\-list\-highlight\-languages\f[R]
494+.B \f[C]--list-highlight-languages\f[R]
487495List supported languages for syntax highlighting, one per line.
488496.TP
489−.B \f[C]\-\-list\-highlight\-styles\f[R]
497+.B \f[C]--list-highlight-styles\f[R]
490498List supported styles for syntax highlighting, one per line.
491−See \f[C]\-\-highlight\-style\f[R].
499+See \f[C]--highlight-style\f[R].
492500.TP
493−.B \f[C]\-v\f[R], \f[C]\-\-version\f[R]
501+.B \f[C]-v\f[R], \f[C]--version\f[R]
494502Print version.
495503.TP
496−.B \f[C]\-h\f[R], \f[C]\-\-help\f[R]
504+.B \f[C]-h\f[R], \f[C]--help\f[R]
497505Show usage message.
498506.SS Reader options
499507.TP
500−.B \f[C]\-\-base\-header\-level=\f[R]\f[I]NUMBER\f[R]
508+.B \f[C]--base-header-level=\f[R]\f[I]NUMBER\f[R]
501509Specify the base level for headers (defaults to 1).
502510.TP
503−.B \f[C]\-\-strip\-empty\-paragraphs\f[R]
511+.B \f[C]--strip-empty-paragraphs\f[R]
504512\f[I]Deprecated. Use the \f[CI]+empty_paragraphs\f[I] extension
505513instead.\f[R] Ignore paragraphs with no content.
506514This option is useful for converting word processing documents where
507−users have used empty paragraphs to create inter\-paragraph space.
515+users have used empty paragraphs to create inter-paragraph space.
508516.TP
509−.B \f[C]\-\-indented\-code\-classes=\f[R]\f[I]CLASSES\f[R]
510−Specify classes to use for indented code blocks\-\-for example,
517+.B \f[C]--indented-code-classes=\f[R]\f[I]CLASSES\f[R]
518+Specify classes to use for indented code blocks--for example,
511519\f[C]perl,numberLines\f[R] or \f[C]haskell\f[R].
512520Multiple classes may be separated by spaces or commas.
513521.TP
514−.B \f[C]\-\-default\-image\-extension=\f[R]\f[I]EXTENSION\f[R]
522+.B \f[C]--default-image-extension=\f[R]\f[I]EXTENSION\f[R]
515523Specify a default extension to use when image paths/URLs have no
516524extension.
517525This allows you to use the same source for formats that require
518526different kinds of images.
519527Currently this option only affects the Markdown and LaTeX readers.
520528.TP
521−.B \f[C]\-\-file\-scope\f[R]
529+.B \f[C]--file-scope\f[R]
522530Parse each file individually before combining for multifile documents.
523531This will allow footnotes in different files with the same identifiers
524532to work as expected.
525533If this option is set, footnotes and links will not work across files.
526−Reading binary files (docx, odt, epub) implies
527−\f[C]\-\-file\-scope\f[R].
534+Reading binary files (docx, odt, epub) implies \f[C]--file-scope\f[R].
528535.TP
529−.B \f[C]\-F\f[R] \f[I]PROGRAM\f[R], \f[C]\-\-filter=\f[R]\f[I]PROGRAM\f[R]
536+.B \f[C]-F\f[R] \f[I]PROGRAM\f[R], \f[C]--filter=\f[R]\f[I]PROGRAM\f[R]
530537Specify an executable to be used as a filter transforming the pandoc AST
531538after the input is parsed and before the output is written.
532539The executable should read JSON from stdin and write JSON to stdout.
@@ -538,7 +545,7 @@ Hence,
538545.IP
539546.nf
540547\f[C]
541−pandoc \-\-filter ./caps.py \-t latex
548+pandoc --filter ./caps.py -t latex
542549\f[R]
543550.fi
544551.PP
@@ -546,7 +553,7 @@ is equivalent to
546553.IP
547554.nf
548555\f[C]
549−pandoc \-t json | ./caps.py latex | pandoc \-f json \-t latex
556+pandoc -t json | ./caps.py latex | pandoc -f json -t latex
550557\f[R]
551558.fi
552559.PP
@@ -562,25 +569,24 @@ JavaScript/node.js.
562569.PP
563570In order of preference, pandoc will look for filters in
564571.IP "1." 3
565−a specified full or relative path (executable or non\-executable)
572+a specified full or relative path (executable or non-executable)
566573.IP "2." 3
567−\f[C]$DATADIR/filters\f[R] (executable or non\-executable) where
568−\f[C]$DATADIR\f[R] is the user data directory (see
569−\f[C]\-\-data\-dir\f[R], above).
574+\f[C]$DATADIR/filters\f[R] (executable or non-executable) where
575+\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
576+above).
570577.IP "3." 3
571578\f[C]$PATH\f[R] (executable only)
572579.PP
573−Filters and lua\-filters are applied in the order specified on the
580+Filters and lua-filters are applied in the order specified on the
574581command line.
575582.RE
576583.TP
577−.B \f[C]\-\-lua\-filter=\f[R]\f[I]SCRIPT\f[R]
584+.B \f[C]--lua-filter=\f[R]\f[I]SCRIPT\f[R]
578585Transform the document in a similar fashion as JSON filters (see
579−\f[C]\-\-filter\f[R]), but use pandoc\[aq]s build\-in lua filtering
580−system.
586+\f[C]--filter\f[R]), but use pandoc\[aq]s build-in lua filtering system.
581587The given lua script is expected to return a list of lua filters which
582588will be applied in order.
583−Each lua filter must contain element\-transforming functions indexed by
589+Each lua filter must contain element-transforming functions indexed by
584590the name of the AST element on which the filter function should be
585591applied.
586592.RS
@@ -589,7 +595,7 @@ The \f[C]pandoc\f[R] lua module provides helper functions for element
589595creation.
590596It is always loaded into the script\[aq]s lua environment.
591597.PP
592−The following is an example lua script for macro\-expansion:
598+The following is an example lua script for macro-expansion:
593599.IP
594600.nf
595601\f[C]
@@ -607,44 +613,44 @@ return {{Str = expand_hello_world}}
607613.PP
608614In order of preference, pandoc will look for lua filters in
609615.IP "1." 3
610−a specified full or relative path (executable or non\-executable)
616+a specified full or relative path (executable or non-executable)
611617.IP "2." 3
612−\f[C]$DATADIR/filters\f[R] (executable or non\-executable) where
613−\f[C]$DATADIR\f[R] is the user data directory (see
614−\f[C]\-\-data\-dir\f[R], above).
618+\f[C]$DATADIR/filters\f[R] (executable or non-executable) where
619+\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
620+above).
615621.RE
616622.TP
617−.B \f[C]\-M\f[R] \f[I]KEY\f[R][\f[C]=\f[R]\f[I]VAL\f[R]], \f[C]\-\-metadata=\f[R]\f[I]KEY\f[R][\f[C]:\f[R]\f[I]VAL\f[R]]
623+.B \f[C]-M\f[R] \f[I]KEY\f[R][\f[C]=\f[R]\f[I]VAL\f[R]], \f[C]--metadata=\f[R]\f[I]KEY\f[R][\f[C]:\f[R]\f[I]VAL\f[R]]
618624Set the metadata field \f[I]KEY\f[R] to the value \f[I]VAL\f[R].
619625A value specified on the command line overrides a value specified in the
620626document using YAML metadata blocks.
621627Values will be parsed as YAML boolean or string values.
622628If no value is specified, the value will be treated as Boolean true.
623−Like \f[C]\-\-variable\f[R], \f[C]\-\-metadata\f[R] causes template
629+Like \f[C]--variable\f[R], \f[C]--metadata\f[R] causes template
624630variables to be set.
625−But unlike \f[C]\-\-variable\f[R], \f[C]\-\-metadata\f[R] affects the
631+But unlike \f[C]--variable\f[R], \f[C]--metadata\f[R] affects the
626632metadata of the underlying document (which is accessible from filters
627633and may be printed in some output formats) and metadata values will be
628634escaped when inserted into the template.
629635.TP
630−.B \f[C]\-\-metadata\-file=\f[R]\f[I]FILE\f[R]
636+.B \f[C]--metadata-file=\f[R]\f[I]FILE\f[R]
631637Read metadata from the supplied YAML (or JSON) file.
632638This option can be used with every input format, but string scalars in
633639the YAML file will always be parsed as Markdown.
634640Generally, the input will be handled the same as in YAML metadata
635641blocks.
636−Metadata values specified inside the document, or by using
637−\f[C]\-M\f[R], overwrite values specified with this option.
642+Metadata values specified inside the document, or by using \f[C]-M\f[R],
643+overwrite values specified with this option.
638644.TP
639−.B \f[C]\-p\f[R], \f[C]\-\-preserve\-tabs\f[R]
645+.B \f[C]-p\f[R], \f[C]--preserve-tabs\f[R]
640646Preserve tabs instead of converting them to spaces (the default).
641647Note that this will only affect tabs in literal code spans and code
642648blocks; tabs in regular text will be treated as spaces.
643649.TP
644−.B \f[C]\-\-tab\-stop=\f[R]\f[I]NUMBER\f[R]
650+.B \f[C]--tab-stop=\f[R]\f[I]NUMBER\f[R]
645651Specify the number of spaces per tab (default is 4).
646652.TP
647−.B \f[C]\-\-track\-changes=accept\f[R]|\f[C]reject\f[R]|\f[C]all\f[R]
653+.B \f[C]--track-changes=accept\f[R]|\f[C]reject\f[R]|\f[C]all\f[R]
648654Specifies what to do with insertions, deletions, and comments produced
649655by the MS Word \[dq]Track Changes\[dq] feature.
650656\f[C]accept\f[R] (the default), inserts all insertions, and ignores all
@@ -653,18 +659,18 @@ deletions.
653659Both \f[C]accept\f[R] and \f[C]reject\f[R] ignore comments.
654660\f[C]all\f[R] puts in insertions, deletions, and comments, wrapped in
655661spans with \f[C]insertion\f[R], \f[C]deletion\f[R],
656−\f[C]comment\-start\f[R], and \f[C]comment\-end\f[R] classes,
662+\f[C]comment-start\f[R], and \f[C]comment-end\f[R] classes,
657663respectively.
658664The author and time of change is included.
659665\f[C]all\f[R] is useful for scripting: only accepting changes from a
660666certain reviewer, say, or before a certain date.
661−If a paragraph is inserted or deleted, \f[C]track\-changes=all\f[R]
667+If a paragraph is inserted or deleted, \f[C]track-changes=all\f[R]
662668produces a span with the class
663−\f[C]paragraph\-insertion\f[R]/\f[C]paragraph\-deletion\f[R] before the
669+\f[C]paragraph-insertion\f[R]/\f[C]paragraph-deletion\f[R] before the
664670affected paragraph break.
665671This option only affects the docx reader.
666672.TP
667−.B \f[C]\-\-extract\-media=\f[R]\f[I]DIR\f[R]
673+.B \f[C]--extract-media=\f[R]\f[I]DIR\f[R]
668674Extract images and other media contained in or linked from the source
669675document to the path \f[I]DIR\f[R], creating it if necessary, and adjust
670676the images references in the document so they point to the extracted
@@ -675,20 +681,20 @@ used.
675681Otherwise the media is read from the file system or downloaded, and new
676682filenames are constructed based on SHA1 hashes of the contents.
677683.TP
678−.B \f[C]\-\-abbreviations=\f[R]\f[I]FILE\f[R]
684+.B \f[C]--abbreviations=\f[R]\f[I]FILE\f[R]
679685Specifies a custom abbreviations file, with abbreviations one to a line.
680686If this option is not specified, pandoc will read the data file
681687\f[C]abbreviations\f[R] from the user data directory or fall back on a
682688system default.
683689To see the system default, use
684−\f[C]pandoc \-\-print\-default\-data\-file=abbreviations\f[R].
690+\f[C]pandoc --print-default-data-file=abbreviations\f[R].
685691The only use pandoc makes of this list is in the Markdown reader.
686692Strings ending in a period that are found in this list will be followed
687693by a nonbreaking space, so that the period will not produce
688−sentence\-ending space in formats like LaTeX.
694+sentence-ending space in formats like LaTeX.
689695.SS General writer options
690696.TP
691−.B \f[C]\-s\f[R], \f[C]\-\-standalone\f[R]
697+.B \f[C]-s\f[R], \f[C]--standalone\f[R]
692698Produce output with an appropriate header and footer (e.g.
693699a standalone HTML, LaTeX, TEI, or RTF file, not a fragment).
694700This option is set automatically for \f[C]pdf\f[R], \f[C]epub\f[R],
@@ -697,102 +703,103 @@ output.
697703For \f[C]native\f[R] output, this option causes metadata to be included;
698704otherwise, metadata is suppressed.
699705.TP
700−.B \f[C]\-\-template=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
706+.B \f[C]--template=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
701707Use the specified file as a custom template for the generated document.
702−Implies \f[C]\-\-standalone\f[R].
708+Implies \f[C]--standalone\f[R].
703709See Templates, below, for a description of template syntax.
704710If no extension is specified, an extension corresponding to the writer
705−will be added, so that \f[C]\-\-template=special\f[R] looks for
711+will be added, so that \f[C]--template=special\f[R] looks for
706712\f[C]special.html\f[R] for HTML output.
707713If the template is not found, pandoc will search for it in the
708714\f[C]templates\f[R] subdirectory of the user data directory (see
709−\f[C]\-\-data\-dir\f[R]).
715+\f[C]--data-dir\f[R]).
710716If this option is not used, a default template appropriate for the
711−output format will be used (see
712−\f[C]\-D/\-\-print\-default\-template\f[R]).
717+output format will be used (see \f[C]-D/--print-default-template\f[R]).
713718.TP
714−.B \f[C]\-V\f[R] \f[I]KEY\f[R][\f[C]=\f[R]\f[I]VAL\f[R]], \f[C]\-\-variable=\f[R]\f[I]KEY\f[R][\f[C]:\f[R]\f[I]VAL\f[R]]
719+.B \f[C]-V\f[R] \f[I]KEY\f[R][\f[C]=\f[R]\f[I]VAL\f[R]], \f[C]--variable=\f[R]\f[I]KEY\f[R][\f[C]:\f[R]\f[I]VAL\f[R]]
715720Set the template variable \f[I]KEY\f[R] to the value \f[I]VAL\f[R] when
716721rendering the document in standalone mode.
717−This is generally only useful when the \f[C]\-\-template\f[R] option is
722+This is generally only useful when the \f[C]--template\f[R] option is
718723used to specify a custom template, since pandoc automatically sets the
719724variables used in the default templates.
720725If no \f[I]VAL\f[R] is specified, the key will be given the value
721726\f[C]true\f[R].
722727.TP
723−.B \f[C]\-D\f[R] \f[I]FORMAT\f[R], \f[C]\-\-print\-default\-template=\f[R]\f[I]FORMAT\f[R]
728+.B \f[C]-D\f[R] \f[I]FORMAT\f[R], \f[C]--print-default-template=\f[R]\f[I]FORMAT\f[R]
724729Print the system default template for an output \f[I]FORMAT\f[R].
725−(See \f[C]\-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.) Templates
730+(See \f[C]-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.) Templates
726731in the user data directory are ignored.
727732.TP
728−.B \f[C]\-\-print\-default\-data\-file=\f[R]\f[I]FILE\f[R]
733+.B \f[C]--print-default-data-file=\f[R]\f[I]FILE\f[R]
729734Print a system default data file.
730735Files in the user data directory are ignored.
731736.TP
732−.B \f[C]\-\-eol=crlf\f[R]|\f[C]lf\f[R]|\f[C]native\f[R]
737+.B \f[C]--eol=crlf\f[R]|\f[C]lf\f[R]|\f[C]native\f[R]
733738Manually specify line endings: \f[C]crlf\f[R] (Windows), \f[C]lf\f[R]
734739(macOS/Linux/UNIX), or \f[C]native\f[R] (line endings appropriate to the
735740OS on which pandoc is being run).
736741The default is \f[C]native\f[R].
737742.TP
738−.B \f[C]\-\-dpi\f[R]=\f[I]NUMBER\f[R]
743+.B \f[C]--dpi\f[R]=\f[I]NUMBER\f[R]
739744Specify the dpi (dots per inch) value for conversion from pixels to
740745inch/centimeters and vice versa.
741746The default is 96dpi.
742747Technically, the correct term would be ppi (pixels per inch).
743748.TP
744−.B \f[C]\-\-wrap=auto\f[R]|\f[C]none\f[R]|\f[C]preserve\f[R]
749+.B \f[C]--wrap=auto\f[R]|\f[C]none\f[R]|\f[C]preserve\f[R]
745750Determine how text is wrapped in the output (the source code, not the
746751rendered version).
747752With \f[C]auto\f[R] (the default), pandoc will attempt to wrap lines to
748−the column width specified by \f[C]\-\-columns\f[R] (default 72).
753+the column width specified by \f[C]--columns\f[R] (default 72).
749754With \f[C]none\f[R], pandoc will not wrap lines at all.
750755With \f[C]preserve\f[R], pandoc will attempt to preserve the wrapping
751756from the source document (that is, where there are nonsemantic newlines
752757in the source, there will be nonsemantic newlines in the output as
753758well).
754759Automatic wrapping does not currently work in HTML output.
760+In \f[C]ipynb\f[R] output, this option affects wrapping of the contents
761+of markdown cells.
755762.TP
756−.B \f[C]\-\-columns=\f[R]\f[I]NUMBER\f[R]
763+.B \f[C]--columns=\f[R]\f[I]NUMBER\f[R]
757764Specify length of lines in characters.
758765This affects text wrapping in the generated source code (see
759−\f[C]\-\-wrap\f[R]).
766+\f[C]--wrap\f[R]).
760767It also affects calculation of column widths for plain text tables (see
761768Tables below).
762769.TP
763−.B \f[C]\-\-toc\f[R], \f[C]\-\-table\-of\-contents\f[R]
770+.B \f[C]--toc\f[R], \f[C]--table-of-contents\f[R]
764771Include an automatically generated table of contents (or, in the case of
765772\f[C]latex\f[R], \f[C]context\f[R], \f[C]docx\f[R], \f[C]odt\f[R],
766773\f[C]opendocument\f[R], \f[C]rst\f[R], or \f[C]ms\f[R], an instruction
767774to create one) in the output document.
768−This option has no effect unless \f[C]\-s/\-\-standalone\f[R] is used,
769−and it has no effect on \f[C]man\f[R], \f[C]docbook4\f[R],
775+This option has no effect unless \f[C]-s/--standalone\f[R] is used, and
776+it has no effect on \f[C]man\f[R], \f[C]docbook4\f[R],
770777\f[C]docbook5\f[R], or \f[C]jats\f[R] output.
771778.TP
772−.B \f[C]\-\-toc\-depth=\f[R]\f[I]NUMBER\f[R]
779+.B \f[C]--toc-depth=\f[R]\f[I]NUMBER\f[R]
773780Specify the number of section levels to include in the table of
774781contents.
775782The default is 3 (which means that level 1, 2, and 3 headers will be
776783listed in the contents).
777784.TP
778−.B \f[C]\-\-strip\-comments\f[R]
785+.B \f[C]--strip-comments\f[R]
779786Strip out HTML comments in the Markdown or Textile source, rather than
780787passing them on to Markdown, Textile or HTML output as raw HTML.
781788This does not apply to HTML comments inside raw HTML blocks when the
782789\f[C]markdown_in_html_blocks\f[R] extension is not set.
783790.TP
784−.B \f[C]\-\-no\-highlight\f[R]
791+.B \f[C]--no-highlight\f[R]
785792Disables syntax highlighting for code blocks and inlines, even when a
786793language attribute is given.
787794.TP
788−.B \f[C]\-\-highlight\-style=\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]
795+.B \f[C]--highlight-style=\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]
789796Specifies the coloring style to be used in highlighted source code.
790797Options are \f[C]pygments\f[R] (the default), \f[C]kate\f[R],
791798\f[C]monochrome\f[R], \f[C]breezeDark\f[R], \f[C]espresso\f[R],
792799\f[C]zenburn\f[R], \f[C]haddock\f[R], and \f[C]tango\f[R].
793800For more information on syntax highlighting in pandoc, see Syntax
794801highlighting, below.
795−See also \f[C]\-\-list\-highlight\-styles\f[R].
802+See also \f[C]--list-highlight-styles\f[R].
796803.RS
797804.PP
798805Instead of a \f[I]STYLE\f[R] name, a JSON file with extension
@@ -801,30 +808,30 @@ This will be parsed as a KDE syntax highlighting theme and (if valid)
801808used as the highlighting style.
802809.PP
803810To generate the JSON version of an existing style, use
804−\f[C]\-\-print\-highlight\-style\f[R].
811+\f[C]--print-highlight-style\f[R].
805812.RE
806813.TP
807−.B \f[C]\-\-print\-highlight\-style=\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]
814+.B \f[C]--print-highlight-style=\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]
808815Prints a JSON version of a highlighting style, which can be modified,
809816saved with a \f[C].theme\f[R] extension, and used with
810−\f[C]\-\-highlight\-style\f[R].
817+\f[C]--highlight-style\f[R].
811818.TP
812−.B \f[C]\-\-syntax\-definition=\f[R]\f[I]FILE\f[R]
819+.B \f[C]--syntax-definition=\f[R]\f[I]FILE\f[R]
813820Instructs pandoc to load a KDE XML syntax definition file, which will be
814821used for syntax highlighting of appropriately marked code blocks.
815822This can be used to add support for new languages or to use altered
816823syntax definitions for existing languages.
817824.TP
818−.B \f[C]\-H\f[R] \f[I]FILE\f[R], \f[C]\-\-include\-in\-header=\f[R]\f[I]FILE\f[R]
825+.B \f[C]-H\f[R] \f[I]FILE\f[R], \f[C]--include-in-header=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
819826Include contents of \f[I]FILE\f[R], verbatim, at the end of the header.
820827This can be used, for example, to include special CSS or JavaScript in
821828HTML documents.
822829This option can be used repeatedly to include multiple files in the
823830header.
824831They will be included in the order specified.
825−Implies \f[C]\-\-standalone\f[R].
832+Implies \f[C]--standalone\f[R].
826833.TP
827−.B \f[C]\-B\f[R] \f[I]FILE\f[R], \f[C]\-\-include\-before\-body=\f[R]\f[I]FILE\f[R]
834+.B \f[C]-B\f[R] \f[I]FILE\f[R], \f[C]--include-before-body=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
828835Include contents of \f[I]FILE\f[R], verbatim, at the beginning of the
829836document body (e.g.
830837after the \f[C]<body>\f[R] tag in HTML, or the
@@ -833,35 +840,35 @@ This can be used to include navigation bars or banners in HTML
833840documents.
834841This option can be used repeatedly to include multiple files.
835842They will be included in the order specified.
836−Implies \f[C]\-\-standalone\f[R].
843+Implies \f[C]--standalone\f[R].
837844.TP
838−.B \f[C]\-A\f[R] \f[I]FILE\f[R], \f[C]\-\-include\-after\-body=\f[R]\f[I]FILE\f[R]
845+.B \f[C]-A\f[R] \f[I]FILE\f[R], \f[C]--include-after-body=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
839846Include contents of \f[I]FILE\f[R], verbatim, at the end of the document
840847body (before the \f[C]</body>\f[R] tag in HTML, or the
841848\f[C]\[rs]end{document}\f[R] command in LaTeX).
842849This option can be used repeatedly to include multiple files.
843850They will be included in the order specified.
844−Implies \f[C]\-\-standalone\f[R].
851+Implies \f[C]--standalone\f[R].
845852.TP
846−.B \f[C]\-\-resource\-path=\f[R]\f[I]SEARCHPATH\f[R]
853+.B \f[C]--resource-path=\f[R]\f[I]SEARCHPATH\f[R]
847854List of paths to search for images and other resources.
848855The paths should be separated by \f[C]:\f[R] on Linux, UNIX, and macOS
849856systems, and by \f[C];\f[R] on Windows.
850−If \f[C]\-\-resource\-path\f[R] is not specified, the default resource
851−path is the working directory.
852−Note that, if \f[C]\-\-resource\-path\f[R] is specified, the working
857+If \f[C]--resource-path\f[R] is not specified, the default resource path
858+is the working directory.
859+Note that, if \f[C]--resource-path\f[R] is specified, the working
853860directory must be explicitly listed or it will not be searched.
854−For example: \f[C]\-\-resource\-path=.:test\f[R] will search the working
861+For example: \f[C]--resource-path=.:test\f[R] will search the working
855862directory and the \f[C]test\f[R] subdirectory, in that order.
856863.RS
857864.PP
858−\f[C]\-\-resource\-path\f[R] only has an effect if (a) the output format
865+\f[C]--resource-path\f[R] only has an effect if (a) the output format
859866embeds images (for example, \f[C]docx\f[R], \f[C]pdf\f[R], or
860−\f[C]html\f[R] with \f[C]\-\-self\-contained\f[R]) or (b) it is used
861−together with \f[C]\-\-extract\-media\f[R].
867+\f[C]html\f[R] with \f[C]--self-contained\f[R]) or (b) it is used
868+together with \f[C]--extract-media\f[R].
862869.RE
863870.TP
864−.B \f[C]\-\-request\-header=\f[R]\f[I]NAME\f[R]\f[C]:\f[R]\f[I]VAL\f[R]
871+.B \f[C]--request-header=\f[R]\f[I]NAME\f[R]\f[C]:\f[R]\f[I]VAL\f[R]
865872Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when
866873making HTTP requests (for example, when a URL is given on the command
867874line, or when resources used in a document must be downloaded).
@@ -869,14 +876,14 @@ If you\[aq]re behind a proxy, you also need to set the environment
869876variable \f[C]http_proxy\f[R] to \f[C]http://...\f[R].
870877.SS Options affecting specific writers
871878.TP
872−.B \f[C]\-\-self\-contained\f[R]
879+.B \f[C]--self-contained\f[R]
873880Produce a standalone HTML file with no external dependencies, using
874881\f[C]data:\f[R] URIs to incorporate the contents of linked scripts,
875882stylesheets, images, and videos.
876−Implies \f[C]\-\-standalone\f[R].
877−The resulting file should be \[dq]self\-contained,\[dq] in the sense
878−that it needs no external files and no net access to be displayed
879−properly by a browser.
883+Implies \f[C]--standalone\f[R].
884+The resulting file should be \[dq]self-contained,\[dq] in the sense that
885+it needs no external files and no net access to be displayed properly by
886+a browser.
880887This option works only with HTML output formats, including
881888\f[C]html4\f[R], \f[C]html5\f[R], \f[C]html+lhs\f[R],
882889\f[C]html5+lhs\f[R], \f[C]s5\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R],
@@ -885,52 +892,53 @@ Scripts, images, and stylesheets at absolute URLs will be downloaded;
885892those at relative URLs will be sought relative to the working directory
886893(if the first source file is local) or relative to the base URL (if the
887894first source file is remote).
888−Elements with the attribute \f[C]data\-external=\[dq]1\[dq]\f[R] will be
895+Elements with the attribute \f[C]data-external=\[dq]1\[dq]\f[R] will be
889896left alone; the documents they link to will not be incorporated in the
890897document.
891898Limitation: resources that are loaded dynamically through JavaScript
892−cannot be incorporated; as a result, \f[C]\-\-self\-contained\f[R] does
893−not work with \f[C]\-\-mathjax\f[R], and some advanced features (e.g.
899+cannot be incorporated; as a result, \f[C]--self-contained\f[R] does not
900+work with \f[C]--mathjax\f[R], and some advanced features (e.g.
894901zoom or speaker notes) may not work in an offline
895−\[dq]self\-contained\[dq] \f[C]reveal.js\f[R] slide show.
902+\[dq]self-contained\[dq] \f[C]reveal.js\f[R] slide show.
896903.TP
897−.B \f[C]\-\-html\-q\-tags\f[R]
904+.B \f[C]--html-q-tags\f[R]
898905Use \f[C]<q>\f[R] tags for quotes in HTML.
899906.TP
900−.B \f[C]\-\-ascii\f[R]
907+.B \f[C]--ascii\f[R]
901908Use only ASCII characters in output.
902909Currently supported for XML and HTML formats (which use entities instead
903−of UTF\-8 when this option is selected), CommonMark, gfm, and Markdown
910+of UTF-8 when this option is selected), CommonMark, gfm, and Markdown
904911(which use entities), roff ms (which use hexadecimal escapes), and to a
905912limited degree LaTeX (which uses standard commands for accented
906913characters when possible).
907914roff man output uses ASCII by default.
908915.TP
909−.B \f[C]\-\-reference\-links\f[R]
910−Use reference\-style links, rather than inline links, in writing
911−Markdown or reStructuredText.
916+.B \f[C]--reference-links\f[R]
917+Use reference-style links, rather than inline links, in writing Markdown
918+or reStructuredText.
912919By default inline links are used.
913920The placement of link references is affected by the
914−\f[C]\-\-reference\-location\f[R] option.
921+\f[C]--reference-location\f[R] option.
915922.TP
916−.B \f[C]\-\-reference\-location = block\f[R]|\f[C]section\f[R]|\f[C]document\f[R]
917−Specify whether footnotes (and references, if \f[C]reference\-links\f[R]
918−is set) are placed at the end of the current (top\-level) block, the
923+.B \f[C]--reference-location = block\f[R]|\f[C]section\f[R]|\f[C]document\f[R]
924+Specify whether footnotes (and references, if \f[C]reference-links\f[R]
925+is set) are placed at the end of the current (top-level) block, the
919926current section, or the document.
920927The default is \f[C]document\f[R].
921928Currently only affects the markdown writer.
922929.TP
923−.B \f[C]\-\-atx\-headers\f[R]
924−Use ATX\-style headers in Markdown output.
925−The default is to use setext\-style headers for levels 1\-2, and then
926−ATX headers.
927−(Note: for \f[C]gfm\f[R] output, ATX headers are always used.)
930+.B \f[C]--atx-headers\f[R]
931+Use ATX-style headers in Markdown output.
932+The default is to use setext-style headers for levels 1-2, and then ATX
933+headers.
934+(Note: for \f[C]gfm\f[R] output, ATX headers are always used.) This
935+option also affects markdown cells in \f[C]ipynb\f[R] output.
928936.TP
929−.B \f[C]\-\-top\-level\-division=[default|section|chapter|part]\f[R]
930−Treat top\-level headers as the given division type in LaTeX, ConTeXt,
937+.B \f[C]--top-level-division=[default|section|chapter|part]\f[R]
938+Treat top-level headers as the given division type in LaTeX, ConTeXt,
931939DocBook, and TEI output.
932940The hierarchy order is part, chapter, then section; all headers are
933−shifted such that the top\-level header becomes the specified type.
941+shifted such that the top-level header becomes the specified type.
934942The default behavior is to determine the best division type via
935943heuristics: unless other conditions apply, \f[C]section\f[R] is chosen.
936944When the LaTeX document class is set to \f[C]report\f[R],
@@ -938,59 +946,58 @@ When the LaTeX document class is set to \f[C]report\f[R],
938946is specified), \f[C]chapter\f[R] is implied as the setting for this
939947option.
940948If \f[C]beamer\f[R] is the output format, specifying either
941−\f[C]chapter\f[R] or \f[C]part\f[R] will cause top\-level headers to
942−become \f[C]\[rs]part{..}\f[R], while second\-level headers remain as
949+\f[C]chapter\f[R] or \f[C]part\f[R] will cause top-level headers to
950+become \f[C]\[rs]part{..}\f[R], while second-level headers remain as
943951their default type.
944952.TP
945−.B \f[C]\-N\f[R], \f[C]\-\-number\-sections\f[R]
953+.B \f[C]-N\f[R], \f[C]--number-sections\f[R]
946954Number section headings in LaTeX, ConTeXt, HTML, or EPUB output.
947955By default, sections are not numbered.
948956Sections with class \f[C]unnumbered\f[R] will never be numbered, even if
949−\f[C]\-\-number\-sections\f[R] is specified.
957+\f[C]--number-sections\f[R] is specified.
950958.TP
951−.B \f[C]\-\-number\-offset=\f[R]\f[I]NUMBER\f[R][\f[C],\f[R]\f[I]NUMBER\f[R]\f[C],\f[R]\f[I]...\f[R]]
959+.B \f[C]--number-offset=\f[R]\f[I]NUMBER\f[R][\f[C],\f[R]\f[I]NUMBER\f[R]\f[C],\f[R]\f[I]...\f[R]]
952960Offset for section headings in HTML output (ignored in other output
953961formats).
954−The first number is added to the section number for top\-level headers,
955−the second for second\-level headers, and so on.
956−So, for example, if you want the first top\-level header in your
957−document to be numbered \[dq]6\[dq], specify
958−\f[C]\-\-number\-offset=5\f[R].
959−If your document starts with a level\-2 header which you want to be
960−numbered \[dq]1.5\[dq], specify \f[C]\-\-number\-offset=1,4\f[R].
962+The first number is added to the section number for top-level headers,
963+the second for second-level headers, and so on.
964+So, for example, if you want the first top-level header in your document
965+to be numbered \[dq]6\[dq], specify \f[C]--number-offset=5\f[R].
966+If your document starts with a level-2 header which you want to be
967+numbered \[dq]1.5\[dq], specify \f[C]--number-offset=1,4\f[R].
961968Offsets are 0 by default.
962−Implies \f[C]\-\-number\-sections\f[R].
969+Implies \f[C]--number-sections\f[R].
963970.TP
964−.B \f[C]\-\-listings\f[R]
971+.B \f[C]--listings\f[R]
965972Use the \f[C]listings\f[R] package for LaTeX code blocks.
966−The package does not support multi\-byte encoding for source code.
967−To handle UTF\-8 you would need to use a custom template.
973+The package does not support multi-byte encoding for source code.
974+To handle UTF-8 you would need to use a custom template.
968975This issue is fully documented here: Encoding issue with the listings
969976package.
970977.TP
971−.B \f[C]\-i\f[R], \f[C]\-\-incremental\f[R]
978+.B \f[C]-i\f[R], \f[C]--incremental\f[R]
972979Make list items in slide shows display incrementally (one by one).
973980The default is for lists to be displayed all at once.
974981.TP
975−.B \f[C]\-\-slide\-level=\f[R]\f[I]NUMBER\f[R]
982+.B \f[C]--slide-level=\f[R]\f[I]NUMBER\f[R]
976983Specifies that headers with the specified level create slides (for
977984\f[C]beamer\f[R], \f[C]s5\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R],
978985\f[C]dzslides\f[R]).
979986Headers above this level in the hierarchy are used to divide the slide
980987show into sections; headers below this level create subheads within a
981988slide.
982−Note that content that is not contained under slide\-level headers will
989+Note that content that is not contained under slide-level headers will
983990not appear in the slide show.
984991The default is to set the slide level based on the contents of the
985992document; see Structuring the slide show.
986993.TP
987−.B \f[C]\-\-section\-divs\f[R]
994+.B \f[C]--section-divs\f[R]
988995Wrap sections in \f[C]<section>\f[R] tags (or \f[C]<div>\f[R] tags for
989996\f[C]html4\f[R]), and attach identifiers to the enclosing
990997\f[C]<section>\f[R] (or \f[C]<div>\f[R]) rather than the header itself.
991998See Header identifiers, below.
992999.TP
993−.B \f[C]\-\-email\-obfuscation=none\f[R]|\f[C]javascript\f[R]|\f[C]references\f[R]
1000+.B \f[C]--email-obfuscation=none\f[R]|\f[C]javascript\f[R]|\f[C]references\f[R]
9941001Specify a method for obfuscating \f[C]mailto:\f[R] links in HTML
9951002documents.
9961003\f[C]none\f[R] leaves \f[C]mailto:\f[R] links as they are.
@@ -999,20 +1006,20 @@ documents.
9991006decimal or hexadecimal character references.
10001007The default is \f[C]none\f[R].
10011008.TP
1002−.B \f[C]\-\-id\-prefix=\f[R]\f[I]STRING\f[R]
1009+.B \f[C]--id-prefix=\f[R]\f[I]STRING\f[R]
10031010Specify a prefix to be added to all identifiers and internal links in
10041011HTML and DocBook output, and to footnote numbers in Markdown and Haddock
10051012output.
10061013This is useful for preventing duplicate identifiers when generating
10071014fragments to be included in other pages.
10081015.TP
1009−.B \f[C]\-T\f[R] \f[I]STRING\f[R], \f[C]\-\-title\-prefix=\f[R]\f[I]STRING\f[R]
1016+.B \f[C]-T\f[R] \f[I]STRING\f[R], \f[C]--title-prefix=\f[R]\f[I]STRING\f[R]
10101017Specify \f[I]STRING\f[R] as a prefix at the beginning of the title that
10111018appears in the HTML header (but not in the title as it appears at the
10121019beginning of the HTML body).
1013−Implies \f[C]\-\-standalone\f[R].
1020+Implies \f[C]--standalone\f[R].
10141021.TP
1015−.B \f[C]\-c\f[R] \f[I]URL\f[R], \f[C]\-\-css=\f[R]\f[I]URL\f[R]
1022+.B \f[C]-c\f[R] \f[I]URL\f[R], \f[C]--css=\f[R]\f[I]URL\f[R]
10161023Link to a CSS style sheet.
10171024This option can be used repeatedly to include multiple files.
10181025They will be included in the order specified.
@@ -1022,11 +1029,11 @@ A stylesheet is required for generating EPUB.
10221029If none is provided using this option (or the \f[C]css\f[R] or
10231030\f[C]stylesheet\f[R] metadata fields), pandoc will look for a file
10241031\f[C]epub.css\f[R] in the user data directory (see
1025−\f[C]\-\-data\-dir\f[R]).
1032+\f[C]--data-dir\f[R]).
10261033If it is not found there, sensible defaults will be used.
10271034.RE
10281035.TP
1029−.B \f[C]\-\-reference\-doc=\f[R]\f[I]FILE\f[R]
1036+.B \f[C]--reference-doc=\f[R]\f[I]FILE\f[R]
10301037Use the specified file as a style reference in producing a docx or ODT
10311038file.
10321039.RS
@@ -1039,24 +1046,93 @@ document properties (including margins, page size, header, and footer)
10391046are used in the new docx.
10401047If no reference docx is specified on the command line, pandoc will look
10411048for a file \f[C]reference.docx\f[R] in the user data directory (see
1042−\f[C]\-\-data\-dir\f[R]).
1049+\f[C]--data-dir\f[R]).
10431050If this is not found either, sensible defaults will be used.
10441051.RS
10451052.PP
10461053To produce a custom \f[C]reference.docx\f[R], first get a copy of the
10471054default \f[C]reference.docx\f[R]:
1048−\f[C]pandoc \-\-print\-default\-data\-file reference.docx > custom\-reference.docx\f[R].
1049−Then open \f[C]custom\-reference.docx\f[R] in Word, modify the styles as
1055+\f[C]pandoc --print-default-data-file reference.docx > custom-reference.docx\f[R].
1056+Then open \f[C]custom-reference.docx\f[R] in Word, modify the styles as
10501057you wish, and save the file.
10511058For best results, do not make changes to this file other than modifying
1052−the styles used by pandoc: [paragraph] Normal, Body Text, First
1053−Paragraph, Compact, Title, Subtitle, Author, Date, Abstract,
1054−Bibliography, Heading 1, Heading 2, Heading 3, Heading 4, Heading 5,
1055−Heading 6, Heading 7, Heading 8, Heading 9, Block Text, Footnote Text,
1056−Definition Term, Definition, Caption, Table Caption, Image Caption,
1057−Figure, Captioned Figure, TOC Heading; [character] Default Paragraph
1058−Font, Body Text Char, Verbatim Char, Footnote Reference, Hyperlink;
1059−[table] Table.
1059+the styles used by pandoc:
1060+.PP
1061+Paragraph styles:
1062+.IP \[bu] 2
1063+Normal
1064+.IP \[bu] 2
1065+Body Text
1066+.IP \[bu] 2
1067+First Paragraph
1068+.IP \[bu] 2
1069+Compact
1070+.IP \[bu] 2
1071+Title
1072+.IP \[bu] 2
1073+Subtitle
1074+.IP \[bu] 2
1075+Author
1076+.IP \[bu] 2
1077+Date
1078+.IP \[bu] 2
1079+Abstract
1080+.IP \[bu] 2
1081+Bibliography
1082+.IP \[bu] 2
1083+Heading 1
1084+.IP \[bu] 2
1085+Heading 2
1086+.IP \[bu] 2
1087+Heading 3
1088+.IP \[bu] 2
1089+Heading 4
1090+.IP \[bu] 2
1091+Heading 5
1092+.IP \[bu] 2
1093+Heading 6
1094+.IP \[bu] 2
1095+Heading 7
1096+.IP \[bu] 2
1097+Heading 8
1098+.IP \[bu] 2
1099+Heading 9
1100+.IP \[bu] 2
1101+Block Text
1102+.IP \[bu] 2
1103+Footnote Text
1104+.IP \[bu] 2
1105+Definition Term
1106+.IP \[bu] 2
1107+Definition
1108+.IP \[bu] 2
1109+Caption
1110+.IP \[bu] 2
1111+Table Caption
1112+.IP \[bu] 2
1113+Image Caption
1114+.IP \[bu] 2
1115+Figure
1116+.IP \[bu] 2
1117+Captioned Figure
1118+.IP \[bu] 2
1119+TOC Heading
1120+.PP
1121+Character styles:
1122+.IP \[bu] 2
1123+Default Paragraph Font
1124+.IP \[bu] 2
1125+Body Text Char
1126+.IP \[bu] 2
1127+Verbatim Char
1128+.IP \[bu] 2
1129+Footnote Reference
1130+.IP \[bu] 2
1131+Hyperlink
1132+.PP
1133+Table style:
1134+.IP \[bu] 2
1135+Table
10601136.RE
10611137.TP
10621138.B ODT
@@ -1066,14 +1142,14 @@ The contents of the reference ODT are ignored, but its stylesheets are
10661142used in the new ODT.
10671143If no reference ODT is specified on the command line, pandoc will look
10681144for a file \f[C]reference.odt\f[R] in the user data directory (see
1069−\f[C]\-\-data\-dir\f[R]).
1145+\f[C]--data-dir\f[R]).
10701146If this is not found either, sensible defaults will be used.
10711147.RS
10721148.PP
10731149To produce a custom \f[C]reference.odt\f[R], first get a copy of the
10741150default \f[C]reference.odt\f[R]:
1075−\f[C]pandoc \-\-print\-default\-data\-file reference.odt > custom\-reference.odt\f[R].
1076−Then open \f[C]custom\-reference.odt\f[R] in LibreOffice, modify the
1151+\f[C]pandoc --print-default-data-file reference.odt > custom-reference.odt\f[R].
1152+Then open \f[C]custom-reference.odt\f[R] in LibreOffice, modify the
10771153styles as you wish, and save the file.
10781154.RE
10791155.TP
@@ -1100,21 +1176,21 @@ these criteria.
11001176check.)
11011177.PP
11021178You can also modify the default \f[C]reference.pptx\f[R]: first run
1103−\f[C]pandoc \-\-print\-default\-data\-file reference.pptx > custom\-reference.pptx\f[R],
1104−and then modify \f[C]custom\-reference.pptx\f[R] in MS PowerPoint
1105−(pandoc will use the first four layout slides, as mentioned above).
1179+\f[C]pandoc --print-default-data-file reference.pptx > custom-reference.pptx\f[R],
1180+and then modify \f[C]custom-reference.pptx\f[R] in MS PowerPoint (pandoc
1181+will use the first four layout slides, as mentioned above).
11061182.RE
11071183.RE
11081184.TP
1109−.B \f[C]\-\-epub\-cover\-image=\f[R]\f[I]FILE\f[R]
1185+.B \f[C]--epub-cover-image=\f[R]\f[I]FILE\f[R]
11101186Use the specified image as the EPUB cover.
11111187It is recommended that the image be less than 1000px in width and
11121188height.
11131189Note that in a Markdown source document you can also specify
1114−\f[C]cover\-image\f[R] in a YAML metadata block (see EPUB Metadata,
1190+\f[C]cover-image\f[R] in a YAML metadata block (see EPUB Metadata,
11151191below).
11161192.TP
1117−.B \f[C]\-\-epub\-metadata=\f[R]\f[I]FILE\f[R]
1193+.B \f[C]--epub-metadata=\f[R]\f[I]FILE\f[R]
11181194Look in the specified XML file for metadata for the EPUB.
11191195The file should contain a series of Dublin Core elements.
11201196For example:
@@ -1123,7 +1199,7 @@ For example:
11231199.nf
11241200\f[C]
11251201 <dc:rights>Creative Commons</dc:rights>
1126− <dc:language>es\-AR</dc:language>
1202+ <dc:language>es-AR</dc:language>
11271203\f[R]
11281204.fi
11291205.PP
@@ -1141,49 +1217,49 @@ document can be used instead.
11411217See below under EPUB Metadata.
11421218.RE
11431219.TP
1144−.B \f[C]\-\-epub\-embed\-font=\f[R]\f[I]FILE\f[R]
1220+.B \f[C]--epub-embed-font=\f[R]\f[I]FILE\f[R]
11451221Embed the specified font in the EPUB.
11461222This option can be repeated to embed multiple fonts.
1147−Wildcards can also be used: for example, \f[C]DejaVuSans\-*.ttf\f[R].
1223+Wildcards can also be used: for example, \f[C]DejaVuSans-*.ttf\f[R].
11481224However, if you use wildcards on the command line, be sure to escape
11491225them or put the whole filename in single quotes, to prevent them from
11501226being interpreted by the shell.
11511227To use the embedded fonts, you will need to add declarations like the
1152−following to your CSS (see \f[C]\-\-css\f[R]):
1228+following to your CSS (see \f[C]--css\f[R]):
11531229.RS
11541230.IP
11551231.nf
11561232\f[C]
1157−\[at]font\-face {
1158−font\-family: DejaVuSans;
1159−font\-style: normal;
1160−font\-weight: normal;
1161−src:url(\[dq]DejaVuSans\-Regular.ttf\[dq]);
1233+\[at]font-face {
1234+font-family: DejaVuSans;
1235+font-style: normal;
1236+font-weight: normal;
1237+src:url(\[dq]DejaVuSans-Regular.ttf\[dq]);
11621238}
1163−\[at]font\-face {
1164−font\-family: DejaVuSans;
1165−font\-style: normal;
1166−font\-weight: bold;
1167−src:url(\[dq]DejaVuSans\-Bold.ttf\[dq]);
1239+\[at]font-face {
1240+font-family: DejaVuSans;
1241+font-style: normal;
1242+font-weight: bold;
1243+src:url(\[dq]DejaVuSans-Bold.ttf\[dq]);
11681244}
1169−\[at]font\-face {
1170−font\-family: DejaVuSans;
1171−font\-style: italic;
1172−font\-weight: normal;
1173−src:url(\[dq]DejaVuSans\-Oblique.ttf\[dq]);
1245+\[at]font-face {
1246+font-family: DejaVuSans;
1247+font-style: italic;
1248+font-weight: normal;
1249+src:url(\[dq]DejaVuSans-Oblique.ttf\[dq]);
11741250}
1175−\[at]font\-face {
1176−font\-family: DejaVuSans;
1177−font\-style: italic;
1178−font\-weight: bold;
1179−src:url(\[dq]DejaVuSans\-BoldOblique.ttf\[dq]);
1251+\[at]font-face {
1252+font-family: DejaVuSans;
1253+font-style: italic;
1254+font-weight: bold;
1255+src:url(\[dq]DejaVuSans-BoldOblique.ttf\[dq]);
11801256}
1181−body { font\-family: \[dq]DejaVuSans\[dq]; }
1257+body { font-family: \[dq]DejaVuSans\[dq]; }
11821258\f[R]
11831259.fi
11841260.RE
11851261.TP
1186−.B \f[C]\-\-epub\-chapter\-level=\f[R]\f[I]NUMBER\f[R]
1262+.B \f[C]--epub-chapter-level=\f[R]\f[I]NUMBER\f[R]
11871263Specify the header level at which to split the EPUB into separate
11881264\[dq]chapter\[dq] files.
11891265The default is to split into chapters at level 1 headers.
@@ -1193,61 +1269,61 @@ Some readers may be slow if the chapter files are too large, so for
11931269large documents with few level 1 headers, one might want to use a
11941270chapter level of 2 or 3.
11951271.TP
1196−.B \f[C]\-\-epub\-subdirectory=\f[R]\f[I]DIRNAME\f[R]
1272+.B \f[C]--epub-subdirectory=\f[R]\f[I]DIRNAME\f[R]
11971273Specify the subdirectory in the OCF container that is to hold the
1198−EPUB\-specific contents.
1274+EPUB-specific contents.
11991275The default is \f[C]EPUB\f[R].
12001276To put the EPUB contents in the top level, use an empty string.
12011277.TP
1202−.B \f[C]\-\-pdf\-engine=pdflatex\f[R]|\f[C]lualatex\f[R]|\f[C]xelatex\f[R]|\f[C]wkhtmltopdf\f[R]|\f[C]weasyprint\f[R]|\f[C]prince\f[R]|\f[C]context\f[R]|\f[C]pdfroff\f[R]
1278+.B \f[C]--pdf-engine=pdflatex\f[R]|\f[C]lualatex\f[R]|\f[C]xelatex\f[R]|\f[C]wkhtmltopdf\f[R]|\f[C]weasyprint\f[R]|\f[C]prince\f[R]|\f[C]context\f[R]|\f[C]pdfroff\f[R]
12031279Use the specified engine when producing PDF output.
12041280The default is \f[C]pdflatex\f[R].
12051281If the engine is not in your PATH, the full path of the engine may be
12061282specified here.
12071283.TP
1208−.B \f[C]\-\-pdf\-engine\-opt=\f[R]\f[I]STRING\f[R]
1209−Use the given string as a command\-line argument to the
1210−\f[C]pdf\-engine\f[R].
1284+.B \f[C]--pdf-engine-opt=\f[R]\f[I]STRING\f[R]
1285+Use the given string as a command-line argument to the
1286+\f[C]pdf-engine\f[R].
12111287If used multiple times, the arguments are provided with spaces between
12121288them.
12131289Note that no check for duplicate options is done.
12141290.SS Citation rendering
12151291.TP
1216−.B \f[C]\-\-bibliography=\f[R]\f[I]FILE\f[R]
1292+.B \f[C]--bibliography=\f[R]\f[I]FILE\f[R]
12171293Set the \f[C]bibliography\f[R] field in the document\[aq]s metadata to
12181294\f[I]FILE\f[R], overriding any value set in the metadata, and process
1219−citations using \f[C]pandoc\-citeproc\f[R].
1295+citations using \f[C]pandoc-citeproc\f[R].
12201296(This is equivalent to
1221−\f[C]\-\-metadata bibliography=FILE \-\-filter pandoc\-citeproc\f[R].)
1222−If \f[C]\-\-natbib\f[R] or \f[C]\-\-biblatex\f[R] is also supplied,
1223−\f[C]pandoc\-citeproc\f[R] is not used, making this equivalent to
1224−\f[C]\-\-metadata bibliography=FILE\f[R].
1297+\f[C]--metadata bibliography=FILE --filter pandoc-citeproc\f[R].) If
1298+\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] is also supplied,
1299+\f[C]pandoc-citeproc\f[R] is not used, making this equivalent to
1300+\f[C]--metadata bibliography=FILE\f[R].
12251301If you supply this argument multiple times, each \f[I]FILE\f[R] will be
12261302added to bibliography.
12271303.TP
1228−.B \f[C]\-\-csl=\f[R]\f[I]FILE\f[R]
1304+.B \f[C]--csl=\f[R]\f[I]FILE\f[R]
12291305Set the \f[C]csl\f[R] field in the document\[aq]s metadata to
12301306\f[I]FILE\f[R], overriding any value set in the metadata.
1231−(This is equivalent to \f[C]\-\-metadata csl=FILE\f[R].) This option is
1232−only relevant with \f[C]pandoc\-citeproc\f[R].
1307+(This is equivalent to \f[C]--metadata csl=FILE\f[R].) This option is
1308+only relevant with \f[C]pandoc-citeproc\f[R].
12331309.TP
1234−.B \f[C]\-\-citation\-abbreviations=\f[R]\f[I]FILE\f[R]
1235−Set the \f[C]citation\-abbreviations\f[R] field in the document\[aq]s
1310+.B \f[C]--citation-abbreviations=\f[R]\f[I]FILE\f[R]
1311+Set the \f[C]citation-abbreviations\f[R] field in the document\[aq]s
12361312metadata to \f[I]FILE\f[R], overriding any value set in the metadata.
12371313(This is equivalent to
1238−\f[C]\-\-metadata citation\-abbreviations=FILE\f[R].) This option is
1239−only relevant with \f[C]pandoc\-citeproc\f[R].
1314+\f[C]--metadata citation-abbreviations=FILE\f[R].) This option is only
1315+relevant with \f[C]pandoc-citeproc\f[R].
12401316.TP
1241−.B \f[C]\-\-natbib\f[R]
1317+.B \f[C]--natbib\f[R]
12421318Use \f[C]natbib\f[R] for citations in LaTeX output.
1243−This option is not for use with the \f[C]pandoc\-citeproc\f[R] filter or
1319+This option is not for use with the \f[C]pandoc-citeproc\f[R] filter or
12441320with PDF output.
12451321It is intended for use in producing a LaTeX file that can be processed
12461322with \f[C]bibtex\f[R].
12471323.TP
1248−.B \f[C]\-\-biblatex\f[R]
1324+.B \f[C]--biblatex\f[R]
12491325Use \f[C]biblatex\f[R] for citations in LaTeX output.
1250−This option is not for use with the \f[C]pandoc\-citeproc\f[R] filter or
1326+This option is not for use with the \f[C]pandoc-citeproc\f[R] filter or
12511327with PDF output.
12521328It is intended for use in producing a LaTeX file that can be processed
12531329with \f[C]bibtex\f[R] or \f[C]biber\f[R].
@@ -1259,10 +1335,10 @@ Formulas are put inside a \f[C]span\f[R] with
12591335\f[C]class=\[dq]math\[dq]\f[R], so that they may be styled differently
12601336from the surrounding text if needed.
12611337However, this gives acceptable results only for basic math, usually you
1262−will want to use \f[C]\-\-mathjax\f[R] or another of the following
1338+will want to use \f[C]--mathjax\f[R] or another of the following
12631339options.
12641340.TP
1265−.B \f[C]\-\-mathjax\f[R][\f[C]=\f[R]\f[I]URL\f[R]]
1341+.B \f[C]--mathjax\f[R][\f[C]=\f[R]\f[I]URL\f[R]]
12661342Use MathJax to display embedded TeX math in HTML output.
12671343TeX math will be put between \f[C]\[rs](...\[rs])\f[R] (for inline math)
12681344or \f[C]\[rs][...\[rs]]\f[R] (for display math) and wrapped in
@@ -1272,27 +1348,27 @@ The \f[I]URL\f[R] should point to the \f[C]MathJax.js\f[R] load script.
12721348If a \f[I]URL\f[R] is not provided, a link to the Cloudflare CDN will be
12731349inserted.
12741350.TP
1275−.B \f[C]\-\-mathml\f[R]
1351+.B \f[C]--mathml\f[R]
12761352Convert TeX math to MathML (in \f[C]epub3\f[R], \f[C]docbook4\f[R],
12771353\f[C]docbook5\f[R], \f[C]jats\f[R], \f[C]html4\f[R] and
12781354\f[C]html5\f[R]).
12791355This is the default in \f[C]odt\f[R] output.
1280−Note that currently only Firefox and Safari (and select e\-book readers)
1356+Note that currently only Firefox and Safari (and select e-book readers)
12811357natively support MathML.
12821358.TP
1283−.B \f[C]\-\-webtex\f[R][\f[C]=\f[R]\f[I]URL\f[R]]
1359+.B \f[C]--webtex\f[R][\f[C]=\f[R]\f[I]URL\f[R]]
12841360Convert TeX formulas to \f[C]<img>\f[R] tags that link to an external
12851361script that converts formulas to images.
1286−The formula will be URL\-encoded and concatenated with the URL provided.
1362+The formula will be URL-encoded and concatenated with the URL provided.
12871363For SVG images you can for example use
1288−\f[C]\-\-webtex https://latex.codecogs.com/svg.latex?\f[R].
1364+\f[C]--webtex https://latex.codecogs.com/svg.latex?\f[R].
12891365If no URL is specified, the CodeCogs URL generating PNGs will be used
12901366(\f[C]https://latex.codecogs.com/png.latex?\f[R]).
1291−Note: the \f[C]\-\-webtex\f[R] option will affect Markdown output as
1292−well as HTML, which is useful if you\[aq]re targeting a version of
1293−Markdown without native math support.
1367+Note: the \f[C]--webtex\f[R] option will affect Markdown output as well
1368+as HTML, which is useful if you\[aq]re targeting a version of Markdown
1369+without native math support.
12941370.TP
1295−.B \f[C]\-\-katex\f[R][\f[C]=\f[R]\f[I]URL\f[R]]
1371+.B \f[C]--katex\f[R][\f[C]=\f[R]\f[I]URL\f[R]]
12961372Use KaTeX to display embedded TeX math in HTML output.
12971373The \f[I]URL\f[R] is the base URL for the KaTeX library.
12981374That directory should contain a \f[C]katex.min.js\f[R] and a
@@ -1300,7 +1376,7 @@ That directory should contain a \f[C]katex.min.js\f[R] and a
13001376If a \f[I]URL\f[R] is not provided, a link to the KaTeX CDN will be
13011377inserted.
13021378.TP
1303−.B \f[C]\-\-gladtex\f[R]
1379+.B \f[C]--gladtex\f[R]
13041380Enclose TeX math in \f[C]<eq>\f[R] tags in HTML output.
13051381The resulting HTML can then be processed by GladTeX to produce images of
13061382the typeset formulas and an HTML file with links to these images.
@@ -1309,36 +1385,36 @@ So, the procedure is:
13091385.IP
13101386.nf
13111387\f[C]
1312−pandoc \-s \-\-gladtex input.md \-o myfile.htex
1313−gladtex \-d myfile\-images myfile.htex
1314−# produces myfile.html and images in myfile\-images
1388+pandoc -s --gladtex input.md -o myfile.htex
1389+gladtex -d myfile-images myfile.htex
1390+# produces myfile.html and images in myfile-images
13151391\f[R]
13161392.fi
13171393.RE
13181394.SS Options for wrapper scripts
13191395.TP
1320−.B \f[C]\-\-dump\-args\f[R]
1321−Print information about command\-line arguments to \f[I]stdout\f[R],
1322−then exit.
1396+.B \f[C]--dump-args\f[R]
1397+Print information about command-line arguments to \f[I]stdout\f[R], then
1398+exit.
13231399This option is intended primarily for use in wrapper scripts.
13241400The first line of output contains the name of the output file specified
1325−with the \f[C]\-o\f[R] option, or \f[C]\-\f[R] (for \f[I]stdout\f[R]) if
1401+with the \f[C]-o\f[R] option, or \f[C]-\f[R] (for \f[I]stdout\f[R]) if
13261402no output file was specified.
1327−The remaining lines contain the command\-line arguments, one per line,
1328−in the order they appear.
1403+The remaining lines contain the command-line arguments, one per line, in
1404+the order they appear.
13291405These do not include regular pandoc options and their arguments, but do
1330−include any options appearing after a \f[C]\-\-\f[R] separator at the
1331−end of the line.
1406+include any options appearing after a \f[C]--\f[R] separator at the end
1407+of the line.
13321408.TP
1333−.B \f[C]\-\-ignore\-args\f[R]
1334−Ignore command\-line arguments (for use in wrapper scripts).
1409+.B \f[C]--ignore-args\f[R]
1410+Ignore command-line arguments (for use in wrapper scripts).
13351411Regular pandoc options are not ignored.
13361412Thus, for example,
13371413.RS
13381414.IP
13391415.nf
13401416\f[C]
1341−pandoc \-\-ignore\-args \-o foo.html \-s foo.txt \-\- \-e latin1
1417+pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
13421418\f[R]
13431419.fi
13441420.PP
@@ -1346,30 +1422,30 @@ is equivalent to
13461422.IP
13471423.nf
13481424\f[C]
1349−pandoc \-o foo.html \-s
1425+pandoc -o foo.html -s
13501426\f[R]
13511427.fi
13521428.RE
13531429.SH TEMPLATES
13541430.PP
1355−When the \f[C]\-s/\-\-standalone\f[R] option is used, pandoc uses a
1431+When the \f[C]-s/--standalone\f[R] option is used, pandoc uses a
13561432template to add header and footer material that is needed for a
1357−self\-standing document.
1433+self-standing document.
13581434To see the default template that is used, just type
13591435.IP
13601436.nf
13611437\f[C]
1362−pandoc \-D *FORMAT*
1438+pandoc -D *FORMAT*
13631439\f[R]
13641440.fi
13651441.PP
13661442where \f[I]FORMAT\f[R] is the name of the output format.
1367−A custom template can be specified using the \f[C]\-\-template\f[R]
1443+A custom template can be specified using the \f[C]--template\f[R]
13681444option.
13691445You can also override the system default templates for a given output
13701446format \f[I]FORMAT\f[R] by putting a file
13711447\f[C]templates/default.*FORMAT*\f[R] in the user data directory (see
1372−\f[C]\-\-data\-dir\f[R], above).
1448+\f[C]--data-dir\f[R], above).
13731449\f[I]Exceptions:\f[R]
13741450.IP \[bu] 2
13751451For \f[C]odt\f[R] output, customize the \f[C]default.opendocument\f[R]
@@ -1377,48 +1453,21 @@ template.
13771453.IP \[bu] 2
13781454For \f[C]pdf\f[R] output, customize the \f[C]default.latex\f[R] template
13791455(or the \f[C]default.context\f[R] template, if you use
1380−\f[C]\-t context\f[R], or the \f[C]default.ms\f[R] template, if you use
1381−\f[C]\-t ms\f[R], or the \f[C]default.html\f[R] template, if you use
1382−\f[C]\-t html\f[R]).
1456+\f[C]-t context\f[R], or the \f[C]default.ms\f[R] template, if you use
1457+\f[C]-t ms\f[R], or the \f[C]default.html\f[R] template, if you use
1458+\f[C]-t html\f[R]).
13831459.IP \[bu] 2
1384−\f[C]docx\f[R] has no template (however, you can use
1385−\f[C]\-\-reference\-doc\f[R] to customize the output).
1460+\f[C]docx\f[R] and \f[C]pptx\f[R] have no template (however, you can use
1461+\f[C]--reference-doc\f[R] to customize the output).
13861462.PP
13871463Templates contain \f[I]variables\f[R], which allow for the inclusion of
13881464arbitrary information at any point in the file.
1389−They may be set at the command line using the \f[C]\-V/\-\-variable\f[R]
1465+They may be set at the command line using the \f[C]-V/--variable\f[R]
13901466option.
13911467If a variable is not set, pandoc will look for the key in the
13921468document\[aq]s metadata \[en] which can be set using either YAML
1393−metadata blocks or with the \f[C]\-\-metadata\f[R] option.
1394−.SS Variables set by pandoc
1395−.PP
1396−Some variables are set automatically by pandoc.
1397−These vary somewhat depending on the output format, but include the
1398−following:
1399−.TP
1400−.B \f[C]sourcefile\f[R], \f[C]outputfile\f[R]
1401−source and destination filenames, as given on the command line.
1402−\f[C]sourcefile\f[R] can also be a list if input comes from multiple
1403−files, or empty if input is from stdin.
1404−You can use the following snippet in your template to distinguish them:
1405−.RS
1406−.IP
1407−.nf
1408−\f[C]
1409−$if(sourcefile)$
1410−$for(sourcefile)$
1411−$sourcefile$
1412−$endfor$
1413−$else$
1414−(stdin)
1415−$endif$
1416−\f[R]
1417−.fi
1418−.PP
1419−Similarly, \f[C]outputfile\f[R] can be \f[C]\-\f[R] if output goes to
1420−the terminal.
1421−.RE
1469+metadata blocks or with the \f[C]-M/--metadata\f[R] option.
1470+.SS Metadata variables
14221471.TP
14231472.B \f[C]title\f[R], \f[C]author\f[R], \f[C]date\f[R]
14241473allow identification of basic aspects of the document.
@@ -1429,81 +1478,96 @@ authors, or through a YAML metadata block:
14291478.IP
14301479.nf
14311480\f[C]
1432−\-\-\-
1481+---
14331482author:
1434−\- Aristotle
1435−\- Peter Abelard
1483+- Aristotle
1484+- Peter Abelard
14361485\&...
14371486\f[R]
14381487.fi
14391488.RE
14401489.TP
14411490.B \f[C]subtitle\f[R]
1442−document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and Word
1443−docx; renders in LaTeX only when using a document class that supports
1444−\f[C]\[rs]subtitle\f[R], such as \f[C]beamer\f[R] or the KOMA\-Script
1445−series (\f[C]scrartcl\f[R], \f[C]scrreprt\f[R], \f[C]scrbook\f[R]).
1446−.TP
1447−.B \f[C]institute\f[R]
1448−author affiliations (in LaTeX and Beamer only).
1449−Can be a list, when there are multiple authors.
1491+document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx
1492+documents
14501493.TP
14511494.B \f[C]abstract\f[R]
1452−document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word docx
1495+document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx
1496+documents
14531497.TP
14541498.B \f[C]keywords\f[R]
1455−list of keywords to be included in HTML, PDF, and AsciiDoc metadata; may
1456−be repeated as for \f[C]author\f[R], above
1457−.TP
1458−.B \f[C]header\-includes\f[R]
1459−contents specified by \f[C]\-H/\-\-include\-in\-header\f[R] (may have
1460−multiple values)
1461−.TP
1462−.B \f[C]toc\f[R]
1463−non\-null value if \f[C]\-\-toc/\-\-table\-of\-contents\f[R] was
1464−specified
1465−.TP
1466−.B \f[C]toc\-title\f[R]
1467−title of table of contents (works only with EPUB, opendocument, odt,
1468−docx, pptx, beamer, LaTeX)
1499+list of keywords to be included in HTML, PDF, ODT, pptx, docx and
1500+AsciiDoc metadata; repeat as for \f[C]author\f[R], above
14691501.TP
1470−.B \f[C]include\-before\f[R]
1471−contents specified by \f[C]\-B/\-\-include\-before\-body\f[R] (may have
1472−multiple values)
1473−.TP
1474−.B \f[C]include\-after\f[R]
1475−contents specified by \f[C]\-A/\-\-include\-after\-body\f[R] (may have
1476−multiple values)
1502+.B \f[C]subject\f[R]
1503+document subject, included in ODT, docx and pptx metadata
14771504.TP
1478−.B \f[C]body\f[R]
1479−body of document
1505+.B \f[C]description\f[R]
1506+document description, included in ODT, docx and pptx metadata.
1507+Some applications show this as \f[C]Comments\f[R] metadata.
14801508.TP
1481−.B \f[C]meta\-json\f[R]
1482−JSON representation of all of the document\[aq]s metadata.
1483−Field values are transformed to the selected output format.
1509+.B \f[C]category\f[R]
1510+document category, included in docx and pptx metadata
1511+.PP
1512+Additionally, any root-level string metadata, not included in ODT, docx
1513+or pptx metadata is added as a \f[I]custom property\f[R].
1514+The following YAML metadata block for instance:
1515+.IP
1516+.nf
1517+\f[C]
1518+---
1519+title: \[aq]This is the title\[aq]
1520+subtitle: \[dq]This is the subtitle\[dq]
1521+author:
1522+- Author One
1523+- Author Two
1524+description: |
1525+ This is a long
1526+ description.
1527+
1528+ It consists of two paragraphs
1529+\&...
1530+\f[R]
1531+.fi
1532+.PP
1533+will include \f[C]title\f[R], \f[C]author\f[R] and \f[C]description\f[R]
1534+as standard document properties and \f[C]subtitle\f[R] as a custom
1535+property when converting to docx, ODT or pptx.
14841536.SS Language variables
14851537.TP
14861538.B \f[C]lang\f[R]
1487−identifies the main language of the document, using a code according to
1488−BCP 47 (e.g.
1489−\f[C]en\f[R] or \f[C]en\-GB\f[R]).
1490−For some output formats, pandoc will convert it to an appropriate format
1491−stored in the additional variables \f[C]babel\-lang\f[R],
1492−\f[C]polyglossia\-lang\f[R] (LaTeX) and \f[C]context\-lang\f[R]
1493−(ConTeXt).
1539+identifies the main language of the document using IETF language tags
1540+(following the BCP 47 standard), such as \f[C]en\f[R] or
1541+\f[C]en-GB\f[R].
1542+The Language subtag lookup tool can look up or verify these tags.
1543+This affects most formats, and controls hyphenation in PDF output when
1544+using LaTeX (through \f[C]babel\f[R] and \f[C]polyglossia\f[R]) or
1545+ConTeXt.
14941546.RS
14951547.PP
1496−Native pandoc Spans and Divs with the lang attribute (value in BCP 47)
1497−can be used to switch the language in that range.
1498−In LaTeX output, \f[C]babel\-otherlangs\f[R] and
1499−\f[C]polyglossia\-otherlangs\f[R] variables will be generated
1500−automatically based on the \f[C]lang\f[R] attributes of Spans and Divs
1501−in the document.
1548+Use native pandoc Divs and Spans with the \f[C]lang\f[R] attribute to
1549+switch the language:
1550+.IP
1551+.nf
1552+\f[C]
1553+---
1554+lang: en-GB
1555+\&...
1556+
1557+Text in the main document language (British English).
1558+
1559+::: {lang=fr-CA}
1560+> Cette citation est \['e]crite en fran\[,c]ais canadien.
1561+:::
1562+
1563+More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de}
1564+\f[R]
1565+.fi
15021566.RE
15031567.TP
15041568.B \f[C]dir\f[R]
1505−the base direction of the document, either \f[C]rtl\f[R]
1506−(right\-to\-left) or \f[C]ltr\f[R] (left\-to\-right).
1569+the base script direction, either \f[C]rtl\f[R] (right-to-left) or
1570+\f[C]ltr\f[R] (left-to-right).
15071571.RS
15081572.PP
15091573For bidirectional documents, native pandoc \f[C]span\f[R]s and
@@ -1515,123 +1579,178 @@ the browser, when generating HTML) supports the Unicode Bidirectional
15151579Algorithm.
15161580.PP
15171581When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[R]
1518−engine is fully supported (use \f[C]\-\-pdf\-engine=xelatex\f[R]).
1582+engine is fully supported (use \f[C]--pdf-engine=xelatex\f[R]).
15191583.RE
1520−.SS Variables for slides
1584+.SS Variables for HTML slides
15211585.PP
1522−Variables are available for producing slide shows with pandoc, including
1523−all reveal.js configuration options.
1586+These affect HTML output when producing slide shows with pandoc.
1587+All reveal.js configuration options are available as variables.
15241588.TP
1525−.B \f[C]titlegraphic\f[R]
1526−title graphic for Beamer documents
1589+.B \f[C]revealjs-url\f[R]
1590+base URL for reveal.js documents (defaults to \f[C]reveal.js\f[R])
15271591.TP
1528−.B \f[C]logo\f[R]
1529−logo for Beamer documents
1592+.B \f[C]s5-url\f[R]
1593+base URL for S5 documents (defaults to \f[C]s5/default\f[R])
15301594.TP
1531−.B \f[C]slidy\-url\f[R]
1595+.B \f[C]slidy-url\f[R]
15321596base URL for Slidy documents (defaults to
15331597\f[C]https://www.w3.org/Talks/Tools/Slidy2\f[R])
15341598.TP
1535−.B \f[C]slideous\-url\f[R]
1599+.B \f[C]slideous-url\f[R]
15361600base URL for Slideous documents (defaults to \f[C]slideous\f[R])
1601+.SS Variables for Beamer slides
1602+.PP
1603+These variables change the appearance of PDF slides using
1604+\f[C]beamer\f[R].
15371605.TP
1538−.B \f[C]s5\-url\f[R]
1539−base URL for S5 documents (defaults to \f[C]s5/default\f[R])
1606+.B \f[C]aspectratio\f[R]
1607+slide aspect ratio (\f[C]43\f[R] for 4:3 [default], \f[C]169\f[R] for
1608+16:9, \f[C]1610\f[R] for 16:10, \f[C]149\f[R] for 14:9, \f[C]141\f[R]
1609+for 1.41:1, \f[C]54\f[R] for 5:4, \f[C]32\f[R] for 3:2)
15401610.TP
1541−.B \f[C]revealjs\-url\f[R]
1542−base URL for reveal.js documents (defaults to \f[C]reveal.js\f[R])
1611+.B \f[C]beamerarticle\f[R]
1612+produce an article from Beamer slides
15431613.TP
1544−.B \f[C]theme\f[R], \f[C]colortheme\f[R], \f[C]fonttheme\f[R], \f[C]innertheme\f[R], \f[C]outertheme\f[R]
1545−themes for LaTeX \f[C]beamer\f[R] documents
1614+.B \f[C]beameroption\f[R]
1615+add extra beamer option with \f[C]\[rs]setbeameroption{}\f[R]
15461616.TP
1547−.B \f[C]themeoptions\f[R]
1548−options for LaTeX beamer themes (a list).
1617+.B \f[C]institute\f[R]
1618+author affiliations: can be a list when there are multiple authors
1619+.TP
1620+.B \f[C]logo\f[R]
1621+logo image for slides
15491622.TP
15501623.B \f[C]navigation\f[R]
1551−controls navigation symbols in \f[C]beamer\f[R] documents (default is
1552−\f[C]empty\f[R] for no navigation symbols; other valid values are
1553−\f[C]frame\f[R], \f[C]vertical\f[R], and \f[C]horizontal\f[R]).
1624+controls navigation symbols (default is \f[C]empty\f[R] for no
1625+navigation symbols; other valid values are \f[C]frame\f[R],
1626+\f[C]vertical\f[R], and \f[C]horizontal\f[R])
15541627.TP
1555−.B \f[C]section\-titles\f[R]
1556−enables on \[dq]title pages\[dq] for new sections in \f[C]beamer\f[R]
1557−documents (default = true).
1628+.B \f[C]section-titles\f[R]
1629+enables \[dq]title pages\[dq] for new sections (default is true)
15581630.TP
1559−.B \f[C]beamerarticle\f[R]
1560−when true, the \f[C]beamerarticle\f[R] package is loaded (for producing
1561−an article from beamer slides).
1631+.B \f[C]theme\f[R], \f[C]colortheme\f[R], \f[C]fonttheme\f[R], \f[C]innertheme\f[R], \f[C]outertheme\f[R]
1632+beamer themes:
15621633.TP
1563−.B \f[C]aspectratio\f[R]
1564−aspect ratio of slides (for beamer only, \f[C]1610\f[R] for 16:10,
1565−\f[C]169\f[R] for 16:9, \f[C]149\f[R] for 14:9, \f[C]141\f[R] for
1566−1.41:1, \f[C]54\f[R] for 5:4, \f[C]43\f[R] for 4:3 which is the default,
1567−and \f[C]32\f[R] for 3:2).
1634+.B \f[C]themeoptions\f[R]
1635+options for LaTeX beamer themes (a list).
1636+.TP
1637+.B \f[C]titlegraphic\f[R]
1638+image for title slide
15681639.SS Variables for LaTeX
15691640.PP
1570−LaTeX variables are used when creating a PDF.
1571−.TP
1572−.B \f[C]papersize\f[R]
1573−paper size, e.g.
1574−\f[C]letter\f[R], \f[C]a4\f[R]
1575−.TP
1576−.B \f[C]fontsize\f[R]
1577−font size for body text (e.g.
1578−\f[C]10pt\f[R], \f[C]12pt\f[R])
1579−.TP
1580−.B \f[C]documentclass\f[R]
1581−document class, e.g.
1582−\f[C]article\f[R], \f[C]report\f[R], \f[C]book\f[R], \f[C]memoir\f[R]
1641+Pandoc uses these variables when creating a PDF with a LaTeX engine.
1642+.SS Layout
15831643.TP
15841644.B \f[C]classoption\f[R]
15851645option for document class, e.g.
1586−\f[C]oneside\f[R]; may be repeated for multiple options
1646+\f[C]oneside\f[R]; repeat for multiple options
15871647.TP
1588−.B \f[C]beameroption\f[R]
1589−In beamer, add extra beamer option with \f[C]\[rs]setbeameroption{}\f[R]
1648+.B \f[C]documentclass\f[R]
1649+document class: usually one of the standard classes, \f[C]article\f[R],
1650+\f[C]report\f[R], and \f[C]book\f[R]; the KOMA-Script equivalents,
1651+\f[C]scrartcl\f[R], \f[C]scrreprt\f[R], and \f[C]scrbook\f[R], which
1652+default to smaller margins; or \f[C]memoir\f[R]
15901653.TP
15911654.B \f[C]geometry\f[R]
15921655option for \f[C]geometry\f[R] package, e.g.
1593−\f[C]margin=1in\f[R]; may be repeated for multiple options
1656+\f[C]margin=1in\f[R]; repeat for multiple options
15941657.TP
1595−.B \f[C]margin\-left\f[R], \f[C]margin\-right\f[R], \f[C]margin\-top\f[R], \f[C]margin\-bottom\f[R]
1596−sets margins, if \f[C]geometry\f[R] is not used (otherwise
1597−\f[C]geometry\f[R] overrides these)
1658+.B \f[C]indent\f[R]
1659+uses document class settings for indentation (the default LaTeX template
1660+otherwise removes indentation and adds space between paragraphs)
15981661.TP
15991662.B \f[C]linestretch\f[R]
16001663adjusts line spacing using the \f[C]setspace\f[R] package, e.g.
16011664\f[C]1.25\f[R], \f[C]1.5\f[R]
16021665.TP
1666+.B \f[C]margin-left\f[R], \f[C]margin-right\f[R], \f[C]margin-top\f[R], \f[C]margin-bottom\f[R]
1667+sets margins if \f[C]geometry\f[R] is not used (otherwise
1668+\f[C]geometry\f[R] overrides these)
1669+.TP
1670+.B \f[C]pagestyle\f[R]
1671+control \f[C]\[rs]pagestyle{}\f[R]: the default article class supports
1672+\f[C]plain\f[R] (default), \f[C]empty\f[R] (no running heads or page
1673+numbers), and \f[C]headings\f[R] (section titles in running heads)
1674+.TP
1675+.B \f[C]papersize\f[R]
1676+paper size, e.g.
1677+\f[C]letter\f[R], \f[C]a4\f[R]
1678+.TP
1679+.B \f[C]secnumdepth\f[R]
1680+numbering depth for sections (with \f[C]--number-sections\f[R] option or
1681+\f[C]numbersections\f[R] variable)
1682+.TP
1683+.B \f[C]subparagraph\f[R]
1684+disables default behavior of LaTeX template that redefines
1685+(sub)paragraphs as sections, changing the appearance of nested headings
1686+in some classes
1687+.SS Fonts
1688+.TP
1689+.B \f[C]fontenc\f[R]
1690+allows font encoding to be specified through \f[C]fontenc\f[R] package
1691+(with \f[C]pdflatex\f[R]); default is \f[C]T1\f[R] (see LaTeX font
1692+encodings guide)
1693+.TP
16031694.B \f[C]fontfamily\f[R]
16041695font package for use with \f[C]pdflatex\f[R]: TeX Live includes many
16051696options, documented in the LaTeX Font Catalogue.
16061697The default is Latin Modern.
16071698.TP
16081699.B \f[C]fontfamilyoptions\f[R]
1609−options for package used as \f[C]fontfamily\f[R]: e.g.
1610−\f[C]osf,sc\f[R] with \f[C]fontfamily\f[R] set to \f[C]mathpazo\f[R]
1611−provides Palatino with old\-style figures and true small caps; may be
1612−repeated for multiple options
1700+options for package used as \f[C]fontfamily\f[R]; repeat for multiple
1701+options.
1702+For example, to use the Libertine font with proportional lowercase
1703+(old-style) figures through the \f[C]libertinus\f[R] package:
1704+.RS
1705+.IP
1706+.nf
1707+\f[C]
1708+---
1709+fontfamily: libertinus
1710+fontfamilyoptions:
1711+- osf
1712+- p
1713+\&...
1714+\f[R]
1715+.fi
1716+.RE
16131717.TP
1614−.B \f[C]mainfont\f[R], \f[C]romanfont\f[R], \f[C]sansfont\f[R], \f[C]monofont\f[R], \f[C]mathfont\f[R], \f[C]CJKmainfont\f[R]
1718+.B \f[C]fontsize\f[R]
1719+font size for body text.
1720+The standard classes allow 10pt, 11pt, and 12pt.
1721+To use another size, set \f[C]documentclass\f[R] to one of the
1722+KOMA-Script classes, such as \f[C]scrartcl\f[R] or \f[C]scrbook\f[R].
1723+.TP
1724+.B \f[C]mainfont\f[R], \f[C]sansfont\f[R], \f[C]monofont\f[R], \f[C]mathfont\f[R], \f[C]CJKmainfont\f[R]
16151725font families for use with \f[C]xelatex\f[R] or \f[C]lualatex\f[R]: take
16161726the name of any system font, using the \f[C]fontspec\f[R] package.
1617−Note that if \f[C]CJKmainfont\f[R] is used, the \f[C]xecjk\f[R] package
1618−must be available.
1727+\f[C]CJKmainfont\f[R] uses the \f[C]xecjk\f[R] package.
16191728.TP
1620−.B \f[C]mainfontoptions\f[R], \f[C]romanfontoptions\f[R], \f[C]sansfontoptions\f[R], \f[C]monofontoptions\f[R], \f[C]mathfontoptions\f[R], \f[C]CJKoptions\f[R]
1729+.B \f[C]mainfontoptions\f[R], \f[C]sansfontoptions\f[R], \f[C]monofontoptions\f[R], \f[C]mathfontoptions\f[R], \f[C]CJKoptions\f[R]
16211730options to use with \f[C]mainfont\f[R], \f[C]sansfont\f[R],
16221731\f[C]monofont\f[R], \f[C]mathfont\f[R], \f[C]CJKmainfont\f[R] in
16231732\f[C]xelatex\f[R] and \f[C]lualatex\f[R].
1624−Allow for any choices available through \f[C]fontspec\f[R], such as the
1625−OpenType features \f[C]Numbers=OldStyle,Numbers=Proportional\f[R].
1626−May be repeated for multiple options.
1627−.TP
1628−.B \f[C]fontenc\f[R]
1629−allows font encoding to be specified through \f[C]fontenc\f[R] package
1630−(with \f[C]pdflatex\f[R]); default is \f[C]T1\f[R] (see guide to LaTeX
1631−font encodings)
1733+Allow for any choices available through \f[C]fontspec\f[R]; repeat for
1734+multiple options.
1735+For example, to use the TeX Gyre version of Palatino with lowercase
1736+figures:
1737+.RS
1738+.IP
1739+.nf
1740+\f[C]
1741+---
1742+mainfont: TeX Gyre Pagella
1743+mainfontoptions:
1744+- Numbers=Lowercase
1745+- Numbers=Proportional
1746+\&...
1747+\f[R]
1748+.fi
1749+.RE
16321750.TP
16331751.B \f[C]microtypeoptions\f[R]
16341752options to pass to the microtype package
1753+.SS Links
16351754.TP
16361755.B \f[C]colorlinks\f[R]
16371756add color to link text; automatically enabled if any of
@@ -1644,78 +1763,67 @@ and links in table of contents, respectively: uses options allowed by
16441763\f[C]xcolor\f[R], including the \f[C]dvipsnames\f[R],
16451764\f[C]svgnames\f[R], and \f[C]x11names\f[R] lists
16461765.TP
1647−.B \f[C]links\-as\-notes\f[R]
1766+.B \f[C]links-as-notes\f[R]
16481767causes links to be printed as footnotes
1768+.SS Front matter
16491769.TP
1650−.B \f[C]indent\f[R]
1651−uses document class settings for indentation (the default LaTeX template
1652−otherwise removes indentation and adds space between paragraphs)
1653−.TP
1654−.B \f[C]subparagraph\f[R]
1655−disables default behavior of LaTeX template that redefines
1656−(sub)paragraphs as sections, changing the appearance of nested headings
1657−in some classes
1770+.B \f[C]lof\f[R], \f[C]lot\f[R]
1771+include list of figures, list of tables
16581772.TP
16591773.B \f[C]thanks\f[R]
1660−specifies contents of acknowledgments footnote after document title.
1774+contents of acknowledgments footnote after document title
16611775.TP
16621776.B \f[C]toc\f[R]
16631777include table of contents (can also be set using
1664−\f[C]\-\-toc/\-\-table\-of\-contents\f[R])
1778+\f[C]--toc/--table-of-contents\f[R])
16651779.TP
1666−.B \f[C]toc\-depth\f[R]
1780+.B \f[C]toc-depth\f[R]
16671781level of section to include in table of contents
1782+.SS BibLaTeX Bibliographies
1783+.PP
1784+These variables function when using BibLaTeX for citation rendering.
16681785.TP
1669−.B \f[C]secnumdepth\f[R]
1670−numbering depth for sections, if sections are numbered
1786+.B \f[C]biblatexoptions\f[R]
1787+list of options for biblatex
16711788.TP
1672−.B \f[C]lof\f[R], \f[C]lot\f[R]
1673−include list of figures, list of tables
1789+.B \f[C]biblio-style\f[R]
1790+bibliography style, when used with \f[C]--natbib\f[R] and
1791+\f[C]--biblatex\f[R].
1792+.TP
1793+.B \f[C]biblio-title\f[R]
1794+bibliography title, when used with \f[C]--natbib\f[R] and
1795+\f[C]--biblatex\f[R].
16741796.TP
16751797.B \f[C]bibliography\f[R]
16761798bibliography to use for resolving references
16771799.TP
1678−.B \f[C]biblio\-style\f[R]
1679−bibliography style, when used with \f[C]\-\-natbib\f[R] and
1680−\f[C]\-\-biblatex\f[R].
1681−.TP
1682−.B \f[C]biblio\-title\f[R]
1683−bibliography title, when used with \f[C]\-\-natbib\f[R] and
1684−\f[C]\-\-biblatex\f[R].
1685−.TP
1686−.B \f[C]biblatexoptions\f[R]
1687−list of options for biblatex.
1688−.TP
16891800.B \f[C]natbiboptions\f[R]
1690−list of options for natbib.
1691−.TP
1692−.B \f[C]pagestyle\f[R]
1693−An option for LaTeX\[aq]s \f[C]\[rs]pagestyle{}\f[R].
1694−The default article class supports \[aq]plain\[aq] (default),
1695−\[aq]empty\[aq], and \[aq]headings\[aq]; headings puts section titles in
1696−the header.
1801+list of options for natbib
16971802.SS Variables for ConTeXt
1698−.TP
1699−.B \f[C]papersize\f[R]
1700−paper size, e.g.
1701−\f[C]letter\f[R], \f[C]A4\f[R], \f[C]landscape\f[R] (see ConTeXt Paper
1702−Setup); may be repeated for multiple options
1703−.TP
1704−.B \f[C]layout\f[R]
1705−options for page margins and text arrangement (see ConTeXt Layout); may
1706−be repeated for multiple options
1707−.TP
1708−.B \f[C]margin\-left\f[R], \f[C]margin\-right\f[R], \f[C]margin\-top\f[R], \f[C]margin\-bottom\f[R]
1709−sets margins, if \f[C]layout\f[R] is not used (otherwise
1710−\f[C]layout\f[R] overrides these)
1803+.PP
1804+Pandoc uses these variables when creating a PDF with ConTeXt.
17111805.TP
17121806.B \f[C]fontsize\f[R]
17131807font size for body text (e.g.
17141808\f[C]10pt\f[R], \f[C]12pt\f[R])
17151809.TP
1716−.B \f[C]mainfont\f[R], \f[C]sansfont\f[R], \f[C]monofont\f[R], \f[C]mathfont\f[R]
1717−font families: take the name of any system font (see ConTeXt Font
1718−Switching)
1810+.B \f[C]headertext\f[R], \f[C]footertext\f[R]
1811+text to be placed in running header or footer (see ConTeXt Headers and
1812+Footers); repeat up to four times for different placement
1813+.TP
1814+.B \f[C]indenting\f[R]
1815+controls indentation of paragraphs, e.g.
1816+\f[C]yes,small,next\f[R] (see ConTeXt Indentation); repeat for multiple
1817+options
1818+.TP
1819+.B \f[C]interlinespace\f[R]
1820+adjusts line spacing, e.g.
1821+\f[C]4ex\f[R] (using \f[C]setupinterlinespace\f[R]); repeat for multiple
1822+options
1823+.TP
1824+.B \f[C]layout\f[R]
1825+options for page margins and text arrangement (see ConTeXt Layout);
1826+repeat for multiple options
17191827.TP
17201828.B \f[C]linkcolor\f[R], \f[C]contrastcolor\f[R]
17211829color for links outside and inside a page, e.g.
@@ -1726,68 +1834,73 @@ typeface style for links, e.g.
17261834\f[C]normal\f[R], \f[C]bold\f[R], \f[C]slanted\f[R],
17271835\f[C]boldslanted\f[R], \f[C]type\f[R], \f[C]cap\f[R], \f[C]small\f[R]
17281836.TP
1729−.B \f[C]indenting\f[R]
1730−controls indentation of paragraphs, e.g.
1731−\f[C]yes,small,next\f[R] (see ConTeXt Indentation); may be repeated for
1732−multiple options
1733−.TP
1734−.B \f[C]whitespace\f[R]
1735−spacing between paragraphs, e.g.
1736−\f[C]none\f[R], \f[C]small\f[R] (using \f[C]setupwhitespace\f[R])
1837+.B \f[C]lof\f[R], \f[C]lot\f[R]
1838+include list of figures, list of tables
17371839.TP
1738−.B \f[C]interlinespace\f[R]
1739−adjusts line spacing, e.g.
1740−\f[C]4ex\f[R] (using \f[C]setupinterlinespace\f[R]); may be repeated for
1741−multiple options
1840+.B \f[C]mainfont\f[R], \f[C]sansfont\f[R], \f[C]monofont\f[R], \f[C]mathfont\f[R]
1841+font families: take the name of any system font (see ConTeXt Font
1842+Switching)
17421843.TP
1743−.B \f[C]headertext\f[R], \f[C]footertext\f[R]
1744−text to be placed in running header or footer (see ConTeXt Headers and
1745−Footers); may be repeated up to four times for different placement
1844+.B \f[C]margin-left\f[R], \f[C]margin-right\f[R], \f[C]margin-top\f[R], \f[C]margin-bottom\f[R]
1845+sets margins, if \f[C]layout\f[R] is not used (otherwise
1846+\f[C]layout\f[R] overrides these)
17461847.TP
17471848.B \f[C]pagenumbering\f[R]
1748−page number style and location (using \f[C]setuppagenumbering\f[R]); may
1749−be repeated for multiple options
1849+page number style and location (using \f[C]setuppagenumbering\f[R]);
1850+repeat for multiple options
17501851.TP
1751−.B \f[C]toc\f[R]
1752−include table of contents (can also be set using
1753−\f[C]\-\-toc/\-\-table\-of\-contents\f[R])
1754−.TP
1755−.B \f[C]lof\f[R], \f[C]lot\f[R]
1756−include list of figures, list of tables
1852+.B \f[C]papersize\f[R]
1853+paper size, e.g.
1854+\f[C]letter\f[R], \f[C]A4\f[R], \f[C]landscape\f[R] (see ConTeXt Paper
1855+Setup); repeat for multiple options
17571856.TP
17581857.B \f[C]pdfa\f[R]
1759−adds to the preamble the setup necessary to generate PDF/A\-1b:2005.
1858+adds to the preamble the setup necessary to generate PDF/A-1b:2005.
17601859To successfully generate PDF/A the required ICC color profiles have to
17611860be available and the content and all included files (such as images)
17621861have to be standard conforming.
17631862The ICC profiles can be obtained from ConTeXt ICC Profiles.
17641863See also ConTeXt PDFA for more details.
1765−.SS Variables for man pages
17661864.TP
1767−.B \f[C]section\f[R]
1768−section number in man pages
1865+.B \f[C]toc\f[R]
1866+include table of contents (can also be set using
1867+\f[C]--toc/--table-of-contents\f[R])
17691868.TP
1770−.B \f[C]header\f[R]
1771−header in man pages
1869+.B \f[C]whitespace\f[R]
1870+spacing between paragraphs, e.g.
1871+\f[C]none\f[R], \f[C]small\f[R] (using \f[C]setupwhitespace\f[R])
1872+.SS Variables for \f[C]wkhtmltopdf\f[R]
1873+.PP
1874+Pandoc uses these variables when creating a PDF with
1875+\f[C]wkhtmltopdf\f[R].
1876+The \f[C]--css\f[R] option also affects the output.
17721877.TP
1773−.B \f[C]footer\f[R]
1774−footer in man pages
1878+.B \f[C]footer-html\f[R], \f[C]header-html\f[R]
1879+add information to the header and footer
1880+.TP
1881+.B \f[C]margin-left\f[R], \f[C]margin-right\f[R], \f[C]margin-top\f[R], \f[C]margin-bottom\f[R]
1882+set the page margins
1883+.TP
1884+.B \f[C]papersize\f[R]
1885+sets the PDF paper size
1886+.SS Variables for man pages
17751887.TP
17761888.B \f[C]adjusting\f[R]
17771889adjusts text to left (\f[C]l\f[R]), right (\f[C]r\f[R]), center
17781890(\f[C]c\f[R]), or both (\f[C]b\f[R]) margins
17791891.TP
1892+.B \f[C]footer\f[R]
1893+footer in man pages
1894+.TP
1895+.B \f[C]header\f[R]
1896+header in man pages
1897+.TP
17801898.B \f[C]hyphenate\f[R]
17811899if \f[C]true\f[R] (the default), hyphenation will be used
1782−.SS Variables for ms
17831900.TP
1784−.B \f[C]pointsize\f[R]
1785−point size (e.g.
1786−\f[C]10p\f[R])
1787−.TP
1788−.B \f[C]lineheight\f[R]
1789−line height (e.g.
1790−\f[C]12p\f[R])
1901+.B \f[C]section\f[R]
1902+section number in man pages
1903+.SS Variables for ms
17911904.TP
17921905.B \f[C]fontfamily\f[R]
17931906font family (e.g.
@@ -1796,9 +1909,87 @@ font family (e.g.
17961909.B \f[C]indent\f[R]
17971910paragraph indent (e.g.
17981911\f[C]2m\f[R])
1912+.TP
1913+.B \f[C]lineheight\f[R]
1914+line height (e.g.
1915+\f[C]12p\f[R])
1916+.TP
1917+.B \f[C]pointsize\f[R]
1918+point size (e.g.
1919+\f[C]10p\f[R])
1920+.SS Structural variables
1921+.PP
1922+Pandoc sets these variables automatically in response to options or
1923+document contents; users can also modify them.
1924+These vary depending on the output format, and include the following:
1925+.TP
1926+.B \f[C]body\f[R]
1927+body of document
1928+.TP
1929+.B \f[C]date-meta\f[R]
1930+the \f[C]date\f[R] variable converted to ISO 8601 YYYY-MM-DD, included
1931+in all HTML based formats (dzslides, epub, html, html4, html5, revealjs,
1932+s5, slideous, slidy).
1933+The recognized formats for \f[C]date\f[R] are: \f[C]mm/dd/yyyy\f[R],
1934+\f[C]mm/dd/yy\f[R], \f[C]yyyy-mm-dd\f[R] (ISO 8601),
1935+\f[C]dd MM yyyy\f[R] (e.g.
1936+either \f[C]02 Apr 2018\f[R] or \f[C]02 April 2018\f[R]),
1937+\f[C]MM dd, yyyy\f[R] (e.g.
1938+\f[C]Apr. 02, 2018\f[R] or
1939+\f[C]April 02, 2018),\f[R]yyyy[mm[dd]]]\f[C](e.g.\f[R]20180402,
1940+\f[C]201804\f[R] or \f[C]2018\f[R]).
1941+.TP
1942+.B \f[C]header-includes\f[R]
1943+contents specified by \f[C]-H/--include-in-header\f[R] (may have
1944+multiple values)
1945+.TP
1946+.B \f[C]include-before\f[R]
1947+contents specified by \f[C]-B/--include-before-body\f[R] (may have
1948+multiple values)
1949+.TP
1950+.B \f[C]include-after\f[R]
1951+contents specified by \f[C]-A/--include-after-body\f[R] (may have
1952+multiple values)
1953+.TP
1954+.B \f[C]meta-json\f[R]
1955+JSON representation of all of the document\[aq]s metadata.
1956+Field values are transformed to the selected output format.
1957+.TP
1958+.B \f[C]numbersections\f[R]
1959+non-null value if \f[C]-N/--number-sections\f[R] was specified
1960+.TP
1961+.B \f[C]sourcefile\f[R], \f[C]outputfile\f[R]
1962+source and destination filenames, as given on the command line.
1963+\f[C]sourcefile\f[R] can also be a list if input comes from multiple
1964+files, or empty if input is from stdin.
1965+You can use the following snippet in your template to distinguish them:
1966+.RS
1967+.IP
1968+.nf
1969+\f[C]
1970+$if(sourcefile)$
1971+$for(sourcefile)$
1972+$sourcefile$
1973+$endfor$
1974+$else$
1975+(stdin)
1976+$endif$
1977+\f[R]
1978+.fi
1979+.PP
1980+Similarly, \f[C]outputfile\f[R] can be \f[C]-\f[R] if output goes to the
1981+terminal.
1982+.RE
1983+.TP
1984+.B \f[C]toc\f[R]
1985+non-null value if \f[C]--toc/--table-of-contents\f[R] was specified
1986+.TP
1987+.B \f[C]toc-title\f[R]
1988+title of table of contents (works only with EPUB, opendocument, odt,
1989+docx, pptx, beamer, LaTeX)
17991990.SS Using variables in templates
18001991.PP
1801−Variable names are sequences of alphanumerics, \f[C]\-\f[R], and
1992+Variable names are sequences of alphanumerics, \f[C]-\f[R], and
18021993\f[C]_\f[R], starting with a letter.
18031994A variable name surrounded by \f[C]$\f[R] signs will be replaced by its
18041995value.
@@ -1833,24 +2024,24 @@ Here a truthy value is any of the following:
18332024.IP \[bu] 2
18342025a string that is not entirely white space,
18352026.IP \[bu] 2
1836−a non\-empty array where the first value is truthy,
2027+a non-empty array where the first value is truthy,
18372028.IP \[bu] 2
18382029any number (including zero),
18392030.IP \[bu] 2
18402031any object,
18412032.IP \[bu] 2
18422033the boolean \f[C]true\f[R] (to specify the boolean \f[C]true\f[R] value
1843−using YAML metadata or the \f[C]\-\-metadata\f[R] flag, use
2034+using YAML metadata or the \f[C]--metadata\f[R] flag, use
18442035\f[C]true\f[R], \f[C]True\f[R], or \f[C]TRUE\f[R]; with the
1845−\f[C]\-\-variable\f[R] flag, simply omit a value for the variable, e.g.
1846−\f[C]\-\-variable draft\f[R]).
2036+\f[C]--variable\f[R] flag, simply omit a value for the variable, e.g.
2037+\f[C]--variable draft\f[R]).
18472038.PP
18482039\f[C]X\f[R] and \f[C]Y\f[R] are placeholders for any valid template
18492040text, and may include interpolated variables or other conditionals.
18502041The \f[C]$else$\f[R] section may be omitted.
18512042.PP
18522043When variables can have multiple values (for example, \f[C]author\f[R]
1853−in a multi\-author document), you can use the \f[C]$for$\f[R] keyword:
2044+in a multi-author document), you can use the \f[C]$for$\f[R] keyword:
18542045.IP
18552046.nf
18562047\f[C]
@@ -1869,6 +2060,9 @@ $for(author)$$author$$sep$, $endfor$
18692060\f[R]
18702061.fi
18712062.PP
2063+Note that the separator needs to be specified immediately before the
2064+\f[C]$endfor\f[R] keyword.
2065+.PP
18722066A dot can be used to select a field of a variable that takes an object
18732067as its value.
18742068So, for example:
@@ -1883,10 +2077,10 @@ If you use custom templates, you may need to revise them as pandoc
18832077changes.
18842078We recommend tracking the changes in the default templates, and
18852079modifying your custom templates accordingly.
1886−An easy way to do this is to fork the pandoc\-templates repository and
2080+An easy way to do this is to fork the pandoc-templates repository and
18872081merge in changes after each pandoc release.
18882082.PP
1889−Templates may contain comments: anything on a line after \f[C]$\-\-\f[R]
2083+Templates may contain comments: anything on a line after \f[C]$--\f[R]
18902084will be treated as a comment and ignored.
18912085.SH EXTENSIONS
18922086.PP
@@ -1894,22 +2088,26 @@ The behavior of some of the readers and writers can be adjusted by
18942088enabling or disabling various extensions.
18952089.PP
18962090An extension can be enabled by adding \f[C]+EXTENSION\f[R] to the format
1897−name and disabled by adding \f[C]\-EXTENSION\f[R].
1898−For example, \f[C]\-\-from markdown_strict+footnotes\f[R] is strict
2091+name and disabled by adding \f[C]-EXTENSION\f[R].
2092+For example, \f[C]--from markdown_strict+footnotes\f[R] is strict
18992093Markdown with footnotes enabled, while
1900−\f[C]\-\-from markdown\-footnotes\-pipe_tables\f[R] is pandoc\[aq]s
1901−Markdown without footnotes or pipe tables.
2094+\f[C]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[aq]s Markdown
2095+without footnotes or pipe tables.
19022096.PP
19032097The markdown reader and writer make by far the most use of extensions.
19042098Extensions only used by them are therefore covered in the section
19052099Pandoc\[aq]s Markdown below (See Markdown variants for
19062100\f[C]commonmark\f[R] and \f[C]gfm\f[R].) In the following, extensions
19072101that also work for other formats are covered.
2102+.PP
2103+Note that markdown extensions added to the \f[C]ipynb\f[R] format affect
2104+Markdown cells in Jupyter notebooks (as do command-line options like
2105+\f[C]--atx-headers\f[R]).
19082106.SS Typography
19092107.SS Extension: \f[C]smart\f[R]
19102108.PP
1911−Interpret straight quotes as curly quotes, \f[C]\-\-\-\f[R] as
1912−em\-dashes, \f[C]\-\-\f[R] as en\-dashes, and \f[C]...\f[R] as ellipses.
2109+Interpret straight quotes as curly quotes, \f[C]---\f[R] as em-dashes,
2110+\f[C]--\f[R] as en-dashes, and \f[C]...\f[R] as ellipses.
19132111Nonbreaking spaces are inserted after certain abbreviations, such as
19142112\[dq]Mr.\[dq]
19152113.PP
@@ -1933,8 +2131,7 @@ comes out straight.
19332131In LaTeX, \f[C]smart\f[R] means to use the standard TeX ligatures for
19342132quotation marks (\f[C]\[ga]\[ga]\f[R] and \f[C]\[aq]\[aq]\f[R] for
19352133double quotes, \f[C]\[ga]\f[R] and \f[C]\[aq]\f[R] for single quotes)
1936−and dashes (\f[C]\-\-\f[R] for en\-dash and \f[C]\-\-\-\f[R] for
1937−em\-dash).
2134+and dashes (\f[C]--\f[R] for en-dash and \f[C]---\f[R] for em-dash).
19382135If \f[C]smart\f[R] is disabled, then in reading LaTeX pandoc will parse
19392136these characters literally.
19402137In writing LaTeX, enabling \f[C]smart\f[R] tells pandoc to use the
@@ -1965,7 +2162,8 @@ Remove all formatting, links, etc.
19652162.IP \[bu] 2
19662163Remove all footnotes.
19672164.IP \[bu] 2
1968−Remove all punctuation, except underscores, hyphens, and periods.
2165+Remove all non-alphanumeric characters, except underscores, hyphens, and
2166+periods.
19692167.IP \[bu] 2
19702168Replace all spaces and newlines with hyphens.
19712169.IP \[bu] 2
@@ -1990,17 +2188,22 @@ _
19902188T{
19912189\f[C]Header identifiers in HTML\f[R]
19922190T}@T{
1993−\f[C]header\-identifiers\-in\-html\f[R]
2191+\f[C]header-identifiers-in-html\f[R]
2192+T}
2193+T{
2194+\f[C]Ma\[^i]tre d\[aq]h\[^o]tel\f[R]
2195+T}@T{
2196+\f[C]ma\[^i]tre-dh\[^o]tel\f[R]
19942197T}
19952198T{
1996−\f[C]*Dogs*?\-\-in *my* house?\f[R]
2199+\f[C]*Dogs*?--in *my* house?\f[R]
19972200T}@T{
1998−\f[C]dogs\-\-in\-my\-house\f[R]
2201+\f[C]dogs--in-my-house\f[R]
19992202T}
20002203T{
20012204\f[C][HTML], [S5], or [RTF]?\f[R]
20022205T}@T{
2003−\f[C]html\-s5\-or\-rtf\f[R]
2206+\f[C]html-s5-or-rtf\f[R]
20042207T}
20052208T{
20062209\f[C]3. Applications\f[R]
@@ -2018,15 +2221,14 @@ These rules should, in most cases, allow one to determine the identifier
20182221from the header text.
20192222The exception is when several headers have the same text; in this case,
20202223the first will get an identifier as described above; the second will get
2021−the same identifier with \f[C]\-1\f[R] appended; the third with
2022−\f[C]\-2\f[R]; and so on.
2224+the same identifier with \f[C]-1\f[R] appended; the third with
2225+\f[C]-2\f[R]; and so on.
20232226.PP
20242227(However, a different algorithm is used if
20252228\f[C]gfm_auto_identifiers\f[R] is enabled; see below.)
20262229.PP
20272230These identifiers are used to provide link targets in the table of
2028−contents generated by the \f[C]\-\-toc|\-\-table\-of\-contents\f[R]
2029−option.
2231+contents generated by the \f[C]--toc|--table-of-contents\f[R] option.
20302232They also make it easy to provide links from one section of a document
20312233to another.
20322234A link to this section, for example, might look like this:
@@ -2034,15 +2236,15 @@ A link to this section, for example, might look like this:
20342236.nf
20352237\f[C]
20362238See the section on
2037−[header identifiers](#header\-identifiers\-in\-html\-latex\-and\-context).
2239+[header identifiers](#header-identifiers-in-html-latex-and-context).
20382240\f[R]
20392241.fi
20402242.PP
20412243Note, however, that this method of providing links to sections works
20422244only in HTML, LaTeX, and ConTeXt formats.
20432245.PP
2044−If the \f[C]\-\-section\-divs\f[R] option is specified, then each
2045−section will be wrapped in a \f[C]section\f[R] (or a \f[C]div\f[R], if
2246+If the \f[C]--section-divs\f[R] option is specified, then each section
2247+will be wrapped in a \f[C]section\f[R] (or a \f[C]div\f[R], if
20462248\f[C]html4\f[R] was specified), and the identifier will be attached to
20472249the enclosing \f[C]<section>\f[R] (or \f[C]<div>\f[R]) tag rather than
20482250the header itself.
@@ -2052,14 +2254,14 @@ treated differently in CSS.
20522254.PP
20532255Causes the identifiers produced by \f[C]auto_identifiers\f[R] to be pure
20542256ASCII.
2055−Accents are stripped off of accented Latin letters, and non\-Latin
2257+Accents are stripped off of accented Latin letters, and non-Latin
20562258letters are omitted.
20572259.SS Extension: \f[C]gfm_auto_identifiers\f[R]
20582260.PP
20592261Changes the algorithm used by \f[C]auto_identifiers\f[R] to conform to
20602262GitHub\[aq]s method.
2061−Spaces are converted to dashes (\f[C]\-\f[R]), uppercase characters to
2062−lowercase characters, and punctuation characters other than \f[C]\-\f[R]
2263+Spaces are converted to dashes (\f[C]-\f[R]), uppercase characters to
2264+lowercase characters, and punctuation characters other than \f[C]-\f[R]
20632265and \f[C]_\f[R] are removed.
20642266.SS Math Input
20652267.PP
@@ -2090,23 +2292,33 @@ addition to \f[C]markdown\f[R]):
20902292.TP
20912293.B input formats
20922294\f[C]latex\f[R], \f[C]org\f[R], \f[C]textile\f[R], \f[C]html\f[R]
2093−(environments, \f[C]\[rs]ref\f[R], and \f[C]\[rs]eqref\f[R] only)
2295+(environments, \f[C]\[rs]ref\f[R], and \f[C]\[rs]eqref\f[R] only),
2296+\f[C]ipynb\f[R]
20942297.TP
20952298.B output formats
20962299\f[C]textile\f[R], \f[C]commonmark\f[R]
2300+.PP
2301+Note: as applied to \f[C]ipynb\f[R], \f[C]raw_html\f[R] and
2302+\f[C]raw_tex\f[R] affect not only raw TeX in markdown cells, but data
2303+with mime type \f[C]text/html\f[R] in output cells.
2304+Since the \f[C]ipynb\f[R] reader attempts to preserve the richest
2305+possible outputs when several options are given, you will get best
2306+results if you disable \f[C]raw_html\f[R] and \f[C]raw_tex\f[R] when
2307+converting to formats like \f[C]docx\f[R] which don\[aq]t allow raw
2308+\f[C]html\f[R] or \f[C]tex\f[R].
20972309.SS Extension: \f[C]native_divs\f[R]
20982310.PP
20992311This extension is enabled by default for HTML input.
21002312This means that \f[C]div\f[R]s are parsed to pandoc native elements.
21012313(Alternatively, you can parse them to raw HTML using
2102−\f[C]\-f html\-native_divs+raw_html\f[R].)
2314+\f[C]-f html-native_divs+raw_html\f[R].)
21032315.PP
21042316When converting HTML to Markdown, for example, you may want to drop all
21052317\f[C]div\f[R]s and \f[C]span\f[R]s:
21062318.IP
21072319.nf
21082320\f[C]
2109−pandoc \-f html\-native_divs\-native_spans \-t markdown
2321+pandoc -f html-native_divs-native_spans -t markdown
21102322\f[R]
21112323.fi
21122324.SS Extension: \f[C]native_spans\f[R]
@@ -2134,15 +2346,15 @@ In Markdown input, \[dq]bird track\[dq] sections will be parsed as
21342346Haskell code rather than block quotations.
21352347Text between \f[C]\[rs]begin{code}\f[R] and \f[C]\[rs]end{code}\f[R]
21362348will also be treated as Haskell code.
2137−For ATX\-style headers the character \[aq]=\[aq] will be used instead of
2349+For ATX-style headers the character \[aq]=\[aq] will be used instead of
21382350\[aq]#\[aq].
21392351.IP \[bu] 2
21402352In Markdown output, code blocks with classes \f[C]haskell\f[R] and
21412353\f[C]literate\f[R] will be rendered using bird tracks, and block
21422354quotations will be indented one space, so they will not be treated as
21432355Haskell code.
2144−In addition, headers will be rendered setext\-style (with underlines)
2145−rather than ATX\-style (with \[aq]#\[aq] characters).
2356+In addition, headers will be rendered setext-style (with underlines)
2357+rather than ATX-style (with \[aq]#\[aq] characters).
21462358(This is because ghc treats \[aq]#\[aq] characters in column 1 as
21472359introducing line numbers.)
21482360.IP \[bu] 2
@@ -2165,7 +2377,7 @@ Examples:
21652377.IP
21662378.nf
21672379\f[C]
2168−pandoc \-f markdown+lhs \-t html
2380+pandoc -f markdown+lhs -t html
21692381\f[R]
21702382.fi
21712383.PP
@@ -2174,7 +2386,7 @@ writes ordinary HTML (without bird tracks).
21742386.IP
21752387.nf
21762388\f[C]
2177−pandoc \-f markdown+lhs \-t html+lhs
2389+pandoc -f markdown+lhs -t html+lhs
21782390\f[R]
21792391.fi
21802392.PP
@@ -2220,7 +2432,7 @@ in \f[C]org\f[R] input.
22202432.PP
22212433In the \f[C]context\f[R] output format this enables the use of Natural
22222434Tables (TABLE) instead of the default Extreme Tables (xtables).
2223−Natural tables allow more fine\-grained global customization but come at
2435+Natural tables allow more fine-grained global customization but come at
22242436a performance penalty compared to extreme tables.
22252437.SH PANDOC\[aq]S MARKDOWN
22262438.PP
@@ -2241,10 +2453,10 @@ Markdown is designed to be easy to write, and, even more importantly,
22412453easy to read:
22422454.RS
22432455.PP
2244−A Markdown\-formatted document should be publishable as\-is, as plain
2456+A Markdown-formatted document should be publishable as-is, as plain
22452457text, without looking like it\[aq]s been marked up with tags or
22462458formatting instructions.
2247−\-\- John Gruber
2459+-- John Gruber
22482460.RE
22492461.PP
22502462This principle has guided pandoc\[aq]s decisions in finding syntax for
@@ -2255,7 +2467,7 @@ from the original aims of Markdown.
22552467Whereas Markdown was originally designed with HTML generation in mind,
22562468pandoc is designed for multiple output formats.
22572469Thus, while pandoc allows the embedding of raw HTML, it discourages it,
2258−and provides other, non\-HTMLish ways of representing important document
2470+and provides other, non-HTMLish ways of representing important document
22592471elements like definition lists, tables, mathematics, and footnotes.
22602472.SS Paragraphs
22612473.PP
@@ -2273,44 +2485,44 @@ a hard line break, since trailing spaces in the cells are ignored.
22732485.SS Headers
22742486.PP
22752487There are two kinds of headers: Setext and ATX.
2276−.SS Setext\-style headers
2488+.SS Setext-style headers
22772489.PP
2278−A setext\-style header is a line of text \[dq]underlined\[dq] with a row
2279−of \f[C]=\f[R] signs (for a level one header) or \f[C]\-\f[R] signs (for
2490+A setext-style header is a line of text \[dq]underlined\[dq] with a row
2491+of \f[C]=\f[R] signs (for a level one header) or \f[C]-\f[R] signs (for
22802492a level two header):
22812493.IP
22822494.nf
22832495\f[C]
2284−A level\-one header
2496+A level-one header
22852497==================
22862498
2287−A level\-two header
2288−\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
2499+A level-two header
2500+------------------
22892501\f[R]
22902502.fi
22912503.PP
22922504The header text can contain inline formatting, such as emphasis (see
22932505Inline formatting, below).
2294−.SS ATX\-style headers
2506+.SS ATX-style headers
22952507.PP
2296−An ATX\-style header consists of one to six \f[C]#\f[R] signs and a line
2508+An ATX-style header consists of one to six \f[C]#\f[R] signs and a line
22972509of text, optionally followed by any number of \f[C]#\f[R] signs.
22982510The number of \f[C]#\f[R] signs at the beginning of the line is the
22992511header level:
23002512.IP
23012513.nf
23022514\f[C]
2303−## A level\-two header
2515+## A level-two header
23042516
2305−### A level\-three header ###
2517+### A level-three header ###
23062518\f[R]
23072519.fi
23082520.PP
2309−As with setext\-style headers, the header text can contain formatting:
2521+As with setext-style headers, the header text can contain formatting:
23102522.IP
23112523.nf
23122524\f[C]
2313−# A level\-one header with a [link](/url) and *emphasis*
2525+# A level-one header with a [link](/url) and *emphasis*
23142526\f[R]
23152527.fi
23162528.SS Extension: \f[C]blank_before_header\f[R]
@@ -2359,7 +2571,7 @@ identifier \f[C]foo\f[R]:
23592571## My header ## {#foo}
23602572
23612573My other header {#foo}
2362−\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
2574+---------------
23632575\f[R]
23642576.fi
23652577.PP
@@ -2369,19 +2581,19 @@ Note that although this syntax allows assignment of classes and
23692581key/value attributes, writers generally don\[aq]t use all of this
23702582information.
23712583Identifiers, classes, and key/value attributes are used in HTML and
2372−HTML\-based formats such as EPUB and slidy.
2584+HTML-based formats such as EPUB and slidy.
23732585Identifiers are used for labels and link anchors in the LaTeX, ConTeXt,
23742586Textile, and AsciiDoc writers.
23752587.PP
23762588Headers with the class \f[C]unnumbered\f[R] will not be numbered, even
2377−if \f[C]\-\-number\-sections\f[R] is specified.
2378−A single hyphen (\f[C]\-\f[R]) in an attribute context is equivalent to
2379−\f[C].unnumbered\f[R], and preferable in non\-English documents.
2589+if \f[C]--number-sections\f[R] is specified.
2590+A single hyphen (\f[C]-\f[R]) in an attribute context is equivalent to
2591+\f[C].unnumbered\f[R], and preferable in non-English documents.
23802592So,
23812593.IP
23822594.nf
23832595\f[C]
2384−# My header {\-}
2596+# My header {-}
23852597\f[R]
23862598.fi
23872599.PP
@@ -2432,7 +2644,7 @@ instead of giving the identifier explicitly:
24322644.IP
24332645.nf
24342646\f[C]
2435−[Header identifiers in HTML](#header\-identifiers\-in\-html)
2647+[Header identifiers in HTML](#header-identifiers-in-html)
24362648\f[R]
24372649.fi
24382650.PP
@@ -2440,7 +2652,7 @@ If there are multiple headers with identical text, the corresponding
24402652reference will link to the first one only, and you will need to use
24412653explicit links to link to the others, as described above.
24422654.PP
2443−Like regular reference links, these references are case\-insensitive.
2655+Like regular reference links, these references are case-insensitive.
24442656.PP
24452657Explicit link reference definitions always take priority over implicit
24462658header references.
@@ -2612,8 +2824,8 @@ LaTeX, Docx, Ms, and PowerPoint.
26122824If highlighting is supported for your output format and language, then
26132825the code block above will appear highlighted, with numbered lines.
26142826(To see which languages are supported, type
2615−\f[C]pandoc \-\-list\-highlight\-languages\f[R].) Otherwise, the code
2616−block above will appear as follows:
2827+\f[C]pandoc --list-highlight-languages\f[R].) Otherwise, the code block
2828+above will appear as follows:
26172829.IP
26182830.nf
26192831\f[C]
@@ -2625,10 +2837,10 @@ block above will appear as follows:
26252837\f[R]
26262838.fi
26272839.PP
2628−The \f[C]numberLines\f[R] (or \f[C]number\-lines\f[R]) class will cause
2840+The \f[C]numberLines\f[R] (or \f[C]number-lines\f[R]) class will cause
26292841the lines of the code block to be numbered, starting with \f[C]1\f[R] or
26302842the value of the \f[C]startFrom\f[R] attribute.
2631−The \f[C]lineAnchors\f[R] (or \f[C]line\-anchors\f[R]) class will cause
2843+The \f[C]lineAnchors\f[R] (or \f[C]line-anchors\f[R]) class will cause
26322844the lines to be clickable anchors in HTML output.
26332845.PP
26342846A shortcut form can also be used for specifying the language of the code
@@ -2656,8 +2868,8 @@ If the \f[C]fenced_code_attributes\f[R] extension is disabled, but input
26562868contains class attribute(s) for the code block, the first class
26572869attribute will be printed after the opening fence as a bare word.
26582870.PP
2659−To prevent all highlighting, use the \f[C]\-\-no\-highlight\f[R] flag.
2660−To set the highlighting style, use \f[C]\-\-highlight\-style\f[R].
2871+To prevent all highlighting, use the \f[C]--no-highlight\f[R] flag.
2872+To set the highlighting style, use \f[C]--highlight-style\f[R].
26612873For more information on highlighting, see Syntax highlighting, below.
26622874.SS Line blocks
26632875.SS Extension: \f[C]line_blocks\f[R]
@@ -2681,7 +2893,7 @@ This is useful for verse and addresses:
26812893\f[R]
26822894.fi
26832895.PP
2684−The lines can be hard\-wrapped if needed, but the continuation line must
2896+The lines can be hard-wrapped if needed, but the continuation line must
26852897begin with a space.
26862898.IP
26872899.nf
@@ -2699,7 +2911,7 @@ This syntax is borrowed from reStructuredText.
26992911.PP
27002912A bullet list is a list of bulleted list items.
27012913A bulleted list item begins with a bullet (\f[C]*\f[R], \f[C]+\f[R], or
2702−\f[C]\-\f[R]).
2914+\f[C]-\f[R]).
27032915Here is a simple example:
27042916.IP
27052917.nf
@@ -2750,10 +2962,10 @@ list item.
27502962.fi
27512963.SS Block content in list items
27522964.PP
2753−A list item may contain multiple paragraphs and other block\-level
2965+A list item may contain multiple paragraphs and other block-level
27542966content.
27552967However, subsequent paragraphs must be preceded by a blank line and
2756−indented to line up with the first non\-space content after the list
2968+indented to line up with the first non-space content after the list
27572969marker.
27582970.IP
27592971.nf
@@ -2784,15 +2996,15 @@ marker:
27842996.PP
27852997List items may include other lists.
27862998In this case the preceding blank line is optional.
2787−The nested list must be indented to line up with the first non\-space
2999+The nested list must be indented to line up with the first non-space
27883000character after the list marker of the containing list item.
27893001.IP
27903002.nf
27913003\f[C]
27923004* fruits
27933005 + apples
2794− \- macintosh
2795− \- red delicious
3006+ - macintosh
3007+ - red delicious
27963008 + pears
27973009 + peaches
27983010* vegetables
@@ -2851,7 +3063,7 @@ Unlike standard Markdown, pandoc allows ordered list items to be marked
28513063with uppercase and lowercase letters and roman numerals, in addition to
28523064Arabic numerals.
28533065List markers may be enclosed in parentheses or followed by a single
2854−right\-parentheses or period.
3066+right-parentheses or period.
28553067They must be separated from the text that follows by at least one space,
28563068and, if the list marker is a capital letter with a period, by at least
28573069two spaces.
@@ -2907,6 +3119,17 @@ If default list markers are desired, use \f[C]#.\f[R]:
29073119#. three
29083120\f[R]
29093121.fi
3122+.SS Extension: \f[C]task_lists\f[R]
3123+.PP
3124+Pandoc supports task lists, using the syntax of GitHub-Flavored
3125+Markdown.
3126+.IP
3127+.nf
3128+\f[C]
3129+- [ ] an unchecked task list item
3130+- [x] checked item
3131+\f[R]
3132+.fi
29103133.SS Definition lists
29113134.SS Extension: \f[C]definition_lists\f[R]
29123135.PP
@@ -2975,7 +3198,7 @@ Term 2
29753198Note that space between items in a definition list is required.
29763199(A variant that loosens this requirement, but disallows \[dq]lazy\[dq]
29773200hard wrapping, can be activated with \f[C]compact_definition_lists\f[R]:
2978−see Non\-pandoc extensions, below.)
3201+see Non-pandoc extensions, below.)
29793202.SS Numbered example lists
29803203.SS Extension: \f[C]example_lists\f[R]
29813204.PP
@@ -3017,7 +3240,7 @@ four spaces, regardless of the length of the list marker.
30173240That is, example lists always behave as if the \f[C]four_space_rule\f[R]
30183241extension is set.
30193242This is because example labels tend to be long, and indenting content to
3020−the first non\-space character after the label would be awkward.
3243+the first non-space character after the label would be awkward.
30213244.SS Compact and loose lists
30223245.PP
30233246Pandoc behaves differently from \f[C]Markdown.pl\f[R] on some \[dq]edge
@@ -3028,9 +3251,9 @@ Consider this source:
30283251\f[C]
30293252+ First
30303253+ Second:
3031− \- Fee
3032− \- Fie
3033− \- Foe
3254+ - Fee
3255+ - Fie
3256+ - Foe
30343257
30353258+ Third
30363259\f[R]
@@ -3057,8 +3280,8 @@ What if you want to put an indented code block after a list?
30573280.IP
30583281.nf
30593282\f[C]
3060−\- item one
3061−\- item two
3283+- item one
3284+- item two
30623285
30633286 { my code block }
30643287\f[R]
@@ -3069,15 +3292,15 @@ Trouble! Here pandoc (like other Markdown implementations) will treat
30693292as a code block.
30703293.PP
30713294To \[dq]cut off\[dq] the list after item two, you can insert some
3072−non\-indented content, like an HTML comment, which won\[aq]t produce
3295+non-indented content, like an HTML comment, which won\[aq]t produce
30733296visible output in any format:
30743297.IP
30753298.nf
30763299\f[C]
3077−\- item one
3078−\- item two
3300+- item one
3301+- item two
30793302
3080−<!\-\- end of list \-\->
3303+<!-- end of list -->
30813304
30823305 { my code block }
30833306\f[R]
@@ -3092,7 +3315,7 @@ one big list:
309233152. two
309333163. three
30943317
3095−<!\-\- \-\->
3318+<!-- -->
30963319
309733201. uno
309833212. dos
@@ -3101,7 +3324,7 @@ one big list:
31013324.fi
31023325.SS Horizontal rules
31033326.PP
3104−A line containing a row of three or more \f[C]*\f[R], \f[C]\-\f[R], or
3327+A line containing a row of three or more \f[C]*\f[R], \f[C]-\f[R], or
31053328\f[C]_\f[R] characters (optionally separated by spaces) produces a
31063329horizontal rule:
31073330.IP
@@ -3109,13 +3332,13 @@ horizontal rule:
31093332\f[C]
31103333* * * *
31113334
3112−\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
3335+---------------
31133336\f[R]
31143337.fi
31153338.SS Tables
31163339.PP
31173340Four kinds of tables may be used.
3118−The first three kinds presuppose the use of a fixed\-width font, such as
3341+The first three kinds presuppose the use of a fixed-width font, such as
31193342Courier.
31203343The fourth kind can be used with proportionally spaced fonts, as it does
31213344not require lining up columns.
@@ -3133,7 +3356,7 @@ Simple tables look like this:
31333356.nf
31343357\f[C]
31353358 Right Left Center Default
3136−\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-
3359+------- ------ ---------- -------
31373360 12 12 12 12
31383361 123 123 123 123
31393362 1 1 1 1
@@ -3147,10 +3370,10 @@ Column alignments are determined by the position of the header text
31473370relative to the dashed line below it:
31483371.IP \[bu] 2
31493372If the dashed line is flush with the header text on the right side but
3150−extends beyond it on the left, the column is right\-aligned.
3373+extends beyond it on the left, the column is right-aligned.
31513374.IP \[bu] 2
31523375If the dashed line is flush with the header text on the left side but
3153−extends beyond it on the right, the column is left\-aligned.
3376+extends beyond it on the right, the column is left-aligned.
31543377.IP \[bu] 2
31553378If the dashed line extends beyond the header text on both sides, the
31563379column is centered.
@@ -3167,11 +3390,11 @@ For example:
31673390.IP
31683391.nf
31693392\f[C]
3170−\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-
3393+------- ------ ---------- -------
31713394 12 12 12 12
31723395 123 123 123 123
31733396 1 1 1 1
3174−\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-
3397+------- ------ ---------- -------
31753398\f[R]
31763399.fi
31773400.PP
@@ -3188,17 +3411,17 @@ Here is an example:
31883411.IP
31893412.nf
31903413\f[C]
3191−\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
3414+-------------------------------------------------------------
31923415 Centered Default Right Left
31933416 Header Aligned Aligned Aligned
3194−\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
3417+----------- ------- --------------- -------------------------
31953418 First row 12.0 Example of a row that
31963419 spans multiple lines.
31973420
31983421 Second row 5.0 Here\[aq]s another one. Note
31993422 the blank line between
32003423 rows.
3201−\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
3424+-------------------------------------------------------------
32023425
32033426Table: Here\[aq]s the caption. It, too, may span
32043427multiple lines.
@@ -3224,14 +3447,14 @@ Headers may be omitted in multiline tables as well as simple tables:
32243447.IP
32253448.nf
32263449\f[C]
3227−\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
3450+----------- ------- --------------- -------------------------
32283451 First row 12.0 Example of a row that
32293452 spans multiple lines.
32303453
32313454 Second row 5.0 Here\[aq]s another one. Note
32323455 the blank line between
32333456 rows.
3234−\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
3457+----------- ------- --------------- -------------------------
32353458
32363459: Here\[aq]s a multiline table without headers.
32373460\f[R]
@@ -3248,15 +3471,15 @@ Grid tables look like this:
32483471\f[C]
32493472: Sample grid table.
32503473
3251−+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
3474++---------------+---------------+--------------------+
32523475| Fruit | Price | Advantages |
32533476+===============+===============+====================+
3254−| Bananas | $1.34 | \- built\-in wrapper |
3255−| | | \- bright color |
3256−+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
3257−| Oranges | $2.10 | \- cures scurvy |
3258−| | | \- tasty |
3259−+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
3477+| Bananas | $1.34 | - built-in wrapper |
3478+| | | - bright color |
3479++---------------+---------------+--------------------+
3480+| Oranges | $2.10 | - cures scurvy |
3481+| | | - tasty |
3482++---------------+---------------+--------------------+
32603483\f[R]
32613484.fi
32623485.PP
@@ -3272,11 +3495,11 @@ the boundaries of the separator line after the header:
32723495.IP
32733496.nf
32743497\f[C]
3275−+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
3498++---------------+---------------+--------------------+
32763499| Right | Left | Centered |
32773500+==============:+:==============+:==================:+
3278−| Bananas | $1.34 | built\-in wrapper |
3279−+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
3501+| Bananas | $1.34 | built-in wrapper |
3502++---------------+---------------+--------------------+
32803503\f[R]
32813504.fi
32823505.PP
@@ -3284,9 +3507,9 @@ For headerless tables, the colons go on the top line instead:
32843507.IP
32853508.nf
32863509\f[C]
3287−+\-\-\-\-\-\-\-\-\-\-\-\-\-\-:+:\-\-\-\-\-\-\-\-\-\-\-\-\-\-+:\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-:+
3510++--------------:+:--------------+:------------------:+
32883511| Right | Left | Centered |
3289−+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
3512++---------------+---------------+--------------------+
32903513\f[R]
32913514.fi
32923515.SS Grid Table Limitations
@@ -3305,7 +3528,7 @@ Pipe tables look like this:
33053528.nf
33063529\f[C]
33073530| Right | Left | Default | Center |
3308−|\-\-\-\-\-\-:|:\-\-\-\-\-|\-\-\-\-\-\-\-\-\-|:\-\-\-\-\-\-:|
3531+|------:|:-----|---------|:------:|
33093532| 12 | 12 | 12 | 12 |
33103533| 123 | 123 | 123 | 123 |
33113534| 1 | 1 | 1 | 1 |
@@ -3328,7 +3551,7 @@ So, this is a perfectly legal (though ugly) pipe table:
33283551.nf
33293552\f[C]
33303553fruit| price
3331−\-\-\-\-\-|\-\-\-\-\-:
3554+-----|-----:
33323555apple|2.05
33333556pear|1.37
33343557orange|3.09
@@ -3338,22 +3561,22 @@ orange|3.09
33383561The cells of pipe tables cannot contain block elements like paragraphs
33393562and lists, and cannot span multiple lines.
33403563If a pipe table contains a row whose printable content is wider than the
3341−column width (see \f[C]\-\-columns\f[R]), then the table will take up
3342−the full text width and the cell contents will wrap, with the relative
3343−cell widths determined by the number of dashes in the line separating
3344−the table header from the table body.
3345−(For example \f[C]\-\-\-|\-\f[R] would make the first column 3/4 and the
3564+column width (see \f[C]--columns\f[R]), then the table will take up the
3565+full text width and the cell contents will wrap, with the relative cell
3566+widths determined by the number of dashes in the line separating the
3567+table header from the table body.
3568+(For example \f[C]---|-\f[R] would make the first column 3/4 and the
33463569second column 1/4 of the full text width.) On the other hand, if no
33473570lines are wider than column width, then cell contents will not be
33483571wrapped, and the cells will be sized to their contents.
33493572.PP
33503573Note: pandoc also recognizes pipe tables of the following form, as can
3351−be produced by Emacs\[aq] orgtbl\-mode:
3574+be produced by Emacs\[aq] orgtbl-mode:
33523575.IP
33533576.nf
33543577\f[C]
33553578| One | Two |
3356−|\-\-\-\-\-+\-\-\-\-\-\-\-|
3579+|-----+-------|
33573580| my | table |
33583581| is | nice |
33593582\f[R]
@@ -3361,7 +3584,7 @@ be produced by Emacs\[aq] orgtbl\-mode:
33613584.PP
33623585The difference is that \f[C]+\f[R] is used instead of \f[C]|\f[R].
33633586Other orgtbl features are not supported.
3364−In particular, to get non\-default column alignment, you\[aq]ll need to
3587+In particular, to get non-default column alignment, you\[aq]ll need to
33653588add colons as above.
33663589.SS Metadata blocks
33673590.SS Extension: \f[C]pandoc_title_block\f[R]
@@ -3426,22 +3649,22 @@ All three metadata fields may contain standard inline formatting
34263649(italics, links, footnotes, etc.).
34273650.PP
34283651Title blocks will always be parsed, but they will affect the output only
3429−when the \f[C]\-\-standalone\f[R] (\f[C]\-s\f[R]) option is chosen.
3430−In HTML output, titles will appear twice: once in the document head \-\-
3652+when the \f[C]--standalone\f[R] (\f[C]-s\f[R]) option is chosen.
3653+In HTML output, titles will appear twice: once in the document head --
34313654this is the title that will appear at the top of the window in a browser
3432−\-\- and once at the beginning of the document body.
3655+-- and once at the beginning of the document body.
34333656The title in the document head can have an optional prefix attached
3434−(\f[C]\-\-title\-prefix\f[R] or \f[C]\-T\f[R] option).
3657+(\f[C]--title-prefix\f[R] or \f[C]-T\f[R] option).
34353658The title in the body appears as an H1 element with class
34363659\[dq]title\[dq], so it can be suppressed or reformatted with CSS.
3437−If a title prefix is specified with \f[C]\-T\f[R] and no title block
3660+If a title prefix is specified with \f[C]-T\f[R] and no title block
34383661appears in the document, the title prefix will be used by itself as the
34393662HTML title.
34403663.PP
34413664The man page writer extracts a title, man page section number, and other
34423665header and footer information from the title line.
34433666The title is assumed to be the first word on the title line, which may
3444−optionally end with a (single\-digit) section number in parentheses.
3667+optionally end with a (single-digit) section number in parentheses.
34453668(There should be no space between the title and the parentheses.)
34463669Anything after this is assumed to be additional footer and header text.
34473670A single pipe character (\f[C]|\f[R]) should be used to separate the
@@ -3474,8 +3697,8 @@ will also have \[dq]Version 4.0\[dq] in the header.
34743697.SS Extension: \f[C]yaml_metadata_block\f[R]
34753698.PP
34763699A YAML metadata block is a valid YAML object, delimited by a line of
3477−three hyphens (\f[C]\-\-\-\f[R]) at the top and a line of three hyphens
3478−(\f[C]\-\-\-\f[R]) or three dots (\f[C]...\f[R]) at the bottom.
3700+three hyphens (\f[C]---\f[R]) at the top and a line of three hyphens
3701+(\f[C]---\f[R]) or three dots (\f[C]...\f[R]) at the bottom.
34793702A YAML metadata block may occur anywhere in the document, but if it is
34803703not at the beginning, it must be preceded by a blank line.
34813704(Note that, because of the way pandoc concatenates input files when
@@ -3485,13 +3708,13 @@ files:
34853708.IP
34863709.nf
34873710\f[C]
3488−pandoc chap1.md chap2.md chap3.md metadata.yaml \-s \-o book.html
3711+pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
34893712\f[R]
34903713.fi
34913714.PP
3492−Just be sure that the YAML file begins with \f[C]\-\-\-\f[R] and ends
3493−with \f[C]\-\-\-\f[R] or \f[C]...\f[R].) Alternatively, you can use the
3494−\f[C]\-\-metadata\-file\f[R] option.
3715+Just be sure that the YAML file begins with \f[C]---\f[R] and ends with
3716+\f[C]---\f[R] or \f[C]...\f[R].) Alternatively, you can use the
3717+\f[C]--metadata-file\f[R] option.
34953718Using that approach however, you cannot reference content (like
34963719footnotes) from the main markdown input document.
34973720.PP
@@ -3506,13 +3729,13 @@ be interpretable as YAML numbers or boolean values (so, for example,
35063729names).
35073730.PP
35083731A document may contain multiple metadata blocks.
3509−The metadata fields will be combined through a \f[I]left\-biased
3732+The metadata fields will be combined through a \f[I]left-biased
35103733union\f[R]: if two metadata blocks attempt to set the same field, the
35113734value from the first block will be taken.
35123735.PP
3513−When pandoc is used with \f[C]\-t markdown\f[R] to create a Markdown
3736+When pandoc is used with \f[C]-t markdown\f[R] to create a Markdown
35143737document, a YAML metadata block will be produced only if the
3515−\f[C]\-s/\-\-standalone\f[R] option is used.
3738+\f[C]-s/--standalone\f[R] option is used.
35163739All of the metadata will appear in a single block at the beginning of
35173740the document.
35183741.PP
@@ -3521,15 +3744,15 @@ Thus, for example, if a title contains a colon, it must be quoted.
35213744The pipe character (\f[C]|\f[R]) can be used to begin an indented block
35223745that will be interpreted literally, without need for escaping.
35233746This form is necessary when the field contains blank lines or
3524−block\-level formatting:
3747+block-level formatting:
35253748.IP
35263749.nf
35273750\f[C]
3528−\-\-\-
3751+---
35293752title: \[aq]This is the title: it contains a colon\[aq]
35303753author:
3531−\- Author One
3532−\- Author Two
3754+- Author One
3755+- Author Two
35333756keywords: [nothing, nothingness]
35343757abstract: |
35353758 This is the abstract.
@@ -3561,12 +3784,12 @@ author if one is given:
35613784.IP
35623785.nf
35633786\f[C]
3564−\-\-\-
3787+---
35653788title: The document title
35663789author:
3567−\- name: Author One
3790+- name: Author One
35683791 affiliation: University of Somewhere
3569−\- name: Author Two
3792+- name: Author Two
35703793 affiliation: University of Nowhere
35713794\&...
35723795\f[R]
@@ -3588,7 +3811,7 @@ $endfor$
35883811.fi
35893812.PP
35903813Raw content to include in the document\[aq]s header may be specified
3591−using \f[C]header\-includes\f[R]; however, it is important to mark up
3814+using \f[C]header-includes\f[R]; however, it is important to mark up
35923815this content as raw code for a particular output format, using the
35933816\f[C]raw_attribute\f[R] extension), or it will be interpreted as
35943817markdown.
@@ -3596,8 +3819,8 @@ For example:
35963819.IP
35973820.nf
35983821\f[C]
3599−header\-includes:
3600−\- |
3822+header-includes:
3823+- |
36013824 \[ga]\[ga]\[ga]{=latex}
36023825 \[rs]let\[rs]oldsection\[rs]section
36033826 \[rs]renewcommand{\[rs]section}[1]{\[rs]clearpage\[rs]oldsection{#1}}
@@ -3635,22 +3858,22 @@ instead of
36353858.fi
36363859.PP
36373860This rule is easier to remember than standard Markdown\[aq]s rule, which
3638−allows only the following characters to be backslash\-escaped:
3861+allows only the following characters to be backslash-escaped:
36393862.IP
36403863.nf
36413864\f[C]
3642−\[rs]\[ga]*_{}[]()>#+\-.!
3865+\[rs]\[ga]*_{}[]()>#+-.!
36433866\f[R]
36443867.fi
36453868.PP
36463869(However, if the \f[C]markdown_strict\f[R] format is used, the standard
36473870Markdown rule will be used.)
36483871.PP
3649−A backslash\-escaped space is parsed as a nonbreaking space.
3872+A backslash-escaped space is parsed as a nonbreaking space.
36503873It will appear in TeX output as \f[C]\[ti]\f[R] and in HTML and XML as
36513874\f[C]\[rs] \f[R] or \f[C]\[rs] \f[R].
36523875.PP
3653−A backslash\-escaped newline (i.e.
3876+A backslash-escaped newline (i.e.
36543877a backslash occurring at the end of a line) is parsed as a hard line
36553878break.
36563879It will appear in TeX output as \f[C]\[rs]\[rs]\f[R] and in HTML as
@@ -3681,7 +3904,7 @@ This is **strong emphasis** and __with underscores__.
36813904.fi
36823905.PP
36833906A \f[C]*\f[R] or \f[C]_\f[R] character surrounded by spaces, or
3684−backslash\-escaped, will not trigger emphasis:
3907+backslash-escaped, will not trigger emphasis:
36853908.IP
36863909.nf
36873910\f[C]
@@ -3757,7 +3980,7 @@ The general rule is that a verbatim span starts with a string of
37573980consecutive backticks (optionally followed by a space) and ends with a
37583981string of the same number of backticks (optionally preceded by a space).
37593982.PP
3760−Note that backslash\-escapes (and other Markdown constructs) do not work
3983+Note that backslash-escapes (and other Markdown constructs) do not work
37613984in verbatim contexts:
37623985.IP
37633986.nf
@@ -3797,7 +4020,7 @@ For compatibility with other Markdown flavors, CSS is also supported:
37974020.IP
37984021.nf
37994022\f[C]
3800−<span style=\[dq]font\-variant:small\-caps;\[dq]>Small caps</span>
4023+<span style=\[dq]font-variant:small-caps;\[dq]>Small caps</span>
38014024\f[R]
38024025.fi
38034026.PP
@@ -3806,13 +4029,13 @@ This will work in all output formats that support small caps.
38064029.SS Extension: \f[C]tex_math_dollars\f[R]
38074030.PP
38084031Anything between two \f[C]$\f[R] characters will be treated as TeX math.
3809−The opening \f[C]$\f[R] must have a non\-space character immediately to
3810−its right, while the closing \f[C]$\f[R] must have a non\-space
3811−character immediately to its left, and must not be followed immediately
3812−by a digit.
4032+The opening \f[C]$\f[R] must have a non-space character immediately to
4033+its right, while the closing \f[C]$\f[R] must have a non-space character
4034+immediately to its left, and must not be followed immediately by a
4035+digit.
38134036Thus, \f[C]$20,000 and $30,000\f[R] won\[aq]t parse as math.
38144037If for some reason you need to enclose text in literal \f[C]$\f[R]
3815−characters, backslash\-escape them and they won\[aq]t be treated as math
4038+characters, backslash-escape them and they won\[aq]t be treated as math
38164039delimiters.
38174040.PP
38184041TeX math will be printed in all output formats.
@@ -3852,22 +4075,22 @@ otherwise appear verbatim.
38524075It will be rendered, if possible, using MathML.
38534076.TP
38544077.B DocBook
3855−If the \f[C]\-\-mathml\f[R] flag is used, it will be rendered using
3856−MathML in an \f[C]inlineequation\f[R] or \f[C]informalequation\f[R] tag.
4078+If the \f[C]--mathml\f[R] flag is used, it will be rendered using MathML
4079+in an \f[C]inlineequation\f[R] or \f[C]informalequation\f[R] tag.
38574080Otherwise it will be rendered, if possible, using Unicode characters.
38584081.TP
38594082.B Docx
38604083It will be rendered using OMML math markup.
38614084.TP
38624085.B FictionBook2
3863−If the \f[C]\-\-webtex\f[R] option is used, formulas are rendered as
4086+If the \f[C]--webtex\f[R] option is used, formulas are rendered as
38644087images using CodeCogs or other compatible web service, downloaded and
3865−embedded in the e\-book.
4088+embedded in the e-book.
38664089Otherwise, they will appear verbatim.
38674090.TP
38684091.B HTML, Slidy, DZSlides, S5, EPUB
3869−The way math is rendered in HTML will depend on the command\-line
3870−options selected.
4092+The way math is rendered in HTML will depend on the command-line options
4093+selected.
38714094Therefore see Math rendering in HTML above.
38724095.SS Raw HTML
38734096.SS Extension: \f[C]raw_html\f[R]
@@ -3883,10 +4106,13 @@ The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
38834106DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile
38844107output, and suppressed in other formats.
38854108.PP
4109+For a more explicit way of including raw HTML in a Markdown document,
4110+see the \f[C]raw_attribute\f[R] extension.
4111+.PP
38864112In the CommonMark format, if \f[C]raw_html\f[R] is enabled,
38874113superscripts, subscripts, strikeouts and small capitals will be
38884114represented as HTML.
3889−Otherwise, plain\-text fallbacks will be used.
4115+Otherwise, plain-text fallbacks will be used.
38904116Note that even if \f[C]raw_html\f[R] is disabled, tables will be
38914117rendered with HTML syntax if they cannot use pipe syntax.
38924118.SS Extension: \f[C]markdown_in_html_blocks\f[R]
@@ -3970,9 +4196,9 @@ Note that in LaTeX environments, like
39704196\f[C]
39714197\[rs]begin{tabular}{|l|l|}\[rs]hline
39724198Age & Frequency \[rs]\[rs] \[rs]hline
3973−18\-\-25 & 15 \[rs]\[rs]
3974−26\-\-35 & 33 \[rs]\[rs]
3975−36\-\-45 & 22 \[rs]\[rs] \[rs]hline
4199+18--25 & 15 \[rs]\[rs]
4200+26--35 & 33 \[rs]\[rs]
4201+36--45 & 22 \[rs]\[rs] \[rs]hline
39764202\[rs]end{tabular}
39774203\f[R]
39784204.fi
@@ -3980,6 +4206,9 @@ Age & Frequency \[rs]\[rs] \[rs]hline
39804206the material between the begin and end tags will be interpreted as raw
39814207LaTeX, not as Markdown.
39824208.PP
4209+For a more explicit and flexible way of including raw TeX in a Markdown
4210+document, see the \f[C]raw_attribute\f[R] extension.
4211+.PP
39834212Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
39844213Emacs Org mode, and ConTeXt.
39854214.SS Generic raw attribute
@@ -4022,13 +4251,13 @@ a pagebreak:
40224251.fi
40234252.PP
40244253The format name should match the target format name (see
4025−\f[C]\-t/\-\-to\f[R], above, for a list, or use
4026−\f[C]pandoc \-\-list\-output\-formats\f[R]).
4254+\f[C]-t/--to\f[R], above, for a list, or use
4255+\f[C]pandoc --list-output-formats\f[R]).
40274256Use \f[C]openxml\f[R] for \f[C]docx\f[R] output, \f[C]opendocument\f[R]
40284257for \f[C]odt\f[R] output, \f[C]html5\f[R] for \f[C]epub3\f[R] output,
40294258\f[C]html4\f[R] for \f[C]epub2\f[R] output, and \f[C]latex\f[R],
40304259\f[C]beamer\f[R], \f[C]ms\f[R], or \f[C]html5\f[R] for \f[C]pdf\f[R]
4031−output (depending on what you use for \f[C]\-\-pdf\-engine\f[R]).
4260+output (depending on what you use for \f[C]--pdf-engine\f[R]).
40324261.PP
40334262This extension presupposes that the relevant kind of inline code or
40344263fenced code block is enabled.
@@ -4302,11 +4531,10 @@ For example:
43024531\f[R]
43034532.fi
43044533.IP \[bu] 2
4305−Dimensions are converted to inches for output in page\-based formats
4306−like LaTeX.
4307−Dimensions are converted to pixels for output in HTML\-like formats.
4308−Use the \f[C]\-\-dpi\f[R] option to specify the number of pixels per
4309−inch.
4534+Dimensions are converted to inches for output in page-based formats like
4535+LaTeX.
4536+Dimensions are converted to pixels for output in HTML-like formats.
4537+Use the \f[C]--dpi\f[R] option to specify the number of pixels per inch.
43104538The default is 96dpi.
43114539.IP \[bu] 2
43124540The \f[C]%\f[R] unit is generally relative to some available space.
@@ -4417,8 +4645,8 @@ belong to the previous footnote.
44174645 { some.code }
44184646
44194647 The whole paragraph can be indented, or just the first
4420− line. In this way, multi\-paragraph footnotes work like
4421− multi\-paragraph list items.
4648+ line. In this way, multi-paragraph footnotes work like
4649+ multi-paragraph list items.
44224650
44234651This paragraph won\[aq]t be part of the note, because it
44244652isn\[aq]t indented.
@@ -4453,21 +4681,21 @@ Inline and regular footnotes may be mixed freely.
44534681.SS Citations
44544682.SS Extension: \f[C]citations\f[R]
44554683.PP
4456−Using an external filter, \f[C]pandoc\-citeproc\f[R], pandoc can
4684+Using an external filter, \f[C]pandoc-citeproc\f[R], pandoc can
44574685automatically generate citations and a bibliography in a number of
44584686styles.
44594687Basic usage is
44604688.IP
44614689.nf
44624690\f[C]
4463−pandoc \-\-filter pandoc\-citeproc myinput.txt
4691+pandoc --filter pandoc-citeproc myinput.txt
44644692\f[R]
44654693.fi
44664694.PP
44674695In order to use this feature, you will need to specify a bibliography
44684696file using the \f[C]bibliography\f[R] metadata field in a YAML metadata
4469−section, or \f[C]\-\-bibliography\f[R] command line argument.
4470−You can supply multiple \f[C]\-\-bibliography\f[R] arguments or set
4697+section, or \f[C]--bibliography\f[R] command line argument.
4698+You can supply multiple \f[C]--bibliography\f[R] arguments or set
44714699\f[C]bibliography\f[R] metadata field to YAML array, if you want to use
44724700multiple bibliography files.
44734701The bibliography may have any of these formats:
@@ -4541,13 +4769,13 @@ T}
45414769Note that \f[C].bib\f[R] can be used with both BibTeX and BibLaTeX
45424770files; use \f[C].bibtex\f[R] to force BibTeX.
45434771.PP
4544−Note that \f[C]pandoc\-citeproc \-\-bib2json\f[R] and
4545−\f[C]pandoc\-citeproc \-\-bib2yaml\f[R] can produce \f[C].json\f[R] and
4772+Note that \f[C]pandoc-citeproc --bib2json\f[R] and
4773+\f[C]pandoc-citeproc --bib2yaml\f[R] can produce \f[C].json\f[R] and
45464774\f[C].yaml\f[R] files from any of the supported formats.
45474775.PP
4548−In\-field markup: In BibTeX and BibLaTeX databases, pandoc\-citeproc
4776+In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc
45494777parses a subset of LaTeX markup; in CSL YAML databases, pandoc Markdown;
4550−and in CSL JSON databases, an HTML\-like markup:
4778+and in CSL JSON databases, an HTML-like markup:
45514779.TP
45524780.B \f[C]<i>...</i>\f[R]
45534781italics
@@ -4555,7 +4783,7 @@ italics
45554783.B \f[C]<b>...</b>\f[R]
45564784bold
45574785.TP
4558−.B \f[C]<span style=\[dq]font\-variant:small\-caps;\[dq]>...</span>\f[R] or \f[C]<sc>...</sc>\f[R]
4786+.B \f[C]<span style=\[dq]font-variant:small-caps;\[dq]>...</span>\f[R] or \f[C]<sc>...</sc>\f[R]
45594787small capitals
45604788.TP
45614789.B \f[C]<sub>...</sub>\f[R]
@@ -4567,60 +4795,60 @@ superscript
45674795.B \f[C]<span class=\[dq]nocase\[dq]>...</span>\f[R]
45684796prevent a phrase from being capitalized as title case
45694797.PP
4570−\f[C]pandoc\-citeproc \-j\f[R] and \f[C]\-y\f[R] interconvert the CSL
4571−JSON and CSL YAML formats as far as possible.
4798+\f[C]pandoc-citeproc -j\f[R] and \f[C]-y\f[R] interconvert the CSL JSON
4799+and CSL YAML formats as far as possible.
45724800.PP
45734801As an alternative to specifying a bibliography file using
4574−\f[C]\-\-bibliography\f[R] or the YAML metadata field
4802+\f[C]--bibliography\f[R] or the YAML metadata field
45754803\f[C]bibliography\f[R], you can include the citation data directly in
45764804the \f[C]references\f[R] field of the document\[aq]s YAML metadata.
4577−The field should contain an array of YAML\-encoded references, for
4805+The field should contain an array of YAML-encoded references, for
45784806example:
45794807.IP
45804808.nf
45814809\f[C]
4582−\-\-\-
4810+---
45834811references:
4584−\- type: article\-journal
4812+- type: article-journal
45854813 id: WatsonCrick1953
45864814 author:
4587− \- family: Watson
4815+ - family: Watson
45884816 given: J. D.
4589− \- family: Crick
4817+ - family: Crick
45904818 given: F. H. C.
45914819 issued:
4592− date\-parts:
4593− \- \- 1953
4594− \- 4
4595− \- 25
4820+ date-parts:
4821+ - - 1953
4822+ - 4
4823+ - 25
45964824 title: \[aq]Molecular structure of nucleic acids: a structure for deoxyribose
45974825 nucleic acid\[aq]
4598− title\-short: Molecular structure of nucleic acids
4599− container\-title: Nature
4826+ title-short: Molecular structure of nucleic acids
4827+ container-title: Nature
46004828 volume: 171
46014829 issue: 4356
4602− page: 737\-738
4830+ page: 737-738
46034831 DOI: 10.1038/171737a0
46044832 URL: http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html
4605− language: en\-GB
4833+ language: en-GB
46064834\&...
46074835\f[R]
46084836.fi
46094837.PP
4610−(\f[C]pandoc\-citeproc \-\-bib2yaml\f[R] can produce these from a
4838+(\f[C]pandoc-citeproc --bib2yaml\f[R] can produce these from a
46114839bibliography file in one of the supported formats.)
46124840.PP
46134841Citations and references can be formatted using any style supported by
46144842the Citation Style Language, listed in the Zotero Style Repository.
4615−These files are specified using the \f[C]\-\-csl\f[R] option or the
4843+These files are specified using the \f[C]--csl\f[R] option or the
46164844\f[C]csl\f[R] metadata field.
4617−By default, \f[C]pandoc\-citeproc\f[R] will use the Chicago Manual of
4618−Style author\-date format.
4845+By default, \f[C]pandoc-citeproc\f[R] will use the Chicago Manual of
4846+Style author-date format.
46194847The CSL project provides further information on finding and editing
46204848styles.
46214849.PP
46224850To make your citations hyperlinks to the corresponding bibliography
4623−entries, add \f[C]link\-citations: true\f[R] to your YAML metadata.
4851+entries, add \f[C]link-citations: true\f[R] to your YAML metadata.
46244852.PP
46254853Citations go inside square brackets and are separated by semicolons.
46264854Each citation must have a key, composed of \[aq]\[at]\[aq] + the
@@ -4628,23 +4856,22 @@ citation identifier from the database, and may optionally have a prefix,
46284856a locator, and a suffix.
46294857The citation key must begin with a letter, digit, or \f[C]_\f[R], and
46304858may contain alphanumerics, \f[C]_\f[R], and internal punctuation
4631−characters (\f[C]:.#$%&\-+?<>\[ti]/\f[R]).
4859+characters (\f[C]:.#$%&-+?<>\[ti]/\f[R]).
46324860Here are some examples:
46334861.IP
46344862.nf
46354863\f[C]
4636−Blah blah [see \[at]doe99, pp. 33\-35; also \[at]smith04, chap. 1].
4864+Blah blah [see \[at]doe99, pp. 33-35; also \[at]smith04, chap. 1].
46374865
4638−Blah blah [\[at]doe99, pp. 33\-35, 38\-39 and *passim*].
4866+Blah blah [\[at]doe99, pp. 33-35, 38-39 and *passim*].
46394867
46404868Blah blah [\[at]smith04; \[at]doe99].
46414869\f[R]
46424870.fi
46434871.PP
4644−\f[C]pandoc\-citeproc\f[R] detects locator terms in the CSL locale
4645−files.
4872+\f[C]pandoc-citeproc\f[R] detects locator terms in the CSL locale files.
46464873Either abbreviated or unabbreviated forms are accepted.
4647−In the \f[C]en\-US\f[R] locale, locator terms can be written in either
4874+In the \f[C]en-US\f[R] locale, locator terms can be written in either
46484875singular or plural forms, as \f[C]book\f[R],
46494876\f[C]bk.\f[R]/\f[C]bks.\f[R]; \f[C]chapter\f[R],
46504877\f[C]chap.\f[R]/\f[C]chaps.\f[R]; \f[C]column\f[R],
@@ -4664,29 +4891,29 @@ singular or plural forms, as \f[C]book\f[R],
46644891\f[C]\[sc]\f[R]/\f[C]\[sc]\[sc]\f[R].
46654892If no locator term is used, \[dq]page\[dq] is assumed.
46664893.PP
4667−\f[C]pandoc\-citeproc\f[R] will use heuristics to distinguish the
4668−locator from the suffix.
4894+\f[C]pandoc-citeproc\f[R] will use heuristics to distinguish the locator
4895+from the suffix.
46694896In complex cases, the locator can be enclosed in curly braces (using
4670−\f[C]pandoc\-citeproc\f[R] 0.15 and higher only):
4897+\f[C]pandoc-citeproc\f[R] 0.15 and higher only):
46714898.IP
46724899.nf
46734900\f[C]
4674−[\[at]smith{ii, A, D\-Z}, with a suffix]
4675−[\[at]smith, {pp. iv, vi\-xi, (xv)\-(xvii)} with suffix here]
4901+[\[at]smith{ii, A, D-Z}, with a suffix]
4902+[\[at]smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
46764903\f[R]
46774904.fi
46784905.PP
4679−A minus sign (\f[C]\-\f[R]) before the \f[C]\[at]\f[R] will suppress
4906+A minus sign (\f[C]-\f[R]) before the \f[C]\[at]\f[R] will suppress
46804907mention of the author in the citation.
46814908This can be useful when the author is already mentioned in the text:
46824909.IP
46834910.nf
46844911\f[C]
4685−Smith says blah [\-\[at]smith04].
4912+Smith says blah [-\[at]smith04].
46864913\f[R]
46874914.fi
46884915.PP
4689−You can also write an in\-text citation, as follows:
4916+You can also write an in-text citation, as follows:
46904917.IP
46914918.nf
46924919\f[C]
@@ -4701,19 +4928,19 @@ with id \f[C]refs\f[R], if one exists:
47014928.IP
47024929.nf
47034930\f[C]
4704−::: #refs
4931+::: {#refs}
47054932:::
47064933\f[R]
47074934.fi
47084935.PP
47094936Otherwise, it will be placed at the end of the document.
47104937Generation of the bibliography can be suppressed by setting
4711−\f[C]suppress\-bibliography: true\f[R] in the YAML metadata.
4938+\f[C]suppress-bibliography: true\f[R] in the YAML metadata.
47124939.PP
47134940If you wish the bibliography to have a section header, you can set
4714−\f[C]reference\-section\-title\f[R] in the metadata, or put the header
4715−at the beginning of the div with id \f[C]refs\f[R] (if you are using it)
4716−or at the end of your document:
4941+\f[C]reference-section-title\f[R] in the metadata, or put the header at
4942+the beginning of the div with id \f[C]refs\f[R] (if you are using it) or
4943+at the end of your document:
47174944.IP
47184945.nf
47194946\f[C]
@@ -4733,7 +4960,7 @@ field and put the citations there:
47334960.IP
47344961.nf
47354962\f[C]
4736−\-\-\-
4963+---
47374964nocite: |
47384965 \[at]item1, \[at]item2
47394966\&...
@@ -4751,7 +4978,7 @@ or not they appear in the document, by using a wildcard:
47514978.IP
47524979.nf
47534980\f[C]
4754−\-\-\-
4981+---
47554982nocite: |
47564983 \[at]*
47574984\&...
@@ -4761,13 +4988,13 @@ nocite: |
47614988For LaTeX output, you can also use \f[C]natbib\f[R] or
47624989\f[C]biblatex\f[R] to render the bibliography.
47634990In order to do so, specify bibliography files as outlined above, and add
4764−\f[C]\-\-natbib\f[R] or \f[C]\-\-biblatex\f[R] argument to
4765−\f[C]pandoc\f[R] invocation.
4991+\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] argument to \f[C]pandoc\f[R]
4992+invocation.
47664993Bear in mind that bibliography files have to be in respective format
47674994(either BibTeX or BibLaTeX).
47684995.PP
4769−For more information, see the pandoc\-citeproc man page.
4770−.SS Non\-pandoc extensions
4996+For more information, see the pandoc-citeproc man page.
4997+.SS Non-pandoc extensions
47714998.PP
47724999The following Markdown syntax extensions are not enabled by default in
47735000pandoc, but may be enabled by adding \f[C]+EXTENSION\f[R] to the format
@@ -4777,13 +5004,13 @@ hard line breaks.
47775004.SS Extension: \f[C]old_dashes\f[R]
47785005.PP
47795006Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes:
4780−\f[C]\-\f[R] before a numeral is an en\-dash, and \f[C]\-\-\f[R] is an
4781−em\-dash.
5007+\f[C]-\f[R] before a numeral is an en-dash, and \f[C]--\f[R] is an
5008+em-dash.
47825009This option only has an effect if \f[C]smart\f[R] is enabled.
47835010It is selected automatically for \f[C]textile\f[R] input.
47845011.SS Extension: \f[C]angle_brackets_escapable\f[R]
47855012.PP
4786−Allow \f[C]<\f[R] and \f[C]>\f[R] to be backslash\-escaped, as they can
5013+Allow \f[C]<\f[R] and \f[C]>\f[R] to be backslash-escaped, as they can
47875014be in GitHub flavored Markdown but not original Markdown.
47885015This is implied by pandoc\[aq]s default \f[C]all_symbols_escapable\f[R].
47895016.SS Extension: \f[C]lists_without_preceding_blankline\f[R]
@@ -4840,10 +5067,10 @@ to be interpreted as inline TeX math, and anything between
48405067display TeX math.
48415068.SS Extension: \f[C]markdown_attribute\f[R]
48425069.PP
4843−By default, pandoc interprets material inside block\-level tags as
5070+By default, pandoc interprets material inside block-level tags as
48445071Markdown.
48455072This extension changes the behavior so that Markdown is only parsed
4846−inside block\-level tags if the tags have the attribute
5073+inside block-level tags if the tags have the attribute
48475074\f[C]markdown=1\f[R].
48485075.SS Extension: \f[C]mmd_title_block\f[R]
48495076.PP
@@ -4882,7 +5109,7 @@ Makes all absolute URIs into links, even when not surrounded by pointy
48825109braces \f[C]<...>\f[R].
48835110.SS Extension: \f[C]mmd_link_attributes\f[R]
48845111.PP
4885−Parses multimarkdown style key\-value attributes on link and image
5112+Parses multimarkdown style key-value attributes on link and image
48865113references.
48875114This extension should not be confused with the \f[C]link_attributes\f[R]
48885115extension.
@@ -4927,12 +5154,12 @@ variants are supported:
49275154\f[C]abbreviations\f[R], \f[C]shortcut_reference_links\f[R],
49285155\f[C]spaced_reference_links\f[R].
49295156.TP
4930−.B \f[C]markdown_github\f[R] (deprecated GitHub\-Flavored Markdown)
5157+.B \f[C]markdown_github\f[R] (deprecated GitHub-Flavored Markdown)
49315158\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]fenced_code_blocks\f[R],
49325159\f[C]auto_identifiers\f[R], \f[C]gfm_auto_identifiers\f[R],
49335160\f[C]backtick_code_blocks\f[R], \f[C]autolink_bare_uris\f[R],
49345161\f[C]space_in_atx_header\f[R], \f[C]intraword_underscores\f[R],
4935−\f[C]strikeout\f[R], \f[C]emoji\f[R],
5162+\f[C]strikeout\f[R], \f[C]task_lists\f[R], \f[C]emoji\f[R],
49365163\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R],
49375164\f[C]lists_without_preceding_blankline\f[R].
49385165.TP
@@ -4952,23 +5179,23 @@ variants are supported:
49525179\f[C]raw_html\f[R], \f[C]shortcut_reference_links\f[R],
49535180\f[C]spaced_reference_links\f[R].
49545181.PP
4955−We also support \f[C]commonmark\f[R] and \f[C]gfm\f[R] (GitHub\-Flavored
5182+We also support \f[C]commonmark\f[R] and \f[C]gfm\f[R] (GitHub-Flavored
49565183Markdown, which is implemented as a set of extensions on
49575184\f[C]commonmark\f[R]).
49585185.PP
49595186Note, however, that \f[C]commonmark\f[R] and \f[C]gfm\f[R] have limited
49605187support for extensions.
4961−Only those listed below (and \f[C]smart\f[R] and \f[C]raw_tex\f[R]) will
4962−work.
5188+Only those listed below (and \f[C]smart\f[R], \f[C]raw_tex\f[R], and
5189+\f[C]hard_line_breaks\f[R]) will work.
49635190The extensions can, however, all be individually disabled.
49645191Also, \f[C]raw_tex\f[R] only affects \f[C]gfm\f[R] output, not input.
49655192.TP
4966−.B \f[C]gfm\f[R] (GitHub\-Flavored Markdown)
5193+.B \f[C]gfm\f[R] (GitHub-Flavored Markdown)
49675194\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]fenced_code_blocks\f[R],
49685195\f[C]auto_identifiers\f[R], \f[C]gfm_auto_identifiers\f[R],
49695196\f[C]backtick_code_blocks\f[R], \f[C]autolink_bare_uris\f[R],
49705197\f[C]space_in_atx_header\f[R], \f[C]intraword_underscores\f[R],
4971−\f[C]strikeout\f[R], \f[C]emoji\f[R],
5198+\f[C]strikeout\f[R], \f[C]task_lists\f[R], \f[C]emoji\f[R],
49725199\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R],
49735200\f[C]lists_without_preceding_blankline\f[R].
49745201.SH PRODUCING SLIDE SHOWS WITH PANDOC
@@ -4993,29 +5220,29 @@ Here\[aq]s the Markdown source for a simple slide show,
49935220
49945221## Getting up
49955222
4996−\- Turn off alarm
4997−\- Get out of bed
5223+- Turn off alarm
5224+- Get out of bed
49985225
49995226## Breakfast
50005227
5001−\- Eat eggs
5002−\- Drink coffee
5228+- Eat eggs
5229+- Drink coffee
50035230
50045231# In the evening
50055232
50065233## Dinner
50075234
5008−\- Eat spaghetti
5009−\- Drink wine
5235+- Eat spaghetti
5236+- Drink wine
50105237
5011−\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
5238+------------------
50125239
50135240
50145241
50155242## Going to sleep
50165243
5017−\- Get in bed
5018−\- Count sheep
5244+- Get in bed
5245+- Count sheep
50195246\f[R]
50205247.fi
50215248.PP
@@ -5023,7 +5250,7 @@ To produce an HTML/JavaScript slide show, simply type
50235250.IP
50245251.nf
50255252\f[C]
5026−pandoc \-t FORMAT \-s habits.txt \-o habits.html
5253+pandoc -t FORMAT -s habits.txt -o habits.html
50275254\f[R]
50285255.fi
50295256.PP
@@ -5031,27 +5258,27 @@ where \f[C]FORMAT\f[R] is either \f[C]s5\f[R], \f[C]slidy\f[R],
50315258\f[C]slideous\f[R], \f[C]dzslides\f[R], or \f[C]revealjs\f[R].
50325259.PP
50335260For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with
5034−the \f[C]\-s/\-\-standalone\f[R] option embeds a link to JavaScript and
5035−CSS files, which are assumed to be available at the relative path
5261+the \f[C]-s/--standalone\f[R] option embeds a link to JavaScript and CSS
5262+files, which are assumed to be available at the relative path
50365263\f[C]s5/default\f[R] (for S5), \f[C]slideous\f[R] (for Slideous),
50375264\f[C]reveal.js\f[R] (for reveal.js), or at the Slidy website at
50385265\f[C]w3.org\f[R] (for Slidy).
5039−(These paths can be changed by setting the \f[C]slidy\-url\f[R],
5040−\f[C]slideous\-url\f[R], \f[C]revealjs\-url\f[R], or \f[C]s5\-url\f[R]
5041−variables; see Variables for slides, above.) For DZSlides, the
5266+(These paths can be changed by setting the \f[C]slidy-url\f[R],
5267+\f[C]slideous-url\f[R], \f[C]revealjs-url\f[R], or \f[C]s5-url\f[R]
5268+variables; see Variables for HTML slides, above.) For DZSlides, the
50425269(relatively short) JavaScript and CSS are included in the file by
50435270default.
50445271.PP
5045−With all HTML slide formats, the \f[C]\-\-self\-contained\f[R] option
5046−can be used to produce a single file that contains all of the data
5047−necessary to display the slide show, including linked scripts,
5048−stylesheets, images, and videos.
5272+With all HTML slide formats, the \f[C]--self-contained\f[R] option can
5273+be used to produce a single file that contains all of the data necessary
5274+to display the slide show, including linked scripts, stylesheets,
5275+images, and videos.
50495276.PP
50505277To produce a PDF slide show using beamer, type
50515278.IP
50525279.nf
50535280\f[C]
5054−pandoc \-t beamer habits.txt \-o habits.pdf
5281+pandoc -t beamer habits.txt -o habits.pdf
50555282\f[R]
50565283.fi
50575284.PP
@@ -5062,7 +5289,7 @@ To produce a Powerpoint slide show, type
50625289.IP
50635290.nf
50645291\f[C]
5065−pandoc habits.txt \-o habits.pptx
5292+pandoc habits.txt -o habits.pptx
50665293\f[R]
50675294.fi
50685295.SS Structuring the slide show
@@ -5072,8 +5299,7 @@ hierarchy that is followed immediately by content, and not another
50725299header, somewhere in the document.
50735300In the example above, level 1 headers are always followed by level 2
50745301headers, which are followed by content, so 2 is the slide level.
5075−This default can be overridden using the \f[C]\-\-slide\-level\f[R]
5076−option.
5302+This default can be overridden using the \f[C]--slide-level\f[R] option.
50775303.PP
50785304The document is carved up into slides according to the following rules:
50795305.IP \[bu] 2
@@ -5102,7 +5328,7 @@ subsections, you can just use level 1 headers for all each slide.
51025328(In that case, level 1 will be the slide level.) But you can also
51035329structure the slide show into sections, as in the example above.
51045330.PP
5105−Note: in reveal.js slide shows, if slide level is 2, a two\-dimensional
5331+Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
51065332layout will be produced, with level 1 headers building horizontally and
51075333level 2 headers building vertically.
51085334It is not recommended that you use deeper nesting of section levels with
@@ -5111,7 +5337,7 @@ reveal.js.
51115337.PP
51125338By default, these writers produce lists that display \[dq]all at
51135339once.\[dq] If you want your lists to display incrementally (one item at
5114−a time), use the \f[C]\-i\f[R] option.
5340+a time), use the \f[C]-i\f[R] option.
51155341If you want a particular list to depart from the default, put it in a
51165342\f[C]div\f[R] block with class \f[C]incremental\f[R] or
51175343\f[C]nonincremental\f[R].
@@ -5122,8 +5348,8 @@ would be incremental regardless of the document default:
51225348\f[C]
51235349::: incremental
51245350
5125−\- Eat spaghetti
5126−\- Drink wine
5351+- Eat spaghetti
5352+- Drink wine
51275353
51285354:::
51295355\f[R]
@@ -5135,24 +5361,24 @@ or
51355361\f[C]
51365362::: nonincremental
51375363
5138−\- Eat spaghetti
5139−\- Drink wine
5364+- Eat spaghetti
5365+- Drink wine
51405366
51415367:::
51425368\f[R]
51435369.fi
51445370.PP
51455371While using \f[C]incremental\f[R] and \f[C]nonincremental\f[R] divs are
5146−the recommended method of setting incremental lists on a per\-case
5147−basis, an older method is also supported: putting lists inside a
5148−blockquote will depart from the document default (that is, it will
5149−display incrementally without the \f[C]\-i\f[R] option and all at once
5150−with the \f[C]\-i\f[R] option):
5372+the recommended method of setting incremental lists on a per-case basis,
5373+an older method is also supported: putting lists inside a blockquote
5374+will depart from the document default (that is, it will display
5375+incrementally without the \f[C]-i\f[R] option and all at once with the
5376+\f[C]-i\f[R] option):
51515377.IP
51525378.nf
51535379\f[C]
5154−> \- Eat spaghetti
5155−> \- Drink wine
5380+> - Eat spaghetti
5381+> - Drink wine
51565382\f[R]
51575383.fi
51585384.PP
@@ -5179,10 +5405,10 @@ content after the pause
51795405You can change the style of HTML slides by putting customized CSS files
51805406in \f[C]$DATADIR/s5/default\f[R] (for S5), \f[C]$DATADIR/slidy\f[R] (for
51815407Slidy), or \f[C]$DATADIR/slideous\f[R] (for Slideous), where
5182−\f[C]$DATADIR\f[R] is the user data directory (see
5183−\f[C]\-\-data\-dir\f[R], above).
5408+\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
5409+above).
51845410The originals may be found in pandoc\[aq]s system data directory
5185−(generally \f[C]$CABALDIR/pandoc\-VERSION/s5/default\f[R]).
5411+(generally \f[C]$CABALDIR/pandoc-VERSION/s5/default\f[R]).
51865412Pandoc will look there for any files it does not find in the user data
51875413directory.
51885414.PP
@@ -5194,20 +5420,19 @@ For example, themes can be used by setting the \f[C]theme\f[R] variable:
51945420.IP
51955421.nf
51965422\f[C]
5197−\-V theme=moon
5423+-V theme=moon
51985424\f[R]
51995425.fi
52005426.PP
5201−Or you can specify a custom stylesheet using the \f[C]\-\-css\f[R]
5202−option.
5427+Or you can specify a custom stylesheet using the \f[C]--css\f[R] option.
52035428.PP
52045429To style beamer slides, you can specify a \f[C]theme\f[R],
52055430\f[C]colortheme\f[R], \f[C]fonttheme\f[R], \f[C]innertheme\f[R], and
5206−\f[C]outertheme\f[R], using the \f[C]\-V\f[R] option:
5431+\f[C]outertheme\f[R], using the \f[C]-V\f[R] option:
52075432.IP
52085433.nf
52095434\f[C]
5210−pandoc \-t beamer habits.txt \-V theme:Warsaw \-o habits.pdf
5435+pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
52115436\f[R]
52125437.fi
52135438.PP
@@ -5236,8 +5461,8 @@ You can add notes to your Markdown document thus:
52365461
52375462This is my note.
52385463
5239−\- It can contain Markdown
5240−\- like this list
5464+- It can contain Markdown
5465+- like this list
52415466
52425467:::
52435468\f[R]
@@ -5289,32 +5514,32 @@ User\[aq]s Guide may also be used: \f[C]allowdisplaybreaks\f[R],
52895514\f[C]shrink\f[R], \f[C]standout\f[R], \f[C]noframenumbering\f[R].
52905515.SS Background in reveal.js and beamer
52915516.PP
5292−Background images can be added to self\-contained reveal.js slideshows
5517+Background images can be added to self-contained reveal.js slideshows
52935518and to beamer slideshows.
52945519.PP
52955520For the same image on every slide, use the configuration option
5296−\f[C]background\-image\f[R] either in the YAML metadata block or as a
5297−command\-line variable.
5521+\f[C]background-image\f[R] either in the YAML metadata block or as a
5522+command-line variable.
52985523(There are no other options in beamer and the rest of this section
52995524concerns reveal.js slideshows.)
53005525.PP
5301−For reveal.js, you can instead use the reveal.js\-native option
5526+For reveal.js, you can instead use the reveal.js-native option
53025527\f[C]parallaxBackgroundImage\f[R].
53035528You can also set \f[C]parallaxBackgroundHorizontal\f[R] and
53045529\f[C]parallaxBackgroundVertical\f[R] the same way and must also set
53055530\f[C]parallaxBackgroundSize\f[R] to have your values take effect.
53065531.PP
53075532To set an image for a particular reveal.js slide, add
5308−\f[C]{data\-background\-image=\[dq]/path/to/image\[dq]}\f[R] to the
5309−first slide\-level header on the slide (which may even be empty).
5533+\f[C]{data-background-image=\[dq]/path/to/image\[dq]}\f[R] to the first
5534+slide-level header on the slide (which may even be empty).
53105535.PP
53115536In reveal.js\[aq]s overview mode, the parallaxBackgroundImage will show
53125537up only on the first slide.
53135538.PP
53145539Other reveal.js background settings also work on individual slides,
5315−including \f[C]data\-background\-size\f[R],
5316−\f[C]data\-background\-repeat\f[R], \f[C]data\-background\-color\f[R],
5317−\f[C]data\-transition\f[R], and \f[C]data\-transition\-speed\f[R].
5540+including \f[C]data-background-size\f[R],
5541+\f[C]data-background-repeat\f[R], \f[C]data-background-color\f[R],
5542+\f[C]data-transition\f[R], and \f[C]data-transition-speed\f[R].
53185543.PP
53195544See the reveal.js documentation for more details.
53205545.PP
@@ -5322,16 +5547,16 @@ For example in reveal.js:
53225547.IP
53235548.nf
53245549\f[C]
5325−\-\-\-
5550+---
53265551title: My Slideshow
53275552parallaxBackgroundImage: /path/to/my/background_image.png
5328−\-\-\-
5553+---
53295554
53305555## Slide One
53315556
53325557Slide 1 has background_image.png as its background.
53335558
5334−## {data\-background\-image=\[dq]/path/to/special_image.jpg\[dq]}
5559+## {data-background-image=\[dq]/path/to/special_image.jpg\[dq]}
53355560
53365561Slide 2 has a special image for its background, even though the header has no content.
53375562\f[R]
@@ -5339,29 +5564,29 @@ Slide 2 has a special image for its background, even though the header has no co
53395564.SH CREATING EPUBS WITH PANDOC
53405565.SS EPUB Metadata
53415566.PP
5342−EPUB metadata may be specified using the \f[C]\-\-epub\-metadata\f[R]
5567+EPUB metadata may be specified using the \f[C]--epub-metadata\f[R]
53435568option, but if the source document is Markdown, it is better to use a
53445569YAML metadata block.
53455570Here is an example:
53465571.IP
53475572.nf
53485573\f[C]
5349−\-\-\-
5574+---
53505575title:
5351−\- type: main
5576+- type: main
53525577 text: My Book
5353−\- type: subtitle
5578+- type: subtitle
53545579 text: An investigation of metadata
53555580creator:
5356−\- role: author
5581+- role: author
53575582 text: John Smith
5358−\- role: editor
5583+- role: editor
53595584 text: Sarah Jones
53605585identifier:
5361−\- scheme: DOI
5586+- scheme: DOI
53625587 text: doi:10.234234.234/33
53635588publisher: My Press
5364−rights: \[co] 2007 John Smith, CC BY\-NC
5589+rights: \[co] 2007 John Smith, CC BY-NC
53655590ibooks:
53665591 version: 1.3.4
53675592\&...
@@ -5373,14 +5598,14 @@ The following fields are recognized:
53735598.B \f[C]identifier\f[R]
53745599Either a string value or an object with fields \f[C]text\f[R] and
53755600\f[C]scheme\f[R].
5376−Valid values for \f[C]scheme\f[R] are \f[C]ISBN\-10\f[R],
5377−\f[C]GTIN\-13\f[R], \f[C]UPC\f[R], \f[C]ISMN\-10\f[R], \f[C]DOI\f[R],
5378−\f[C]LCCN\f[R], \f[C]GTIN\-14\f[R], \f[C]ISBN\-13\f[R],
5601+Valid values for \f[C]scheme\f[R] are \f[C]ISBN-10\f[R],
5602+\f[C]GTIN-13\f[R], \f[C]UPC\f[R], \f[C]ISMN-10\f[R], \f[C]DOI\f[R],
5603+\f[C]LCCN\f[R], \f[C]GTIN-14\f[R], \f[C]ISBN-13\f[R],
53795604\f[C]Legal deposit number\f[R], \f[C]URN\f[R], \f[C]OCLC\f[R],
5380−\f[C]ISMN\-13\f[R], \f[C]ISBN\-A\f[R], \f[C]JP\f[R], \f[C]OLCC\f[R].
5605+\f[C]ISMN-13\f[R], \f[C]ISBN-A\f[R], \f[C]JP\f[R], \f[C]OLCC\f[R].
53815606.TP
53825607.B \f[C]title\f[R]
5383−Either a string value, or an object with fields \f[C]file\-as\f[R] and
5608+Either a string value, or an object with fields \f[C]file-as\f[R] and
53845609\f[C]type\f[R], or a list of such objects.
53855610Valid values for \f[C]type\f[R] are \f[C]main\f[R], \f[C]subtitle\f[R],
53865611\f[C]short\f[R], \f[C]collection\f[R], \f[C]edition\f[R],
@@ -5388,16 +5613,16 @@ Valid values for \f[C]type\f[R] are \f[C]main\f[R], \f[C]subtitle\f[R],
53885613.TP
53895614.B \f[C]creator\f[R]
53905615Either a string value, or an object with fields \f[C]role\f[R],
5391−\f[C]file\-as\f[R], and \f[C]text\f[R], or a list of such objects.
5616+\f[C]file-as\f[R], and \f[C]text\f[R], or a list of such objects.
53925617Valid values for \f[C]role\f[R] are MARC relators, but pandoc will
5393−attempt to translate the human\-readable versions (like \[dq]author\[dq]
5618+attempt to translate the human-readable versions (like \[dq]author\[dq]
53945619and \[dq]editor\[dq]) to the appropriate marc relators.
53955620.TP
53965621.B \f[C]contributor\f[R]
53975622Same format as \f[C]creator\f[R].
53985623.TP
53995624.B \f[C]date\f[R]
5400−A string value in \f[C]YYYY\-MM\-DD\f[R] format.
5625+A string value in \f[C]YYYY-MM-DD\f[R] format.
54015626(Only the year is necessary.) Pandoc will attempt to convert other
54025627common date formats.
54035628.TP
@@ -5426,36 +5651,36 @@ A string value.
54265651.B \f[C]rights\f[R]
54275652A string value.
54285653.TP
5429−.B \f[C]cover\-image\f[R]
5654+.B \f[C]cover-image\f[R]
54305655A string value (path to cover image).
54315656.TP
54325657.B \f[C]css\f[R] (or legacy: \f[C]stylesheet\f[R])
54335658A string value (path to CSS stylesheet).
54345659.TP
5435−.B \f[C]page\-progression\-direction\f[R]
5660+.B \f[C]page-progression-direction\f[R]
54365661Either \f[C]ltr\f[R] or \f[C]rtl\f[R].
5437−Specifies the \f[C]page\-progression\-direction\f[R] attribute for the
5662+Specifies the \f[C]page-progression-direction\f[R] attribute for the
54385663\f[C]spine\f[R] element.
54395664.TP
54405665.B \f[C]ibooks\f[R]
5441−iBooks\-specific metadata, with the following fields:
5666+iBooks-specific metadata, with the following fields:
54425667.RS
54435668.IP \[bu] 2
54445669\f[C]version\f[R]: (string)
54455670.IP \[bu] 2
5446−\f[C]specified\-fonts\f[R]: \f[C]true\f[R]|\f[C]false\f[R] (default
5671+\f[C]specified-fonts\f[R]: \f[C]true\f[R]|\f[C]false\f[R] (default
54475672\f[C]false\f[R])
54485673.IP \[bu] 2
5449−\f[C]ipad\-orientation\-lock\f[R]:
5450−\f[C]portrait\-only\f[R]|\f[C]landscape\-only\f[R]
5674+\f[C]ipad-orientation-lock\f[R]:
5675+\f[C]portrait-only\f[R]|\f[C]landscape-only\f[R]
54515676.IP \[bu] 2
5452−\f[C]iphone\-orientation\-lock\f[R]:
5453−\f[C]portrait\-only\f[R]|\f[C]landscape\-only\f[R]
5677+\f[C]iphone-orientation-lock\f[R]:
5678+\f[C]portrait-only\f[R]|\f[C]landscape-only\f[R]
54545679.IP \[bu] 2
54555680\f[C]binding\f[R]: \f[C]true\f[R]|\f[C]false\f[R] (default
54565681\f[C]true\f[R])
54575682.IP \[bu] 2
5458−\f[C]scroll\-axis\f[R]:
5683+\f[C]scroll-axis\f[R]:
54595684\f[C]vertical\f[R]|\f[C]horizontal\f[R]|\f[C]default\f[R]
54605685.RE
54615686.SS The \f[C]epub:type\f[R] attribute
@@ -5510,7 +5735,7 @@ T}@T{
55105735frontmatter
55115736T}
55125737T{
5513−copyright\-page
5738+copyright-page
55145739T}@T{
55155740frontmatter
55165741T}
@@ -5580,9 +5805,9 @@ T}
55805805By default, pandoc will download media referenced from any
55815806\f[C]<img>\f[R], \f[C]<audio>\f[R], \f[C]<video>\f[R] or
55825807\f[C]<source>\f[R] element present in the generated EPUB, and include it
5583−in the EPUB container, yielding a completely self\-contained EPUB.
5808+in the EPUB container, yielding a completely self-contained EPUB.
55845809If you want to link to external media resources instead, use raw HTML in
5585−your source and add \f[C]data\-external=\[dq]1\[dq]\f[R] to the tag with
5810+your source and add \f[C]data-external=\[dq]1\[dq]\f[R] to the tag with
55865811the \f[C]src\f[R] attribute.
55875812For example:
55885813.IP
@@ -5590,11 +5815,122 @@ For example:
55905815\f[C]
55915816<audio controls=\[dq]1\[dq]>
55925817 <source src=\[dq]http://example.com/music/toccata.mp3\[dq]
5593− data\-external=\[dq]1\[dq] type=\[dq]audio/mpeg\[dq]>
5818+ data-external=\[dq]1\[dq] type=\[dq]audio/mpeg\[dq]>
55945819 </source>
55955820</audio>
55965821\f[R]
55975822.fi
5823+.SH CREATING JUPYTER NOTEBOOKS WITH PANDOC
5824+.PP
5825+When creating a Jupyter notebook, pandoc will try to infer the notebook
5826+structure.
5827+Code blocks with the class \f[C]code\f[R] will be taken as code cells,
5828+and intervening content will be taken as Markdown cells.
5829+Attachments will automatically be created for images in Markdown cells.
5830+Metadata will be taken from the \f[C]jupyter\f[R] metadata field.
5831+For example:
5832+.IP
5833+.nf
5834+\f[C]
5835+---
5836+title: My notebook
5837+jupyter:
5838+ nbformat: 4
5839+ nbformat_minor: 5
5840+ kernelspec:
5841+ display_name: Python 2
5842+ language: python
5843+ name: python2
5844+ language_info:
5845+ codemirror_mode:
5846+ name: ipython
5847+ version: 2
5848+ file_extension: \[dq].py\[dq]
5849+ mimetype: \[dq]text/x-python\[dq]
5850+ name: \[dq]python\[dq]
5851+ nbconvert_exporter: \[dq]python\[dq]
5852+ pygments_lexer: \[dq]ipython2\[dq]
5853+ version: \[dq]2.7.15\[dq]
5854+---
5855+
5856+# Lorem ipsum
5857+
5858+**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
5859+bibendum felis dictum sodales.
5860+
5861+\[ga]\[ga]\[ga] code
5862+print(\[dq]hello\[dq])
5863+\[ga]\[ga]\[ga]
5864+
5865+## Pyout
5866+
5867+\[ga]\[ga]\[ga] code
5868+from IPython.display import HTML
5869+HTML(\[dq]\[dq]\[dq]
5870+<script>
5871+console.log(\[dq]hello\[dq]);
5872+</script>
5873+<b>HTML</b>
5874+\[dq]\[dq]\[dq])
5875+\[ga]\[ga]\[ga]
5876+
5877+## Image
5878+
5879+This image  will be
5880+included as a cell attachment.
5881+\f[R]
5882+.fi
5883+.PP
5884+If you want to add cell attributes, group cells differently, or add
5885+output to code cells, then you need to include divs to indicate the
5886+structure.
5887+You can use either fenced divs or native divs for this.
5888+Here is an example:
5889+.IP
5890+.nf
5891+\f[C]
5892+:::::: {.cell .markdown}
5893+# Lorem
5894+
5895+**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
5896+bibendum felis dictum sodales.
5897+::::::
5898+
5899+:::::: {.cell .code execution_count=1}
5900+\[ga]\[ga]\[ga] {.python}
5901+print(\[dq]hello\[dq])
5902+\[ga]\[ga]\[ga]
5903+
5904+::: {.output .stream .stdout}
5905+\[ga]\[ga]\[ga]
5906+hello
5907+\[ga]\[ga]\[ga]
5908+:::
5909+::::::
5910+
5911+:::::: {.cell .code execution_count=2}
5912+\[ga]\[ga]\[ga] {.python}
5913+from IPython.display import HTML
5914+HTML(\[dq]\[dq]\[dq]
5915+<script>
5916+console.log(\[dq]hello\[dq]);
5917+</script>
5918+<b>HTML</b>
5919+\[dq]\[dq]\[dq])
5920+\[ga]\[ga]\[ga]
5921+
5922+::: {.output .execute_result execution_count=2}
5923+\[ga]\[ga]\[ga]{=html}
5924+<script>
5925+console.log(\[dq]hello\[dq]);
5926+</script>
5927+<b>HTML</b>
5928+hello
5929+\[ga]\[ga]\[ga]
5930+:::
5931+::::::
5932+\f[R]
5933+.fi
55985934.SH SYNTAX HIGHLIGHTING
55995935.PP
56005936Pandoc will automatically highlight syntax in fenced code blocks that
@@ -5603,25 +5939,25 @@ The Haskell library skylighting is used for highlighting.
56035939Currently highlighting is supported only for HTML, EPUB, Docx, Ms, and
56045940LaTeX/PDF output.
56055941To see a list of language names that pandoc will recognize, type
5606−\f[C]pandoc \-\-list\-highlight\-languages\f[R].
5942+\f[C]pandoc --list-highlight-languages\f[R].
56075943.PP
5608−The color scheme can be selected using the
5609−\f[C]\-\-highlight\-style\f[R] option.
5944+The color scheme can be selected using the \f[C]--highlight-style\f[R]
5945+option.
56105946The default color scheme is \f[C]pygments\f[R], which imitates the
56115947default color scheme used by the Python library pygments (though
56125948pygments is not actually used to do the highlighting).
56135949To see a list of highlight styles, type
5614−\f[C]pandoc \-\-list\-highlight\-styles\f[R].
5950+\f[C]pandoc --list-highlight-styles\f[R].
56155951.PP
56165952If you are not satisfied with the predefined styles, you can use
5617−\f[C]\-\-print\-highlight\-style\f[R] to generate a JSON
5618−\f[C].theme\f[R] file which can be modified and used as the argument to
5619−\f[C]\-\-highlight\-style\f[R].
5953+\f[C]--print-highlight-style\f[R] to generate a JSON \f[C].theme\f[R]
5954+file which can be modified and used as the argument to
5955+\f[C]--highlight-style\f[R].
56205956To get a JSON version of the \f[C]pygments\f[R] style, for example:
56215957.IP
56225958.nf
56235959\f[C]
5624−pandoc \-\-print\-highlight\-style pygments > my.theme
5960+pandoc --print-highlight-style pygments > my.theme
56255961\f[R]
56265962.fi
56275963.PP
@@ -5629,19 +5965,21 @@ Then edit \f[C]my.theme\f[R] and use it like this:
56295965.IP
56305966.nf
56315967\f[C]
5632−pandoc \-\-highlight\-style my.theme
5968+pandoc --highlight-style my.theme
56335969\f[R]
56345970.fi
56355971.PP
5636−If you are not satisfied with the built\-in highlighting, or you want
5972+If you are not satisfied with the built-in highlighting, or you want
56375973highlight a language that isn\[aq]t supported, you can use the
5638−\f[C]\-\-syntax\-definition\f[R] option to load a KDE\-style XML syntax
5974+\f[C]--syntax-definition\f[R] option to load a KDE-style XML syntax
56395975definition file.
56405976Before writing your own, have a look at KDE\[aq]s repository of syntax
56415977definitions.
56425978.PP
5643−To disable highlighting, use the \f[C]\-\-no\-highlight\f[R] option.
5644−.SH CUSTOM STYLES IN DOCX
5979+To disable highlighting, use the \f[C]--no-highlight\f[R] option.
5980+.SH CUSTOM STYLES
5981+.PP
5982+Custom styles can be used in the docx and ICML formats.
56455983.SS Input
56465984.PP
56475985The docx reader, by default, only reads those styles that it can convert
@@ -5649,19 +5987,19 @@ into pandoc elements, either by direct conversion or interpreting the
56495987derivation of the input document\[aq]s styles.
56505988.PP
56515989By enabling the \f[C]styles\f[R] extension in the docx reader
5652−(\f[C]\-f docx+styles\f[R]), you can produce output that maintains the
5653−styles of the input document, using the \f[C]custom\-style\f[R] class.
5990+(\f[C]-f docx+styles\f[R]), you can produce output that maintains the
5991+styles of the input document, using the \f[C]custom-style\f[R] class.
56545992Paragraph styles are interpreted as divs, while character styles are
56555993interpreted as spans.
56565994.PP
5657−For example, using the \f[C]custom\-style\-reference.docx\f[R] file in
5658−the test directory, we have the following different outputs:
5995+For example, using the \f[C]custom-style-reference.docx\f[R] file in the
5996+test directory, we have the following different outputs:
56595997.PP
56605998Without the \f[C]+styles\f[R] extension:
56615999.IP
56626000.nf
56636001\f[C]
5664−$ pandoc test/docx/custom\-style\-reference.docx \-f docx \-t markdown
6002+$ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
56656003This is some text.
56666004
56676005This is text with an *emphasized* text style. And this is text with a
@@ -5675,32 +6013,32 @@ And with the extension:
56756013.IP
56766014.nf
56776015\f[C]
5678−$ pandoc test/docx/custom\-style\-reference.docx \-f docx+styles \-t markdown
6016+$ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
56796017
5680−::: {custom\-style=\[dq]FirstParagraph\[dq]}
6018+::: {custom-style=\[dq]FirstParagraph\[dq]}
56816019This is some text.
56826020:::
56836021
5684−::: {custom\-style=\[dq]BodyText\[dq]}
5685−This is text with an [emphasized]{custom\-style=\[dq]Emphatic\[dq]} text style.
5686−And this is text with a [strengthened]{custom\-style=\[dq]Strengthened\[dq]}
6022+::: {custom-style=\[dq]BodyText\[dq]}
6023+This is text with an [emphasized]{custom-style=\[dq]Emphatic\[dq]} text style.
6024+And this is text with a [strengthened]{custom-style=\[dq]Strengthened\[dq]}
56876025text style.
56886026:::
56896027
5690−::: {custom\-style=\[dq]MyBlockStyle\[dq]}
6028+::: {custom-style=\[dq]MyBlockStyle\[dq]}
56916029> Here is a styled paragraph that inherits from Block Text.
56926030:::
56936031\f[R]
56946032.fi
56956033.PP
56966034With these custom styles, you can use your input document as a
5697−reference\-doc while creating docx output (see below), and maintain the
6035+reference-doc while creating docx output (see below), and maintain the
56986036same styles in your input and output files.
56996037.SS Output
57006038.PP
5701−By default, pandoc\[aq]s docx output applies a predefined set of styles
5702−for blocks such as paragraphs and block quotes, and uses largely default
5703−formatting (italics, bold) for inlines.
6039+By default, pandoc\[aq]s docx and ICML output applies a predefined set
6040+of styles for blocks such as paragraphs and block quotes, and uses
6041+largely default formatting (italics, bold) for inlines.
57046042This will work for most purposes, especially alongside a
57056043\f[C]reference.docx\f[R] file.
57066044However, if you need to apply your own styles to blocks, or match a
@@ -5708,13 +6046,13 @@ preexisting set of styles, pandoc allows you to define custom styles for
57086046blocks and text using \f[C]div\f[R]s and \f[C]span\f[R]s, respectively.
57096047.PP
57106048If you define a \f[C]div\f[R] or \f[C]span\f[R] with the attribute
5711−\f[C]custom\-style\f[R], pandoc will apply your specified style to the
6049+\f[C]custom-style\f[R], pandoc will apply your specified style to the
57126050contained elements.
57136051So, for example using the \f[C]bracketed_spans\f[R] syntax,
57146052.IP
57156053.nf
57166054\f[C]
5717−[Get out]{custom\-style=\[dq]Emphatically\[dq]}, he said.
6055+[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said.
57186056\f[R]
57196057.fi
57206058.PP
@@ -5726,9 +6064,9 @@ Similarly, using the \f[C]fenced_divs\f[R] syntax,
57266064\f[C]
57276065Dickinson starts the poem simply:
57286066
5729−::: {custom\-style=\[dq]Poetry\[dq]}
5730−| A Bird came down the Walk\-\-\-
5731−| He did not know I saw\-\-\-
6067+::: {custom-style=\[dq]Poetry\[dq]}
6068+| A Bird came down the Walk---
6069+| He did not know I saw---
57326070:::
57336071\f[R]
57346072.fi
@@ -5736,8 +6074,8 @@ Dickinson starts the poem simply:
57366074would style the two contained lines with the \f[C]Poetry\f[R] paragraph
57376075style.
57386076.PP
5739−If the styles are not yet in your reference.docx, they will be defined
5740−in the output file as inheriting from normal text.
6077+For docx output, styles will be defined in the output file as inheriting
6078+from normal text, if the styles are not yet in your reference.docx.
57416079If they are already defined, pandoc will not alter the definition.
57426080.PP
57436081This feature allows for greatest customization in conjunction with
@@ -5747,7 +6085,7 @@ write a filter to apply the styles necessary.
57476085If you want all italics to be transformed to the \f[C]Emphasis\f[R]
57486086character style (perhaps to change their color), you can write a filter
57496087which will transform all italicized inlines to inlines within an
5750−\f[C]Emphasis\f[R] custom\-style \f[C]span\f[R].
6088+\f[C]Emphasis\f[R] custom-style \f[C]span\f[R].
57516089.SH CUSTOM WRITERS
57526090.PP
57536091Pandoc can be extended with custom writers written in lua.
@@ -5760,7 +6098,7 @@ For example:
57606098.IP
57616099.nf
57626100\f[C]
5763−pandoc \-t data/sample.lua
6101+pandoc -t data/sample.lua
57646102\f[R]
57656103.fi
57666104.PP
@@ -5771,12 +6109,12 @@ needs, do
57716109.IP
57726110.nf
57736111\f[C]
5774−pandoc \-\-print\-default\-data\-file sample.lua
6112+pandoc --print-default-data-file sample.lua
57756113\f[R]
57766114.fi
57776115.SH A NOTE ON SECURITY
57786116.PP
5779−If you use pandoc to convert user\-contributed content in a web
6117+If you use pandoc to convert user-contributed content in a web
57806118application, here are some things to keep in mind:
57816119.IP "1." 3
57826120Although pandoc itself will not create or modify any files other than
@@ -5797,8 +6135,8 @@ cases.
57976135It is wise to put any pandoc operations under a timeout, to avoid DOS
57986136attacks that exploit these issues.
57996137If you are using the pandoc executable, you can add the command line
5800−options \f[C]+RTS \-M512M \-RTS\f[R] (for example) to limit the heap
5801−size to 512MB.
6138+options \f[C]+RTS -M512M -RTS\f[R] (for example) to limit the heap size
6139+to 512MB.
58026140.IP "4." 3
58036141The HTML generated by pandoc is not guaranteed to be safe.
58046142If \f[C]raw_html\f[R] is enabled for the Markdown input, users can
@@ -5809,7 +6147,7 @@ To be safe, you should run all the generated HTML through an HTML
58096147sanitizer.
58106148.SH AUTHORS
58116149.PP
5812−Copyright 2006\-2017 John MacFarlane (jgm\[at]berkeley.edu).
6150+Copyright 2006--2019 John MacFarlane (jgm\[at]berkeley.edu).
58136151Released under the GPL, version 2 or greater.
58146152This software carries no warranty of any kind.
58156153(See COPYRIGHT for full copyright and warranty notices.) For a full list