@@ -1,5 +1,5 @@
11.\"t
2−.TH PANDOC 1 "January 29, 2017" "pandoc 1.19.2"
2+.TH PANDOC 1 "March 26, 2017" "pandoc 2.0"
33.SH NAME
44pandoc - general markup converter
55.SH SYNOPSIS
@@ -18,10 +18,11 @@ Markdown, MultiMarkdown, reStructuredText, XHTML, HTML5, LaTeX
1818(including \f[C]beamer\f[] slide shows), ConTeXt, RTF, OPML, DocBook,
1919OpenDocument, ODT, Word docx, GNU Texinfo, MediaWiki markup, DokuWiki
2020markup, ZimWiki markup, Haddock markup, EPUB (v2 or v3), FictionBook2,
21−Textile, groff man pages, Emacs Org mode, AsciiDoc, InDesign ICML, TEI
22−Simple, and Slidy, Slideous, DZSlides, reveal.js or S5 HTML slide shows.
23−It can also produce PDF output on systems where LaTeX, ConTeXt, or
24−\f[C]wkhtmltopdf\f[] is installed.
21+Textile, groff man, groff ms, Emacs Org mode, AsciiDoc, InDesign ICML,
22+TEI Simple, and Slidy, Slideous, DZSlides, reveal.js or S5 HTML slide
23+shows.
24+It can also produce PDF output on systems where LaTeX, ConTeXt,
25+\f[C]pdfroff\f[], or \f[C]wkhtmltopdf\f[] is installed.
2526.PP
2627Pandoc's enhanced version of Markdown includes syntax for footnotes,
2728tables, flexible ordered lists, definition lists, fenced code blocks,
@@ -57,7 +58,7 @@ Otherwise, the \f[I]input\-files\f[] are concatenated (with a blank line
5758between each) and used as input.
5859Output goes to \f[I]stdout\f[] by default (though output to
5960\f[I]stdout\f[] is disabled for the \f[C]odt\f[], \f[C]docx\f[],
60−\f[C]epub\f[], and \f[C]epub3\f[] output formats).
61+\f[C]epub2\f[], and \f[C]epub3\f[] output formats).
6162For output to a file, use the \f[C]\-o\f[] option:
6263.IP
6364.nf
@@ -89,6 +90,15 @@ pandoc\ \-f\ html\ \-t\ markdown\ http://www.fsf.org
8990\f[]
9091.fi
9192.PP
93+It is possible to supply a custom User\-Agent string when requesting a
94+document from a URL, by setting an environment variable:
95+.IP
96+.nf
97+\f[C]
98+USER_AGENT="Mozilla/5.0"\ pandoc\ \-f\ html\ \-t\ markdown\ http://www.fsf.org
99+\f[]
100+.fi
101+.PP
92102If multiple input files are given, \f[C]pandoc\f[] will concatenate them
93103all (with blank lines between them) before parsing.
94104This feature is disabled for binary input formats such as \f[C]EPUB\f[],
@@ -172,29 +182,32 @@ pandoc\ test.txt\ \-o\ test.pdf
172182Production of a PDF requires that a LaTeX engine be installed (see
173183\f[C]\-\-latex\-engine\f[], below), and assumes that the following LaTeX
174184packages are available: \f[C]amsfonts\f[], \f[C]amsmath\f[],
175−\f[C]lm\f[], \f[C]ifxetex\f[], \f[C]ifluatex\f[], \f[C]eurosym\f[],
176−\f[C]listings\f[] (if the \f[C]\-\-listings\f[] option is used),
177−\f[C]fancyvrb\f[], \f[C]longtable\f[], \f[C]booktabs\f[],
178−\f[C]graphicx\f[] and \f[C]grffile\f[] (if the document contains
179−images), \f[C]hyperref\f[], \f[C]ulem\f[], \f[C]geometry\f[] (with the
180−\f[C]geometry\f[] variable set), \f[C]setspace\f[] (with
181−\f[C]linestretch\f[]), and \f[C]babel\f[] (with \f[C]lang\f[]).
185+\f[C]lm\f[], \f[C]unicode\-math\f[], \f[C]ifxetex\f[],
186+\f[C]ifluatex\f[], \f[C]eurosym\f[], \f[C]listings\f[] (if the
187+\f[C]\-\-listings\f[] option is used), \f[C]fancyvrb\f[],
188+\f[C]longtable\f[], \f[C]booktabs\f[], \f[C]graphicx\f[] and
189+\f[C]grffile\f[] (if the document contains images), \f[C]hyperref\f[],
190+\f[C]ulem\f[], \f[C]geometry\f[] (with the \f[C]geometry\f[] variable
191+set), \f[C]setspace\f[] (with \f[C]linestretch\f[]), and \f[C]babel\f[]
192+(with \f[C]lang\f[]).
182193The use of \f[C]xelatex\f[] or \f[C]lualatex\f[] as the LaTeX engine
183−requires \f[C]fontspec\f[]; \f[C]xelatex\f[] uses \f[C]mathspec\f[],
184−\f[C]polyglossia\f[] (with \f[C]lang\f[]), \f[C]xecjk\f[], and
185−\f[C]bidi\f[] (with the \f[C]dir\f[] variable set).
194+requires \f[C]fontspec\f[].
195+\f[C]xelatex\f[] uses \f[C]polyglossia\f[] (with \f[C]lang\f[]),
196+\f[C]xecjk\f[], and \f[C]bidi\f[] (with the \f[C]dir\f[] variable set).
197+If the \f[C]mathspec\f[] variable is set, \f[C]xelatex\f[] will use
198+\f[C]mathspec\f[] instead of \f[C]unicode\-math\f[].
186199The \f[C]upquote\f[] and \f[C]microtype\f[] packages are used if
187−available, and \f[C]csquotes\f[] will be used for smart punctuation if
200+available, and \f[C]csquotes\f[] will be used for [smart punctuation] if
188201added to the template or included in any header file.
189202The \f[C]natbib\f[], \f[C]biblatex\f[], \f[C]bibtex\f[], and
190203\f[C]biber\f[] packages can optionally be used for citation rendering.
191204These are included with all recent versions of TeX Live.
192205.PP
193−Alternatively, pandoc can use ConTeXt or \f[C]wkhtmltopdf\f[] to create
194−a PDF.
206+Alternatively, pandoc can use ConTeXt, \f[C]wkhtmltopdf\f[], or
207+\f[C]pdfroff\f[] to create a PDF.
195208To do this, specify an output file with a \f[C]\&.pdf\f[] extension, as
196−before, but add \f[C]\-t\ context\f[] or \f[C]\-t\ html5\f[] to the
197−command line.
209+before, but add \f[C]\-t\ context\f[], \f[C]\-t\ html5\f[], or
210+\f[C]\-t\ ms\f[] to the command line.
198211.PP
199212PDF output can be controlled using variables for LaTeX (if LaTeX is
200213used) and variables for ConTeXt (if ConTeXt is used).
@@ -243,18 +256,20 @@ Specify output format.
243256(original unextended Markdown), \f[C]markdown_phpextra\f[] (PHP Markdown
244257Extra), \f[C]markdown_github\f[] (GitHub\-Flavored Markdown),
245258\f[C]markdown_mmd\f[] (MultiMarkdown), \f[C]commonmark\f[] (CommonMark
246−Markdown), \f[C]rst\f[] (reStructuredText), \f[C]html\f[] (XHTML),
247−\f[C]html5\f[] (HTML5), \f[C]latex\f[] (LaTeX), \f[C]beamer\f[] (LaTeX
248−beamer slide show), \f[C]context\f[] (ConTeXt), \f[C]man\f[] (groff
249−man), \f[C]mediawiki\f[] (MediaWiki markup), \f[C]dokuwiki\f[] (DokuWiki
259+Markdown), \f[C]rst\f[] (reStructuredText), \f[C]html4\f[] (XHTML 1.0
260+Transitional), \f[C]html\f[] or \f[C]html5\f[] (HTML5/XHTML polyglot
261+markup), \f[C]latex\f[] (LaTeX), \f[C]beamer\f[] (LaTeX beamer slide
262+show), \f[C]context\f[] (ConTeXt), \f[C]man\f[] (groff man),
263+\f[C]mediawiki\f[] (MediaWiki markup), \f[C]dokuwiki\f[] (DokuWiki
250264markup), \f[C]zimwiki\f[] (ZimWiki markup), \f[C]textile\f[] (Textile),
251265\f[C]org\f[] (Emacs Org mode), \f[C]texinfo\f[] (GNU Texinfo),
252−\f[C]opml\f[] (OPML), \f[C]docbook\f[] (DocBook 4), \f[C]docbook5\f[]
253−(DocBook 5), \f[C]opendocument\f[] (OpenDocument), \f[C]odt\f[]
254−(OpenOffice text document), \f[C]docx\f[] (Word docx), \f[C]haddock\f[]
255−(Haddock markup), \f[C]rtf\f[] (rich text format), \f[C]epub\f[] (EPUB
256−v2 book), \f[C]epub3\f[] (EPUB v3), \f[C]fb2\f[] (FictionBook2 e\-book),
257−\f[C]asciidoc\f[] (AsciiDoc), \f[C]icml\f[] (InDesign ICML),
266+\f[C]opml\f[] (OPML), \f[C]docbook\f[] or \f[C]docbook4\f[] (DocBook 4),
267+\f[C]docbook5\f[] (DocBook 5), \f[C]jats\f[] (JATS XML),
268+\f[C]opendocument\f[] (OpenDocument), \f[C]odt\f[] (OpenOffice text
269+document), \f[C]docx\f[] (Word docx), \f[C]haddock\f[] (Haddock markup),
270+\f[C]rtf\f[] (rich text format), \f[C]epub2\f[] (EPUB v2 book),
271+\f[C]epub\f[] or \f[C]epub3\f[] (EPUB v3), \f[C]fb2\f[] (FictionBook2
272+e\-book), \f[C]asciidoc\f[] (AsciiDoc), \f[C]icml\f[] (InDesign ICML),
258273\f[C]tei\f[] (TEI Simple), \f[C]slidy\f[] (Slidy HTML and JavaScript
259274slide show), \f[C]slideous\f[] (Slideous HTML and JavaScript slide
260275show), \f[C]dzslides\f[] (DZSlides HTML5 + JavaScript slide show),
@@ -265,7 +280,7 @@ Note that \f[C]odt\f[], \f[C]epub\f[], and \f[C]epub3\f[] output will
265280not be directed to \f[I]stdout\f[]; an output filename must be specified
266281using the \f[C]\-o/\-\-output\f[] option.
267282If \f[C]+lhs\f[] is appended to \f[C]markdown\f[], \f[C]rst\f[],
268−\f[C]latex\f[], \f[C]beamer\f[], \f[C]html\f[], or \f[C]html5\f[], the
283+\f[C]latex\f[], \f[C]beamer\f[], \f[C]html4\f[], or \f[C]html5\f[], the
269284output will be rendered as literate Haskell source: see Literate Haskell
270285support, below.
271286Markdown syntax extensions can be individually enabled or disabled by
@@ -340,6 +355,23 @@ Currently this only has an effect with PDF output.
340355.RS
341356.RE
342357.TP
358+.B \f[C]\-\-quiet\f[]
359+Suppress warning messages.
360+.RS
361+.RE
362+.TP
363+.B \f[C]\-\-fail\-if\-warnings\f[]
364+Exit with error status if there are any warnings.
365+.RS
366+.RE
367+.TP
368+.B \f[C]\-\-log=\f[]\f[I]FILE\f[]
369+Write log messages in machine\-readable JSON format to \f[I]FILE\f[].
370+All messages above DEBUG level will be written, regardless of verbosity
371+settings (\f[C]\-\-verbose\f[], \f[C]\-\-quiet\f[]).
372+.RS
373+.RE
374+.TP
343375.B \f[C]\-\-list\-input\-formats\f[]
344376List supported input formats, one per line.
345377.RS
@@ -379,41 +411,6 @@ Show usage message.
379411.RE
380412.SS Reader options
381413.TP
382−.B \f[C]\-R\f[], \f[C]\-\-parse\-raw\f[]
383−Parse untranslatable HTML codes and LaTeX environments as raw HTML or
384−LaTeX, instead of ignoring them.
385−Affects only HTML and LaTeX input.
386−Raw HTML can be printed in Markdown, reStructuredText, Emacs Org mode,
387−HTML, Slidy, Slideous, DZSlides, reveal.js, and S5 output; raw LaTeX can
388−be printed in Markdown, reStructuredText, Emacs Org mode, LaTeX, and
389−ConTeXt output.
390−The default is for the readers to omit untranslatable HTML codes and
391−LaTeX environments.
392−(The LaTeX reader does pass through untranslatable LaTeX
393−\f[I]commands\f[], even if \f[C]\-R\f[] is not specified.)
394−.RS
395−.RE
396−.TP
397−.B \f[C]\-S\f[], \f[C]\-\-smart\f[]
398−Produce typographically correct output, converting straight quotes to
399−curly quotes, \f[C]\-\-\-\f[] to em\-dashes, \f[C]\-\-\f[] to
400−en\-dashes, and \f[C]\&...\f[] to ellipses.
401−Nonbreaking spaces are inserted after certain abbreviations, such as
402−\[lq]Mr.\[rq] (Note: This option is selected automatically when the
403−output format is \f[C]latex\f[] or \f[C]context\f[], unless
404−\f[C]\-\-no\-tex\-ligatures\f[] is used.
405−It has no effect for \f[C]latex\f[] input.)
406−.RS
407−.RE
408−.TP
409−.B \f[C]\-\-old\-dashes\f[]
410−Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes:
411−\f[C]\-\f[] before a numeral is an en\-dash, and \f[C]\-\-\f[] is an
412−em\-dash.
413−This option is selected automatically for \f[C]textile\f[] input.
414−.RS
415−.RE
416−.TP
417414.B \f[C]\-\-base\-header\-level=\f[]\f[I]NUMBER\f[]
418415Specify the base level for headers (defaults to 1).
419416.RS
@@ -487,6 +484,37 @@ a specified full or relative path (executable or non\-executable)
487484\f[C]$PATH\f[] (executable only)
488485.RE
489486.TP
487+.B \f[C]\-\-lua\-filter=\f[]\f[I]SCRIPT\f[]
488+Transform the document in a similar fashion as JSON filters (see
489+\f[C]\-\-filter\f[]), but use pandoc's build\-in lua filtering system.
490+The given lua script is expected to return a list of lua filters which
491+will be applied in order.
492+Each lua filter must contain element\-transforming functions indexed by
493+the name of the AST element on which the filter function should be
494+applied.
495+.RS
496+.PP
497+The \f[C]pandoc\f[] lua module provides helper functions for element
498+creation.
499+It is always loaded into the script's lua environment.
500+.PP
501+The following is an example lua script for macro\-expansion:
502+.IP
503+.nf
504+\f[C]
505+function\ expand_hello_world(inline)
506+\ \ if\ inline.c\ ==\ \[aq]{{helloworld}}\[aq]\ then
507+\ \ \ \ return\ pandoc.Emph{\ pandoc.Str\ "Hello,\ World"\ }
508+\ \ else
509+\ \ \ \ return\ inline
510+\ \ end
511+end
512+
513+return\ {{Str\ =\ expand_hello_world}}
514+\f[]
515+.fi
516+.RE
517+.TP
490518.B \f[C]\-M\f[] \f[I]KEY\f[][\f[C]=\f[]\f[I]VAL\f[]], \f[C]\-\-metadata=\f[]\f[I]KEY\f[][\f[C]:\f[]\f[I]VAL\f[]]
491519Set the metadata field \f[I]KEY\f[] to the value \f[I]VAL\f[].
492520A value specified on the command line overrides a value specified in the
@@ -501,13 +529,6 @@ and may be printed in some output formats).
501529.RS
502530.RE
503531.TP
504−.B \f[C]\-\-normalize\f[]
505−Normalize the document after reading: merge adjacent \f[C]Str\f[] or
506−\f[C]Emph\f[] elements, for example, and remove repeated
507−\f[C]Space\f[]s.
508−.RS
509−.RE
510−.TP
511532.B \f[C]\-p\f[], \f[C]\-\-preserve\-tabs\f[]
512533Preserve tabs instead of converting them to spaces (the default).
513534Note that this will only affect tabs in literal code spans and code
@@ -539,10 +560,29 @@ This option only affects the docx reader.
539560.RE
540561.TP
541562.B \f[C]\-\-extract\-media=\f[]\f[I]DIR\f[]
542−Extract images and other media contained in a docx or epub container to
543−the path \f[I]DIR\f[], creating it if necessary, and adjust the images
544−references in the document so they point to the extracted files.
545−This option only affects the docx and epub readers.
563+Extract images and other media contained in or linked from the source
564+document to the path \f[I]DIR\f[], creating it if necessary, and adjust
565+the images references in the document so they point to the extracted
566+files.
567+If the source format is a binary container (docx, epub, or odt), the
568+media is extracted from the container and the original filenames are
569+used.
570+Otherwise the media is read from the file system or downloaded, and new
571+filenames are constructed based on SHA1 hashes of the contents.
572+.RS
573+.RE
574+.TP
575+.B \f[C]\-\-abbreviations=\f[]\f[I]FILE\f[]
576+Specifies a custom abbreviations file, with abbreviations one to a line.
577+If this option is not specified, pandoc will read the data file
578+\f[C]abbreviations\f[] from the user data directory or fall back on a
579+system default.
580+To see the system default, use
581+\f[C]pandoc\ \-\-print\-default\-data\-file=abbreviations\f[].
582+The only use pandoc makes of this list is in the Markdown reader.
583+Strings ending in a period that are found in this list will be followed
584+by a nonbreaking space, so that the period will not produce
585+sentence\-ending space in formats like LaTeX.
546586.RS
547587.RE
548588.SS General writer options
@@ -595,6 +635,14 @@ Files in the user data directory are ignored.
595635.RS
596636.RE
597637.TP
638+.B \f[C]\-\-eol=crlf\f[]|\f[C]lf\f[]|\f[C]native\f[]
639+Manually specify line endings: \f[C]crlf\f[] (Windows), \f[C]lf\f[]
640+(MacOS/linux/unix), or \f[C]native\f[] (line endings appropriate to the
641+OS on which pandoc is being run).
642+The default is \f[C]native\f[].
643+.RS
644+.RE
645+.TP
598646.B \f[C]\-\-dpi\f[]=\f[I]NUMBER\f[]
599647Specify the dpi (dots per inch) value for conversion from pixels to
600648inch/centimeters and vice versa.
@@ -617,11 +665,6 @@ Automatic wrapping does not currently work in HTML output.
617665.RS
618666.RE
619667.TP
620−.B \f[C]\-\-no\-wrap\f[]
621−Deprecated synonym for \f[C]\-\-wrap=none\f[].
622−.RS
623−.RE
624−.TP
625668.B \f[C]\-\-columns=\f[]\f[I]NUMBER\f[]
626669Specify length of lines in characters.
627670This affects text wrapping in the generated source code (see
@@ -633,11 +676,11 @@ Tables below).
633676.TP
634677.B \f[C]\-\-toc\f[], \f[C]\-\-table\-of\-contents\f[]
635678Include an automatically generated table of contents (or, in the case of
636−\f[C]latex\f[], \f[C]context\f[], \f[C]docx\f[], and \f[C]rst\f[], an
637−instruction to create one) in the output document.
638−This option has no effect on \f[C]man\f[], \f[C]docbook\f[],
639−\f[C]docbook5\f[], \f[C]slidy\f[], \f[C]slideous\f[], \f[C]s5\f[], or
640−\f[C]odt\f[] output.
679+\f[C]latex\f[], \f[C]context\f[], \f[C]docx\f[], \f[C]rst\f[], or
680+\f[C]ms\f[], an instruction to create one) in the output document.
681+This option has no effect on \f[C]man\f[], \f[C]docbook4\f[],
682+\f[C]docbook5\f[], \f[C]jats\f[], \f[C]slidy\f[], \f[C]slideous\f[],
683+\f[C]s5\f[], or \f[C]odt\f[] output.
641684.RS
642685.RE
643686.TP
@@ -655,7 +698,7 @@ language attribute is given.
655698.RS
656699.RE
657700.TP
658−.B \f[C]\-\-highlight\-style=\f[]\f[I]STYLE\f[]
701+.B \f[C]\-\-highlight\-style=\f[]\f[I]STYLE\f[]|\f[I]FILE\f[]
659702Specifies the coloring style to be used in highlighted source code.
660703Options are \f[C]pygments\f[] (the default), \f[C]kate\f[],
661704\f[C]monochrome\f[], \f[C]breezeDark\f[], \f[C]espresso\f[],
@@ -664,6 +707,21 @@ For more information on syntax highlighting in pandoc, see Syntax
664707highlighting, below.
665708See also \f[C]\-\-list\-highlight\-styles\f[].
666709.RS
710+.PP
711+Instead of a \f[I]STYLE\f[] name, a JSON file with extension
712+\f[C]\&.theme\f[] may be supplied.
713+This will be parsed as a KDE syntax highlighting theme and (if valid)
714+used as the highlighting style.
715+To see a sample theme that can be modified,
716+\f[C]pandoc\ \-\-print\-default\-data\-file\ default.theme\f[].
717+.RE
718+.TP
719+.B \f[C]\-\-syntax\-definition=\f[]\f[I]FILE\f[]
720+Instructs pandoc to load a KDE XML syntax definition file, which will be
721+used for syntax highlighting of appropriately marked code blocks.
722+This can be used to add support for new languages or to use altered
723+syntax definitions for existing languages.
724+.RS
667725.RE
668726.TP
669727.B \f[C]\-H\f[] \f[I]FILE\f[], \f[C]\-\-include\-in\-header=\f[]\f[I]FILE\f[]
@@ -698,6 +756,19 @@ They will be included in the order specified.
698756Implies \f[C]\-\-standalone\f[].
699757.RS
700758.RE
759+.TP
760+.B \f[C]\-\-resource\-path=\f[]\f[I]SEARCHPATH\f[]
761+List of paths to search for images and other resources.
762+The paths should be separated by \f[C]:\f[] on linux, unix, and MacOS
763+systems, and by \f[C];\f[] on Windows.
764+If \f[C]\-\-resource\-path\f[] is not specified, the default resource
765+path is the working directory.
766+Note that, if \f[C]\-\-resource\-path\f[] is specified, the working
767+directory must be explicitly listed or it will not be searched.
768+For example: \f[C]\-\-resource\-path=.:test\f[] will search the working
769+directory and the \f[C]test\f[] subdirectory, in that order.
770+.RS
771+.RE
701772.SS Options affecting specific writers
702773.TP
703774.B \f[C]\-\-self\-contained\f[]
@@ -708,13 +779,16 @@ The resulting file should be \[lq]self\-contained,\[rq] in the sense
708779that it needs no external files and no net access to be displayed
709780properly by a browser.
710781This option works only with HTML output formats, including
711−\f[C]html\f[], \f[C]html5\f[], \f[C]html+lhs\f[], \f[C]html5+lhs\f[],
782+\f[C]html4\f[], \f[C]html5\f[], \f[C]html+lhs\f[], \f[C]html5+lhs\f[],
712783\f[C]s5\f[], \f[C]slidy\f[], \f[C]slideous\f[], \f[C]dzslides\f[], and
713784\f[C]revealjs\f[].
714785Scripts, images, and stylesheets at absolute URLs will be downloaded;
715786those at relative URLs will be sought relative to the working directory
716787(if the first source file is local) or relative to the base URL (if the
717788first source file is remote).
789+Elements with the attribute \f[C]data\-external="1"\f[] will be left
790+alone; the documents they link to will not be incorporated in the
791+document.
718792Limitation: resources that are loaded dynamically through JavaScript
719793cannot be incorporated; as a result, \f[C]\-\-self\-contained\f[] does
720794not work with \f[C]\-\-mathjax\f[], and some advanced features
@@ -730,8 +804,8 @@ Use \f[C]<q>\f[] tags for quotes in HTML.
730804.TP
731805.B \f[C]\-\-ascii\f[]
732806Use only ASCII characters in output.
733−Currently supported only for HTML output (which uses numerical entities
734−instead of UTF\-8 when this option is selected).
807+Currently supported only for HTML and DocBook output (which uses
808+numerical entities instead of UTF\-8 when this option is selected).
735809.RS
736810.RE
737811.TP
@@ -760,11 +834,6 @@ ATX headers.
760834.RS
761835.RE
762836.TP
763−.B \f[C]\-\-chapters\f[]
764−Deprecated synonym for \f[C]\-\-top\-level\-division=chapter\f[].
765−.RS
766−.RE
767−.TP
768837.B \f[C]\-\-top\-level\-division=[default|section|chapter|part]\f[]
769838Treat top\-level headers as the given division type in LaTeX, ConTeXt,
770839DocBook, and TEI output.
@@ -805,25 +874,6 @@ Implies \f[C]\-\-number\-sections\f[].
805874.RS
806875.RE
807876.TP
808−.B \f[C]\-\-no\-tex\-ligatures\f[]
809−Do not use the TeX ligatures for quotation marks, apostrophes, and
810−dashes (\f[C]`...\[aq]\f[], \f[C]``..\[aq]\[aq]\f[], \f[C]\-\-\f[],
811−\f[C]\-\-\-\f[]) when writing or reading LaTeX or ConTeXt.
812−In reading LaTeX, parse the characters \f[C]`\f[], \f[C]\[aq]\f[], and
813−\f[C]\-\f[] literally, rather than parsing ligatures for quotation marks
814−and dashes.
815−In writing LaTeX or ConTeXt, print unicode quotation mark and dash
816−characters literally, rather than converting them to the standard ASCII
817−TeX ligatures.
818−Note: normally \f[C]\-\-smart\f[] is selected automatically for LaTeX
819−and ConTeXt output, but it must be specified explicitly if
820−\f[C]\-\-no\-tex\-ligatures\f[] is selected.
821−If you use literal curly quotes, dashes, and ellipses in your source,
822−then you may want to use \f[C]\-\-no\-tex\-ligatures\f[] without
823−\f[C]\-\-smart\f[].
824−.RS
825−.RE
826−.TP
827877.B \f[C]\-\-listings\f[]
828878Use the \f[C]listings\f[] package for LaTeX code blocks
829879.RS
@@ -842,6 +892,8 @@ Specifies that headers with the specified level create slides (for
842892Headers above this level in the hierarchy are used to divide the slide
843893show into sections; headers below this level create subheads within a
844894slide.
895+Note that content that is not contained under slide\-level headers will
896+not appear in the slide show.
845897The default is to set the slide level based on the contents of the
846898document; see Structuring the slide show.
847899.RS
@@ -867,8 +919,9 @@ The default is \f[C]none\f[].
867919.RE
868920.TP
869921.B \f[C]\-\-id\-prefix=\f[]\f[I]STRING\f[]
870−Specify a prefix to be added to all automatically generated identifiers
871−in HTML and DocBook output, and to footnote numbers in Markdown output.
922+Specify a prefix to be added to all identifiers and internal links in
923+HTML and DocBook output, and to footnote numbers in Markdown and Haddock
924+output.
872925This is useful for preventing duplicate identifiers when generating
873926fragments to be included in other pages.
874927.RS
@@ -887,29 +940,20 @@ Link to a CSS style sheet.
887940This option can be used repeatedly to include multiple files.
888941They will be included in the order specified.
889942.RS
943+.PP
944+A stylesheet is required for generating EPUB.
945+If none is provided using this option (or the \f[C]stylesheet\f[]
946+metadata field), pandoc will look for a file \f[C]epub.css\f[] in the
947+user data directory (see \f[C]\-\-data\-dir\f[]).
948+If it is not found there, sensible defaults will be used.
890949.RE
891950.TP
892−.B \f[C]\-\-reference\-odt=\f[]\f[I]FILE\f[]
893−Use the specified file as a style reference in producing an ODT.
894−For best results, the reference ODT should be a modified version of an
895−ODT produced using pandoc.
896−The contents of the reference ODT are ignored, but its stylesheets are
897−used in the new ODT.
898−If no reference ODT is specified on the command line, pandoc will look
899−for a file \f[C]reference.odt\f[] in the user data directory (see
900−\f[C]\-\-data\-dir\f[]).
901−If this is not found either, sensible defaults will be used.
951+.B \f[C]\-\-reference\-doc=\f[]\f[I]FILE\f[]
952+Use the specified file as a style reference in producing a docx or ODT
953+file.
902954.RS
903−.PP
904−To produce a custom \f[C]reference.odt\f[], first get a copy of the
905−default \f[C]reference.odt\f[]:
906−\f[C]pandoc\ \-\-print\-default\-data\-file\ reference.odt\ >\ custom\-reference.odt\f[].
907−Then open \f[C]custom\-reference.docx\f[] in LibreOffice, modify the
908−styles as you wish, and save the file.
909−.RE
910955.TP
911−.B \f[C]\-\-reference\-docx=\f[]\f[I]FILE\f[]
912−Use the specified file as a style reference in producing a docx file.
956+.B Docx
913957For best results, the reference docx should be a modified version of a
914958docx file produced using pandoc.
915959The contents of the reference docx are ignored, but its stylesheets and
@@ -930,19 +974,30 @@ For best results, do not make changes to this file other than modifying
930974the styles used by pandoc: [paragraph] Normal, Body Text, First
931975Paragraph, Compact, Title, Subtitle, Author, Date, Abstract,
932976Bibliography, Heading 1, Heading 2, Heading 3, Heading 4, Heading 5,
933−Heading 6, Block Text, Footnote Text, Definition Term, Definition,
934−Caption, Table Caption, Image Caption, Figure, Figure With Caption, TOC
935−Heading; [character] Default Paragraph Font, Body Text Char, Verbatim
936−Char, Footnote Reference, Hyperlink; [table] Normal Table.
977+Heading 6, Heading 7, Heading 8, Heading 9, Block Text, Footnote Text,
978+Definition Term, Definition, Caption, Table Caption, Image Caption,
979+Figure, Captioned Figure, TOC Heading; [character] Default Paragraph
980+Font, Body Text Char, Verbatim Char, Footnote Reference, Hyperlink;
981+[table] Table.
937982.RE
938983.TP
939−.B \f[C]\-\-epub\-stylesheet=\f[]\f[I]FILE\f[]
940−Use the specified CSS file to style the EPUB.
941−If no stylesheet is specified, pandoc will look for a file
942−\f[C]epub.css\f[] in the user data directory (see
984+.B ODT
985+For best results, the reference ODT should be a modified version of an
986+ODT produced using pandoc.
987+The contents of the reference ODT are ignored, but its stylesheets are
988+used in the new ODT.
989+If no reference ODT is specified on the command line, pandoc will look
990+for a file \f[C]reference.odt\f[] in the user data directory (see
943991\f[C]\-\-data\-dir\f[]).
944−If it is not found there, sensible defaults will be used.
992+If this is not found either, sensible defaults will be used.
945993.RS
994+.PP
995+To produce a custom \f[C]reference.odt\f[], first get a copy of the
996+default \f[C]reference.odt\f[]:
997+\f[C]pandoc\ \-\-print\-default\-data\-file\ reference.odt\ >\ custom\-reference.odt\f[].
998+Then open \f[C]custom\-reference.odt\f[] in LibreOffice, modify the
999+styles as you wish, and save the file.
1000+.RE
9461001.RE
9471002.TP
9481003.B \f[C]\-\-epub\-cover\-image=\f[]\f[I]FILE\f[]
@@ -989,7 +1044,7 @@ However, if you use wildcards on the command line, be sure to escape
9891044them or put the whole filename in single quotes, to prevent them from
9901045being interpreted by the shell.
9911046To use the embedded fonts, you will need to add declarations like the
992−following to your CSS (see \f[C]\-\-epub\-stylesheet\f[]):
1047+following to your CSS (see \f[C]\-\-css\f[]):
9931048.RS
9941049.IP
9951050.nf
@@ -1115,12 +1170,9 @@ copy of the script, so it can be cached.
11151170.RS
11161171.RE
11171172.TP
1118−.B \f[C]\-\-mathml\f[][\f[C]=\f[]\f[I]URL\f[]]
1119−Convert TeX math to MathML (in \f[C]docbook\f[], \f[C]docbook5\f[],
1120−\f[C]html\f[] and \f[C]html5\f[]).
1121−In standalone \f[C]html\f[] output, a small JavaScript (or a link to
1122−such a script if a \f[I]URL\f[] is supplied) will be inserted that
1123−allows the MathML to be viewed on some browsers.
1173+.B \f[C]\-\-mathml\f[]
1174+Convert TeX math to MathML (in \f[C]docbook4\f[], \f[C]docbook5\f[],
1175+\f[C]jats\f[], \f[C]html4\f[] and \f[C]html5\f[]).
11241176.RS
11251177.RE
11261178.TP
@@ -1252,7 +1304,7 @@ For \f[C]pdf\f[] output, customize the \f[C]default.latex\f[] template
12521304use \f[C]\-t\ context\f[]).
12531305.IP \[bu] 2
12541306\f[C]docx\f[] has no template (however, you can use
1255−\f[C]\-\-reference\-docx\f[] to customize the output).
1307+\f[C]\-\-reference\-doc\f[] to customize the output).
12561308.PP
12571309Templates contain \f[I]variables\f[], which allow for the inclusion of
12581310arbitrary information at any point in the file.
@@ -1266,6 +1318,29 @@ Some variables are set automatically by pandoc.
12661318These vary somewhat depending on the output format, but include metadata
12671319fields as well as the following:
12681320.TP
1321+.B \f[C]sourcefile\f[], \f[C]outputfile\f[]
1322+source and destination filenames, as given on the command line.
1323+\f[C]sourcefile\f[] can also be a list if input comes from multiple
1324+files, or empty if input is from stdin.
1325+You can use the following snippet in your template to distinguish them:
1326+.RS
1327+.IP
1328+.nf
1329+\f[C]
1330+$if(sourcefile)$
1331+$for(sourcefile)$
1332+$sourcefile$
1333+$endfor$
1334+$else$
1335+(stdin)
1336+$endif$
1337+\f[]
1338+.fi
1339+.PP
1340+Similarly, \f[C]outputfile\f[] can be \f[C]\-\f[] if output goes to the
1341+terminal.
1342+.RE
1343+.TP
12691344.B \f[C]title\f[], \f[C]author\f[], \f[C]date\f[]
12701345allow identification of basic aspects of the document.
12711346Included in PDF metadata through LaTeX and ConTeXt.
@@ -1344,7 +1419,8 @@ body of document
13441419.RE
13451420.TP
13461421.B \f[C]meta\-json\f[]
1347−JSON representation of all of the document's metadata
1422+JSON representation of all of the document's metadata.
1423+Field values are transformed to the selected output format.
13481424.RS
13491425.RE
13501426.SS Language variables
@@ -1398,6 +1474,16 @@ engine is fully supported (use \f[C]\-\-latex\-engine=xelatex\f[]).
13981474Variables are available for producing slide shows with pandoc, including
13991475all reveal.js configuration options.
14001476.TP
1477+.B \f[C]titlegraphic\f[]
1478+title graphic for Beamer documents
1479+.RS
1480+.RE
1481+.TP
1482+.B \f[C]logo\f[]
1483+logo for Beamer documents
1484+.RS
1485+.RE
1486+.TP
14011487.B \f[C]slidy\-url\f[]
14021488base URL for Slidy documents (defaults to
14031489\f[C]http://www.w3.org/Talks/Tools/Slidy2\f[])
@@ -1467,7 +1553,7 @@ LaTeX variables are used when creating a PDF.
14671553.TP
14681554.B \f[C]papersize\f[]
14691555paper size, e.g.
1470−\f[C]letter\f[], \f[C]A4\f[]
1556+\f[C]letter\f[], \f[C]a4\f[]
14711557.RS
14721558.RE
14731559.TP
@@ -1745,6 +1831,31 @@ adjusts text to left (\f[C]l\f[]), right (\f[C]r\f[]), center
17451831if \f[C]true\f[] (the default), hyphenation will be used
17461832.RS
17471833.RE
1834+.SS Variables for ms
1835+.TP
1836+.B \f[C]pointsize\f[]
1837+point size (e.g.
1838+\f[C]10p\f[])
1839+.RS
1840+.RE
1841+.TP
1842+.B \f[C]lineheight\f[]
1843+line height (e.g.
1844+\f[C]12p\f[])
1845+.RS
1846+.RE
1847+.TP
1848+.B \f[C]fontfamily\f[]
1849+font family (e.g.
1850+\f[C]T\f[] or \f[C]P\f[])
1851+.RS
1852+.RE
1853+.TP
1854+.B \f[C]indent\f[]
1855+paragraph indent (e.g.
1856+\f[C]2m\f[])
1857+.RS
1858+.RE
17481859.SS Using variables in templates
17491860.PP
17501861Variable names are sequences of alphanumerics, \f[C]\-\f[], and
@@ -1925,6 +2036,12 @@ I\ like\ several\ of\ their\ flavors\ of\ ice\ cream:
19252036#22,\ for\ example,\ and\ #5.
19262037\f[]
19272038.fi
2039+.SS Extension: \f[C]space_in_atx_header\f[]
2040+.PP
2041+Many Markdown implementations do not require a space between the opening
2042+\f[C]#\f[]s of an ATX header and the header text, so that
2043+\f[C]#5\ bolt\f[] and \f[C]#hashtag\f[] count as headers.
2044+With this extension, pandoc does require the space.
19282045.SS Header identifiers
19292046.SS Extension: \f[C]header_attributes\f[]
19302047.PP
@@ -2065,9 +2182,9 @@ only in HTML, LaTeX, and ConTeXt formats.
20652182.PP
20662183If the \f[C]\-\-section\-divs\f[] option is specified, then each section
20672184will be wrapped in a \f[C]div\f[] (or a \f[C]section\f[], if
2068−\f[C]\-\-html5\f[] was specified), and the identifier will be attached
2069−to the enclosing \f[C]<div>\f[] (or \f[C]<section>\f[]) tag rather than
2070−the header itself.
2185+\f[C]html5\f[] was specified), and the identifier will be attached to
2186+the enclosing \f[C]<div>\f[] (or \f[C]<section>\f[]) tag rather than the
2187+header itself.
20712188This allows entire sections to be manipulated using JavaScript or
20722189treated differently in CSS.
20732190.SS Extension: \f[C]implicit_header_references\f[]
@@ -2285,10 +2402,10 @@ Here \f[C]mycode\f[] is an identifier, \f[C]haskell\f[] and
22852402\f[C]numberLines\f[] are classes, and \f[C]startFrom\f[] is an attribute
22862403with value \f[C]100\f[].
22872404Some output formats can use this information to do syntax highlighting.
2288−Currently, the only output formats that uses this information are HTML
2289−and LaTeX.
2290−If highlighting is supported for your output format and language, then
2291−the code block above will appear highlighted, with numbered lines.
2405+Currently, the only output formats that uses this information are HTML,
2406+LaTeX, Docx, and Ms.\ If highlighting is supported for your output
2407+format and language, then the code block above will appear highlighted,
2408+with numbered lines.
22922409(To see which languages are supported, type
22932410\f[C]pandoc\ \-\-list\-highlight\-languages\f[].) Otherwise, the code
22942411block above will appear as follows:
@@ -3164,7 +3281,8 @@ Note that YAML escaping rules must be followed.
31643281Thus, for example, if a title contains a colon, it must be quoted.
31653282The pipe character (\f[C]|\f[]) can be used to begin an indented block
31663283that will be interpreted literally, without need for escaping.
3167−This form is necessary when the field contains blank lines:
3284+This form is necessary when the field contains blank lines or
3285+block\-level formatting:
31683286.IP
31693287.nf
31703288\f[C]
@@ -3283,19 +3401,6 @@ This is a nice alternative to Markdown's \[lq]invisible\[rq] way of
32833401indicating hard line breaks using two trailing spaces on a line.
32843402.PP
32853403Backslash escapes do not work in verbatim contexts.
3286−.SS Smart punctuation
3287−.SS Extension
3288−.PP
3289−If the \f[C]\-\-smart\f[] option is specified, pandoc will produce
3290−typographically correct output, converting straight quotes to curly
3291−quotes, \f[C]\-\-\-\f[] to em\-dashes, \f[C]\-\-\f[] to en\-dashes, and
3292−\f[C]\&...\f[] to ellipses.
3293−Nonbreaking spaces are inserted after certain abbreviations, such as
3294−\[lq]Mr.\[rq]
3295−.PP
3296−Note: if your LaTeX template or any included header file call for the
3297−\f[C]csquotes\f[] package, pandoc will detect this automatically and use
3298−\f[C]\\enquote{...}\f[] for quoted text.
32993404.SS Inline formatting
33003405.SS Emphasis
33013406.PP
@@ -3560,7 +3665,9 @@ If the \f[C]\-\-webtex\f[] option is used, TeX formulas will be
35603665converted to \f[C]<img>\f[] tags that link to an external script that
35613666converts formulas to images.
35623667The formula will be URL\-encoded and concatenated with the URL provided.
3563−If no URL is specified, the CodeCogs will be used
3668+For SVG images you can for example use
3669+\f[C]\-\-webtex\ https://latex.codecogs.com/svg.latex?\f[].
3670+If no URL is specified, the CodeCogs URL generating PNGs will be used
35643671(\f[C]https://latex.codecogs.com/png.latex?\f[]).
35653672.IP "7." 3
35663673If the \f[C]\-\-mathjax\f[] option is used, TeX math will be displayed
@@ -3742,10 +3849,11 @@ before or after the link).
37423849.PP
37433850The link consists of link text in square brackets, followed by a label
37443851in square brackets.
3745−(There can be space between the two.) The link definition consists of
3746−the bracketed label, followed by a colon and a space, followed by the
3747−URL, and optionally (after a space) a link title either in quotes or in
3748−parentheses.
3852+(There cannot be space between the two unless the
3853+\f[C]spaced_reference_links\f[] extension is enabled.) The link
3854+definition consists of the bracketed label, followed by a colon and a
3855+space, followed by the URL, and optionally (after a space) a link title
3856+either in quotes or in parentheses.
37493857The label must not be parseable as a citation (assuming the
37503858\f[C]citations\f[] extension is enabled): citations take precedence over
37513859link labels.
@@ -3887,6 +3995,10 @@ One way to do this is to insert a nonbreaking space after the image:
38873995![This\ image\ won\[aq]t\ be\ a\ figure](/url/of/image.png)\\\
38883996\f[]
38893997.fi
3998+.PP
3999+Note that in reveal.js slide shows, an image in a paragraph by itself
4000+that has the \f[C]stretch\f[] class will fill the screen, and the
4001+caption and figure tags will be omitted.
38904002.SS Extension: \f[C]link_attributes\f[]
38914003.PP
38924004Attributes can be set on links and images:
@@ -4006,6 +4118,31 @@ note.]
40064118.fi
40074119.PP
40084120Inline and regular footnotes may be mixed freely.
4121+.SS Typography
4122+.SS Extension: \f[C]smart\f[]
4123+.PP
4124+Interpret straight quotes as curly quotes, \f[C]\-\-\-\f[] as
4125+em\-dashes, \f[C]\-\-\f[] as en\-dashes, and \f[C]\&...\f[] as ellipses.
4126+Nonbreaking spaces are inserted after certain abbreviations, such as
4127+\[lq]Mr.\[rq] This option currently affects the input formats
4128+\f[C]markdown\f[], \f[C]commonmark\f[], \f[C]latex\f[],
4129+\f[C]mediawiki\f[], \f[C]org\f[], \f[C]rst\f[], and \f[C]twiki\f[], and
4130+the output formats \f[C]markdown\f[], \f[C]latex\f[], and
4131+\f[C]context\f[].
4132+.PP
4133+Note: If you are \f[I]writing\f[] Markdown, then the \f[C]smart\f[]
4134+extension has the reverse effect: what would have been curly quotes
4135+comes out straight.
4136+.PP
4137+In LaTeX, \f[C]smart\f[] means to use the standard TeX ligatures for
4138+quotation marks (\f[C]``\f[] and \f[C]\[aq]\[aq]\f[] for double quotes,
4139+\f[C]`\f[] and \f[C]\[aq]\f[] for single quotes) and dashes
4140+(\f[C]\-\-\f[] for en\-dash and \f[C]\-\-\-\f[] for em\-dash).
4141+If \f[C]smart\f[] is disabled, then in reading LaTeX pandoc will parse
4142+these characters literally.
4143+In writing LaTeX, enabling \f[C]smart\f[] tells pandoc to use the
4144+ligatures when possible; if \f[C]smart\f[] is disabled pandoc will use
4145+unicode quotation mark and dash characters.
40094146.SS Citations
40104147.SS Extension: \f[C]citations\f[]
40114148.PP
@@ -4311,6 +4448,13 @@ pandoc, but may be enabled by adding \f[C]+EXTENSION\f[] to the format
43114448name, where \f[C]EXTENSION\f[] is the name of the extension.
43124449Thus, for example, \f[C]markdown+hard_line_breaks\f[] is Markdown with
43134450hard line breaks.
4451+.SS Extension: \f[C]old_dashes\f[]
4452+.PP
4453+Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes:
4454+\f[C]\-\f[] before a numeral is an en\-dash, and \f[C]\-\-\f[] is an
4455+em\-dash.
4456+This option only has an effect if \f[C]smart\f[] is enabled.
4457+It is selected automatically for \f[C]textile\f[] input.
43144458.SS Extension: \f[C]angle_brackets_escapable\f[]
43154459.PP
43164460Allow \f[C]<\f[] and \f[C]>\f[] to be backslash\-escaped, as they can be
@@ -4320,6 +4464,16 @@ This is implied by pandoc's default \f[C]all_symbols_escapable\f[].
43204464.PP
43214465Allow a list to occur right after a paragraph, with no intervening blank
43224466space.
4467+.SS Extension: \f[C]spaced_reference_links\f[]
4468+.PP
4469+Allow whitespace between the two components of a reference link, for
4470+example,
4471+.IP
4472+.nf
4473+\f[C]
4474+[foo]\ [bar].
4475+\f[]
4476+.fi
43234477.SS Extension: \f[C]hard_line_breaks\f[]
43244478.PP
43254479Causes all newlines within a paragraph to be interpreted as hard line
@@ -4593,6 +4747,9 @@ Headers \f[I]above\f[] the slide level in the hierarchy create
45934747\[lq]title slides,\[rq] which just contain the section title and help to
45944748break the slide show into sections.
45954749.IP \[bu] 2
4750+Content \f[I]above\f[] the slide level will not appear in the slide
4751+show.
4752+.IP \[bu] 2
45964753A title page is constructed automatically from the document's title
45974754block, if present.
45984755(In the case of beamer, this can be disabled by commenting out some
@@ -4887,7 +5044,7 @@ For example:
48875044If you append \f[C]+lhs\f[] (or \f[C]+literate_haskell\f[]) to an
48885045appropriate input or output format (\f[C]markdown\f[],
48895046\f[C]markdown_strict\f[], \f[C]rst\f[], or \f[C]latex\f[] for input or
4890−output; \f[C]beamer\f[], \f[C]html\f[] or \f[C]html5\f[] for output
5047+output; \f[C]beamer\f[], \f[C]html4\f[] or \f[C]html5\f[] for output
48915048only), pandoc will treat the document as literate Haskell source.
48925049This means that
48935050.IP \[bu] 2
@@ -4940,12 +5097,16 @@ pandoc\ \-f\ markdown+lhs\ \-t\ html+lhs
49405097.PP
49415098writes HTML with the Haskell code in bird tracks, so it can be copied
49425099and pasted as literate Haskell source.
5100+.PP
5101+Note that GHC expects the bird tracks in the first column, so indentend
5102+literate code blocks (e.g.\ inside an itemized environment) will not be
5103+picked up by the Haskell compiler.
49435104.SH SYNTAX HIGHLIGHTING
49445105.PP
49455106Pandoc will automatically highlight syntax in fenced code blocks that
49465107are marked with a language name.
4947−The Haskell library highlighting\-kate is used for highlighting, which
4948−works in HTML, Docx, and LaTeX/PDF output.
5108+The Haskell library skylighting is used for highlighting, which works in
5109+HTML, Docx, Ms, and LaTeX/PDF output.
49495110To see a list of language names that pandoc will recognize, type
49505111\f[C]pandoc\ \-\-list\-highlight\-languages\f[].
49515112.PP
@@ -5038,7 +5199,7 @@ pandoc\ \-\-print\-default\-data\-file\ sample.lua
50385199.fi
50395200.SH AUTHORS
50405201.PP
5041−© 2006\-2016 John MacFarlane (jgm\@berkeley.edu).
5202+© 2006\-2017 John MacFarlane (jgm\@berkeley.edu).
50425203Released under the GPL, version 2 or greater.
50435204This software carries no warranty of any kind.
50445205(See COPYRIGHT for full copyright and warranty notices.)