diff options
Diffstat (limited to 'man/pandoc.1')
| -rw-r--r-- | man/pandoc.1 | 2359 |
1 files changed, 1511 insertions, 848 deletions
diff --git a/man/pandoc.1 b/man/pandoc.1 index 104458b06..7cac72ebd 100644 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -1,63 +1,63 @@ .\"t -.TH PANDOC 1 "January 29, 2017" "pandoc 1.19.2.4" +.TH PANDOC 1 "March 2, 2018" "pandoc 2.1.2" .SH NAME pandoc - general markup converter .SH SYNOPSIS .PP -\f[C]pandoc\f[] [\f[I]options\f[]] [\f[I]input\-file\f[]]\&... +\f[C]pandoc\f[] [\f[I]options\f[]] [\f[I]input\-file\f[]]... .SH DESCRIPTION .PP Pandoc is a Haskell library for converting from one markup format to another, and a command\-line tool that uses this library. -It can read Markdown, CommonMark, PHP Markdown Extra, GitHub\-Flavored -Markdown, MultiMarkdown, and (subsets of) Textile, reStructuredText, -HTML, LaTeX, MediaWiki markup, TWiki markup, Haddock markup, OPML, Emacs -Org mode, DocBook, txt2tags, EPUB, ODT and Word docx; and it can write -plain text, Markdown, CommonMark, PHP Markdown Extra, GitHub\-Flavored -Markdown, MultiMarkdown, reStructuredText, XHTML, HTML5, LaTeX -(including \f[C]beamer\f[] slide shows), ConTeXt, RTF, OPML, DocBook, -OpenDocument, ODT, Word docx, GNU Texinfo, MediaWiki markup, DokuWiki -markup, ZimWiki markup, Haddock markup, EPUB (v2 or v3), FictionBook2, -Textile, groff man pages, Emacs Org mode, AsciiDoc, InDesign ICML, TEI -Simple, and Slidy, Slideous, DZSlides, reveal.js or S5 HTML slide shows. -It can also produce PDF output on systems where LaTeX, ConTeXt, or -\f[C]wkhtmltopdf\f[] is installed. -.PP -Pandoc's enhanced version of Markdown includes syntax for footnotes, -tables, flexible ordered lists, definition lists, fenced code blocks, -superscripts and subscripts, strikeout, metadata blocks, automatic -tables of contents, embedded LaTeX math, citations, and Markdown inside -HTML block elements. -(These enhancements, described further under Pandoc's Markdown, can be -disabled using the \f[C]markdown_strict\f[] input or output format.) -.PP -In contrast to most existing tools for converting Markdown to HTML, -which use regex substitutions, pandoc has a modular design: it consists -of a set of readers, which parse text in a given format and produce a -native representation of the document, and a set of writers, which -convert this native representation into a target format. +.PP +Pandoc can read Markdown, CommonMark, PHP Markdown Extra, +GitHub\-Flavored Markdown, MultiMarkdown, and (subsets of) Textile, +reStructuredText, HTML, LaTeX, MediaWiki markup, TWiki markup, TikiWiki +markup, Creole 1.0, Haddock markup, OPML, Emacs Org mode, DocBook, JATS, +Muse, txt2tags, Vimwiki, EPUB, ODT, and Word docx. +.PP +Pandoc can write plain text, Markdown, CommonMark, PHP Markdown Extra, +GitHub\-Flavored Markdown, MultiMarkdown, reStructuredText, XHTML, +HTML5, LaTeX (including \f[C]beamer\f[] slide shows), ConTeXt, RTF, +OPML, DocBook, JATS, OpenDocument, ODT, Word docx, GNU Texinfo, +MediaWiki markup, DokuWiki markup, ZimWiki markup, Haddock markup, EPUB +(v2 or v3), FictionBook2, Textile, groff man, groff ms, Emacs Org mode, +AsciiDoc, InDesign ICML, TEI Simple, Muse, PowerPoint slide shows and +Slidy, Slideous, DZSlides, reveal.js or S5 HTML slide shows. +It can also produce PDF output on systems where LaTeX, ConTeXt, +\f[C]pdfroff\f[], \f[C]wkhtmltopdf\f[], \f[C]prince\f[], or +\f[C]weasyprint\f[] is installed. +.PP +Pandoc\[aq]s enhanced version of Markdown includes syntax for tables, +definition lists, metadata blocks, \f[C]Div\f[] blocks, footnotes and +citations, embedded LaTeX (including math), Markdown inside HTML block +elements, and much more. +These enhancements, described further under Pandoc\[aq]s Markdown, can +be disabled using the \f[C]markdown_strict\f[] format. +.PP +Pandoc has a modular design: it consists of a set of readers, which +parse text in a given format and produce a native representation of the +document (like an \f[I]abstract syntax tree\f[] or AST), and a set of +writers, which convert this native representation into a target format. Thus, adding an input or output format requires only adding a reader or writer. +Users can also run custom pandoc filters to modify the intermediate AST. .PP -Because pandoc's intermediate representation of a document is less +Because pandoc\[aq]s intermediate representation of a document is less expressive than many of the formats it converts between, one should not expect perfect conversions between every format and every other. Pandoc attempts to preserve the structural elements of a document, but not formatting details such as margin size. And some document elements, such as complex tables, may not fit into -pandoc's simple document model. -While conversions from pandoc's Markdown to all formats aspire to be -perfect, conversions from formats more expressive than pandoc's Markdown -can be expected to be lossy. +pandoc\[aq]s simple document model. +While conversions from pandoc\[aq]s Markdown to all formats aspire to be +perfect, conversions from formats more expressive than pandoc\[aq]s +Markdown can be expected to be lossy. .SS Using \f[C]pandoc\f[] .PP -If no \f[I]input\-file\f[] is specified, input is read from +If no \f[I]input\-files\f[] are specified, input is read from \f[I]stdin\f[]. -Otherwise, the \f[I]input\-files\f[] are concatenated (with a blank line -between each) and used as input. -Output goes to \f[I]stdout\f[] by default (though output to -\f[I]stdout\f[] is disabled for the \f[C]odt\f[], \f[C]docx\f[], -\f[C]epub\f[], and \f[C]epub3\f[] output formats). +Output goes to \f[I]stdout\f[] by default. For output to a file, use the \f[C]\-o\f[] option: .IP .nf @@ -66,10 +66,10 @@ pandoc\ \-o\ output.html\ input.txt \f[] .fi .PP -By default, pandoc produces a document fragment, not a standalone -document with a proper header and footer. -To produce a standalone document, use the \f[C]\-s\f[] or -\f[C]\-\-standalone\f[] flag: +By default, pandoc produces a document fragment. +To produce a standalone document (e.g. +a valid HTML file including \f[C]<head>\f[] and \f[C]<body>\f[]), use +the \f[C]\-s\f[] or \f[C]\-\-standalone\f[] flag: .IP .nf \f[C] @@ -78,27 +78,17 @@ pandoc\ \-s\ \-o\ output.html\ input.txt .fi .PP For more information on how standalone documents are produced, see -Templates, below. -.PP -Instead of a file, an absolute URI may be given. -In this case pandoc will fetch the content using HTTP: -.IP -.nf -\f[C] -pandoc\ \-f\ html\ \-t\ markdown\ http://www.fsf.org -\f[] -.fi +Templates below. .PP If multiple input files are given, \f[C]pandoc\f[] will concatenate them all (with blank lines between them) before parsing. -This feature is disabled for binary input formats such as \f[C]EPUB\f[], -\f[C]odt\f[], and \f[C]docx\f[]. +(Use \f[C]\-\-file\-scope\f[] to parse files individually.) +.SS Specifying formats .PP The format of the input and output can be specified explicitly using command\-line options. -The input format can be specified using the \f[C]\-r/\-\-read\f[] or -\f[C]\-f/\-\-from\f[] options, the output format using the -\f[C]\-w/\-\-write\f[] or \f[C]\-t/\-\-to\f[] options. +The input format can be specified using the \f[C]\-f/\-\-from\f[] +option, the output format using the \f[C]\-t/\-\-to\f[] option. Thus, to convert \f[C]hello.txt\f[] from Markdown to LaTeX, you could type: .IP @@ -116,17 +106,15 @@ pandoc\ \-f\ html\ \-t\ markdown\ hello.html \f[] .fi .PP -Supported output formats are listed below under the \f[C]\-t/\-\-to\f[] -option. -Supported input formats are listed below under the \f[C]\-f/\-\-from\f[] -option. -Note that the \f[C]rst\f[], \f[C]textile\f[], \f[C]latex\f[], and -\f[C]html\f[] readers are not complete; there are some constructs that -they do not parse. +Supported input and output formats are listed below under Options (see +\f[C]\-f\f[] for input formats and \f[C]\-t\f[] for output formats). +You can also use \f[C]pandoc\ \-\-list\-input\-formats\f[] and +\f[C]pandoc\ \-\-list\-output\-formats\f[] to print lists of supported +formats. .PP If the input or output format is not specified explicitly, \f[C]pandoc\f[] will attempt to guess it from the extensions of the -input and output filenames. +filenames. Thus, for example, .IP .nf @@ -137,11 +125,12 @@ pandoc\ \-o\ hello.tex\ hello.txt .PP will convert \f[C]hello.txt\f[] from Markdown to LaTeX. If no output file is specified (so that output goes to \f[I]stdout\f[]), -or if the output file's extension is unknown, the output format will +or if the output file\[aq]s extension is unknown, the output format will default to HTML. If no input file is specified (so that input comes from \f[I]stdin\f[]), -or if the input files' extensions are unknown, the input format will be -assumed to be Markdown unless explicitly specified. +or if the input files\[aq] extensions are unknown, the input format will +be assumed to be Markdown. +.SS Character encoding .PP Pandoc uses the UTF\-8 character encoding for both input and output. If your local character encoding is not UTF\-8, you should pipe input @@ -160,8 +149,7 @@ the \f[C]\-s/\-\-standalone\f[] option. .SS Creating a PDF .PP To produce a PDF, specify an output file with a \f[C]\&.pdf\f[] -extension. -By default, pandoc will use LaTeX to convert it to PDF: +extension: .IP .nf \f[C] @@ -169,67 +157,96 @@ pandoc\ test.txt\ \-o\ test.pdf \f[] .fi .PP -Production of a PDF requires that a LaTeX engine be installed (see -\f[C]\-\-latex\-engine\f[], below), and assumes that the following LaTeX -packages are available: \f[C]amsfonts\f[], \f[C]amsmath\f[], -\f[C]lm\f[], \f[C]ifxetex\f[], \f[C]ifluatex\f[], \f[C]eurosym\f[], -\f[C]listings\f[] (if the \f[C]\-\-listings\f[] option is used), -\f[C]fancyvrb\f[], \f[C]longtable\f[], \f[C]booktabs\f[], -\f[C]graphicx\f[] and \f[C]grffile\f[] (if the document contains -images), \f[C]hyperref\f[], \f[C]ulem\f[], \f[C]geometry\f[] (with the +By default, pandoc will use LaTeX to create the PDF, which requires that +a LaTeX engine be installed (see \f[C]\-\-pdf\-engine\f[] below). +.PP +Alternatively, pandoc can use ConTeXt, \f[C]pdfroff\f[], or any of the +following HTML/CSS\-to\-PDF\-engines, to create a PDF: +\f[C]wkhtmltopdf\f[], \f[C]weasyprint\f[] or \f[C]prince\f[]. +To do this, specify an output file with a \f[C]\&.pdf\f[] extension, as +before, but add the \f[C]\-\-pdf\-engine\f[] option or +\f[C]\-t\ context\f[], \f[C]\-t\ html\f[], or \f[C]\-t\ ms\f[] to the +command line (\f[C]\-t\ html\f[] defaults to +\f[C]\-\-pdf\-engine=wkhtmltopdf\f[]). +.PP +PDF output can be controlled using variables for LaTeX (if LaTeX is +used) and variables for ConTeXt (if ConTeXt is used). +When using an HTML/CSS\-to\-PDF\-engine, \f[C]\-\-css\f[] affects the +output. +If \f[C]wkhtmltopdf\f[] is used, then the variables +\f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[], +\f[C]margin\-bottom\f[], \f[C]footer\-html\f[], \f[C]header\-html\f[] +and \f[C]papersize\f[] will affect the output. +.PP +To debug the PDF creation, it can be useful to look at the intermediate +representation: instead of \f[C]\-o\ test.pdf\f[], use for example +\f[C]\-s\ \-o\ test.tex\f[] to output the generated LaTeX. +You can then test it with \f[C]pdflatex\ test.tex\f[]. +.PP +When using LaTeX, the following packages need to be available (they are +included with all recent versions of TeX Live): \f[C]amsfonts\f[], +\f[C]amsmath\f[], \f[C]lm\f[], \f[C]unicode\-math\f[], \f[C]ifxetex\f[], +\f[C]ifluatex\f[], \f[C]listings\f[] (if the \f[C]\-\-listings\f[] +option is used), \f[C]fancyvrb\f[], \f[C]longtable\f[], +\f[C]booktabs\f[], \f[C]graphicx\f[] and \f[C]grffile\f[] (if the +document contains images), \f[C]hyperref\f[], \f[C]xcolor\f[] (with +\f[C]colorlinks\f[]), \f[C]ulem\f[], \f[C]geometry\f[] (with the \f[C]geometry\f[] variable set), \f[C]setspace\f[] (with \f[C]linestretch\f[]), and \f[C]babel\f[] (with \f[C]lang\f[]). The use of \f[C]xelatex\f[] or \f[C]lualatex\f[] as the LaTeX engine -requires \f[C]fontspec\f[]; \f[C]xelatex\f[] uses \f[C]mathspec\f[], -\f[C]polyglossia\f[] (with \f[C]lang\f[]), \f[C]xecjk\f[], and -\f[C]bidi\f[] (with the \f[C]dir\f[] variable set). +requires \f[C]fontspec\f[]. +\f[C]xelatex\f[] uses \f[C]polyglossia\f[] (with \f[C]lang\f[]), +\f[C]xecjk\f[], and \f[C]bidi\f[] (with the \f[C]dir\f[] variable set). +If the \f[C]mathspec\f[] variable is set, \f[C]xelatex\f[] will use +\f[C]mathspec\f[] instead of \f[C]unicode\-math\f[]. The \f[C]upquote\f[] and \f[C]microtype\f[] packages are used if -available, and \f[C]csquotes\f[] will be used for smart punctuation if -added to the template or included in any header file. +available, and \f[C]csquotes\f[] will be used for typography if added to +the template or included in any header file. The \f[C]natbib\f[], \f[C]biblatex\f[], \f[C]bibtex\f[], and \f[C]biber\f[] packages can optionally be used for citation rendering. -These are included with all recent versions of TeX Live. +.SS Reading from the Web .PP -Alternatively, pandoc can use ConTeXt or \f[C]wkhtmltopdf\f[] to create -a PDF. -To do this, specify an output file with a \f[C]\&.pdf\f[] extension, as -before, but add \f[C]\-t\ context\f[] or \f[C]\-t\ html5\f[] to the -command line. +Instead of an input file, an absolute URI may be given. +In this case pandoc will fetch the content using HTTP: +.IP +.nf +\f[C] +pandoc\ \-f\ html\ \-t\ markdown\ http://www.fsf.org +\f[] +.fi .PP -PDF output can be controlled using variables for LaTeX (if LaTeX is -used) and variables for ConTeXt (if ConTeXt is used). -If \f[C]wkhtmltopdf\f[] is used, then the variables -\f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[], -\f[C]margin\-bottom\f[], and \f[C]papersize\f[] will affect the output, -as will \f[C]\-\-css\f[]. +It is possible to supply a custom User\-Agent string or other header +when requesting a document from a URL: +.IP +.nf +\f[C] +pandoc\ \-f\ html\ \-t\ markdown\ \-\-request\-header\ User\-Agent:"Mozilla/5.0"\ \\ +\ \ http://www.fsf.org +\f[] +.fi .SH OPTIONS .SS General options .TP .B \f[C]\-f\f[] \f[I]FORMAT\f[], \f[C]\-r\f[] \f[I]FORMAT\f[], \f[C]\-\-from=\f[]\f[I]FORMAT\f[], \f[C]\-\-read=\f[]\f[I]FORMAT\f[] Specify input format. \f[I]FORMAT\f[] can be \f[C]native\f[] (native Haskell), \f[C]json\f[] -(JSON version of native AST), \f[C]markdown\f[] (pandoc's extended +(JSON version of native AST), \f[C]markdown\f[] (pandoc\[aq]s extended Markdown), \f[C]markdown_strict\f[] (original unextended Markdown), -\f[C]markdown_phpextra\f[] (PHP Markdown Extra), -\f[C]markdown_github\f[] (GitHub\-Flavored Markdown), -\f[C]markdown_mmd\f[] (MultiMarkdown), \f[C]commonmark\f[] (CommonMark -Markdown), \f[C]textile\f[] (Textile), \f[C]rst\f[] (reStructuredText), -\f[C]html\f[] (HTML), \f[C]docbook\f[] (DocBook), \f[C]t2t\f[] -(txt2tags), \f[C]docx\f[] (docx), \f[C]odt\f[] (ODT), \f[C]epub\f[] -(EPUB), \f[C]opml\f[] (OPML), \f[C]org\f[] (Emacs Org mode), -\f[C]mediawiki\f[] (MediaWiki markup), \f[C]twiki\f[] (TWiki markup), -\f[C]haddock\f[] (Haddock markup), or \f[C]latex\f[] (LaTeX). -If \f[C]+lhs\f[] is appended to \f[C]markdown\f[], \f[C]rst\f[], -\f[C]latex\f[], or \f[C]html\f[], the input will be treated as literate -Haskell source: see Literate Haskell support, below. -Markdown syntax extensions can be individually enabled or disabled by -appending \f[C]+EXTENSION\f[] or \f[C]\-EXTENSION\f[] to the format -name. -So, for example, \f[C]markdown_strict+footnotes+definition_lists\f[] is -strict Markdown with footnotes and definition lists enabled, and -\f[C]markdown\-pipe_tables+hard_line_breaks\f[] is pandoc's Markdown -without pipe tables and with hard line breaks. -See Pandoc's Markdown, below, for a list of extensions and their names. +\f[C]markdown_phpextra\f[] (PHP Markdown Extra), \f[C]markdown_mmd\f[] +(MultiMarkdown), \f[C]gfm\f[] (GitHub\-Flavored Markdown), +\f[C]commonmark\f[] (CommonMark Markdown), \f[C]textile\f[] (Textile), +\f[C]rst\f[] (reStructuredText), \f[C]html\f[] (HTML), \f[C]docbook\f[] +(DocBook), \f[C]t2t\f[] (txt2tags), \f[C]docx\f[] (docx), \f[C]odt\f[] +(ODT), \f[C]epub\f[] (EPUB), \f[C]opml\f[] (OPML), \f[C]org\f[] (Emacs +Org mode), \f[C]mediawiki\f[] (MediaWiki markup), \f[C]twiki\f[] (TWiki +markup), \f[C]tikiwiki\f[] (TikiWiki markup), \f[C]creole\f[] (Creole +1.0), \f[C]haddock\f[] (Haddock markup), or \f[C]latex\f[] (LaTeX). +(\f[C]markdown_github\f[] provides deprecated and less accurate support +for Github\-Flavored Markdown; please use \f[C]gfm\f[] instead, unless +you need to use extensions other than \f[C]smart\f[].) Extensions can be +individually enabled or disabled by appending \f[C]+EXTENSION\f[] or +\f[C]\-EXTENSION\f[] to the format name. +See Extensions below, for a list of extensions and their names. See \f[C]\-\-list\-input\-formats\f[] and \f[C]\-\-list\-extensions\f[], below. .RS @@ -239,38 +256,39 @@ below. Specify output format. \f[I]FORMAT\f[] can be \f[C]native\f[] (native Haskell), \f[C]json\f[] (JSON version of native AST), \f[C]plain\f[] (plain text), -\f[C]markdown\f[] (pandoc's extended Markdown), \f[C]markdown_strict\f[] -(original unextended Markdown), \f[C]markdown_phpextra\f[] (PHP Markdown -Extra), \f[C]markdown_github\f[] (GitHub\-Flavored Markdown), -\f[C]markdown_mmd\f[] (MultiMarkdown), \f[C]commonmark\f[] (CommonMark -Markdown), \f[C]rst\f[] (reStructuredText), \f[C]html\f[] (XHTML), -\f[C]html5\f[] (HTML5), \f[C]latex\f[] (LaTeX), \f[C]beamer\f[] (LaTeX -beamer slide show), \f[C]context\f[] (ConTeXt), \f[C]man\f[] (groff -man), \f[C]mediawiki\f[] (MediaWiki markup), \f[C]dokuwiki\f[] (DokuWiki -markup), \f[C]zimwiki\f[] (ZimWiki markup), \f[C]textile\f[] (Textile), +\f[C]markdown\f[] (pandoc\[aq]s extended Markdown), +\f[C]markdown_strict\f[] (original unextended Markdown), +\f[C]markdown_phpextra\f[] (PHP Markdown Extra), \f[C]markdown_mmd\f[] +(MultiMarkdown), \f[C]gfm\f[] (GitHub\-Flavored Markdown), +\f[C]commonmark\f[] (CommonMark Markdown), \f[C]rst\f[] +(reStructuredText), \f[C]html4\f[] (XHTML 1.0 Transitional), +\f[C]html\f[] or \f[C]html5\f[] (HTML5/XHTML polyglot markup), +\f[C]latex\f[] (LaTeX), \f[C]beamer\f[] (LaTeX beamer slide show), +\f[C]context\f[] (ConTeXt), \f[C]man\f[] (groff man), \f[C]mediawiki\f[] +(MediaWiki markup), \f[C]dokuwiki\f[] (DokuWiki markup), +\f[C]zimwiki\f[] (ZimWiki markup), \f[C]textile\f[] (Textile), \f[C]org\f[] (Emacs Org mode), \f[C]texinfo\f[] (GNU Texinfo), -\f[C]opml\f[] (OPML), \f[C]docbook\f[] (DocBook 4), \f[C]docbook5\f[] -(DocBook 5), \f[C]opendocument\f[] (OpenDocument), \f[C]odt\f[] -(OpenOffice text document), \f[C]docx\f[] (Word docx), \f[C]haddock\f[] -(Haddock markup), \f[C]rtf\f[] (rich text format), \f[C]epub\f[] (EPUB -v2 book), \f[C]epub3\f[] (EPUB v3), \f[C]fb2\f[] (FictionBook2 e\-book), -\f[C]asciidoc\f[] (AsciiDoc), \f[C]icml\f[] (InDesign ICML), +\f[C]opml\f[] (OPML), \f[C]docbook\f[] or \f[C]docbook4\f[] (DocBook 4), +\f[C]docbook5\f[] (DocBook 5), \f[C]jats\f[] (JATS XML), +\f[C]opendocument\f[] (OpenDocument), \f[C]odt\f[] (OpenOffice text +document), \f[C]docx\f[] (Word docx), \f[C]haddock\f[] (Haddock markup), +\f[C]rtf\f[] (rich text format), \f[C]epub2\f[] (EPUB v2 book), +\f[C]epub\f[] or \f[C]epub3\f[] (EPUB v3), \f[C]fb2\f[] (FictionBook2 +e\-book), \f[C]asciidoc\f[] (AsciiDoc), \f[C]icml\f[] (InDesign ICML), \f[C]tei\f[] (TEI Simple), \f[C]slidy\f[] (Slidy HTML and JavaScript slide show), \f[C]slideous\f[] (Slideous HTML and JavaScript slide show), \f[C]dzslides\f[] (DZSlides HTML5 + JavaScript slide show), \f[C]revealjs\f[] (reveal.js HTML5 + JavaScript slide show), \f[C]s5\f[] -(S5 HTML and JavaScript slide show), or the path of a custom lua writer -(see Custom writers, below). -Note that \f[C]odt\f[], \f[C]epub\f[], and \f[C]epub3\f[] output will -not be directed to \f[I]stdout\f[]; an output filename must be specified -using the \f[C]\-o/\-\-output\f[] option. -If \f[C]+lhs\f[] is appended to \f[C]markdown\f[], \f[C]rst\f[], -\f[C]latex\f[], \f[C]beamer\f[], \f[C]html\f[], or \f[C]html5\f[], the -output will be rendered as literate Haskell source: see Literate Haskell -support, below. -Markdown syntax extensions can be individually enabled or disabled by -appending \f[C]+EXTENSION\f[] or \f[C]\-EXTENSION\f[] to the format -name, as described above under \f[C]\-f\f[]. +(S5 HTML and JavaScript slide show), \f[C]pptx\f[] (PowerPoint slide +show) or the path of a custom lua writer (see Custom writers, below). +(\f[C]markdown_github\f[] provides deprecated and less accurate support +for Github\-Flavored Markdown; please use \f[C]gfm\f[] instead, unless +you use extensions that do not work with \f[C]gfm\f[].) Note that +\f[C]odt\f[], \f[C]docx\f[], and \f[C]epub\f[] output will not be +directed to \f[I]stdout\f[] unless forced with \f[C]\-o\ \-\f[]. +Extensions can be individually enabled or disabled by appending +\f[C]+EXTENSION\f[] or \f[C]\-EXTENSION\f[] to the format name. +See Extensions below, for a list of extensions and their names. See \f[C]\-\-list\-output\-formats\f[] and \f[C]\-\-list\-extensions\f[], below. .RS @@ -278,9 +296,9 @@ See \f[C]\-\-list\-output\-formats\f[] and .TP .B \f[C]\-o\f[] \f[I]FILE\f[], \f[C]\-\-output=\f[]\f[I]FILE\f[] Write output to \f[I]FILE\f[] instead of \f[I]stdout\f[]. -If \f[I]FILE\f[] is \f[C]\-\f[], output will go to \f[I]stdout\f[]. -(Exception: if the output format is \f[C]odt\f[], \f[C]docx\f[], -\f[C]epub\f[], or \f[C]epub3\f[], output to stdout is disabled.) +If \f[I]FILE\f[] is \f[C]\-\f[], output will go to \f[I]stdout\f[], even +if a non\-textual format (\f[C]docx\f[], \f[C]odt\f[], \f[C]epub2\f[], +\f[C]epub3\f[]) is specified. .RS .RE .TP @@ -288,7 +306,7 @@ If \f[I]FILE\f[] is \f[C]\-\f[], output will go to \f[I]stdout\f[]. Specify the user data directory to search for pandoc data files. If this option is not specified, the default user data directory will be used. -This is, in Unix: +This is, in UNIX: .RS .IP .nf @@ -317,7 +335,7 @@ You can find the default user data directory on your system by looking at the output of \f[C]pandoc\ \-\-version\f[]. A \f[C]reference.odt\f[], \f[C]reference.docx\f[], \f[C]epub.css\f[], \f[C]templates\f[], \f[C]slidy\f[], \f[C]slideous\f[], or \f[C]s5\f[] -directory placed in this directory will override pandoc's normal +directory placed in this directory will override pandoc\[aq]s normal defaults. .RE .TP @@ -329,7 +347,7 @@ To enable bash completion with pandoc, add this to your .IP .nf \f[C] -\ eval\ "$(pandoc\ \-\-bash\-completion)" +eval\ "$(pandoc\ \-\-bash\-completion)" \f[] .fi .RE @@ -340,6 +358,23 @@ Currently this only has an effect with PDF output. .RS .RE .TP +.B \f[C]\-\-quiet\f[] +Suppress warning messages. +.RS +.RE +.TP +.B \f[C]\-\-fail\-if\-warnings\f[] +Exit with error status if there are any warnings. +.RS +.RE +.TP +.B \f[C]\-\-log=\f[]\f[I]FILE\f[] +Write log messages in machine\-readable JSON format to \f[I]FILE\f[]. +All messages above DEBUG level will be written, regardless of verbosity +settings (\f[C]\-\-verbose\f[], \f[C]\-\-quiet\f[]). +.RS +.RE +.TP .B \f[C]\-\-list\-input\-formats\f[] List supported input formats, one per line. .RS @@ -350,10 +385,12 @@ List supported output formats, one per line. .RS .RE .TP -.B \f[C]\-\-list\-extensions\f[] -List supported Markdown extensions, one per line, followed by a -\f[C]+\f[] or \f[C]\-\f[] indicating whether it is enabled by default in -pandoc's Markdown. +.B \f[C]\-\-list\-extensions\f[][\f[C]=\f[]\f[I]FORMAT\f[]] +List supported extensions, one per line, preceded by a \f[C]+\f[] or +\f[C]\-\f[] indicating whether it is enabled by default in +\f[I]FORMAT\f[]. +If \f[I]FORMAT\f[] is not specified, defaults for pandoc\[aq]s Markdown +are given. .RS .RE .TP @@ -379,48 +416,21 @@ Show usage message. .RE .SS Reader options .TP -.B \f[C]\-R\f[], \f[C]\-\-parse\-raw\f[] -Parse untranslatable HTML codes and LaTeX environments as raw HTML or -LaTeX, instead of ignoring them. -Affects only HTML and LaTeX input. -Raw HTML can be printed in Markdown, reStructuredText, Emacs Org mode, -HTML, Slidy, Slideous, DZSlides, reveal.js, and S5 output; raw LaTeX can -be printed in Markdown, reStructuredText, Emacs Org mode, LaTeX, and -ConTeXt output. -The default is for the readers to omit untranslatable HTML codes and -LaTeX environments. -(The LaTeX reader does pass through untranslatable LaTeX -\f[I]commands\f[], even if \f[C]\-R\f[] is not specified.) -.RS -.RE -.TP -.B \f[C]\-S\f[], \f[C]\-\-smart\f[] -Produce typographically correct output, converting straight quotes to -curly quotes, \f[C]\-\-\-\f[] to em\-dashes, \f[C]\-\-\f[] to -en\-dashes, and \f[C]\&...\f[] to ellipses. -Nonbreaking spaces are inserted after certain abbreviations, such as -\[lq]Mr.\[rq] (Note: This option is selected automatically when the -output format is \f[C]latex\f[] or \f[C]context\f[], unless -\f[C]\-\-no\-tex\-ligatures\f[] is used. -It has no effect for \f[C]latex\f[] input.) -.RS -.RE -.TP -.B \f[C]\-\-old\-dashes\f[] -Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: -\f[C]\-\f[] before a numeral is an en\-dash, and \f[C]\-\-\f[] is an -em\-dash. -This option is selected automatically for \f[C]textile\f[] input. +.B \f[C]\-\-base\-header\-level=\f[]\f[I]NUMBER\f[] +Specify the base level for headers (defaults to 1). .RS .RE .TP -.B \f[C]\-\-base\-header\-level=\f[]\f[I]NUMBER\f[] -Specify the base level for headers (defaults to 1). +.B \f[C]\-\-strip\-empty\-paragraphs\f[] +\f[I]Deprecated. Use the \f[CI]+empty_paragraphs\f[I] extension +instead.\f[] Ignore paragraphs with no content. +This option is useful for converting word processing documents where +users have used empty paragraphs to create inter\-paragraph space. .RS .RE .TP .B \f[C]\-\-indented\-code\-classes=\f[]\f[I]CLASSES\f[] -Specify classes to use for indented code blocks\[en]for example, +Specify classes to use for indented code blocks\-\-for example, \f[C]perl,numberLines\f[] or \f[C]haskell\f[]. Multiple classes may be separated by spaces or commas. .RS @@ -448,7 +458,7 @@ Reading binary files (docx, odt, epub) implies \f[C]\-\-file\-scope\f[]. Specify an executable to be used as a filter transforming the pandoc AST after the input is parsed and before the output is written. The executable should read JSON from stdin and write JSON to stdout. -The JSON must be formatted like pandoc's own JSON input and output. +The JSON must be formatted like pandoc\[aq]s own JSON input and output. The name of the output format will be passed to the filter as the first argument. Hence, @@ -476,15 +486,52 @@ writing filters in Haskell. Those who would prefer to write filters in python can use the module \f[C]pandocfilters\f[], installable from PyPI. There are also pandoc filter libraries in PHP, perl, and -javascript/node.js. +JavaScript/node.js. .PP In order of preference, pandoc will look for filters in .IP "1." 3 a specified full or relative path (executable or non\-executable) .IP "2." 3 -\f[C]$DATADIR/filters\f[] (executable or non\-executable) +\f[C]$DATADIR/filters\f[] (executable or non\-executable) where +\f[C]$DATADIR\f[] is the user data directory (see +\f[C]\-\-data\-dir\f[], above). .IP "3." 3 \f[C]$PATH\f[] (executable only) +.PP +Filters and lua\-filters are applied in the order specified on the +command line. +.RE +.TP +.B \f[C]\-\-lua\-filter=\f[]\f[I]SCRIPT\f[] +Transform the document in a similar fashion as JSON filters (see +\f[C]\-\-filter\f[]), but use pandoc\[aq]s build\-in lua filtering +system. +The given lua script is expected to return a list of lua filters which +will be applied in order. +Each lua filter must contain element\-transforming functions indexed by +the name of the AST element on which the filter function should be +applied. +.RS +.PP +The \f[C]pandoc\f[] lua module provides helper functions for element +creation. +It is always loaded into the script\[aq]s lua environment. +.PP +The following is an example lua script for macro\-expansion: +.IP +.nf +\f[C] +function\ expand_hello_world(inline) +\ \ if\ inline.c\ ==\ \[aq]{{helloworld}}\[aq]\ then +\ \ \ \ return\ pandoc.Emph{\ pandoc.Str\ "Hello,\ World"\ } +\ \ else +\ \ \ \ return\ inline +\ \ end +end + +return\ {{Str\ =\ expand_hello_world}} +\f[] +.fi .RE .TP .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[]] @@ -501,13 +548,6 @@ and may be printed in some output formats). .RS .RE .TP -.B \f[C]\-\-normalize\f[] -Normalize the document after reading: merge adjacent \f[C]Str\f[] or -\f[C]Emph\f[] elements, for example, and remove repeated -\f[C]Space\f[]s. -.RS -.RE -.TP .B \f[C]\-p\f[], \f[C]\-\-preserve\-tabs\f[] Preserve tabs instead of converting them to spaces (the default). Note that this will only affect tabs in literal code spans and code @@ -522,7 +562,7 @@ Specify the number of spaces per tab (default is 4). .TP .B \f[C]\-\-track\-changes=accept\f[]|\f[C]reject\f[]|\f[C]all\f[] Specifies what to do with insertions, deletions, and comments produced -by the MS Word \[lq]Track Changes\[rq] feature. +by the MS Word "Track Changes" feature. \f[C]accept\f[] (the default), inserts all insertions, and ignores all deletions. \f[C]reject\f[] inserts all deletions and ignores insertions. @@ -534,22 +574,45 @@ respectively. The author and time of change is included. \f[C]all\f[] is useful for scripting: only accepting changes from a certain reviewer, say, or before a certain date. +If a paragraph is inserted or deleted, \f[C]track\-changes=all\f[] +produces a span with the class +\f[C]paragraph\-insertion\f[]/\f[C]paragraph\-deletion\f[] before the +affected paragraph break. This option only affects the docx reader. .RS .RE .TP .B \f[C]\-\-extract\-media=\f[]\f[I]DIR\f[] -Extract images and other media contained in a docx or epub container to -the path \f[I]DIR\f[], creating it if necessary, and adjust the images -references in the document so they point to the extracted files. -This option only affects the docx and epub readers. +Extract images and other media contained in or linked from the source +document to the path \f[I]DIR\f[], creating it if necessary, and adjust +the images references in the document so they point to the extracted +files. +If the source format is a binary container (docx, epub, or odt), the +media is extracted from the container and the original filenames are +used. +Otherwise the media is read from the file system or downloaded, and new +filenames are constructed based on SHA1 hashes of the contents. +.RS +.RE +.TP +.B \f[C]\-\-abbreviations=\f[]\f[I]FILE\f[] +Specifies a custom abbreviations file, with abbreviations one to a line. +If this option is not specified, pandoc will read the data file +\f[C]abbreviations\f[] from the user data directory or fall back on a +system default. +To see the system default, use +\f[C]pandoc\ \-\-print\-default\-data\-file=abbreviations\f[]. +The only use pandoc makes of this list is in the Markdown reader. +Strings ending in a period that are found in this list will be followed +by a nonbreaking space, so that the period will not produce +sentence\-ending space in formats like LaTeX. .RS .RE .SS General writer options .TP .B \f[C]\-s\f[], \f[C]\-\-standalone\f[] -Produce output with an appropriate header and footer (e.g.\ a standalone -HTML, LaTeX, TEI, or RTF file, not a fragment). +Produce output with an appropriate header and footer (e.g. +a standalone HTML, LaTeX, TEI, or RTF file, not a fragment). This option is set automatically for \f[C]pdf\f[], \f[C]epub\f[], \f[C]epub3\f[], \f[C]fb2\f[], \f[C]docx\f[], and \f[C]odt\f[] output. .RS @@ -595,6 +658,14 @@ Files in the user data directory are ignored. .RS .RE .TP +.B \f[C]\-\-eol=crlf\f[]|\f[C]lf\f[]|\f[C]native\f[] +Manually specify line endings: \f[C]crlf\f[] (Windows), \f[C]lf\f[] +(macOS/Linux/UNIX), or \f[C]native\f[] (line endings appropriate to the +OS on which pandoc is being run). +The default is \f[C]native\f[]. +.RS +.RE +.TP .B \f[C]\-\-dpi\f[]=\f[I]NUMBER\f[] Specify the dpi (dots per inch) value for conversion from pixels to inch/centimeters and vice versa. @@ -617,11 +688,6 @@ Automatic wrapping does not currently work in HTML output. .RS .RE .TP -.B \f[C]\-\-no\-wrap\f[] -Deprecated synonym for \f[C]\-\-wrap=none\f[]. -.RS -.RE -.TP .B \f[C]\-\-columns=\f[]\f[I]NUMBER\f[] Specify length of lines in characters. This affects text wrapping in the generated source code (see @@ -633,11 +699,11 @@ Tables below). .TP .B \f[C]\-\-toc\f[], \f[C]\-\-table\-of\-contents\f[] Include an automatically generated table of contents (or, in the case of -\f[C]latex\f[], \f[C]context\f[], \f[C]docx\f[], and \f[C]rst\f[], an -instruction to create one) in the output document. -This option has no effect on \f[C]man\f[], \f[C]docbook\f[], -\f[C]docbook5\f[], \f[C]slidy\f[], \f[C]slideous\f[], \f[C]s5\f[], or -\f[C]odt\f[] output. +\f[C]latex\f[], \f[C]context\f[], \f[C]docx\f[], \f[C]odt\f[], +\f[C]opendocument\f[], \f[C]rst\f[], or \f[C]ms\f[], an instruction to +create one) in the output document. +This option has no effect on \f[C]man\f[], \f[C]docbook4\f[], +\f[C]docbook5\f[], or \f[C]jats\f[] output. .RS .RE .TP @@ -649,13 +715,21 @@ listed in the contents). .RS .RE .TP +.B \f[C]\-\-strip\-comments\f[] +Strip out HTML comments in the Markdown or Textile source, rather than +passing them on to Markdown, Textile or HTML output as raw HTML. +This does not apply to HTML comments inside raw HTML blocks when the +\f[C]markdown_in_html_blocks\f[] extension is not set. +.RS +.RE +.TP .B \f[C]\-\-no\-highlight\f[] Disables syntax highlighting for code blocks and inlines, even when a language attribute is given. .RS .RE .TP -.B \f[C]\-\-highlight\-style=\f[]\f[I]STYLE\f[] +.B \f[C]\-\-highlight\-style=\f[]\f[I]STYLE\f[]|\f[I]FILE\f[] Specifies the coloring style to be used in highlighted source code. Options are \f[C]pygments\f[] (the default), \f[C]kate\f[], \f[C]monochrome\f[], \f[C]breezeDark\f[], \f[C]espresso\f[], @@ -664,6 +738,29 @@ For more information on syntax highlighting in pandoc, see Syntax highlighting, below. See also \f[C]\-\-list\-highlight\-styles\f[]. .RS +.PP +Instead of a \f[I]STYLE\f[] name, a JSON file with extension +\f[C]\&.theme\f[] may be supplied. +This will be parsed as a KDE syntax highlighting theme and (if valid) +used as the highlighting style. +.PP +To generate the JSON version of an existing style, use +\f[C]\-\-print\-highlight\-style\f[]. +.RE +.TP +.B \f[C]\-\-print\-highlight\-style=\f[]\f[I]STYLE\f[]|\f[I]FILE\f[] +Prints a JSON version of a highlighting style, which can be modified, +saved with a \f[C]\&.theme\f[] extension, and used with +\f[C]\-\-highlight\-style\f[]. +.RS +.RE +.TP +.B \f[C]\-\-syntax\-definition=\f[]\f[I]FILE\f[] +Instructs pandoc to load a KDE XML syntax definition file, which will be +used for syntax highlighting of appropriately marked code blocks. +This can be used to add support for new languages or to use altered +syntax definitions for existing languages. +.RS .RE .TP .B \f[C]\-H\f[] \f[I]FILE\f[], \f[C]\-\-include\-in\-header=\f[]\f[I]FILE\f[] @@ -679,8 +776,9 @@ Implies \f[C]\-\-standalone\f[]. .TP .B \f[C]\-B\f[] \f[I]FILE\f[], \f[C]\-\-include\-before\-body=\f[]\f[I]FILE\f[] Include contents of \f[I]FILE\f[], verbatim, at the beginning of the -document body (e.g.\ after the \f[C]<body>\f[] tag in HTML, or the -\f[C]\\begin{document}\f[] command in LaTeX). +document body (e.g. +after the \f[C]<body>\f[] tag in HTML, or the \f[C]\\begin{document}\f[] +command in LaTeX). This can be used to include navigation bars or banners in HTML documents. This option can be used repeatedly to include multiple files. @@ -698,28 +796,52 @@ They will be included in the order specified. Implies \f[C]\-\-standalone\f[]. .RS .RE +.TP +.B \f[C]\-\-resource\-path=\f[]\f[I]SEARCHPATH\f[] +List of paths to search for images and other resources. +The paths should be separated by \f[C]:\f[] on Linux, UNIX, and macOS +systems, and by \f[C];\f[] on Windows. +If \f[C]\-\-resource\-path\f[] is not specified, the default resource +path is the working directory. +Note that, if \f[C]\-\-resource\-path\f[] is specified, the working +directory must be explicitly listed or it will not be searched. +For example: \f[C]\-\-resource\-path=.:test\f[] will search the working +directory and the \f[C]test\f[] subdirectory, in that order. +.RS +.RE +.TP +.B \f[C]\-\-request\-header=\f[]\f[I]NAME\f[]\f[C]:\f[]\f[I]VAL\f[] +Set the request header \f[I]NAME\f[] to the value \f[I]VAL\f[] when +making HTTP requests (for example, when a URL is given on the command +line, or when resources used in a document must be downloaded). +.RS +.RE .SS Options affecting specific writers .TP .B \f[C]\-\-self\-contained\f[] Produce a standalone HTML file with no external dependencies, using \f[C]data:\f[] URIs to incorporate the contents of linked scripts, stylesheets, images, and videos. -The resulting file should be \[lq]self\-contained,\[rq] in the sense -that it needs no external files and no net access to be displayed -properly by a browser. +Implies \f[C]\-\-standalone\f[]. +The resulting file should be "self\-contained," in the sense that it +needs no external files and no net access to be displayed properly by a +browser. This option works only with HTML output formats, including -\f[C]html\f[], \f[C]html5\f[], \f[C]html+lhs\f[], \f[C]html5+lhs\f[], +\f[C]html4\f[], \f[C]html5\f[], \f[C]html+lhs\f[], \f[C]html5+lhs\f[], \f[C]s5\f[], \f[C]slidy\f[], \f[C]slideous\f[], \f[C]dzslides\f[], and \f[C]revealjs\f[]. Scripts, images, and stylesheets at absolute URLs will be downloaded; those at relative URLs will be sought relative to the working directory (if the first source file is local) or relative to the base URL (if the first source file is remote). +Elements with the attribute \f[C]data\-external="1"\f[] will be left +alone; the documents they link to will not be incorporated in the +document. Limitation: resources that are loaded dynamically through JavaScript cannot be incorporated; as a result, \f[C]\-\-self\-contained\f[] does -not work with \f[C]\-\-mathjax\f[], and some advanced features ( -e.g.\ zoom or speaker notes) may not work in an offline -\[lq]self\-contained\[rq] \f[C]reveal.js\f[] slide show. +not work with \f[C]\-\-mathjax\f[], and some advanced features (e.g. +zoom or speaker notes) may not work in an offline "self\-contained" +\f[C]reveal.js\f[] slide show. .RS .RE .TP @@ -730,8 +852,8 @@ Use \f[C]<q>\f[] tags for quotes in HTML. .TP .B \f[C]\-\-ascii\f[] Use only ASCII characters in output. -Currently supported only for HTML output (which uses numerical entities -instead of UTF\-8 when this option is selected). +Currently supported only for HTML and DocBook output (which uses +numerical entities instead of UTF\-8 when this option is selected). .RS .RE .TP @@ -757,11 +879,7 @@ Currently only affects the markdown writer. Use ATX\-style headers in Markdown and AsciiDoc output. The default is to use setext\-style headers for levels 1\-2, and then ATX headers. -.RS -.RE -.TP -.B \f[C]\-\-chapters\f[] -Deprecated synonym for \f[C]\-\-top\-level\-division=chapter\f[]. +(Note: for \f[C]gfm\f[] output, ATX headers are always used.) .RS .RE .TP @@ -790,40 +908,20 @@ Sections with class \f[C]unnumbered\f[] will never be numbered, even if .RS .RE .TP -.B \f[C]\-\-number\-offset=\f[]\f[I]NUMBER\f[][\f[C],\f[]\f[I]NUMBER\f[]\f[C],\f[]\f[I]\&...\f[]] +.B \f[C]\-\-number\-offset=\f[]\f[I]NUMBER\f[][\f[C],\f[]\f[I]NUMBER\f[]\f[C],\f[]\f[I]...\f[]] Offset for section headings in HTML output (ignored in other output formats). The first number is added to the section number for top\-level headers, the second for second\-level headers, and so on. So, for example, if you want the first top\-level header in your -document to be numbered \[lq]6\[rq], specify -\f[C]\-\-number\-offset=5\f[]. +document to be numbered "6", specify \f[C]\-\-number\-offset=5\f[]. If your document starts with a level\-2 header which you want to be -numbered \[lq]1.5\[rq], specify \f[C]\-\-number\-offset=1,4\f[]. +numbered "1.5", specify \f[C]\-\-number\-offset=1,4\f[]. Offsets are 0 by default. Implies \f[C]\-\-number\-sections\f[]. .RS .RE .TP -.B \f[C]\-\-no\-tex\-ligatures\f[] -Do not use the TeX ligatures for quotation marks, apostrophes, and -dashes (\f[C]`...\[aq]\f[], \f[C]``..\[aq]\[aq]\f[], \f[C]\-\-\f[], -\f[C]\-\-\-\f[]) when writing or reading LaTeX or ConTeXt. -In reading LaTeX, parse the characters \f[C]`\f[], \f[C]\[aq]\f[], and -\f[C]\-\f[] literally, rather than parsing ligatures for quotation marks -and dashes. -In writing LaTeX or ConTeXt, print unicode quotation mark and dash -characters literally, rather than converting them to the standard ASCII -TeX ligatures. -Note: normally \f[C]\-\-smart\f[] is selected automatically for LaTeX -and ConTeXt output, but it must be specified explicitly if -\f[C]\-\-no\-tex\-ligatures\f[] is selected. -If you use literal curly quotes, dashes, and ellipses in your source, -then you may want to use \f[C]\-\-no\-tex\-ligatures\f[] without -\f[C]\-\-smart\f[]. -.RS -.RE -.TP .B \f[C]\-\-listings\f[] Use the \f[C]listings\f[] package for LaTeX code blocks .RS @@ -842,15 +940,17 @@ Specifies that headers with the specified level create slides (for Headers above this level in the hierarchy are used to divide the slide show into sections; headers below this level create subheads within a slide. +Note that content that is not contained under slide\-level headers will +not appear in the slide show. The default is to set the slide level based on the contents of the document; see Structuring the slide show. .RS .RE .TP .B \f[C]\-\-section\-divs\f[] -Wrap sections in \f[C]<div>\f[] tags (or \f[C]<section>\f[] tags in -HTML5), and attach identifiers to the enclosing \f[C]<div>\f[] (or -\f[C]<section>\f[]) rather than the header itself. +Wrap sections in \f[C]<section>\f[] tags (or \f[C]<div>\f[] tags for +\f[C]html4\f[]), and attach identifiers to the enclosing +\f[C]<section>\f[] (or \f[C]<div>\f[]) rather than the header itself. See Header identifiers, below. .RS .RE @@ -867,8 +967,9 @@ The default is \f[C]none\f[]. .RE .TP .B \f[C]\-\-id\-prefix=\f[]\f[I]STRING\f[] -Specify a prefix to be added to all automatically generated identifiers -in HTML and DocBook output, and to footnote numbers in Markdown output. +Specify a prefix to be added to all identifiers and internal links in +HTML and DocBook output, and to footnote numbers in Markdown and Haddock +output. This is useful for preventing duplicate identifiers when generating fragments to be included in other pages. .RS @@ -887,29 +988,20 @@ Link to a CSS style sheet. This option can be used repeatedly to include multiple files. They will be included in the order specified. .RS +.PP +A stylesheet is required for generating EPUB. +If none is provided using this option (or the \f[C]stylesheet\f[] +metadata field), pandoc will look for a file \f[C]epub.css\f[] in the +user data directory (see \f[C]\-\-data\-dir\f[]). +If it is not found there, sensible defaults will be used. .RE .TP -.B \f[C]\-\-reference\-odt=\f[]\f[I]FILE\f[] -Use the specified file as a style reference in producing an ODT. -For best results, the reference ODT should be a modified version of an -ODT produced using pandoc. -The contents of the reference ODT are ignored, but its stylesheets are -used in the new ODT. -If no reference ODT is specified on the command line, pandoc will look -for a file \f[C]reference.odt\f[] in the user data directory (see -\f[C]\-\-data\-dir\f[]). -If this is not found either, sensible defaults will be used. +.B \f[C]\-\-reference\-doc=\f[]\f[I]FILE\f[] +Use the specified file as a style reference in producing a docx or ODT +file. .RS -.PP -To produce a custom \f[C]reference.odt\f[], first get a copy of the -default \f[C]reference.odt\f[]: -\f[C]pandoc\ \-\-print\-default\-data\-file\ reference.odt\ >\ custom\-reference.odt\f[]. -Then open \f[C]custom\-reference.docx\f[] in LibreOffice, modify the -styles as you wish, and save the file. -.RE .TP -.B \f[C]\-\-reference\-docx=\f[]\f[I]FILE\f[] -Use the specified file as a style reference in producing a docx file. +.B Docx For best results, the reference docx should be a modified version of a docx file produced using pandoc. The contents of the reference docx are ignored, but its stylesheets and @@ -930,19 +1022,58 @@ For best results, do not make changes to this file other than modifying the styles used by pandoc: [paragraph] Normal, Body Text, First Paragraph, Compact, Title, Subtitle, Author, Date, Abstract, Bibliography, Heading 1, Heading 2, Heading 3, Heading 4, Heading 5, -Heading 6, Block Text, Footnote Text, Definition Term, Definition, -Caption, Table Caption, Image Caption, Figure, Figure With Caption, TOC -Heading; [character] Default Paragraph Font, Body Text Char, Verbatim -Char, Footnote Reference, Hyperlink; [table] Normal Table. +Heading 6, Heading 7, Heading 8, Heading 9, Block Text, Footnote Text, +Definition Term, Definition, Caption, Table Caption, Image Caption, +Figure, Captioned Figure, TOC Heading; [character] Default Paragraph +Font, Body Text Char, Verbatim Char, Footnote Reference, Hyperlink; +[table] Table. .RE .TP -.B \f[C]\-\-epub\-stylesheet=\f[]\f[I]FILE\f[] -Use the specified CSS file to style the EPUB. -If no stylesheet is specified, pandoc will look for a file -\f[C]epub.css\f[] in the user data directory (see +.B ODT +For best results, the reference ODT should be a modified version of an +ODT produced using pandoc. +The contents of the reference ODT are ignored, but its stylesheets are +used in the new ODT. +If no reference ODT is specified on the command line, pandoc will look +for a file \f[C]reference.odt\f[] in the user data directory (see \f[C]\-\-data\-dir\f[]). -If it is not found there, sensible defaults will be used. +If this is not found either, sensible defaults will be used. .RS +.PP +To produce a custom \f[C]reference.odt\f[], first get a copy of the +default \f[C]reference.odt\f[]: +\f[C]pandoc\ \-\-print\-default\-data\-file\ reference.odt\ >\ custom\-reference.odt\f[]. +Then open \f[C]custom\-reference.odt\f[] in LibreOffice, modify the +styles as you wish, and save the file. +.RE +.TP +.B PowerPoint +Any template included with a recent install of Microsoft PowerPoint +(either with \f[C]\&.pptx\f[] or \f[C]\&.potx\f[] extension) should +work, as will most templates derived from these. +.RS +.PP +The specific requirement is that the template should contain the +following four layouts as its first four layouts: +.IP "1." 3 +Title Slide +.IP "2." 3 +Title and Content +.IP "3." 3 +Section Header +.IP "4." 3 +Two Content +.PP +All templates included with a recent version of MS PowerPoint will fit +these criteria. +(You can click on \f[C]Layout\f[] under the \f[C]Home\f[] menu to +check.) +.PP +You can also modify the default \f[C]reference.pptx\f[]: first run +\f[C]pandoc\ \-\-print\-default\-data\-file\ reference.pptx\ >\ custom\-reference.pptx\f[], +and then modify \f[C]custom\-reference.pptx\f[] in MS PowerPoint (pandoc +will use the first four layout slides, as mentioned above). +.RE .RE .TP .B \f[C]\-\-epub\-cover\-image=\f[]\f[I]FILE\f[] @@ -989,7 +1120,7 @@ However, if you use wildcards on the command line, be sure to escape them or put the whole filename in single quotes, to prevent them from being interpreted by the shell. To use the embedded fonts, you will need to add declarations like the -following to your CSS (see \f[C]\-\-epub\-stylesheet\f[]): +following to your CSS (see \f[C]\-\-css\f[]): .RS .IP .nf @@ -1025,7 +1156,7 @@ body\ {\ font\-family:\ "DejaVuSans";\ } .TP .B \f[C]\-\-epub\-chapter\-level=\f[]\f[I]NUMBER\f[] Specify the header level at which to split the EPUB into separate -\[lq]chapter\[rq] files. +"chapter" files. The default is to split into chapters at level 1 headers. This option only affects the internal composition of the EPUB, not the way chapters and sections are displayed to users. @@ -1035,17 +1166,25 @@ chapter level of 2 or 3. .RS .RE .TP -.B \f[C]\-\-latex\-engine=pdflatex\f[]|\f[C]lualatex\f[]|\f[C]xelatex\f[] -Use the specified LaTeX engine when producing PDF output. +.B \f[C]\-\-epub\-subdirectory=\f[]\f[I]DIRNAME\f[] +Specify the subdirectory in the OCF container that is to hold the +EPUB\-specific contents. +The default is \f[C]EPUB\f[]. +To put the EPUB contents in the top level, use an empty string. +.RS +.RE +.TP +.B \f[C]\-\-pdf\-engine=pdflatex\f[]|\f[C]lualatex\f[]|\f[C]xelatex\f[]|\f[C]wkhtmltopdf\f[]|\f[C]weasyprint\f[]|\f[C]prince\f[]|\f[C]context\f[]|\f[C]pdfroff\f[] +Use the specified engine when producing PDF output. The default is \f[C]pdflatex\f[]. If the engine is not in your PATH, the full path of the engine may be specified here. .RS .RE .TP -.B \f[C]\-\-latex\-engine\-opt=\f[]\f[I]STRING\f[] +.B \f[C]\-\-pdf\-engine\-opt=\f[]\f[I]STRING\f[] Use the given string as a command\-line argument to the -\f[C]latex\-engine\f[]. +\f[C]pdf\-engine\f[]. If used multiple times, the arguments are provided with spaces between them. Note that no check for duplicate options is done. @@ -1054,7 +1193,7 @@ Note that no check for duplicate options is done. .SS Citation rendering .TP .B \f[C]\-\-bibliography=\f[]\f[I]FILE\f[] -Set the \f[C]bibliography\f[] field in the document's metadata to +Set the \f[C]bibliography\f[] field in the document\[aq]s metadata to \f[I]FILE\f[], overriding any value set in the metadata, and process citations using \f[C]pandoc\-citeproc\f[]. (This is equivalent to @@ -1068,15 +1207,15 @@ added to bibliography. .RE .TP .B \f[C]\-\-csl=\f[]\f[I]FILE\f[] -Set the \f[C]csl\f[] field in the document's metadata to \f[I]FILE\f[], -overriding any value set in the metadata. +Set the \f[C]csl\f[] field in the document\[aq]s metadata to +\f[I]FILE\f[], overriding any value set in the metadata. (This is equivalent to \f[C]\-\-metadata\ csl=FILE\f[].) This option is only relevant with \f[C]pandoc\-citeproc\f[]. .RS .RE .TP .B \f[C]\-\-citation\-abbreviations=\f[]\f[I]FILE\f[] -Set the \f[C]citation\-abbreviations\f[] field in the document's +Set the \f[C]citation\-abbreviations\f[] field in the document\[aq]s metadata to \f[I]FILE\f[], overriding any value set in the metadata. (This is equivalent to \f[C]\-\-metadata\ citation\-abbreviations=FILE\f[].) This option is @@ -1102,78 +1241,55 @@ with \f[C]bibtex\f[] or \f[C]biber\f[]. .RS .RE .SS Math rendering in HTML -.TP -.B \f[C]\-m\f[] [\f[I]URL\f[]], \f[C]\-\-latexmathml\f[][\f[C]=\f[]\f[I]URL\f[]] -Use the LaTeXMathML script to display embedded TeX math in HTML output. -To insert a link to a local copy of the \f[C]LaTeXMathML.js\f[] script, -provide a \f[I]URL\f[]. -If no \f[I]URL\f[] is provided, the contents of the script will be -inserted directly into the HTML header, preserving portability at the -price of efficiency. -If you plan to use math on several pages, it is much better to link to a -copy of the script, so it can be cached. -.RS -.RE -.TP -.B \f[C]\-\-mathml\f[][\f[C]=\f[]\f[I]URL\f[]] -Convert TeX math to MathML (in \f[C]docbook\f[], \f[C]docbook5\f[], -\f[C]html\f[] and \f[C]html5\f[]). -In standalone \f[C]html\f[] output, a small JavaScript (or a link to -such a script if a \f[I]URL\f[] is supplied) will be inserted that -allows the MathML to be viewed on some browsers. -.RS -.RE -.TP -.B \f[C]\-\-jsmath\f[][\f[C]=\f[]\f[I]URL\f[]] -Use jsMath to display embedded TeX math in HTML output. -The \f[I]URL\f[] should point to the jsMath load script (e.g. -\f[C]jsMath/easy/load.js\f[]); if provided, it will be linked to in the -header of standalone HTML documents. -If a \f[I]URL\f[] is not provided, no link to the jsMath load script -will be inserted; it is then up to the author to provide such a link in -the HTML template. -.RS -.RE +.PP +The default is to render TeX math as far as possible using Unicode +characters. +Formulas are put inside a \f[C]span\f[] with \f[C]class="math"\f[], so +that they may be styled differently from the surrounding text if needed. +However, this gives acceptable results only for basic math, usually you +will want to use \f[C]\-\-mathjax\f[] or another of the following +options. .TP .B \f[C]\-\-mathjax\f[][\f[C]=\f[]\f[I]URL\f[]] Use MathJax to display embedded TeX math in HTML output. +TeX math will be put between \f[C]\\(...\\)\f[] (for inline math) or +\f[C]\\[...\\]\f[] (for display math) and wrapped in \f[C]<span>\f[] +tags with class \f[C]math\f[]. +Then the MathJax JavaScript will render it. The \f[I]URL\f[] should point to the \f[C]MathJax.js\f[] load script. -If a \f[I]URL\f[] is not provided, a link to the MathJax CDN will be +If a \f[I]URL\f[] is not provided, a link to the Cloudflare CDN will be inserted. .RS .RE .TP -.B \f[C]\-\-gladtex\f[] -Enclose TeX math in \f[C]<eq>\f[] tags in HTML output. -These can then be processed by gladTeX to produce links to images of the -typeset formulas. -.RS -.RE -.TP -.B \f[C]\-\-mimetex\f[][\f[C]=\f[]\f[I]URL\f[]] -Render TeX math using the mimeTeX CGI script. -If \f[I]URL\f[] is not specified, it is assumed that the script is at -\f[C]/cgi\-bin/mimetex.cgi\f[]. +.B \f[C]\-\-mathml\f[] +Convert TeX math to MathML (in \f[C]epub3\f[], \f[C]docbook4\f[], +\f[C]docbook5\f[], \f[C]jats\f[], \f[C]html4\f[] and \f[C]html5\f[]). +This is the default in \f[C]odt\f[] output. +Note that currently only Firefox and Safari (and select e\-book readers) +natively support MathML. .RS .RE .TP .B \f[C]\-\-webtex\f[][\f[C]=\f[]\f[I]URL\f[]] -Render TeX formulas using an external script that converts TeX formulas -to images. -The formula will be concatenated with the URL provided. -If \f[I]URL\f[] is not specified, the CodeCogs will be used. +Convert TeX formulas to \f[C]<img>\f[] tags that link to an external +script that converts formulas to images. +The formula will be URL\-encoded and concatenated with the URL provided. +For SVG images you can for example use +\f[C]\-\-webtex\ https://latex.codecogs.com/svg.latex?\f[]. +If no URL is specified, the CodeCogs URL generating PNGs will be used +(\f[C]https://latex.codecogs.com/png.latex?\f[]). Note: the \f[C]\-\-webtex\f[] option will affect Markdown output as well -as HTML, which is useful if you're targeting a version of Markdown +as HTML, which is useful if you\[aq]re targeting a version of Markdown without native math support. .RS .RE .TP .B \f[C]\-\-katex\f[][\f[C]=\f[]\f[I]URL\f[]] Use KaTeX to display embedded TeX math in HTML output. -The \f[I]URL\f[] should point to the \f[C]katex.js\f[] load script. +The \f[I]URL\f[] is the base URL for the KaTeX library. If a \f[I]URL\f[] is not provided, a link to the KaTeX CDN will be inserted. -Note: KaTeX seems to work best with \f[C]html5\f[] output. .RS .RE .TP @@ -1184,6 +1300,60 @@ inserted. Note that this option does not imply \f[C]\-\-katex\f[]. .RS .RE +.TP +.B \f[C]\-m\f[] [\f[I]URL\f[]], \f[C]\-\-latexmathml\f[][\f[C]=\f[]\f[I]URL\f[]] +\f[I]Deprecated.\f[] Use the LaTeXMathML script to display embedded TeX +math in HTML output. +TeX math will be displayed between \f[C]$\f[] or \f[C]$$\f[] characters +and put in \f[C]<span>\f[] tags with class \f[C]LaTeX\f[]. +The LaTeXMathML JavaScript will then change it to MathML. +Note that currently only Firefox and Safari (and select e\-book readers) +natively support MathML. +To insert a link the \f[C]LaTeXMathML.js\f[] script, provide a +\f[I]URL\f[]. +.RS +.RE +.TP +.B \f[C]\-\-jsmath\f[][\f[C]=\f[]\f[I]URL\f[]] +\f[I]Deprecated.\f[] Use jsMath (the predecessor of MathJax) to display +embedded TeX math in HTML output. +TeX math will be put inside \f[C]<span>\f[] tags (for inline math) or +\f[C]<div>\f[] tags (for display math) with class \f[C]math\f[] and +rendered by the jsMath script. +The \f[I]URL\f[] should point to the script (e.g. +\f[C]jsMath/easy/load.js\f[]); if provided, it will be linked to in the +header of standalone HTML documents. +If a \f[I]URL\f[] is not provided, no link to the jsMath load script +will be inserted; it is then up to the author to provide such a link in +the HTML template. +.RS +.RE +.TP +.B \f[C]\-\-gladtex\f[] +\f[I]Deprecated.\f[] Enclose TeX math in \f[C]<eq>\f[] tags in HTML +output. +The resulting HTML can then be processed by gladTeX to produce images of +the typeset formulas and an HTML file with links to these images. +So, the procedure is: +.RS +.IP +.nf +\f[C] +pandoc\ \-s\ \-\-gladtex\ input.md\ \-o\ myfile.htex +gladtex\ \-d\ myfile\-images\ myfile.htex +#\ produces\ myfile.html\ and\ images\ in\ myfile\-images +\f[] +.fi +.RE +.TP +.B \f[C]\-\-mimetex\f[][\f[C]=\f[]\f[I]URL\f[]] +\f[I]Deprecated.\f[] Render TeX math using the mimeTeX CGI script, which +generates an image for each TeX formula. +This should work in all browsers. +If \f[I]URL\f[] is not specified, it is assumed that the script is at +\f[C]/cgi\-bin/mimetex.cgi\f[]. +.RS +.RE .SS Options for wrapper scripts .TP .B \f[C]\-\-dump\-args\f[] @@ -1247,12 +1417,13 @@ For \f[C]odt\f[] output, customize the \f[C]default.opendocument\f[] template. .IP \[bu] 2 For \f[C]pdf\f[] output, customize the \f[C]default.latex\f[] template -(or the \f[C]default.beamer\f[] template, if you use -\f[C]\-t\ beamer\f[], or the \f[C]default.context\f[] template, if you -use \f[C]\-t\ context\f[]). +(or the \f[C]default.context\f[] template, if you use +\f[C]\-t\ context\f[], or the \f[C]default.ms\f[] template, if you use +\f[C]\-t\ ms\f[], or the \f[C]default.html5\f[] template, if you use +\f[C]\-t\ html5\f[]). .IP \[bu] 2 \f[C]docx\f[] has no template (however, you can use -\f[C]\-\-reference\-docx\f[] to customize the output). +\f[C]\-\-reference\-doc\f[] to customize the output). .PP Templates contain \f[I]variables\f[], which allow for the inclusion of arbitrary information at any point in the file. @@ -1266,6 +1437,29 @@ Some variables are set automatically by pandoc. These vary somewhat depending on the output format, but include metadata fields as well as the following: .TP +.B \f[C]sourcefile\f[], \f[C]outputfile\f[] +source and destination filenames, as given on the command line. +\f[C]sourcefile\f[] can also be a list if input comes from multiple +files, or empty if input is from stdin. +You can use the following snippet in your template to distinguish them: +.RS +.IP +.nf +\f[C] +$if(sourcefile)$ +$for(sourcefile)$ +$sourcefile$ +$endfor$ +$else$ +(stdin) +$endif$ +\f[] +.fi +.PP +Similarly, \f[C]outputfile\f[] can be \f[C]\-\f[] if output goes to the +terminal. +.RE +.TP .B \f[C]title\f[], \f[C]author\f[], \f[C]date\f[] allow identification of basic aspects of the document. Included in PDF metadata through LaTeX and ConTeXt. @@ -1322,7 +1516,8 @@ specified .RE .TP .B \f[C]toc\-title\f[] -title of table of contents (works only with EPUB and docx) +title of table of contents (works only with EPUB, opendocument, odt, +docx, pptx) .RS .RE .TP @@ -1344,7 +1539,8 @@ body of document .RE .TP .B \f[C]meta\-json\f[] -JSON representation of all of the document's metadata +JSON representation of all of the document\[aq]s metadata. +Field values are transformed to the selected output format. .RS .RE .SS Language variables @@ -1358,23 +1554,12 @@ stored in the additional variables \f[C]babel\-lang\f[], \f[C]polyglossia\-lang\f[] (LaTeX) and \f[C]context\-lang\f[] (ConTeXt). .RS .PP -Native pandoc \f[C]span\f[]s and \f[C]div\f[]s with the lang attribute -(value in BCP 47) can be used to switch the language in that range. -.RE -.TP -.B \f[C]otherlangs\f[] -a list of other languages used in the document in the YAML metadata, -according to BCP 47. -For example: \f[C]otherlangs:\ [en\-GB,\ fr]\f[]. -This is automatically generated from the \f[C]lang\f[] attributes in all -\f[C]span\f[]s and \f[C]div\f[]s but can be overridden. -Currently only used by LaTeX through the generated -\f[C]babel\-otherlangs\f[] and \f[C]polyglossia\-otherlangs\f[] -variables. -The LaTeX writer outputs polyglossia commands in the text but the -\f[C]babel\-newcommands\f[] variable contains mappings for them to the -corresponding babel. -.RS +Native pandoc Spans and Divs with the lang attribute (value in BCP 47) +can be used to switch the language in that range. +In LaTeX output, \f[C]babel\-otherlangs\f[] and +\f[C]polyglossia\-otherlangs\f[] variables will be generated +automatically based on the \f[C]lang\f[] attributes of Spans and Divs in +the document. .RE .TP .B \f[C]dir\f[] @@ -1386,21 +1571,31 @@ For bidirectional documents, native pandoc \f[C]span\f[]s and \f[C]div\f[]s with the \f[C]dir\f[] attribute (value \f[C]rtl\f[] or \f[C]ltr\f[]) can be used to override the base direction in some output formats. -This may not always be necessary if the final renderer (e.g.\ the -browser, when generating HTML) supports the Unicode Bidirectional +This may not always be necessary if the final renderer (e.g. +the browser, when generating HTML) supports the Unicode Bidirectional Algorithm. .PP When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[] -engine is fully supported (use \f[C]\-\-latex\-engine=xelatex\f[]). +engine is fully supported (use \f[C]\-\-pdf\-engine=xelatex\f[]). .RE .SS Variables for slides .PP Variables are available for producing slide shows with pandoc, including all reveal.js configuration options. .TP +.B \f[C]titlegraphic\f[] +title graphic for Beamer documents +.RS +.RE +.TP +.B \f[C]logo\f[] +logo for Beamer documents +.RS +.RE +.TP .B \f[C]slidy\-url\f[] base URL for Slidy documents (defaults to -\f[C]http://www.w3.org/Talks/Tools/Slidy2\f[]) +\f[C]https://www.w3.org/Talks/Tools/Slidy2\f[]) .RS .RE .TP @@ -1437,8 +1632,8 @@ controls navigation symbols in \f[C]beamer\f[] documents (default is .RE .TP .B \f[C]section\-titles\f[] -enables on \[lq]title pages\[rq] for new sections in \f[C]beamer\f[] -documents (default = true). +enables on "title pages" for new sections in \f[C]beamer\f[] documents +(default = true). .RS .RE .TP @@ -1448,17 +1643,11 @@ an article from beamer slides). .RS .RE .TP -.B \f[C]colorlinks\f[] -add color to link text; automatically enabled if any of -\f[C]linkcolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], or -\f[C]toccolor\f[] are set (for beamer only). -.RS -.RE -.TP -.B \f[C]linkcolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], \f[C]toccolor\f[] -color for internal links, citation links, external links, and links in -table of contents: uses any of the predefined LaTeX colors (for beamer -only). +.B \f[C]aspectratio\f[] +aspect ratio of slides (for beamer only, \f[C]1610\f[] for 16:10, +\f[C]169\f[] for 16:9, \f[C]149\f[] for 14:9, \f[C]141\f[] for 1.41:1, +\f[C]54\f[] for 5:4, \f[C]43\f[] for 4:3 which is the default, and +\f[C]32\f[] for 3:2). .RS .RE .SS Variables for LaTeX @@ -1467,7 +1656,7 @@ LaTeX variables are used when creating a PDF. .TP .B \f[C]papersize\f[] paper size, e.g. -\f[C]letter\f[], \f[C]A4\f[] +\f[C]letter\f[], \f[C]a4\f[] .RS .RE .TP @@ -1561,7 +1750,8 @@ add color to link text; automatically enabled if any of .TP .B \f[C]linkcolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], \f[C]toccolor\f[] color for internal links, citation links, external links, and links in -table of contents: uses any of the predefined LaTeX colors +table of contents: uses options allowed by \f[C]xcolor\f[], including +the \f[C]dvipsnames\f[], \f[C]svgnames\f[], and \f[C]x11names\f[] lists .RS .RE .TP @@ -1630,6 +1820,19 @@ bibliography title, when used with \f[C]\-\-natbib\f[] and list of options for biblatex. .RS .RE +.TP +.B \f[C]natbiboptions\f[] +list of options for natbib. +.RS +.RE +.TP +.B \f[C]pagestyle\f[] +An option for LaTeX\[aq]s \f[C]\\pagestyle{}\f[]. +The default article class supports \[aq]plain\[aq] (default), +\[aq]empty\[aq], and \[aq]headings\[aq]; headings puts section titles in +the header. +.RS +.RE .SS Variables for ConTeXt .TP .B \f[C]papersize\f[] @@ -1745,6 +1948,31 @@ adjusts text to left (\f[C]l\f[]), right (\f[C]r\f[]), center if \f[C]true\f[] (the default), hyphenation will be used .RS .RE +.SS Variables for ms +.TP +.B \f[C]pointsize\f[] +point size (e.g. +\f[C]10p\f[]) +.RS +.RE +.TP +.B \f[C]lineheight\f[] +line height (e.g. +\f[C]12p\f[]) +.RS +.RE +.TP +.B \f[C]fontfamily\f[] +font family (e.g. +\f[C]T\f[] or \f[C]P\f[]) +.RS +.RE +.TP +.B \f[C]indent\f[] +paragraph indent (e.g. +\f[C]2m\f[]) +.RS +.RE .SS Using variables in templates .PP Variable names are sequences of alphanumerics, \f[C]\-\f[], and @@ -1818,19 +2046,370 @@ We recommend tracking the changes in the default templates, and modifying your custom templates accordingly. An easy way to do this is to fork the pandoc\-templates repository and merge in changes after each pandoc release. -.SH PANDOC'S MARKDOWN +.PP +Templates may contain comments: anything on a line after \f[C]$\-\-\f[] +will be treated as a comment and ignored. +.SH EXTENSIONS +.PP +The behavior of some of the readers and writers can be adjusted by +enabling or disabling various extensions. +.PP +An extension can be enabled by adding \f[C]+EXTENSION\f[] to the format +name and disabled by adding \f[C]\-EXTENSION\f[]. +For example, \f[C]\-\-from\ markdown_strict+footnotes\f[] is strict +Markdown with footnotes enabled, while +\f[C]\-\-from\ markdown\-footnotes\-pipe_tables\f[] is pandoc\[aq]s +Markdown without footnotes or pipe tables. +.PP +The markdown reader and writer make by far the most use of extensions. +Extensions only used by them are therefore covered in the section +Pandoc\[aq]s Markdown below (See Markdown variants for +\f[C]commonmark\f[] and \f[C]gfm\f[].) In the following, extensions that +also work for other formats are covered. +.SS Typography +.SS Extension: \f[C]smart\f[] +.PP +Interpret straight quotes as curly quotes, \f[C]\-\-\-\f[] as +em\-dashes, \f[C]\-\-\f[] as en\-dashes, and \f[C]\&...\f[] as ellipses. +Nonbreaking spaces are inserted after certain abbreviations, such as +"Mr." +.PP +This extension can be enabled/disabled for the following formats: +.TP +.B input formats +\f[C]markdown\f[], \f[C]commonmark\f[], \f[C]latex\f[], +\f[C]mediawiki\f[], \f[C]org\f[], \f[C]rst\f[], \f[C]twiki\f[] +.RS +.RE +.TP +.B output formats +\f[C]markdown\f[], \f[C]latex\f[], \f[C]context\f[], \f[C]rst\f[] +.RS +.RE +.TP +.B enabled by default in +\f[C]markdown\f[], \f[C]latex\f[], \f[C]context\f[] (both input and +output) +.RS +.RE +.PP +Note: If you are \f[I]writing\f[] Markdown, then the \f[C]smart\f[] +extension has the reverse effect: what would have been curly quotes +comes out straight. +.PP +In LaTeX, \f[C]smart\f[] means to use the standard TeX ligatures for +quotation marks (\f[C]``\f[] and \f[C]\[aq]\[aq]\f[] for double quotes, +\f[C]`\f[] and \f[C]\[aq]\f[] for single quotes) and dashes +(\f[C]\-\-\f[] for en\-dash and \f[C]\-\-\-\f[] for em\-dash). +If \f[C]smart\f[] is disabled, then in reading LaTeX pandoc will parse +these characters literally. +In writing LaTeX, enabling \f[C]smart\f[] tells pandoc to use the +ligatures when possible; if \f[C]smart\f[] is disabled pandoc will use +unicode quotation mark and dash characters. +.SS Headers and sections +.SS Extension: \f[C]auto_identifiers\f[] +.PP +A header without an explicitly specified identifier will be +automatically assigned a unique identifier based on the header text. +.PP +This extension can be enabled/disabled for the following formats: +.TP +.B input formats +\f[C]markdown\f[], \f[C]latex\f[], \f[C]rst\f[], \f[C]mediawiki\f[], +\f[C]textile\f[] +.RS +.RE +.TP +.B output formats +\f[C]markdown\f[], \f[C]muse\f[] +.RS +.RE +.TP +.B enabled by default in +\f[C]markdown\f[], \f[C]muse\f[] +.RS +.RE +.PP +The algorithm used to derive the identifier from the header text is: +.IP \[bu] 2 +Remove all formatting, links, etc. +.IP \[bu] 2 +Remove all footnotes. +.IP \[bu] 2 +Remove all punctuation, except underscores, hyphens, and periods. +.IP \[bu] 2 +Replace all spaces and newlines with hyphens. +.IP \[bu] 2 +Convert all alphabetic characters to lowercase. +.IP \[bu] 2 +Remove everything up to the first letter (identifiers may not begin with +a number or punctuation mark). +.IP \[bu] 2 +If nothing is left after this, use the identifier \f[C]section\f[]. +.PP +Thus, for example, +.PP +.TS +tab(@); +l l. +T{ +Header +T}@T{ +Identifier +T} +_ +T{ +\f[C]Header\ identifiers\ in\ HTML\f[] +T}@T{ +\f[C]header\-identifiers\-in\-html\f[] +T} +T{ +\f[C]*Dogs*?\-\-in\ *my*\ house?\f[] +T}@T{ +\f[C]dogs\-\-in\-my\-house\f[] +T} +T{ +\f[C][HTML],\ [S5],\ or\ [RTF]?\f[] +T}@T{ +\f[C]html\-s5\-or\-rtf\f[] +T} +T{ +\f[C]3.\ Applications\f[] +T}@T{ +\f[C]applications\f[] +T} +T{ +\f[C]33\f[] +T}@T{ +\f[C]section\f[] +T} +.TE +.PP +These rules should, in most cases, allow one to determine the identifier +from the header text. +The exception is when several headers have the same text; in this case, +the first will get an identifier as described above; the second will get +the same identifier with \f[C]\-1\f[] appended; the third with +\f[C]\-2\f[]; and so on. +.PP +These identifiers are used to provide link targets in the table of +contents generated by the \f[C]\-\-toc|\-\-table\-of\-contents\f[] +option. +They also make it easy to provide links from one section of a document +to another. +A link to this section, for example, might look like this: +.IP +.nf +\f[C] +See\ the\ section\ on +[header\ identifiers](#header\-identifiers\-in\-html\-latex\-and\-context). +\f[] +.fi +.PP +Note, however, that this method of providing links to sections works +only in HTML, LaTeX, and ConTeXt formats. +.PP +If the \f[C]\-\-section\-divs\f[] option is specified, then each section +will be wrapped in a \f[C]section\f[] (or a \f[C]div\f[], if +\f[C]html4\f[] was specified), and the identifier will be attached to +the enclosing \f[C]<section>\f[] (or \f[C]<div>\f[]) tag rather than the +header itself. +This allows entire sections to be manipulated using JavaScript or +treated differently in CSS. +.SS Extension: \f[C]ascii_identifiers\f[] +.PP +Causes the identifiers produced by \f[C]auto_identifiers\f[] to be pure +ASCII. +Accents are stripped off of accented Latin letters, and non\-Latin +letters are omitted. +.SS Math Input +.PP +The extensions \f[C]tex_math_dollars\f[], +\f[C]tex_math_single_backslash\f[], and +\f[C]tex_math_double_backslash\f[] are described in the section about +Pandoc\[aq]s Markdown. +.PP +However, they can also be used with HTML input. +This is handy for reading web pages formatted using MathJax, for +example. +.SS Raw HTML/TeX +.PP +The following extensions (especially how they affect Markdown +input/output) are also described in more detail in their respective +sections of Pandoc\[aq]s Markdown. +.SS Extension: \f[C]raw_html\f[] +.PP +When converting from HTML, parse elements to raw HTML which are not +representable in pandoc\[aq]s AST. +By default, this is disabled for HTML input. +.SS Extension: \f[C]raw_tex\f[] +.PP +Allows raw LaTeX, TeX, and ConTeXt to be included in a document. +.PP +This extension can be enabled/disabled for the following formats (in +addition to \f[C]markdown\f[]): +.TP +.B input formats +\f[C]latex\f[], \f[C]org\f[], \f[C]textile\f[] +.RS +.RE +.TP +.B output formats +\f[C]textile\f[] +.RS +.RE +.SS Extension: \f[C]native_divs\f[] +.PP +This extension is enabled by default for HTML input. +This means that \f[C]div\f[]s are parsed to pandoc native elements. +(Alternatively, you can parse them to raw HTML using +\f[C]\-f\ html\-native_divs+raw_html\f[].) +.PP +When converting HTML to Markdown, for example, you may want to drop all +\f[C]div\f[]s and \f[C]span\f[]s: +.IP +.nf +\f[C] +pandoc\ \-f\ html\-native_divs\-native_spans\ \-t\ markdown +\f[] +.fi +.SS Extension: \f[C]native_spans\f[] +.PP +Analogous to \f[C]native_divs\f[] above. +.SS Literate Haskell support +.SS Extension: \f[C]literate_haskell\f[] +.PP +Treat the document as literate Haskell source. +.PP +This extension can be enabled/disabled for the following formats: +.TP +.B input formats +\f[C]markdown\f[], \f[C]rst\f[], \f[C]latex\f[] +.RS +.RE +.TP +.B output formats +\f[C]markdown\f[], \f[C]rst\f[], \f[C]latex\f[], \f[C]html\f[] +.RS +.RE +.PP +If you append \f[C]+lhs\f[] (or \f[C]+literate_haskell\f[]) to one of +the formats above, pandoc will treat the document as literate Haskell +source. +This means that +.IP \[bu] 2 +In Markdown input, "bird track" sections will be parsed as Haskell code +rather than block quotations. +Text between \f[C]\\begin{code}\f[] and \f[C]\\end{code}\f[] will also +be treated as Haskell code. +For ATX\-style headers the character \[aq]=\[aq] will be used instead of +\[aq]#\[aq]. +.IP \[bu] 2 +In Markdown output, code blocks with classes \f[C]haskell\f[] and +\f[C]literate\f[] will be rendered using bird tracks, and block +quotations will be indented one space, so they will not be treated as +Haskell code. +In addition, headers will be rendered setext\-style (with underlines) +rather than ATX\-style (with \[aq]#\[aq] characters). +(This is because ghc treats \[aq]#\[aq] characters in column 1 as +introducing line numbers.) +.IP \[bu] 2 +In restructured text input, "bird track" sections will be parsed as +Haskell code. +.IP \[bu] 2 +In restructured text output, code blocks with class \f[C]haskell\f[] +will be rendered using bird tracks. +.IP \[bu] 2 +In LaTeX input, text in \f[C]code\f[] environments will be parsed as +Haskell code. +.IP \[bu] 2 +In LaTeX output, code blocks with class \f[C]haskell\f[] will be +rendered inside \f[C]code\f[] environments. +.IP \[bu] 2 +In HTML output, code blocks with class \f[C]haskell\f[] will be rendered +with class \f[C]literatehaskell\f[] and bird tracks. +.PP +Examples: +.IP +.nf +\f[C] +pandoc\ \-f\ markdown+lhs\ \-t\ html +\f[] +.fi +.PP +reads literate Haskell source formatted with Markdown conventions and +writes ordinary HTML (without bird tracks). +.IP +.nf +\f[C] +pandoc\ \-f\ markdown+lhs\ \-t\ html+lhs +\f[] +.fi +.PP +writes HTML with the Haskell code in bird tracks, so it can be copied +and pasted as literate Haskell source. +.PP +Note that GHC expects the bird tracks in the first column, so indentend +literate code blocks (e.g. +inside an itemized environment) will not be picked up by the Haskell +compiler. +.SS Other extensions +.SS Extension: \f[C]empty_paragraphs\f[] +.PP +Allows empty paragraphs. +By default empty paragraphs are omitted. +.PP +This extension can be enabled/disabled for the following formats: +.TP +.B input formats +\f[C]docx\f[], \f[C]html\f[] +.RS +.RE +.TP +.B output formats +\f[C]markdown\f[], \f[C]docx\f[], \f[C]odt\f[], \f[C]opendocument\f[], +\f[C]html\f[] +.RS +.RE +.SS Extension: \f[C]styles\f[] +.PP +Read all docx styles as divs (for paragraph styles) and spans (for +character styles) regardless of whether pandoc understands the meaning +of these styles. +This can be used with docx custom styles. +Disabled by default. +.TP +.B input formats +\f[C]docx\f[] +.RS +.RE +.SS Extension: \f[C]amuse\f[] +.PP +In the \f[C]muse\f[] input format, this enables Text::Amuse extensions +to Emacs Muse markup. +.SS Extension: \f[C]citations\f[] +.PP +Some aspects of Pandoc\[aq]s Markdown citation syntax are also accepted +in \f[C]org\f[] input. +.SS Extension: \f[C]ntb\f[] +.PP +In the \f[C]context\f[] output format this enables the use of Natural +Tables (TABLE) instead of the default Extreme Tables (xtables). +Natural tables allow more fine\-grained global customization but come at +a performance penalty compared to extreme tables. +.SH PANDOC\[aq]S MARKDOWN .PP Pandoc understands an extended and slightly revised version of John -Gruber's Markdown syntax. +Gruber\[aq]s Markdown syntax. This document explains the syntax, noting differences from standard Markdown. Except where noted, these differences can be suppressed by using the \f[C]markdown_strict\f[] format instead of \f[C]markdown\f[]. -An extensions can be enabled by adding \f[C]+EXTENSION\f[] to the format -name and disabled by adding \f[C]\-EXTENSION\f[]. -For example, \f[C]markdown_strict+footnotes\f[] is strict Markdown with -footnotes enabled, while \f[C]markdown\-footnotes\-pipe_tables\f[] is -pandoc's Markdown without footnotes or pipe tables. +Extensions can be enabled or disabled to specify the behavior more +granularly. +They are described in the following. +See also Extensions above, for extensions that work also on other +formats. .SS Philosophy .PP Markdown is designed to be easy to write, and, even more importantly, @@ -1838,16 +2417,16 @@ easy to read: .RS .PP A Markdown\-formatted document should be publishable as\-is, as plain -text, without looking like it's been marked up with tags or formatting -instructions. -\[en] John Gruber +text, without looking like it\[aq]s been marked up with tags or +formatting instructions. +\-\- John Gruber .RE .PP -This principle has guided pandoc's decisions in finding syntax for +This principle has guided pandoc\[aq]s decisions in finding syntax for tables, footnotes, and other extensions. .PP -There is, however, one respect in which pandoc's aims are different from -the original aims of Markdown. +There is, however, one respect in which pandoc\[aq]s aims are different +from the original aims of Markdown. Whereas Markdown was originally designed with HTML generation in mind, pandoc is designed for multiple output formats. Thus, while pandoc allows the embedding of raw HTML, it discourages it, @@ -1871,8 +2450,8 @@ a hard line break, since trailing spaces in the cells are ignored. There are two kinds of headers: Setext and ATX. .SS Setext\-style headers .PP -A setext\-style header is a line of text \[lq]underlined\[rq] with a row -of \f[C]=\f[] signs (for a level one header) or \f[C]\-\f[] signs (for a +A setext\-style header is a line of text "underlined" with a row of +\f[C]=\f[] signs (for a level one header) or \f[C]\-\f[] signs (for a level two header): .IP .nf @@ -1925,7 +2504,15 @@ I\ like\ several\ of\ their\ flavors\ of\ ice\ cream: #22,\ for\ example,\ and\ #5. \f[] .fi +.SS Extension: \f[C]space_in_atx_header\f[] +.PP +Many Markdown implementations do not require a space between the opening +\f[C]#\f[]s of an ATX header and the header text, so that +\f[C]#5\ bolt\f[] and \f[C]#hashtag\f[] count as headers. +With this extension, pandoc does require the space. .SS Header identifiers +.PP +See also the \f[C]auto_identifiers\f[] extension above. .SS Extension: \f[C]header_attributes\f[] .PP Headers can be assigned attributes using this syntax at the end of the @@ -1954,7 +2541,7 @@ My\ other\ header\ \ \ {#foo} (This syntax is compatible with PHP Markdown Extra.) .PP Note that although this syntax allows assignment of classes and -key/value attributes, writers generally don't use all of this +key/value attributes, writers generally don\[aq]t use all of this information. Identifiers, classes, and key/value attributes are used in HTML and HTML\-based formats such as EPUB and slidy. @@ -1980,96 +2567,6 @@ is just the same as #\ My\ header\ {.unnumbered} \f[] .fi -.SS Extension: \f[C]auto_identifiers\f[] -.PP -A header without an explicitly specified identifier will be -automatically assigned a unique identifier based on the header text. -To derive the identifier from the header text, -.IP \[bu] 2 -Remove all formatting, links, etc. -.IP \[bu] 2 -Remove all footnotes. -.IP \[bu] 2 -Remove all punctuation, except underscores, hyphens, and periods. -.IP \[bu] 2 -Replace all spaces and newlines with hyphens. -.IP \[bu] 2 -Convert all alphabetic characters to lowercase. -.IP \[bu] 2 -Remove everything up to the first letter (identifiers may not begin with -a number or punctuation mark). -.IP \[bu] 2 -If nothing is left after this, use the identifier \f[C]section\f[]. -.PP -Thus, for example, -.PP -.TS -tab(@); -l l. -T{ -Header -T}@T{ -Identifier -T} -_ -T{ -\f[C]Header\ identifiers\ in\ HTML\f[] -T}@T{ -\f[C]header\-identifiers\-in\-html\f[] -T} -T{ -\f[C]*Dogs*?\-\-in\ *my*\ house?\f[] -T}@T{ -\f[C]dogs\-\-in\-my\-house\f[] -T} -T{ -\f[C][HTML],\ [S5],\ or\ [RTF]?\f[] -T}@T{ -\f[C]html\-s5\-or\-rtf\f[] -T} -T{ -\f[C]3.\ Applications\f[] -T}@T{ -\f[C]applications\f[] -T} -T{ -\f[C]33\f[] -T}@T{ -\f[C]section\f[] -T} -.TE -.PP -These rules should, in most cases, allow one to determine the identifier -from the header text. -The exception is when several headers have the same text; in this case, -the first will get an identifier as described above; the second will get -the same identifier with \f[C]\-1\f[] appended; the third with -\f[C]\-2\f[]; and so on. -.PP -These identifiers are used to provide link targets in the table of -contents generated by the \f[C]\-\-toc|\-\-table\-of\-contents\f[] -option. -They also make it easy to provide links from one section of a document -to another. -A link to this section, for example, might look like this: -.IP -.nf -\f[C] -See\ the\ section\ on -[header\ identifiers](#header\-identifiers\-in\-html\-latex\-and\-context). -\f[] -.fi -.PP -Note, however, that this method of providing links to sections works -only in HTML, LaTeX, and ConTeXt formats. -.PP -If the \f[C]\-\-section\-divs\f[] option is specified, then each section -will be wrapped in a \f[C]div\f[] (or a \f[C]section\f[], if -\f[C]\-\-html5\f[] was specified), and the identifier will be attached -to the enclosing \f[C]<div>\f[] (or \f[C]<section>\f[]) tag rather than -the header itself. -This allows entire sections to be manipulated using JavaScript or -treated differently in CSS. .SS Extension: \f[C]implicit_header_references\f[] .PP Pandoc behaves as if reference links have been defined for each header. @@ -2153,8 +2650,8 @@ indented more than three spaces.) \f[] .fi .PP -A \[lq]lazy\[rq] form, which requires the \f[C]>\f[] character only on -the first line of each block, is also allowed: +A "lazy" form, which requires the \f[C]>\f[] character only on the first +line of each block, is also allowed: .IP .nf \f[C] @@ -2285,8 +2782,8 @@ Here \f[C]mycode\f[] is an identifier, \f[C]haskell\f[] and \f[C]numberLines\f[] are classes, and \f[C]startFrom\f[] is an attribute with value \f[C]100\f[]. Some output formats can use this information to do syntax highlighting. -Currently, the only output formats that uses this information are HTML -and LaTeX. +Currently, the only output formats that uses this information are HTML, +LaTeX, Docx, Ms, and PowerPoint. If highlighting is supported for your output format and language, then the code block above will appear highlighted, with numbered lines. (To see which languages are supported, type @@ -2303,6 +2800,12 @@ block above will appear as follows: \f[] .fi .PP +The \f[C]numberLines\f[] (or \f[C]number\-lines\f[]) class will cause +the lines of the code block to be numbered, starting with \f[C]1\f[] or +the value of the \f[C]startFrom\f[] attribute. +The \f[C]lineAnchors\f[] (or \f[C]line\-anchors\f[]) class will cause +the lines to be clickable anchors in HTML output. +.PP A shortcut form can also be used for specifying the language of the code block: .IP @@ -2382,8 +2885,8 @@ Here is a simple example: \f[] .fi .PP -This will produce a \[lq]compact\[rq] list. -If you want a \[lq]loose\[rq] list, in which each item is formatted as a +This will produce a "compact" list. +If you want a "loose" list, in which each item is formatted as a paragraph, put spaces between the items: .IP .nf @@ -2411,7 +2914,7 @@ List items look best if subsequent lines are flush with the first line \f[] .fi .PP -But Markdown also allows a \[lq]lazy\[rq] format: +But Markdown also allows a "lazy" format: .IP .nf \f[C] @@ -2420,14 +2923,13 @@ list\ item. *\ and\ my\ second. \f[] .fi -.SS The four\-space rule +.SS Block content in list items .PP A list item may contain multiple paragraphs and other block\-level content. However, subsequent paragraphs must be preceded by a blank line and -indented four spaces or a tab. -The list will look better if the first paragraph is aligned with the -rest: +indented to line up with the first non\-space content after the list +marker. .IP .nf \f[C] @@ -2442,26 +2944,40 @@ rest: \f[] .fi .PP +Exception: if the list marker is followed by an indented code block, +which must begin 5 spaces after the list marker, then subsequent +paragraphs must begin two columns after the last character of the list +marker: +.IP +.nf +\f[C] +*\ \ \ \ \ code + +\ \ continuation\ paragraph +\f[] +.fi +.PP List items may include other lists. In this case the preceding blank line is optional. -The nested list must be indented four spaces or one tab: +The nested list must be indented to line up with the first non\-space +character after the list marker of the containing list item. .IP .nf \f[C] *\ fruits -\ \ \ \ +\ apples -\ \ \ \ \ \ \ \ \-\ macintosh -\ \ \ \ \ \ \ \ \-\ red\ delicious -\ \ \ \ +\ pears -\ \ \ \ +\ peaches +\ \ +\ apples +\ \ \ \ \-\ macintosh +\ \ \ \ \-\ red\ delicious +\ \ +\ pears +\ \ +\ peaches *\ vegetables -\ \ \ \ +\ broccoli -\ \ \ \ +\ chard +\ \ +\ broccoli +\ \ +\ chard \f[] .fi .PP -As noted above, Markdown allows you to write list items -\[lq]lazily,\[rq] instead of indenting continuation lines. +As noted above, Markdown allows you to write list items "lazily," +instead of indenting continuation lines. However, if there are multiple paragraphs or other blocks in a list item, the first line of each must be indented. .IP @@ -2477,18 +2993,6 @@ bad\ but\ is\ legal. list\ item. \f[] .fi -.PP -\f[B]Note:\f[] Although the four\-space rule for continuation paragraphs -comes from the official Markdown syntax guide, the reference -implementation, \f[C]Markdown.pl\f[], does not follow it. -So pandoc will give different results than \f[C]Markdown.pl\f[] when -authors have indented continuation paragraphs fewer than four spaces. -.PP -The Markdown syntax guide is not explicit whether the four\-space rule -applies to \f[I]all\f[] block\-level content in a list item; it only -mentions paragraphs and code blocks. -But it implies that the rule applies to all block\-level content -(including nested lists), and pandoc interprets it that way. .SS Ordered lists .PP Ordered lists work just like bulleted lists, except that the items begin @@ -2527,8 +3031,8 @@ They must be separated from the text that follows by at least one space, and, if the list marker is a capital letter with a period, by at least two spaces. .PP -The \f[C]fancy_lists\f[] extension also allows `\f[C]#\f[]' to be used -as an ordered list marker in place of a numeral: +The \f[C]fancy_lists\f[] extension also allows \[aq]\f[C]#\f[]\[aq] to +be used as an ordered list marker in place of a numeral: .IP .nf \f[C] @@ -2610,9 +3114,8 @@ one or more block elements (paragraph, code block, list, etc.), each indented four spaces or one tab stop. The body of the definition (including the first line, aside from the colon or tilde) should be indented four spaces. -However, as with other Markdown lists, you can \[lq]lazily\[rq] omit -indentation except at the beginning of a paragraph or other block -element: +However, as with other Markdown lists, you can "lazily" omit indentation +except at the beginning of a paragraph or other block element: .IP .nf \f[C] @@ -2644,16 +3147,16 @@ Term\ 2 .fi .PP Note that space between items in a definition list is required. -(A variant that loosens this requirement, but disallows \[lq]lazy\[rq] -hard wrapping, can be activated with \f[C]compact_definition_lists\f[]: -see Non\-pandoc extensions, below.) +(A variant that loosens this requirement, but disallows "lazy" hard +wrapping, can be activated with \f[C]compact_definition_lists\f[]: see +Non\-pandoc extensions, below.) .SS Numbered example lists .SS Extension: \f[C]example_lists\f[] .PP The special list marker \f[C]\@\f[] can be used for sequentially numbered examples. -The first list item with a \f[C]\@\f[] marker will be numbered `1', the -next `2', and so on, throughout the document. +The first list item with a \f[C]\@\f[] marker will be numbered +\[aq]1\[aq], the next \[aq]2\[aq], and so on, throughout the document. The numbered examples need not occur in a single list; each new list using \f[C]\@\f[] will take up where the last stopped. So, for example: @@ -2682,10 +3185,17 @@ As\ (\@good)\ illustrates,\ ... .PP The label can be any string of alphanumeric characters, underscores, or hyphens. +.PP +Note: continuation paragraphs in example lists must always be indented +four spaces, regardless of the length of the list marker. +That is, example lists always behave as if the \f[C]four_space_rule\f[] +extension is set. +This is because example labels tend to be long, and indenting content to +the first non\-space character after the label would be awkward. .SS Compact and loose lists .PP -Pandoc behaves differently from \f[C]Markdown.pl\f[] on some \[lq]edge -cases\[rq] involving lists. +Pandoc behaves differently from \f[C]Markdown.pl\f[] on some "edge +cases" involving lists. Consider this source: .IP .nf @@ -2700,15 +3210,14 @@ Consider this source: \f[] .fi .PP -Pandoc transforms this into a \[lq]compact list\[rq] (with no -\f[C]<p>\f[] tags around \[lq]First\[rq], \[lq]Second\[rq], or -\[lq]Third\[rq]), while Markdown puts \f[C]<p>\f[] tags around -\[lq]Second\[rq] and \[lq]Third\[rq] (but not \[lq]First\[rq]), because -of the blank space around \[lq]Third\[rq]. +Pandoc transforms this into a "compact list" (with no \f[C]<p>\f[] tags +around "First", "Second", or "Third"), while Markdown puts \f[C]<p>\f[] +tags around "Second" and "Third" (but not "First"), because of the blank +space around "Third". Pandoc follows a simple rule: if the text is followed by a blank line, it is treated as a paragraph. -Since \[lq]Second\[rq] is followed by a list, and not a blank line, it -isn't treated as a paragraph. +Since "Second" is followed by a list, and not a blank line, it isn\[aq]t +treated as a paragraph. The fact that the list is followed by a blank line is irrelevant. (Note: Pandoc works this way even when the \f[C]markdown_strict\f[] format is specified. @@ -2732,9 +3241,9 @@ Trouble! Here pandoc (like other Markdown implementations) will treat \f[C]{\ my\ code\ block\ }\f[] as the second paragraph of item two, and not as a code block. .PP -To \[lq]cut off\[rq] the list after item two, you can insert some -non\-indented content, like an HTML comment, which won't produce visible -output in any format: +To "cut off" the list after item two, you can insert some non\-indented +content, like an HTML comment, which won\[aq]t produce visible output in +any format: .IP .nf \f[C] @@ -2953,6 +3462,15 @@ For headerless tables, the colons go on the top line instead: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \f[] .fi +.SS Grid Table Limitations +.PP +Pandoc does not support grid tables with row spans or column spans. +This means that neither variable numbers of columns across rows nor +variable numbers of rows across columns are supported by Pandoc. +All grid tables must have the same number of columns in each row, and +the same number of rows in each column. +For example, the Docutils sample grid tables will not render as expected +with Pandoc. .SS Extension: \f[C]pipe_tables\f[] .PP Pipe tables look like this: @@ -2996,9 +3514,12 @@ If a pipe table contains a row whose printable content is wider than the column width (see \f[C]\-\-columns\f[]), then the cell contents will wrap, with the relative cell widths determined by the widths of the separator lines. +(In this case, the table will take up the full text width.) If no lines +are wider than column width, then cell contents will not be wrapped, and +the cells will be sized to their contents. .PP Note: pandoc also recognizes pipe tables of the following form, as can -be produced by Emacs' orgtbl\-mode: +be produced by Emacs\[aq] orgtbl\-mode: .IP .nf \f[C] @@ -3011,8 +3532,8 @@ be produced by Emacs' orgtbl\-mode: .PP The difference is that \f[C]+\f[] is used instead of \f[C]|\f[]. Other orgtbl features are not supported. -In particular, to get non\-default column alignment, you'll need to add -colons as above. +In particular, to get non\-default column alignment, you\[aq]ll need to +add colons as above. .SS Metadata blocks .SS Extension: \f[C]pandoc_title_block\f[] .PP @@ -3077,13 +3598,13 @@ All three metadata fields may contain standard inline formatting .PP Title blocks will always be parsed, but they will affect the output only when the \f[C]\-\-standalone\f[] (\f[C]\-s\f[]) option is chosen. -In HTML output, titles will appear twice: once in the document head -\[en] this is the title that will appear at the top of the window in a -browser \[en] and once at the beginning of the document body. +In HTML output, titles will appear twice: once in the document head \-\- +this is the title that will appear at the top of the window in a browser +\-\- and once at the beginning of the document body. The title in the document head can have an optional prefix attached (\f[C]\-\-title\-prefix\f[] or \f[C]\-T\f[] option). -The title in the body appears as an H1 element with class -\[lq]title\[rq], so it can be suppressed or reformatted with CSS. +The title in the body appears as an H1 element with class "title", so it +can be suppressed or reformatted with CSS. If a title prefix is specified with \f[C]\-T\f[] and no title block appears in the document, the title prefix will be used by itself as the HTML title. @@ -3112,7 +3633,7 @@ will yield a man page with the title \f[C]PANDOC\f[] and section 1. \f[] .fi .PP -will also have \[lq]Pandoc User Manuals\[rq] in the footer. +will also have "Pandoc User Manuals" in the footer. .IP .nf \f[C] @@ -3120,7 +3641,7 @@ will also have \[lq]Pandoc User Manuals\[rq] in the footer. \f[] .fi .PP -will also have \[lq]Version 4.0\[rq] in the header. +will also have "Version 4.0" in the header. .SS Extension: \f[C]yaml_metadata_block\f[] .PP A YAML metadata block is a valid YAML object, delimited by a line of @@ -3164,7 +3685,8 @@ Note that YAML escaping rules must be followed. Thus, for example, if a title contains a colon, it must be quoted. The pipe character (\f[C]|\f[]) can be used to begin an indented block that will be interpreted literally, without need for escaping. -This form is necessary when the field contains blank lines: +This form is necessary when the field contains blank lines or +block\-level formatting: .IP .nf \f[C] @@ -3229,6 +3751,23 @@ $endif$ $endfor$ \f[] .fi +.PP +Raw content to include in the document\[aq]s header may be specified +using \f[C]header\-includes\f[]; however, it is important to mark up +this content as raw code for a particular output format, using the +\f[C]raw_attribute\f[] extension), or it will be interpreted as +markdown. +For example: +.IP +.nf +\f[C] +header\-includes: +\-\ ```{=latex} +\ \ \\let\\oldsection\\section +\ \ \\renewcommand{\\section}[1]{\\clearpage\\oldsection{#1}} +\ \ ``` +\f[] +.fi .SS Backslash escapes .SS Extension: \f[C]all_symbols_escapable\f[] .PP @@ -3259,7 +3798,7 @@ instead of \f[] .fi .PP -This rule is easier to remember than standard Markdown's rule, which +This rule is easier to remember than standard Markdown\[aq]s rule, which allows only the following characters to be backslash\-escaped: .IP .nf @@ -3275,27 +3814,15 @@ A backslash\-escaped space is parsed as a nonbreaking space. It will appear in TeX output as \f[C]~\f[] and in HTML and XML as \f[C]\\ \f[] or \f[C]\\ \f[]. .PP -A backslash\-escaped newline (i.e.\ a backslash occurring at the end of -a line) is parsed as a hard line break. +A backslash\-escaped newline (i.e. +a backslash occurring at the end of a line) is parsed as a hard line +break. It will appear in TeX output as \f[C]\\\\\f[] and in HTML as \f[C]<br\ />\f[]. -This is a nice alternative to Markdown's \[lq]invisible\[rq] way of +This is a nice alternative to Markdown\[aq]s "invisible" way of indicating hard line breaks using two trailing spaces on a line. .PP Backslash escapes do not work in verbatim contexts. -.SS Smart punctuation -.SS Extension -.PP -If the \f[C]\-\-smart\f[] option is specified, pandoc will produce -typographically correct output, converting straight quotes to curly -quotes, \f[C]\-\-\-\f[] to em\-dashes, \f[C]\-\-\f[] to en\-dashes, and -\f[C]\&...\f[] to ellipses. -Nonbreaking spaces are inserted after certain abbreviations, such as -\[lq]Mr.\[rq] -.PP -Note: if your LaTeX template or any included header file call for the -\f[C]csquotes\f[] package, pandoc will detect this automatically and use -\f[C]\\enquote{...}\f[] for quoted text. .SS Inline formatting .SS Emphasis .PP @@ -3367,8 +3894,8 @@ If the superscripted or subscripted text contains spaces, these spaces must be escaped with backslashes. (This is to prevent accidental superscripting and subscripting through the ordinary use of \f[C]~\f[] and \f[C]^\f[].) Thus, if you want the -letter P with `a cat' in subscripts, use \f[C]P~a\\\ cat~\f[], not -\f[C]P~a\ cat~\f[]. +letter P with \[aq]a cat\[aq] in subscripts, use \f[C]P~a\\\ cat~\f[], +not \f[C]P~a\ cat~\f[]. .SS Verbatim .PP To make a short span of text verbatim, put it inside backticks: @@ -3414,24 +3941,31 @@ blocks: .fi .SS Small caps .PP -To write small caps, you can use an HTML span tag: +To write small caps, use the \f[C]smallcaps\f[] class: .IP .nf \f[C] -<span\ style="font\-variant:small\-caps;">Small\ caps</span> +[Small\ caps]{.smallcaps} \f[] .fi .PP -(The semicolon is optional and there may be space after the colon.) This -will work in all output formats that support small caps. +Or, without the \f[C]bracketed_spans\f[] extension: +.IP +.nf +\f[C] +<span\ class="smallcaps">Small\ caps</span> +\f[] +.fi .PP -Alternatively, you can also use the new \f[C]bracketed_spans\f[] syntax: +For compatibility with other Markdown flavors, CSS is also supported: .IP .nf \f[C] -[Small\ caps]{style="font\-variant:small\-caps;"} +<span\ style="font\-variant:small\-caps;">Small\ caps</span> \f[] .fi +.PP +This will work in all output formats that support small caps. .SS Math .SS Extension: \f[C]tex_math_dollars\f[] .PP @@ -3440,9 +3974,9 @@ The opening \f[C]$\f[] must have a non\-space character immediately to its right, while the closing \f[C]$\f[] must have a non\-space character immediately to its left, and must not be followed immediately by a digit. -Thus, \f[C]$20,000\ and\ $30,000\f[] won't parse as math. +Thus, \f[C]$20,000\ and\ $30,000\f[] won\[aq]t parse as math. If for some reason you need to enclose text in literal \f[C]$\f[] -characters, backslash\-escape them and they won't be treated as math +characters, backslash\-escape them and they won\[aq]t be treated as math delimiters. .PP TeX math will be printed in all output formats. @@ -3469,7 +4003,7 @@ It will be rendered inside a \f[C]\@math\f[] command. .RE .TP .B groff man -It will be rendered verbatim without \f[C]$\f[]'s. +It will be rendered verbatim without \f[C]$\f[]\[aq]s. .RS .RE .TP @@ -3483,12 +4017,17 @@ It will be rendered inside \f[C]<span\ class="math">\f[] tags. .RS .RE .TP -.B RTF, OpenDocument, ODT +.B RTF, OpenDocument It will be rendered, if possible, using Unicode characters, and will otherwise appear verbatim. .RS .RE .TP +.B ODT +It will be rendered, if possible, using MathML. +.RS +.RE +.TP .B DocBook If the \f[C]\-\-mathml\f[] flag is used, it will be rendered using MathML in an \f[C]inlineequation\f[] or \f[C]informalequation\f[] tag. @@ -3511,62 +4050,9 @@ Otherwise, they will appear verbatim. .TP .B HTML, Slidy, DZSlides, S5, EPUB The way math is rendered in HTML will depend on the command\-line -options selected: +options selected. +Therefore see Math rendering in HTML above. .RS -.IP "1." 3 -The default is to render TeX math as far as possible using Unicode -characters, as with RTF, DocBook, and OpenDocument output. -Formulas are put inside a \f[C]span\f[] with \f[C]class="math"\f[], so -that they may be styled differently from the surrounding text if needed. -.IP "2." 3 -If the \f[C]\-\-latexmathml\f[] option is used, TeX math will be -displayed between \f[C]$\f[] or \f[C]$$\f[] characters and put in -\f[C]<span>\f[] tags with class \f[C]LaTeX\f[]. -The LaTeXMathML script will be used to render it as formulas. -(This trick does not work in all browsers, but it works in Firefox. -In browsers that do not support LaTeXMathML, TeX math will appear -verbatim between \f[C]$\f[] characters.) -.IP "3." 3 -If the \f[C]\-\-jsmath\f[] option is used, TeX math will be put inside -\f[C]<span>\f[] tags (for inline math) or \f[C]<div>\f[] tags (for -display math) with class \f[C]math\f[]. -The jsMath script will be used to render it. -.IP "4." 3 -If the \f[C]\-\-mimetex\f[] option is used, the mimeTeX CGI script will -be called to generate images for each TeX formula. -This should work in all browsers. -The \f[C]\-\-mimetex\f[] option takes an optional URL as argument. -If no URL is specified, it will be assumed that the mimeTeX CGI script -is at \f[C]/cgi\-bin/mimetex.cgi\f[]. -.IP "5." 3 -If the \f[C]\-\-gladtex\f[] option is used, TeX formulas will be -enclosed in \f[C]<eq>\f[] tags in the HTML output. -The resulting \f[C]htex\f[] file may then be processed by gladTeX, which -will produce image files for each formula and an HTML file with links to -these images. -So, the procedure is: -.RS 4 -.IP -.nf -\f[C] -pandoc\ \-s\ \-\-gladtex\ myfile.txt\ \-o\ myfile.htex -gladtex\ \-d\ myfile\-images\ myfile.htex -#\ produces\ myfile.html\ and\ images\ in\ myfile\-images -\f[] -.fi -.RE -.IP "6." 3 -If the \f[C]\-\-webtex\f[] option is used, TeX formulas will be -converted to \f[C]<img>\f[] tags that link to an external script that -converts formulas to images. -The formula will be URL\-encoded and concatenated with the URL provided. -If no URL is specified, the CodeCogs will be used -(\f[C]https://latex.codecogs.com/png.latex?\f[]). -.IP "7." 3 -If the \f[C]\-\-mathjax\f[] option is used, TeX math will be displayed -between \f[C]\\(...\\)\f[] (for inline math) or \f[C]\\[...\\]\f[] (for -display math) and put in \f[C]<span>\f[] tags with class \f[C]math\f[]. -The MathJax script will be used to render it as formulas. .RE .SS Raw HTML .SS Extension: \f[C]raw_html\f[] @@ -3583,9 +4069,9 @@ DZSlides, EPUB, Markdown, Emacs Org mode, and Textile output, and suppressed in other formats. .SS Extension: \f[C]markdown_in_html_blocks\f[] .PP -Standard Markdown allows you to include HTML \[lq]blocks\[rq]: blocks of -HTML between balanced tags that are separated from the surrounding text -with blank lines, and start and end at the left margin. +Standard Markdown allows you to include HTML "blocks": blocks of HTML +between balanced tags that are separated from the surrounding text with +blank lines, and start and end at the left margin. Within these blocks, everything is interpreted as HTML, not Markdown; so (for example), \f[C]*\f[] does not signify emphasis. .PP @@ -3642,7 +4128,6 @@ Use native pandoc \f[C]Span\f[] blocks for content inside For the most part this should give the same output as \f[C]raw_html\f[], but it makes it easier to write pandoc filters to manipulate groups of inlines. -.SS Raw TeX .SS Extension: \f[C]raw_tex\f[] .PP In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be @@ -3675,12 +4160,46 @@ LaTeX, not as Markdown. .PP Inline LaTeX is ignored in output formats other than Markdown, LaTeX, Emacs Org mode, and ConTeXt. +.SS Generic raw attribute +.SS Extension: \f[C]raw_attribute\f[] +.PP +Inline spans and fenced code blocks with a special kind of attribute +will be parsed as raw content with the designated format. +For example, the following produces a raw groff \f[C]ms\f[] block: +.IP +.nf +\f[C] +```{=ms} +\&.MYMACRO +blah\ blah +``` +\f[] +.fi +.PP +And the following produces a raw \f[C]html\f[] inline element: +.IP +.nf +\f[C] +This\ is\ `<a>html</a>`{=html} +\f[] +.fi +.PP +The format name should match the target format name (see +\f[C]\-t/\-\-to\f[], above, for a list, or use +\f[C]pandoc\ \-\-list\-output\-formats\f[]). +.PP +This extension presupposes that the relevant kind of inline code or +fenced code block is enabled. +Thus, for example, to use a raw attribute with a backtick code block, +\f[C]backtick_code_blocks\f[] must be enabled. +.PP +The raw attribute cannot be combined with regular attributes. .SS LaTeX macros .SS Extension: \f[C]latex_macros\f[] .PP -For output formats other than LaTeX, pandoc will parse LaTeX -\f[C]\\newcommand\f[] and \f[C]\\renewcommand\f[] definitions and apply -the resulting macros to all LaTeX math. +For output formats other than LaTeX, pandoc will parse LaTeX macro +definitions and apply the resulting macros to all LaTeX math and raw +LaTeX. So, for example, the following will work in all output formats, not just LaTeX: .IP @@ -3692,8 +4211,15 @@ $\\tuple{a,\ b,\ c}$ \f[] .fi .PP -In LaTeX output, the \f[C]\\newcommand\f[] definition will simply be -passed unchanged to the output. +Note that LaTeX macros will not be applied if they occur inside inside a +raw span or block marked with the \f[C]raw_attribute\f[] extension. +.PP +When \f[C]latex_macros\f[] is disabled, the raw LaTeX and math will not +have macros applied. +This is usually a better approach when you are targeting LaTeX or PDF. +.PP +Whether or not \f[C]latex_macros\f[] is enabled, the macro definitions +will still be passed through as raw LaTeX. .SS Links .PP Markdown allows links to be specified in several ways. @@ -3742,10 +4268,11 @@ before or after the link). .PP The link consists of link text in square brackets, followed by a label in square brackets. -(There can be space between the two.) The link definition consists of -the bracketed label, followed by a colon and a space, followed by the -URL, and optionally (after a space) a link title either in quotes or in -parentheses. +(There cannot be space between the two unless the +\f[C]spaced_reference_links\f[] extension is enabled.) The link +definition consists of the bracketed label, followed by a colon and a +space, followed by the URL, and optionally (after a space) a link title +either in quotes or in parentheses. The label must not be parseable as a citation (assuming the \f[C]citations\f[] extension is enabled): citations take precedence over link labels. @@ -3853,7 +4380,7 @@ slide shows and EPUB), LaTeX, and ConTeXt. .SS Images .PP A link immediately preceded by a \f[C]!\f[] will be treated as an image. -The link text will be used as the image's alt text: +The link text will be used as the image\[aq]s alt text: .IP .nf \f[C] @@ -3866,11 +4393,9 @@ The link text will be used as the image's alt text: .fi .SS Extension: \f[C]implicit_figures\f[] .PP -An image occurring by itself in a paragraph will be rendered as a figure -with a caption. (In LaTeX, a figure environment will be used; in HTML, -the image will be placed in a \f[C]div\f[] with class \f[C]figure\f[], -together with a caption in a \f[C]p\f[] with class \f[C]caption\f[].) -The image's alt text will be used as the caption. +An image with nonempty alt text, occurring by itself in a paragraph, +will be rendered as a figure with a caption. +The image\[aq]s alt text will be used as the caption. .IP .nf \f[C] @@ -3878,15 +4403,25 @@ The image's alt text will be used as the caption. \f[] .fi .PP +How this is rendered depends on the output format. +Some output formats (e.g. +RTF) do not yet support figures. +In those formats, you\[aq]ll just get an image in a paragraph by itself, +with no caption. +.PP If you just want a regular inline image, just make sure it is not the only thing in the paragraph. One way to do this is to insert a nonbreaking space after the image: .IP .nf \f[C] -![This\ image\ won\[aq]t\ be\ a\ figure](/url/of/image.png)\\\ +![This\ image\ won\[aq]t\ be\ a\ figure](/url/of/image.png)\\ \f[] .fi +.PP +Note that in reveal.js slide shows, an image in a paragraph by itself +that has the \f[C]stretch\f[] class will fill the screen, and the +caption and figure tags will be omitted. .SS Extension: \f[C]link_attributes\f[] .PP Attributes can be set on links and images: @@ -3942,12 +4477,67 @@ identifier (LaTeX \f[C]\\caption\f[]), or both (HTML). When no \f[C]width\f[] or \f[C]height\f[] attributes are specified, the fallback is to look at the image resolution and the dpi metadata embedded in the image file. -.SS Spans +.SS Divs and Spans +.PP +Using the \f[C]native_divs\f[] and \f[C]native_spans\f[] extensions (see +above), HTML syntax can be used as part of markdown to create native +\f[C]Div\f[] and \f[C]Span\f[] elements in the pandoc AST (as opposed to +raw HTML). +However, there is also nicer syntax available: +.SS Extension: \f[C]fenced_divs\f[] +.PP +Allow special fenced syntax for native \f[C]Div\f[] blocks. +A Div starts with a fence containing at least three consecutive colons +plus some attributes. +The attributes may optionally be followed by another string of +consecutive colons. +The attribute syntax is exactly as in fenced code blocks (see Extension: +\f[C]fenced_code_attributes\f[]). +As with fenced code blocks, one can use either attributes in curly +braces or a single unbraced word, which will be treated as a class name. +The Div ends with another line containing a string of at least three +consecutive colons. +The fenced Div should be separated by blank lines from preceding and +following blocks. +.PP +Example: +.IP +.nf +\f[C] +:::::\ {#special\ .sidebar} +Here\ is\ a\ paragraph. + +And\ another. +::::: +\f[] +.fi +.PP +Fenced divs can be nested. +Opening fences are distinguished because they \f[I]must\f[] have +attributes: +.IP +.nf +\f[C] +:::\ Warning\ :::::: +This\ is\ a\ warning. + +:::\ Danger +This\ is\ a\ warning\ within\ a\ warning. +::: +:::::::::::::::::: +\f[] +.fi +.PP +Fences without attributes are always closing fences. +Unlike with fenced code blocks, the number of colons in the closing +fence need not match the number in the opening fence. +However, it can be helpful for visual clarity to use fences of different +lengths to distinguish nested divs from their parents. .SS Extension: \f[C]bracketed_spans\f[] .PP A bracketed sequence of inlines, as one would use to begin a link, will -be treated as a span with attributes if it is followed immediately by -attributes: +be treated as a \f[C]Span\f[] with attributes if it is followed +immediately by attributes: .IP .nf \f[C] @@ -3957,7 +4547,7 @@ attributes: .SS Footnotes .SS Extension: \f[C]footnotes\f[] .PP -Pandoc's Markdown allows footnotes, using the following syntax: +Pandoc\[aq]s Markdown allows footnotes, using the following syntax: .IP .nf \f[C] @@ -4141,7 +4731,7 @@ JSON and CSL YAML formats as far as possible. As an alternative to specifying a bibliography file using \f[C]\-\-bibliography\f[] or the YAML metadata field \f[C]bibliography\f[], you can include the citation data directly in the -\f[C]references\f[] field of the document's YAML metadata. +\f[C]references\f[] field of the document\[aq]s YAML metadata. The field should contain an array of YAML\-encoded references, for example: .IP @@ -4191,7 +4781,7 @@ To make your citations hyperlinks to the corresponding bibliography entries, add \f[C]link\-citations:\ true\f[] to your YAML metadata. .PP Citations go inside square brackets and are separated by semicolons. -Each citation must have a key, composed of `\@' + the citation +Each citation must have a key, composed of \[aq]\@\[aq] + the citation identifier from the database, and may optionally have a prefix, a locator, and a suffix. The citation key must begin with a letter, digit, or \f[C]_\f[], and may @@ -4226,7 +4816,7 @@ singular or plural forms, as \f[C]book\f[], \f[C]bk.\f[]/\f[C]bks.\f[]; \f[C]s.v.\f[]/\f[C]s.vv.\f[]; \f[C]verse\f[], \f[C]v.\f[]/\f[C]vv.\f[]; \f[C]volume\f[], \f[C]vol.\f[]/\f[C]vols.\f[]; \f[C]¶\f[]/\f[C]¶¶\f[]; \f[C]§\f[]/\f[C]§§\f[]. -If no locator term is used, \[lq]page\[rq] is assumed. +If no locator term is used, "page" is assumed. .PP A minus sign (\f[C]\-\f[]) before the \f[C]\@\f[] will suppress mention of the author in the citation. @@ -4311,15 +4901,36 @@ pandoc, but may be enabled by adding \f[C]+EXTENSION\f[] to the format name, where \f[C]EXTENSION\f[] is the name of the extension. Thus, for example, \f[C]markdown+hard_line_breaks\f[] is Markdown with hard line breaks. +.SS Extension: \f[C]old_dashes\f[] +.PP +Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: +\f[C]\-\f[] before a numeral is an en\-dash, and \f[C]\-\-\f[] is an +em\-dash. +This option only has an effect if \f[C]smart\f[] is enabled. +It is selected automatically for \f[C]textile\f[] input. .SS Extension: \f[C]angle_brackets_escapable\f[] .PP Allow \f[C]<\f[] and \f[C]>\f[] to be backslash\-escaped, as they can be in GitHub flavored Markdown but not original Markdown. -This is implied by pandoc's default \f[C]all_symbols_escapable\f[]. +This is implied by pandoc\[aq]s default \f[C]all_symbols_escapable\f[]. .SS Extension: \f[C]lists_without_preceding_blankline\f[] .PP Allow a list to occur right after a paragraph, with no intervening blank space. +.SS Extension: \f[C]four_space_rule\f[] +.PP +Selects the pandoc <= 2.0 behavior for parsing lists, so that four +spaces indent are needed for list item continuation paragraphs. +.SS Extension: \f[C]spaced_reference_links\f[] +.PP +Allow whitespace between the two components of a reference link, for +example, +.IP +.nf +\f[C] +[foo]\ [bar]. +\f[] +.fi .SS Extension: \f[C]hard_line_breaks\f[] .PP Causes all newlines within a paragraph to be interpreted as hard line @@ -4395,12 +5006,6 @@ opposed to being parsed as paragraphs). .PP Makes all absolute URIs into links, even when not surrounded by pointy braces \f[C]<...>\f[]. -.SS Extension: \f[C]ascii_identifiers\f[] -.PP -Causes the identifiers produced by \f[C]auto_identifiers\f[] to be pure -ASCII. -Accents are stripped off of accented Latin letters, and non\-Latin -letters are omitted. .SS Extension: \f[C]mmd_link_attributes\f[] .PP Parses multimarkdown style key\-value attributes on link and image @@ -4429,15 +5034,15 @@ in several respects: No blank line is required between consecutive items of the definition list. .IP \[bu] 2 -To get a \[lq]tight\[rq] or \[lq]compact\[rq] list, omit space between -consecutive items; the space between a term and its definition does not -affect anything. +To get a "tight" or "compact" list, omit space between consecutive +items; the space between a term and its definition does not affect +anything. .IP \[bu] 2 Lazy wrapping of paragraphs is not allowed: the entire definition must be indented four spaces. .SS Markdown variants .PP -In addition to pandoc's extended Markdown, the following Markdown +In addition to pandoc\[aq]s extended Markdown, the following Markdown variants are supported: .TP .B \f[C]markdown_phpextra\f[] (PHP Markdown Extra) @@ -4445,17 +5050,19 @@ variants are supported: \f[C]markdown_attribute\f[], \f[C]fenced_code_blocks\f[], \f[C]definition_lists\f[], \f[C]intraword_underscores\f[], \f[C]header_attributes\f[], \f[C]link_attributes\f[], -\f[C]abbreviations\f[], \f[C]shortcut_reference_links\f[]. +\f[C]abbreviations\f[], \f[C]shortcut_reference_links\f[], +\f[C]spaced_reference_links\f[]. .RS .RE .TP -.B \f[C]markdown_github\f[] (GitHub\-Flavored Markdown) +.B \f[C]markdown_github\f[] (deprecated GitHub\-Flavored Markdown) \f[C]pipe_tables\f[], \f[C]raw_html\f[], \f[C]fenced_code_blocks\f[], -\f[C]auto_identifiers\f[], \f[C]ascii_identifiers\f[], +\f[C]gfm_auto_identifiers\f[], \f[C]ascii_identifiers\f[], \f[C]backtick_code_blocks\f[], \f[C]autolink_bare_uris\f[], -\f[C]intraword_underscores\f[], \f[C]strikeout\f[], -\f[C]hard_line_breaks\f[], \f[C]emoji\f[], -\f[C]shortcut_reference_links\f[], \f[C]angle_brackets_escapable\f[]. +\f[C]space_in_atx_header\f[], \f[C]intraword_underscores\f[], +\f[C]strikeout\f[], \f[C]emoji\f[], \f[C]shortcut_reference_links\f[], +\f[C]angle_brackets_escapable\f[], +\f[C]lists_without_preceding_blankline\f[]. .RS .RE .TP @@ -4466,35 +5073,49 @@ variants are supported: \f[C]footnotes\f[], \f[C]definition_lists\f[], \f[C]all_symbols_escapable\f[], \f[C]implicit_header_references\f[], \f[C]auto_identifiers\f[], \f[C]mmd_header_identifiers\f[], -\f[C]shortcut_reference_links\f[]. +\f[C]shortcut_reference_links\f[], \f[C]implicit_figures\f[], +\f[C]superscript\f[], \f[C]subscript\f[], \f[C]backtick_code_blocks\f[], +\f[C]spaced_reference_links\f[], \f[C]raw_attribute\f[]. .RS .RE .TP .B \f[C]markdown_strict\f[] (Markdown.pl) -\f[C]raw_html\f[] +\f[C]raw_html\f[], \f[C]shortcut_reference_links\f[], +\f[C]spaced_reference_links\f[]. .RS .RE -.SS Extensions with formats other than Markdown .PP -Some of the extensions discussed above can be used with formats other -than Markdown: -.IP \[bu] 2 -\f[C]auto_identifiers\f[] can be used with \f[C]latex\f[], \f[C]rst\f[], -\f[C]mediawiki\f[], and \f[C]textile\f[] input (and is used by default). -.IP \[bu] 2 -\f[C]tex_math_dollars\f[], \f[C]tex_math_single_backslash\f[], and -\f[C]tex_math_double_backslash\f[] can be used with \f[C]html\f[] input. -(This is handy for reading web pages formatted using MathJax, for -example.) +We also support \f[C]commonmark\f[] and \f[C]gfm\f[] (GitHub\-Flavored +Markdown, which is implemented as a set of extensions on +\f[C]commonmark\f[]). +.PP +Note, however, that \f[C]commonmark\f[] and \f[C]gfm\f[] have limited +support for extensions. +Only those listed below (and \f[C]smart\f[] and \f[C]raw_tex\f[]) will +work. +The extensions can, however, all be individually disabled. +Also, \f[C]raw_tex\f[] only affects \f[C]gfm\f[] output, not input. +.TP +.B \f[C]gfm\f[] (GitHub\-Flavored Markdown) +\f[C]pipe_tables\f[], \f[C]raw_html\f[], \f[C]fenced_code_blocks\f[], +\f[C]auto_identifiers\f[], \f[C]ascii_identifiers\f[], +\f[C]backtick_code_blocks\f[], \f[C]autolink_bare_uris\f[], +\f[C]intraword_underscores\f[], \f[C]strikeout\f[], +\f[C]hard_line_breaks\f[], \f[C]emoji\f[], +\f[C]shortcut_reference_links\f[], \f[C]angle_brackets_escapable\f[]. +.RS +.RE .SH PRODUCING SLIDE SHOWS WITH PANDOC .PP You can use pandoc to produce an HTML + JavaScript slide presentation that can be viewed via a web browser. There are five ways to do this, using S5, DZSlides, Slidy, Slideous, or reveal.js. -You can also produce a PDF slide show using LaTeX \f[C]beamer\f[]. +You can also produce a PDF slide show using LaTeX \f[C]beamer\f[], or +slides shows in Microsoft PowerPoint format. .PP -Here's the Markdown source for a simple slide show, \f[C]habits.txt\f[]: +Here\[aq]s the Markdown source for a simple slide show, +\f[C]habits.txt\f[]: .IP .nf \f[C] @@ -4570,6 +5191,14 @@ pandoc\ \-t\ beamer\ habits.txt\ \-o\ habits.pdf .PP Note that a reveal.js slide show can also be converted to a PDF by printing it to a file from the browser. +.PP +To produce a Powerpoint slide show, type +.IP +.nf +\f[C] +pandoc\ habits.txt\ \-o\ habits.pptx +\f[] +.fi .SS Structuring the slide show .PP By default, the \f[I]slide level\f[] is the highest header level in the @@ -4589,17 +5218,20 @@ A header at the slide level always starts a new slide. Headers \f[I]below\f[] the slide level in the hierarchy create headers \f[I]within\f[] a slide. .IP \[bu] 2 -Headers \f[I]above\f[] the slide level in the hierarchy create -\[lq]title slides,\[rq] which just contain the section title and help to -break the slide show into sections. +Headers \f[I]above\f[] the slide level in the hierarchy create "title +slides," which just contain the section title and help to break the +slide show into sections. +.IP \[bu] 2 +Content \f[I]above\f[] the slide level will not appear in the slide +show. .IP \[bu] 2 -A title page is constructed automatically from the document's title +A title page is constructed automatically from the document\[aq]s title block, if present. (In the case of beamer, this can be disabled by commenting out some lines in the default template.) .PP These rules are designed to support many different styles of slide show. -If you don't care about structuring your slides into sections and +If you don\[aq]t care about structuring your slides into sections and subsections, you can just use level 1 headers for all each slide. (In that case, level 1 will be the slide level.) But you can also structure the slide show into sections, as in the example above. @@ -4611,12 +5243,45 @@ It is not recommended that you use deeper nesting of section levels with reveal.js. .SS Incremental lists .PP -By default, these writers produce lists that display \[lq]all at -once.\[rq] If you want your lists to display incrementally (one item at -a time), use the \f[C]\-i\f[] option. -If you want a particular list to depart from the default (that is, to +By default, these writers produce lists that display "all at once." If +you want your lists to display incrementally (one item at a time), use +the \f[C]\-i\f[] option. +If you want a particular list to depart from the default, put it in a +\f[C]div\f[] block with class \f[C]incremental\f[] or +\f[C]nonincremental\f[]. +So, for example, using the \f[C]fenced\ div\f[] syntax, the following +would be incremental regardless of the document default: +.IP +.nf +\f[C] +:::\ incremental + +\-\ Eat\ spaghetti +\-\ Drink\ wine + +::: +\f[] +.fi +.PP +or +.IP +.nf +\f[C] +:::\ nonincremental + +\-\ Eat\ spaghetti +\-\ Drink\ wine + +::: +\f[] +.fi +.PP +While using \f[C]incremental\f[] and \f[C]nonincremental\f[] divs are +the recommended method of setting incremental lists on a per\-case +basis, an older method is also supported: putting lists inside a +blockquote will depart from the document default (that is, it will display incrementally without the \f[C]\-i\f[] option and all at once -with the \f[C]\-i\f[] option), put it in a block quote: +with the \f[C]\-i\f[] option): .IP .nf \f[C] @@ -4625,12 +5290,12 @@ with the \f[C]\-i\f[] option), put it in a block quote: \f[] .fi .PP -In this way incremental and nonincremental lists can be mixed in a +Both methods allow incremental and nonincremental lists to be mixed in a single document. .SS Inserting pauses .PP -You can add \[lq]pauses\[rq] within a slide by including a paragraph -containing three dots, separated by spaces: +You can add "pauses" within a slide by including a paragraph containing +three dots, separated by spaces: .IP .nf \f[C] @@ -4650,8 +5315,8 @@ in \f[C]$DATADIR/s5/default\f[] (for S5), \f[C]$DATADIR/slidy\f[] (for Slidy), or \f[C]$DATADIR/slideous\f[] (for Slideous), where \f[C]$DATADIR\f[] is the user data directory (see \f[C]\-\-data\-dir\f[], above). -The originals may be found in pandoc's system data directory (generally -\f[C]$CABALDIR/pandoc\-VERSION/s5/default\f[]). +The originals may be found in pandoc\[aq]s system data directory +(generally \f[C]$CABALDIR/pandoc\-VERSION/s5/default\f[]). Pandoc will look there for any files it does not find in the user data directory. .PP @@ -4696,25 +5361,47 @@ This is recommended especially for bibliographies: .fi .SS Speaker notes .PP -reveal.js has good support for speaker notes. +Speaker notes are supported in reveal.js and PowerPoint (pptx) output. You can add notes to your Markdown document thus: .IP .nf \f[C] -<div\ class="notes"> +:::\ notes + This\ is\ my\ note. \-\ It\ can\ contain\ Markdown \-\ like\ this\ list -</div> +::: \f[] .fi .PP -To show the notes window, press \f[C]s\f[] while viewing the -presentation. +To show the notes window in reveal.js, press \f[C]s\f[] while viewing +the presentation. +Speaker notes in PowerPoint will be available, as usual, in handouts and +presenter view. +.PP Notes are not yet supported for other slide formats, but the notes will not appear on the slides themselves. +.SS Columns +.PP +To put material in side by side columns, you can use a native div +container with class \f[C]columns\f[], containing two or more div +containers with class \f[C]column\f[] and a \f[C]width\f[] attribute: +.IP +.nf +\f[C] +::::::::::::::\ {.columns} +:::\ {.column\ width="40%"} +contents... +::: +:::\ {.column\ width="60%"} +contents... +::: +:::::::::::::: +\f[] +.fi .SS Frame attributes in beamer .PP Sometimes it is necessary to add the LaTeX \f[C][fragile]\f[] option to @@ -4730,7 +5417,7 @@ introducing the slide: .fi .PP All of the other frame attributes described in Section 8.1 of the Beamer -User's Guide may also be used: \f[C]allowdisplaybreaks\f[], +User\[aq]s Guide may also be used: \f[C]allowdisplaybreaks\f[], \f[C]allowframebreaks\f[], \f[C]b\f[], \f[C]c\f[], \f[C]t\f[], \f[C]environment\f[], \f[C]label\f[], \f[C]plain\f[], \f[C]shrink\f[]. .SH CREATING EPUBS WITH PANDOC @@ -4759,6 +5446,8 @@ identifier: \ \ text:\ doi:10.234234.234/33 publisher:\ \ My\ Press rights:\ ©\ 2007\ John\ Smith,\ CC\ BY\-NC +ibooks: +\ \ version:\ 1.3.4 \&... \f[] .fi @@ -4789,8 +5478,8 @@ Valid values for \f[C]type\f[] are \f[C]main\f[], \f[C]subtitle\f[], Either a string value, or an object with fields \f[C]role\f[], \f[C]file\-as\f[], and \f[C]text\f[], or a list of such objects. Valid values for \f[C]role\f[] are MARC relators, but pandoc will -attempt to translate the human\-readable versions (like \[lq]author\[rq] -and \[lq]editor\[rq]) to the appropriate marc relators. +attempt to translate the human\-readable versions (like "author" and +"editor") to the appropriate marc relators. .RS .RE .TP @@ -4863,6 +5552,27 @@ Specifies the \f[C]page\-progression\-direction\f[] attribute for the \f[C]spine\f[] element. .RS .RE +.TP +.B \f[C]ibooks\f[] +iBooks\-specific metadata, with the following fields: +.RS +.IP \[bu] 2 +\f[C]version\f[]: (string) +.IP \[bu] 2 +\f[C]specified\-fonts\f[]: \f[C]true\f[]|\f[C]false\f[] (default +\f[C]false\f[]) +.IP \[bu] 2 +\f[C]ipad\-orientation\-lock\f[]: +\f[C]portrait\-only\f[]|\f[C]landscape\-only\f[] +.IP \[bu] 2 +\f[C]iphone\-orientation\-lock\f[]: +\f[C]portrait\-only\f[]|\f[C]landscape\-only\f[] +.IP \[bu] 2 +\f[C]binding\f[]: \f[C]true\f[]|\f[C]false\f[] (default \f[C]true\f[]) +.IP \[bu] 2 +\f[C]scroll\-axis\f[]: +\f[C]vertical\f[]|\f[C]horizontal\f[]|\f[C]default\f[] +.RE .SS Linked media .PP By default, pandoc will download linked media (including audio and @@ -4882,70 +5592,12 @@ For example: </audio> \f[] .fi -.SH LITERATE HASKELL SUPPORT -.PP -If you append \f[C]+lhs\f[] (or \f[C]+literate_haskell\f[]) to an -appropriate input or output format (\f[C]markdown\f[], -\f[C]markdown_strict\f[], \f[C]rst\f[], or \f[C]latex\f[] for input or -output; \f[C]beamer\f[], \f[C]html\f[] or \f[C]html5\f[] for output -only), pandoc will treat the document as literate Haskell source. -This means that -.IP \[bu] 2 -In Markdown input, \[lq]bird track\[rq] sections will be parsed as -Haskell code rather than block quotations. -Text between \f[C]\\begin{code}\f[] and \f[C]\\end{code}\f[] will also -be treated as Haskell code. -For ATX\-style headers the character `=' will be used instead of `#'. -.IP \[bu] 2 -In Markdown output, code blocks with classes \f[C]haskell\f[] and -\f[C]literate\f[] will be rendered using bird tracks, and block -quotations will be indented one space, so they will not be treated as -Haskell code. -In addition, headers will be rendered setext\-style (with underlines) -rather than ATX\-style (with `#' characters). -(This is because ghc treats `#' characters in column 1 as introducing -line numbers.) -.IP \[bu] 2 -In restructured text input, \[lq]bird track\[rq] sections will be parsed -as Haskell code. -.IP \[bu] 2 -In restructured text output, code blocks with class \f[C]haskell\f[] -will be rendered using bird tracks. -.IP \[bu] 2 -In LaTeX input, text in \f[C]code\f[] environments will be parsed as -Haskell code. -.IP \[bu] 2 -In LaTeX output, code blocks with class \f[C]haskell\f[] will be -rendered inside \f[C]code\f[] environments. -.IP \[bu] 2 -In HTML output, code blocks with class \f[C]haskell\f[] will be rendered -with class \f[C]literatehaskell\f[] and bird tracks. -.PP -Examples: -.IP -.nf -\f[C] -pandoc\ \-f\ markdown+lhs\ \-t\ html -\f[] -.fi -.PP -reads literate Haskell source formatted with Markdown conventions and -writes ordinary HTML (without bird tracks). -.IP -.nf -\f[C] -pandoc\ \-f\ markdown+lhs\ \-t\ html+lhs -\f[] -.fi -.PP -writes HTML with the Haskell code in bird tracks, so it can be copied -and pasted as literate Haskell source. .SH SYNTAX HIGHLIGHTING .PP Pandoc will automatically highlight syntax in fenced code blocks that are marked with a language name. -The Haskell library highlighting\-kate is used for highlighting, which -works in HTML, Docx, and LaTeX/PDF output. +The Haskell library skylighting is used for highlighting, which works in +HTML, Docx, Ms, and LaTeX/PDF output. To see a list of language names that pandoc will recognize, type \f[C]pandoc\ \-\-list\-highlight\-languages\f[]. .PP @@ -4958,10 +5610,65 @@ To see a list of highlight styles, type \f[C]pandoc\ \-\-list\-highlight\-styles\f[]. .PP To disable highlighting, use the \f[C]\-\-no\-highlight\f[] option. -.SH CUSTOM STYLES IN DOCX OUTPUT +.SH CUSTOM STYLES IN DOCX +.SS Input +.PP +The docx reader, by default, only reads those styles that it can convert +into pandoc elements, either by direct conversion or interpreting the +derivation of the input document\[aq]s styles. +.PP +By enabling the \f[C]styles\f[] extension in the docx reader +(\f[C]\-f\ docx+styles\f[]), you can produce output that maintains the +styles of the input document, using the \f[C]custom\-style\f[] class. +Paragraph styles are interpreted as divs, while character styles are +interpreted as spans. +.PP +For example, using the \f[C]custom\-style\-reference.docx\f[] file in +the test directory, we have the following different outputs: +.PP +Without the \f[C]+styles\f[] extension: +.IP +.nf +\f[C] +$\ pandoc\ test/docx/custom\-style\-reference.docx\ \-f\ docx\ \-t\ markdown +This\ is\ some\ text. + +This\ is\ text\ with\ an\ *emphasized*\ text\ style.\ And\ this\ is\ text\ with\ a +**strengthened**\ text\ style. + +>\ Here\ is\ a\ styled\ paragraph\ that\ inherits\ from\ Block\ Text. +\f[] +.fi +.PP +And with the extension: +.IP +.nf +\f[C] +$\ pandoc\ test/docx/custom\-style\-reference.docx\ \-f\ docx+styles\ \-t\ markdown + +:::\ {custom\-style="FirstParagraph"} +This\ is\ some\ text. +::: + +:::\ {custom\-style="BodyText"} +This\ is\ text\ with\ an\ [emphasized]{custom\-style="Emphatic"}\ text\ style. +And\ this\ is\ text\ with\ a\ [strengthened]{custom\-style="Strengthened"} +text\ style. +::: + +:::\ {custom\-style="MyBlockStyle"} +>\ Here\ is\ a\ styled\ paragraph\ that\ inherits\ from\ Block\ Text. +::: +\f[] +.fi +.PP +With these custom styles, you can use your input document as a +reference\-doc while creating docx output (see below), and maintain the +same styles in your input and output files. +.SS Output .PP -By default, pandoc's docx output applies a predefined set of styles for -blocks such as paragraphs and block quotes, and uses largely default +By default, pandoc\[aq]s docx output applies a predefined set of styles +for blocks such as paragraphs and block quotes, and uses largely default formatting (italics, bold) for inlines. This will work for most purposes, especially alongside a \f[C]reference.docx\f[] file. @@ -4972,26 +5679,26 @@ blocks and text using \f[C]div\f[]s and \f[C]span\f[]s, respectively. If you define a \f[C]div\f[] or \f[C]span\f[] with the attribute \f[C]custom\-style\f[], pandoc will apply your specified style to the contained elements. -So, for example, +So, for example using the \f[C]bracketed_spans\f[] syntax, .IP .nf \f[C] -<span\ custom\-style="Emphatically">Get\ out,</span>\ he\ said. +[Get\ out]{custom\-style="Emphatically"},\ he\ said. \f[] .fi .PP -would produce a docx file with \[lq]Get out,\[rq] styled with character -style \f[C]Emphatically\f[]. -Similarly, +would produce a docx file with "Get out" styled with character style +\f[C]Emphatically\f[]. +Similarly, using the \f[C]fenced_divs\f[] syntax, .IP .nf \f[C] Dickinson\ starts\ the\ poem\ simply: -<div\ custom\-style="Poetry"> +:::\ {custom\-style="Poetry"} |\ A\ Bird\ came\ down\ the\ Walk\-\-\- |\ He\ did\ not\ know\ I\ saw\-\-\- -</div> +::: \f[] .fi .PP @@ -5038,55 +5745,11 @@ pandoc\ \-\-print\-default\-data\-file\ sample.lua .fi .SH AUTHORS .PP -© 2006\-2016 John MacFarlane (jgm\@berkeley.edu). +Copyright 2006\-2017 John MacFarlane (jgm\@berkeley.edu). Released under the GPL, version 2 or greater. This software carries no warranty of any kind. -(See COPYRIGHT for full copyright and warranty notices.) -.PP -Contributors include Arata Mizuki, Aaron Wolen, Albert Krewinkel, Alex -Ivkin, Alex Vong, Alexander Kondratskiy, Alexander Sulfrian, Alexander V -Vershilov, Alfred Wechselberger, Andreas Lööw, Andrew Dunning, Antoine -Latter, Arata Mizuki, Arlo O'Keeffe, Artyom Kazak, B. -Scott Michel, Ben Gamari, Beni Cherniavsky\-Paskin, Benoit Schweblin, -Bjorn Buckwalter, Bradley Kuhn, Brent Yorgey, Bryan O'Sullivan, Caleb -McDaniel, Calvin Beck, Carlos Sosa, Chris Black, Christian Conkle, -Christoffer Ackelman, Christoffer Sawicki, Clare Macrae, Clint Adams, -Conal Elliott, Craig S. -Bosma, Daniel Bergey, Daniel T. -Staal, Daniele D'Orazio, David Lazar, David Röthlisberger, Denis -Laxalde, Douglas Calvert, Emanuel Evans, Emily Eisenberg, Eric Kow, Eric -Seidel, Felix Yan, Florian Eitel, François Gannaz, Freiric Barral, -Freirich Raabe, Frerich Raabe, Fyodor Sheremetyev, Gabor Pali, Gavin -Beatty, Gottfried Haider, Greg Maslov, Greg Rundlett, Grégory Bataille, -Gwern Branwen, Hans\-Peter Deifel, Henrik Tramberend, Henry de Valence, -Hubert Plociniczak, Ilya V. -Portnov, Ivo Clarysse, J. -Lewis Muir, Jaime Marquínez Ferrándiz, Jakob Voß, James Aspnes, Jamie F. -Olson, Jan Larres, Jan Schulz, Jason Ronallo, Jeff Arnold, Jeff -Runningen, Jens Petersen, Jesse Rosenthal, Joe Hillenbrand, John -MacFarlane, John Muccigrosso, Jonas Smedegaard, Jonathan Daugherty, Jose -Luis Duran, Josef Svenningsson, Julien Cretel, Juliusz Gonera, Justin -Bogner, Jérémy Bobbio, Kelsey Hightower, Kolen Cheung, Konstantin Zudov, -Kristof Bastiaensen, Lars\-Dominik Braun, Luke Plant, Mark Szepieniec, -Mark Wright, Martin Linn, Masayoshi Takahashi, Matej Kollar, Mathias -Schenner, Mathieu Duponchelle, Matthew Eddey, Matthew Pickering, -Matthias C. -M. -Troffaes, Mauro Bieg, Max Bolingbroke, Max Rydahl Andersen, Merijn -Verstraaten, Michael Beaumont, Michael Chladek, Michael Snoyman, Michael -Thompson, MinRK, Morton Fox, Nathan Gass, Neil Mayhew, Nick Bart, -Nicolas Kaiser, Nikolay Yakimov, Oliver Matthews, Ophir Lifshitz, Pablo -Rodríguez, Paul Rivier, Paulo Tanimoto, Peter Wang, Philippe Ombredanne, -Phillip Alday, Prayag Verma, Puneeth Chaganti, Ralf Stephan, Raniere -Silva, Recai Oktaş, RyanGlScott, Scott Morrison, Sergei Trofimovich, -Sergey Astanin, Shahbaz Youssefi, Shaun Attfield, Sidarth Kapur, -Sidharth Kapur, Simon Hengel, Sumit Sahrawat, Thomas Hodgson, Thomas -Weißschuh, Tim Lin, Timothy Humphries, Tiziano Müller, Todd Sifleet, Tom -Leese, Uli Köhler, Václav Zeman, Viktor Kronvall, Vincent, Václav -Haisman, Václav Zeman, Wandmalfarbe, Waldir Pimenta, Wikiwide, Xavier -Olive, bumper314, csforste, infinity0x, nkalvi, qerub, robabla, -roblabla, rodja.trappe, rski, shreevatsa.public, takahashim, tgkokk, -thsutton. +(See COPYRIGHT for full copyright and warranty notices.) For a full list +of contributors, see the file AUTHORS.md in the pandoc source code. .PP The Pandoc source code and all documentation may be downloaded from <http://pandoc.org>. |