diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/capitalizeHeaders.hs | 20 | ||||
| -rw-r--r-- | man/pandoc.1 | 5092 | ||||
| -rw-r--r-- | man/pandoc.1.template | 10 | ||||
| -rw-r--r-- | man/removeLinks.hs | 9 | ||||
| -rw-r--r-- | man/removeNotes.hs | 9 |
5 files changed, 5140 insertions, 0 deletions
diff --git a/man/capitalizeHeaders.hs b/man/capitalizeHeaders.hs new file mode 100644 index 000000000..863381c1f --- /dev/null +++ b/man/capitalizeHeaders.hs @@ -0,0 +1,20 @@ +import Text.Pandoc.JSON +import Text.Pandoc.Walk +import Data.Char (toUpper) + +main :: IO () +main = toJSONFilter capitalizeHeaders + +capitalizeHeaders :: Block -> Block +capitalizeHeaders (Header 1 attr xs) = Header 1 attr $ walk capitalize xs +capitalizeHeaders x = x + +capitalize :: Inline -> Inline +capitalize (Str xs) = Str $ map toUpper xs +capitalize x = x + +{- +capitalizeHeaderLinks :: Inline -> Inline +capitalizeHeaderLinks (Link xs t@('#':_,_)) = Link (walk capitalize xs) t +capitalizeHeaderLinks x = x +-} diff --git a/man/pandoc.1 b/man/pandoc.1 new file mode 100644 index 000000000..a9cb65854 --- /dev/null +++ b/man/pandoc.1 @@ -0,0 +1,5092 @@ +.\"t +.TH PANDOC 1 "January 29, 2017" "pandoc 1.19.2" +.SH NAME +pandoc - general markup converter +.SH SYNOPSIS +.PP +\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. +Thus, adding an input or output format requires only adding a reader or +writer. +.PP +Because pandoc'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. +.SS Using \f[C]pandoc\f[] +.PP +If no \f[I]input\-file\f[] is 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). +For output to a file, use the \f[C]\-o\f[] option: +.IP +.nf +\f[C] +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: +.IP +.nf +\f[C] +pandoc\ \-s\ \-o\ output.html\ input.txt +\f[] +.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 +.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[]. +.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. +Thus, to convert \f[C]hello.txt\f[] from Markdown to LaTeX, you could +type: +.IP +.nf +\f[C] +pandoc\ \-f\ markdown\ \-t\ latex\ hello.txt +\f[] +.fi +.PP +To convert \f[C]hello.html\f[] from HTML to Markdown: +.IP +.nf +\f[C] +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. +.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. +Thus, for example, +.IP +.nf +\f[C] +pandoc\ \-o\ hello.tex\ hello.txt +\f[] +.fi +.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 +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. +.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 +and output through \f[C]iconv\f[]: +.IP +.nf +\f[C] +iconv\ \-t\ utf\-8\ input.txt\ |\ pandoc\ |\ iconv\ \-f\ utf\-8 +\f[] +.fi +.PP +Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF, +OPML, DocBook, and Texinfo), information about the character encoding is +included in the document header, which will only be included if you use +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: +.IP +.nf +\f[C] +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 +\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). +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. +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. +.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. +.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[]. +.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 +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. +See \f[C]\-\-list\-input\-formats\f[] and \f[C]\-\-list\-extensions\f[], +below. +.RS +.RE +.TP +.B \f[C]\-t\f[] \f[I]FORMAT\f[], \f[C]\-w\f[] \f[I]FORMAT\f[], \f[C]\-\-to=\f[]\f[I]FORMAT\f[], \f[C]\-\-write=\f[]\f[I]FORMAT\f[] +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]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]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[]. +See \f[C]\-\-list\-output\-formats\f[] and +\f[C]\-\-list\-extensions\f[], below. +.RS +.RE +.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.) +.RS +.RE +.TP +.B \f[C]\-\-data\-dir=\f[]\f[I]DIRECTORY\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: +.RS +.IP +.nf +\f[C] +$HOME/.pandoc +\f[] +.fi +.PP +in Windows XP: +.IP +.nf +\f[C] +C:\\Documents\ And\ Settings\\USERNAME\\Application\ Data\\pandoc +\f[] +.fi +.PP +and in Windows Vista or later: +.IP +.nf +\f[C] +C:\\Users\\USERNAME\\AppData\\Roaming\\pandoc +\f[] +.fi +.PP +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 +defaults. +.RE +.TP +.B \f[C]\-\-bash\-completion\f[] +Generate a bash completion script. +To enable bash completion with pandoc, add this to your +\f[C]\&.bashrc\f[]: +.RS +.IP +.nf +\f[C] +\ eval\ "$(pandoc\ \-\-bash\-completion)" +\f[] +.fi +.RE +.TP +.B \f[C]\-\-verbose\f[] +Give verbose debugging output. +Currently this only has an effect with PDF output. +.RS +.RE +.TP +.B \f[C]\-\-list\-input\-formats\f[] +List supported input formats, one per line. +.RS +.RE +.TP +.B \f[C]\-\-list\-output\-formats\f[] +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. +.RS +.RE +.TP +.B \f[C]\-\-list\-highlight\-languages\f[] +List supported languages for syntax highlighting, one per line. +.RS +.RE +.TP +.B \f[C]\-\-list\-highlight\-styles\f[] +List supported styles for syntax highlighting, one per line. +See \f[C]\-\-highlight\-style\f[]. +.RS +.RE +.TP +.B \f[C]\-v\f[], \f[C]\-\-version\f[] +Print version. +.RS +.RE +.TP +.B \f[C]\-h\f[], \f[C]\-\-help\f[] +Show usage message. +.RS +.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. +.RS +.RE +.TP +.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]\-\-indented\-code\-classes=\f[]\f[I]CLASSES\f[] +Specify classes to use for indented code blocks\[en]for example, +\f[C]perl,numberLines\f[] or \f[C]haskell\f[]. +Multiple classes may be separated by spaces or commas. +.RS +.RE +.TP +.B \f[C]\-\-default\-image\-extension=\f[]\f[I]EXTENSION\f[] +Specify a default extension to use when image paths/URLs have no +extension. +This allows you to use the same source for formats that require +different kinds of images. +Currently this option only affects the Markdown and LaTeX readers. +.RS +.RE +.TP +.B \f[C]\-\-file\-scope\f[] +Parse each file individually before combining for multifile documents. +This will allow footnotes in different files with the same identifiers +to work as expected. +If this option is set, footnotes and links will not work across files. +Reading binary files (docx, odt, epub) implies \f[C]\-\-file\-scope\f[]. +.RS +.RE +.TP +.B \f[C]\-\-filter=\f[]\f[I]PROGRAM\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 name of the output format will be passed to the filter as the first +argument. +Hence, +.RS +.IP +.nf +\f[C] +pandoc\ \-\-filter\ ./caps.py\ \-t\ latex +\f[] +.fi +.PP +is equivalent to +.IP +.nf +\f[C] +pandoc\ \-t\ json\ |\ ./caps.py\ latex\ |\ pandoc\ \-f\ json\ \-t\ latex +\f[] +.fi +.PP +The latter form may be useful for debugging filters. +.PP +Filters may be written in any language. +\f[C]Text.Pandoc.JSON\f[] exports \f[C]toJSONFilter\f[] to facilitate +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. +.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) +.IP "3." 3 +\f[C]$PATH\f[] (executable only) +.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[]] +Set the metadata field \f[I]KEY\f[] to the value \f[I]VAL\f[]. +A value specified on the command line overrides a value specified in the +document. +Values will be parsed as YAML boolean or string values. +If no value is specified, the value will be treated as Boolean true. +Like \f[C]\-\-variable\f[], \f[C]\-\-metadata\f[] causes template +variables to be set. +But unlike \f[C]\-\-variable\f[], \f[C]\-\-metadata\f[] affects the +metadata of the underlying document (which is accessible from filters +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 +blocks; tabs in regular text will be treated as spaces. +.RS +.RE +.TP +.B \f[C]\-\-tab\-stop=\f[]\f[I]NUMBER\f[] +Specify the number of spaces per tab (default is 4). +.RS +.RE +.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. +\f[C]accept\f[] (the default), inserts all insertions, and ignores all +deletions. +\f[C]reject\f[] inserts all deletions and ignores insertions. +Both \f[C]accept\f[] and \f[C]reject\f[] ignore comments. +\f[C]all\f[] puts in insertions, deletions, and comments, wrapped in +spans with \f[C]insertion\f[], \f[C]deletion\f[], +\f[C]comment\-start\f[], and \f[C]comment\-end\f[] classes, +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. +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. +.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). +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 +.RE +.TP +.B \f[C]\-\-template=\f[]\f[I]FILE\f[] +Use \f[I]FILE\f[] as a custom template for the generated document. +Implies \f[C]\-\-standalone\f[]. +See Templates, below, for a description of template syntax. +If no extension is specified, an extension corresponding to the writer +will be added, so that \f[C]\-\-template=special\f[] looks for +\f[C]special.html\f[] for HTML output. +If the template is not found, pandoc will search for it in the +\f[C]templates\f[] subdirectory of the user data directory (see +\f[C]\-\-data\-dir\f[]). +If this option is not used, a default template appropriate for the +output format will be used (see +\f[C]\-D/\-\-print\-default\-template\f[]). +.RS +.RE +.TP +.B \f[C]\-V\f[] \f[I]KEY\f[][\f[C]=\f[]\f[I]VAL\f[]], \f[C]\-\-variable=\f[]\f[I]KEY\f[][\f[C]:\f[]\f[I]VAL\f[]] +Set the template variable \f[I]KEY\f[] to the value \f[I]VAL\f[] when +rendering the document in standalone mode. +This is generally only useful when the \f[C]\-\-template\f[] option is +used to specify a custom template, since pandoc automatically sets the +variables used in the default templates. +If no \f[I]VAL\f[] is specified, the key will be given the value +\f[C]true\f[]. +.RS +.RE +.TP +.B \f[C]\-D\f[] \f[I]FORMAT\f[], \f[C]\-\-print\-default\-template=\f[]\f[I]FORMAT\f[] +Print the system default template for an output \f[I]FORMAT\f[]. +(See \f[C]\-t\f[] for a list of possible \f[I]FORMAT\f[]s.) Templates in +the user data directory are ignored. +.RS +.RE +.TP +.B \f[C]\-\-print\-default\-data\-file=\f[]\f[I]FILE\f[] +Print a system default data file. +Files in the user data directory are ignored. +.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. +The default is 96dpi. +Technically, the correct term would be ppi (pixels per inch). +.RS +.RE +.TP +.B \f[C]\-\-wrap=auto\f[]|\f[C]none\f[]|\f[C]preserve\f[] +Determine how text is wrapped in the output (the source code, not the +rendered version). +With \f[C]auto\f[] (the default), pandoc will attempt to wrap lines to +the column width specified by \f[C]\-\-columns\f[] (default 72). +With \f[C]none\f[], pandoc will not wrap lines at all. +With \f[C]preserve\f[], pandoc will attempt to preserve the wrapping +from the source document (that is, where there are nonsemantic newlines +in the source, there will be nonsemantic newlines in the output as +well). +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 +\f[C]\-\-wrap\f[]). +It also affects calculation of column widths for plain text tables (see +Tables below). +.RS +.RE +.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. +.RS +.RE +.TP +.B \f[C]\-\-toc\-depth=\f[]\f[I]NUMBER\f[] +Specify the number of section levels to include in the table of +contents. +The default is 3 (which means that level 1, 2, and 3 headers will be +listed in the contents). +.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[] +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[], +\f[C]zenburn\f[], \f[C]haddock\f[], and \f[C]tango\f[]. +For more information on syntax highlighting in pandoc, see Syntax +highlighting, below. +See also \f[C]\-\-list\-highlight\-styles\f[]. +.RS +.RE +.TP +.B \f[C]\-H\f[] \f[I]FILE\f[], \f[C]\-\-include\-in\-header=\f[]\f[I]FILE\f[] +Include contents of \f[I]FILE\f[], verbatim, at the end of the header. +This can be used, for example, to include special CSS or JavaScript in +HTML documents. +This option can be used repeatedly to include multiple files in the +header. +They will be included in the order specified. +Implies \f[C]\-\-standalone\f[]. +.RS +.RE +.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). +This can be used to include navigation bars or banners in HTML +documents. +This option can be used repeatedly to include multiple files. +They will be included in the order specified. +Implies \f[C]\-\-standalone\f[]. +.RS +.RE +.TP +.B \f[C]\-A\f[] \f[I]FILE\f[], \f[C]\-\-include\-after\-body=\f[]\f[I]FILE\f[] +Include contents of \f[I]FILE\f[], verbatim, at the end of the document +body (before the \f[C]</body>\f[] tag in HTML, or the +\f[C]\\end{document}\f[] command in LaTeX). +This option can be used repeatedly to include multiple files. +They will be included in the order specified. +Implies \f[C]\-\-standalone\f[]. +.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. +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]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). +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. +.RS +.RE +.TP +.B \f[C]\-\-html\-q\-tags\f[] +Use \f[C]<q>\f[] tags for quotes in HTML. +.RS +.RE +.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). +.RS +.RE +.TP +.B \f[C]\-\-reference\-links\f[] +Use reference\-style links, rather than inline links, in writing +Markdown or reStructuredText. +By default inline links are used. +The placement of link references is affected by the +\f[C]\-\-reference\-location\f[] option. +.RS +.RE +.TP +.B \f[C]\-\-reference\-location\ =\ block\f[]|\f[C]section\f[]|\f[C]document\f[] +Specify whether footnotes (and references, if \f[C]reference\-links\f[] +is set) are placed at the end of the current (top\-level) block, the +current section, or the document. +The default is \f[C]document\f[]. +Currently only affects the markdown writer. +.RS +.RE +.TP +.B \f[C]\-\-atx\-headers\f[] +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[]. +.RS +.RE +.TP +.B \f[C]\-\-top\-level\-division=[default|section|chapter|part]\f[] +Treat top\-level headers as the given division type in LaTeX, ConTeXt, +DocBook, and TEI output. +The hierarchy order is part, chapter, then section; all headers are +shifted such that the top\-level header becomes the specified type. +The default behavior is to determine the best division type via +heuristics: unless other conditions apply, \f[C]section\f[] is chosen. +When the LaTeX document class is set to \f[C]report\f[], \f[C]book\f[], +or \f[C]memoir\f[] (unless the \f[C]article\f[] option is specified), +\f[C]chapter\f[] is implied as the setting for this option. +If \f[C]beamer\f[] is the output format, specifying either +\f[C]chapter\f[] or \f[C]part\f[] will cause top\-level headers to +become \f[C]\\part{..}\f[], while second\-level headers remain as their +default type. +.RS +.RE +.TP +.B \f[C]\-N\f[], \f[C]\-\-number\-sections\f[] +Number section headings in LaTeX, ConTeXt, HTML, or EPUB output. +By default, sections are not numbered. +Sections with class \f[C]unnumbered\f[] will never be numbered, even if +\f[C]\-\-number\-sections\f[] is specified. +.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[]] +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[]. +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[]. +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 +.RE +.TP +.B \f[C]\-i\f[], \f[C]\-\-incremental\f[] +Make list items in slide shows display incrementally (one by one). +The default is for lists to be displayed all at once. +.RS +.RE +.TP +.B \f[C]\-\-slide\-level=\f[]\f[I]NUMBER\f[] +Specifies that headers with the specified level create slides (for +\f[C]beamer\f[], \f[C]s5\f[], \f[C]slidy\f[], \f[C]slideous\f[], +\f[C]dzslides\f[]). +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. +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. +See Header identifiers, below. +.RS +.RE +.TP +.B \f[C]\-\-email\-obfuscation=none\f[]|\f[C]javascript\f[]|\f[C]references\f[] +Specify a method for obfuscating \f[C]mailto:\f[] links in HTML +documents. +\f[C]none\f[] leaves \f[C]mailto:\f[] links as they are. +\f[C]javascript\f[] obfuscates them using JavaScript. +\f[C]references\f[] obfuscates them by printing their letters as decimal +or hexadecimal character references. +The default is \f[C]none\f[]. +.RS +.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. +This is useful for preventing duplicate identifiers when generating +fragments to be included in other pages. +.RS +.RE +.TP +.B \f[C]\-T\f[] \f[I]STRING\f[], \f[C]\-\-title\-prefix=\f[]\f[I]STRING\f[] +Specify \f[I]STRING\f[] as a prefix at the beginning of the title that +appears in the HTML header (but not in the title as it appears at the +beginning of the HTML body). +Implies \f[C]\-\-standalone\f[]. +.RS +.RE +.TP +.B \f[C]\-c\f[] \f[I]URL\f[], \f[C]\-\-css=\f[]\f[I]URL\f[] +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 +.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. +.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. +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 +document properties (including margins, page size, header, and footer) +are used in the new docx. +If no reference docx is specified on the command line, pandoc will look +for a file \f[C]reference.docx\f[] in the user data directory (see +\f[C]\-\-data\-dir\f[]). +If this is not found either, sensible defaults will be used. +.RS +.PP +To produce a custom \f[C]reference.docx\f[], first get a copy of the +default \f[C]reference.docx\f[]: +\f[C]pandoc\ \-\-print\-default\-data\-file\ reference.docx\ >\ custom\-reference.docx\f[]. +Then open \f[C]custom\-reference.docx\f[] in Word, modify the styles as +you wish, and save the file. +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. +.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 +\f[C]\-\-data\-dir\f[]). +If it is not found there, sensible defaults will be used. +.RS +.RE +.TP +.B \f[C]\-\-epub\-cover\-image=\f[]\f[I]FILE\f[] +Use the specified image as the EPUB cover. +It is recommended that the image be less than 1000px in width and +height. +Note that in a Markdown source document you can also specify +\f[C]cover\-image\f[] in a YAML metadata block (see EPUB Metadata, +below). +.RS +.RE +.TP +.B \f[C]\-\-epub\-metadata=\f[]\f[I]FILE\f[] +Look in the specified XML file for metadata for the EPUB. +The file should contain a series of Dublin Core elements. +For example: +.RS +.IP +.nf +\f[C] +\ <dc:rights>Creative\ Commons</dc:rights> +\ <dc:language>es\-AR</dc:language> +\f[] +.fi +.PP +By default, pandoc will include the following metadata elements: +\f[C]<dc:title>\f[] (from the document title), \f[C]<dc:creator>\f[] +(from the document authors), \f[C]<dc:date>\f[] (from the document date, +which should be in ISO 8601 format), \f[C]<dc:language>\f[] (from the +\f[C]lang\f[] variable, or, if is not set, the locale), and +\f[C]<dc:identifier\ id="BookId">\f[] (a randomly generated UUID). +Any of these may be overridden by elements in the metadata file. +.PP +Note: if the source document is Markdown, a YAML metadata block in the +document can be used instead. +See below under EPUB Metadata. +.RE +.TP +.B \f[C]\-\-epub\-embed\-font=\f[]\f[I]FILE\f[] +Embed the specified font in the EPUB. +This option can be repeated to embed multiple fonts. +Wildcards can also be used: for example, \f[C]DejaVuSans\-*.ttf\f[]. +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[]): +.RS +.IP +.nf +\f[C] +\@font\-face\ { +font\-family:\ DejaVuSans; +font\-style:\ normal; +font\-weight:\ normal; +src:url("DejaVuSans\-Regular.ttf"); +} +\@font\-face\ { +font\-family:\ DejaVuSans; +font\-style:\ normal; +font\-weight:\ bold; +src:url("DejaVuSans\-Bold.ttf"); +} +\@font\-face\ { +font\-family:\ DejaVuSans; +font\-style:\ italic; +font\-weight:\ normal; +src:url("DejaVuSans\-Oblique.ttf"); +} +\@font\-face\ { +font\-family:\ DejaVuSans; +font\-style:\ italic; +font\-weight:\ bold; +src:url("DejaVuSans\-BoldOblique.ttf"); +} +body\ {\ font\-family:\ "DejaVuSans";\ } +\f[] +.fi +.RE +.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. +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. +Some readers may be slow if the chapter files are too large, so for +large documents with few level 1 headers, one might want to use a +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. +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[] +Use the given string as a command\-line argument to the +\f[C]latex\-engine\f[]. +If used multiple times, the arguments are provided with spaces between +them. +Note that no check for duplicate options is done. +.RS +.RE +.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 +\f[I]FILE\f[], overriding any value set in the metadata, and process +citations using \f[C]pandoc\-citeproc\f[]. +(This is equivalent to +\f[C]\-\-metadata\ bibliography=FILE\ \-\-filter\ pandoc\-citeproc\f[].) +If \f[C]\-\-natbib\f[] or \f[C]\-\-biblatex\f[] is also supplied, +\f[C]pandoc\-citeproc\f[] is not used, making this equivalent to +\f[C]\-\-metadata\ bibliography=FILE\f[]. +If you supply this argument multiple times, each \f[I]FILE\f[] will be +added to bibliography. +.RS +.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. +(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 +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 +only relevant with \f[C]pandoc\-citeproc\f[]. +.RS +.RE +.TP +.B \f[C]\-\-natbib\f[] +Use \f[C]natbib\f[] for citations in LaTeX output. +This option is not for use with the \f[C]pandoc\-citeproc\f[] filter or +with PDF output. +It is intended for use in producing a LaTeX file that can be processed +with \f[C]bibtex\f[]. +.RS +.RE +.TP +.B \f[C]\-\-biblatex\f[] +Use \f[C]biblatex\f[] for citations in LaTeX output. +This option is not for use with the \f[C]pandoc\-citeproc\f[] filter or +with PDF output. +It is intended for use in producing a LaTeX file that can be processed +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 +.TP +.B \f[C]\-\-mathjax\f[][\f[C]=\f[]\f[I]URL\f[]] +Use MathJax to display embedded TeX math in HTML output. +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 +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[]. +.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. +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 +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. +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 +.B \f[C]\-\-katex\-stylesheet=\f[]\f[I]URL\f[] +The \f[I]URL\f[] should point to the \f[C]katex.css\f[] stylesheet. +If this option is not specified, a link to the KaTeX CDN will be +inserted. +Note that this option does not imply \f[C]\-\-katex\f[]. +.RS +.RE +.SS Options for wrapper scripts +.TP +.B \f[C]\-\-dump\-args\f[] +Print information about command\-line arguments to \f[I]stdout\f[], then +exit. +This option is intended primarily for use in wrapper scripts. +The first line of output contains the name of the output file specified +with the \f[C]\-o\f[] option, or \f[C]\-\f[] (for \f[I]stdout\f[]) if no +output file was specified. +The remaining lines contain the command\-line arguments, one per line, +in the order they appear. +These do not include regular pandoc options and their arguments, but do +include any options appearing after a \f[C]\-\-\f[] separator at the end +of the line. +.RS +.RE +.TP +.B \f[C]\-\-ignore\-args\f[] +Ignore command\-line arguments (for use in wrapper scripts). +Regular pandoc options are not ignored. +Thus, for example, +.RS +.IP +.nf +\f[C] +pandoc\ \-\-ignore\-args\ \-o\ foo.html\ \-s\ foo.txt\ \-\-\ \-e\ latin1 +\f[] +.fi +.PP +is equivalent to +.IP +.nf +\f[C] +pandoc\ \-o\ foo.html\ \-s +\f[] +.fi +.RE +.SH TEMPLATES +.PP +When the \f[C]\-s/\-\-standalone\f[] option is used, pandoc uses a +template to add header and footer material that is needed for a +self\-standing document. +To see the default template that is used, just type +.IP +.nf +\f[C] +pandoc\ \-D\ *FORMAT* +\f[] +.fi +.PP +where \f[I]FORMAT\f[] is the name of the output format. +A custom template can be specified using the \f[C]\-\-template\f[] +option. +You can also override the system default templates for a given output +format \f[I]FORMAT\f[] by putting a file +\f[C]templates/default.*FORMAT*\f[] in the user data directory (see +\f[C]\-\-data\-dir\f[], above). +\f[I]Exceptions:\f[] +.IP \[bu] 2 +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[]). +.IP \[bu] 2 +\f[C]docx\f[] has no template (however, you can use +\f[C]\-\-reference\-docx\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. +Variables may be set within the document using YAML metadata blocks. +They may also be set at the command line using the +\f[C]\-V/\-\-variable\f[] option: variables set in this way override +metadata fields with the same name. +.SS Variables set by pandoc +.PP +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]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. +These can be set through a pandoc title block, which allows for multiple +authors, or through a YAML metadata block: +.RS +.IP +.nf +\f[C] +\-\-\- +author: +\-\ Aristotle +\-\ Peter\ Abelard +\&... +\f[] +.fi +.RE +.TP +.B \f[C]subtitle\f[] +document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and Word +docx; renders in LaTeX only when using a document class that supports +\f[C]\\subtitle\f[], such as \f[C]beamer\f[] or the KOMA\-Script series +(\f[C]scrartcl\f[], \f[C]scrreprt\f[], \f[C]scrbook\f[]). +.RS +.RE +.TP +.B \f[C]institute\f[] +author affiliations (in LaTeX and Beamer only). +Can be a list, when there are multiple authors. +.RS +.RE +.TP +.B \f[C]abstract\f[] +document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word docx +.RS +.RE +.TP +.B \f[C]keywords\f[] +list of keywords to be included in HTML, PDF, and AsciiDoc metadata; may +be repeated as for \f[C]author\f[], above +.RS +.RE +.TP +.B \f[C]header\-includes\f[] +contents specified by \f[C]\-H/\-\-include\-in\-header\f[] (may have +multiple values) +.RS +.RE +.TP +.B \f[C]toc\f[] +non\-null value if \f[C]\-\-toc/\-\-table\-of\-contents\f[] was +specified +.RS +.RE +.TP +.B \f[C]toc\-title\f[] +title of table of contents (works only with EPUB and docx) +.RS +.RE +.TP +.B \f[C]include\-before\f[] +contents specified by \f[C]\-B/\-\-include\-before\-body\f[] (may have +multiple values) +.RS +.RE +.TP +.B \f[C]include\-after\f[] +contents specified by \f[C]\-A/\-\-include\-after\-body\f[] (may have +multiple values) +.RS +.RE +.TP +.B \f[C]body\f[] +body of document +.RS +.RE +.TP +.B \f[C]meta\-json\f[] +JSON representation of all of the document's metadata +.RS +.RE +.SS Language variables +.TP +.B \f[C]lang\f[] +identifies the main language of the document, using a code according to +BCP 47 (e.g. +\f[C]en\f[] or \f[C]en\-GB\f[]). +For some output formats, pandoc will convert it to an appropriate format +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 +.RE +.TP +.B \f[C]dir\f[] +the base direction of the document, either \f[C]rtl\f[] +(right\-to\-left) or \f[C]ltr\f[] (left\-to\-right). +.RS +.PP +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 +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[]). +.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]slidy\-url\f[] +base URL for Slidy documents (defaults to +\f[C]http://www.w3.org/Talks/Tools/Slidy2\f[]) +.RS +.RE +.TP +.B \f[C]slideous\-url\f[] +base URL for Slideous documents (defaults to \f[C]slideous\f[]) +.RS +.RE +.TP +.B \f[C]s5\-url\f[] +base URL for S5 documents (defaults to \f[C]s5/default\f[]) +.RS +.RE +.TP +.B \f[C]revealjs\-url\f[] +base URL for reveal.js documents (defaults to \f[C]reveal.js\f[]) +.RS +.RE +.TP +.B \f[C]theme\f[], \f[C]colortheme\f[], \f[C]fonttheme\f[], \f[C]innertheme\f[], \f[C]outertheme\f[] +themes for LaTeX \f[C]beamer\f[] documents +.RS +.RE +.TP +.B \f[C]themeoptions\f[] +options for LaTeX beamer themes (a list). +.RS +.RE +.TP +.B \f[C]navigation\f[] +controls navigation symbols in \f[C]beamer\f[] documents (default is +\f[C]empty\f[] for no navigation symbols; other valid values are +\f[C]frame\f[], \f[C]vertical\f[], and \f[C]horizontal\f[]). +.RS +.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). +.RS +.RE +.TP +.B \f[C]beamerarticle\f[] +when true, the \f[C]beamerarticle\f[] package is loaded (for producing +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). +.RS +.RE +.SS Variables for LaTeX +.PP +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[] +.RS +.RE +.TP +.B \f[C]fontsize\f[] +font size for body text (e.g. +\f[C]10pt\f[], \f[C]12pt\f[]) +.RS +.RE +.TP +.B \f[C]documentclass\f[] +document class, e.g. +\f[C]article\f[], \f[C]report\f[], \f[C]book\f[], \f[C]memoir\f[] +.RS +.RE +.TP +.B \f[C]classoption\f[] +option for document class, e.g. +\f[C]oneside\f[]; may be repeated for multiple options +.RS +.RE +.TP +.B \f[C]geometry\f[] +option for \f[C]geometry\f[] package, e.g. +\f[C]margin=1in\f[]; may be repeated for multiple options +.RS +.RE +.TP +.B \f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[], \f[C]margin\-bottom\f[] +sets margins, if \f[C]geometry\f[] is not used (otherwise +\f[C]geometry\f[] overrides these) +.RS +.RE +.TP +.B \f[C]linestretch\f[] +adjusts line spacing using the \f[C]setspace\f[] package, e.g. +\f[C]1.25\f[], \f[C]1.5\f[] +.RS +.RE +.TP +.B \f[C]fontfamily\f[] +font package for use with \f[C]pdflatex\f[]: TeX Live includes many +options, documented in the LaTeX Font Catalogue. +The default is Latin Modern. +.RS +.RE +.TP +.B \f[C]fontfamilyoptions\f[] +options for package used as \f[C]fontfamily\f[]: e.g. +\f[C]osf,sc\f[] with \f[C]fontfamily\f[] set to \f[C]mathpazo\f[] +provides Palatino with old\-style figures and true small caps; may be +repeated for multiple options +.RS +.RE +.TP +.B \f[C]mainfont\f[], \f[C]sansfont\f[], \f[C]monofont\f[], \f[C]mathfont\f[], \f[C]CJKmainfont\f[] +font families for use with \f[C]xelatex\f[] or \f[C]lualatex\f[]: take +the name of any system font, using the \f[C]fontspec\f[] package. +Note that if \f[C]CJKmainfont\f[] is used, the \f[C]xecjk\f[] package +must be available. +.RS +.RE +.TP +.B \f[C]mainfontoptions\f[], \f[C]sansfontoptions\f[], \f[C]monofontoptions\f[], \f[C]mathfontoptions\f[], \f[C]CJKoptions\f[] +options to use with \f[C]mainfont\f[], \f[C]sansfont\f[], +\f[C]monofont\f[], \f[C]mathfont\f[], \f[C]CJKmainfont\f[] in +\f[C]xelatex\f[] and \f[C]lualatex\f[]. +Allow for any choices available through \f[C]fontspec\f[], such as the +OpenType features \f[C]Numbers=OldStyle,Numbers=Proportional\f[]. +May be repeated for multiple options. +.RS +.RE +.TP +.B \f[C]fontenc\f[] +allows font encoding to be specified through \f[C]fontenc\f[] package +(with \f[C]pdflatex\f[]); default is \f[C]T1\f[] (see guide to LaTeX +font encodings) +.RS +.RE +.TP +.B \f[C]microtypeoptions\f[] +options to pass to the microtype package +.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 +.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 +.RS +.RE +.TP +.B \f[C]links\-as\-notes\f[] +causes links to be printed as footnotes +.RS +.RE +.TP +.B \f[C]indent\f[] +uses document class settings for indentation (the default LaTeX template +otherwise removes indentation and adds space between paragraphs) +.RS +.RE +.TP +.B \f[C]subparagraph\f[] +disables default behavior of LaTeX template that redefines +(sub)paragraphs as sections, changing the appearance of nested headings +in some classes +.RS +.RE +.TP +.B \f[C]thanks\f[] +specifies contents of acknowledgments footnote after document title. +.RS +.RE +.TP +.B \f[C]toc\f[] +include table of contents (can also be set using +\f[C]\-\-toc/\-\-table\-of\-contents\f[]) +.RS +.RE +.TP +.B \f[C]toc\-depth\f[] +level of section to include in table of contents +.RS +.RE +.TP +.B \f[C]secnumdepth\f[] +numbering depth for sections, if sections are numbered +.RS +.RE +.TP +.B \f[C]lof\f[], \f[C]lot\f[] +include list of figures, list of tables +.RS +.RE +.TP +.B \f[C]bibliography\f[] +bibliography to use for resolving references +.RS +.RE +.TP +.B \f[C]biblio\-style\f[] +bibliography style, when used with \f[C]\-\-natbib\f[] and +\f[C]\-\-biblatex\f[]. +.RS +.RE +.TP +.B \f[C]biblio\-title\f[] +bibliography title, when used with \f[C]\-\-natbib\f[] and +\f[C]\-\-biblatex\f[]. +.RS +.RE +.TP +.B \f[C]biblatexoptions\f[] +list of options for biblatex. +.RS +.RE +.SS Variables for ConTeXt +.TP +.B \f[C]papersize\f[] +paper size, e.g. +\f[C]letter\f[], \f[C]A4\f[], \f[C]landscape\f[] (see ConTeXt Paper +Setup); may be repeated for multiple options +.RS +.RE +.TP +.B \f[C]layout\f[] +options for page margins and text arrangement (see ConTeXt Layout); may +be repeated for multiple options +.RS +.RE +.TP +.B \f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[], \f[C]margin\-bottom\f[] +sets margins, if \f[C]layout\f[] is not used (otherwise \f[C]layout\f[] +overrides these) +.RS +.RE +.TP +.B \f[C]fontsize\f[] +font size for body text (e.g. +\f[C]10pt\f[], \f[C]12pt\f[]) +.RS +.RE +.TP +.B \f[C]mainfont\f[], \f[C]sansfont\f[], \f[C]monofont\f[], \f[C]mathfont\f[] +font families: take the name of any system font (see ConTeXt Font +Switching) +.RS +.RE +.TP +.B \f[C]linkcolor\f[], \f[C]contrastcolor\f[] +color for links outside and inside a page, e.g. +\f[C]red\f[], \f[C]blue\f[] (see ConTeXt Color) +.RS +.RE +.TP +.B \f[C]linkstyle\f[] +typeface style for links, e.g. +\f[C]normal\f[], \f[C]bold\f[], \f[C]slanted\f[], \f[C]boldslanted\f[], +\f[C]type\f[], \f[C]cap\f[], \f[C]small\f[] +.RS +.RE +.TP +.B \f[C]indenting\f[] +controls indentation of paragraphs, e.g. +\f[C]yes,small,next\f[] (see ConTeXt Indentation); may be repeated for +multiple options +.RS +.RE +.TP +.B \f[C]whitespace\f[] +spacing between paragraphs, e.g. +\f[C]none\f[], \f[C]small\f[] (using \f[C]setupwhitespace\f[]) +.RS +.RE +.TP +.B \f[C]interlinespace\f[] +adjusts line spacing, e.g. +\f[C]4ex\f[] (using \f[C]setupinterlinespace\f[]); may be repeated for +multiple options +.RS +.RE +.TP +.B \f[C]headertext\f[], \f[C]footertext\f[] +text to be placed in running header or footer (see ConTeXt Headers and +Footers); may be repeated up to four times for different placement +.RS +.RE +.TP +.B \f[C]pagenumbering\f[] +page number style and location (using \f[C]setuppagenumbering\f[]); may +be repeated for multiple options +.RS +.RE +.TP +.B \f[C]toc\f[] +include table of contents (can also be set using +\f[C]\-\-toc/\-\-table\-of\-contents\f[]) +.RS +.RE +.TP +.B \f[C]lof\f[], \f[C]lot\f[] +include list of figures, list of tables +.RS +.RE +.SS Variables for man pages +.TP +.B \f[C]section\f[] +section number in man pages +.RS +.RE +.TP +.B \f[C]header\f[] +header in man pages +.RS +.RE +.TP +.B \f[C]footer\f[] +footer in man pages +.RS +.RE +.TP +.B \f[C]adjusting\f[] +adjusts text to left (\f[C]l\f[]), right (\f[C]r\f[]), center +(\f[C]c\f[]), or both (\f[C]b\f[]) margins +.RS +.RE +.TP +.B \f[C]hyphenate\f[] +if \f[C]true\f[] (the default), hyphenation will be used +.RS +.RE +.SS Using variables in templates +.PP +Variable names are sequences of alphanumerics, \f[C]\-\f[], and +\f[C]_\f[], starting with a letter. +A variable name surrounded by \f[C]$\f[] signs will be replaced by its +value. +For example, the string \f[C]$title$\f[] in +.IP +.nf +\f[C] +<title>$title$</title> +\f[] +.fi +.PP +will be replaced by the document title. +.PP +To write a literal \f[C]$\f[] in a template, use \f[C]$$\f[]. +.PP +Templates may contain conditionals. +The syntax is as follows: +.IP +.nf +\f[C] +$if(variable)$ +X +$else$ +Y +$endif$ +\f[] +.fi +.PP +This will include \f[C]X\f[] in the template if \f[C]variable\f[] has a +non\-null value; otherwise it will include \f[C]Y\f[]. +\f[C]X\f[] and \f[C]Y\f[] are placeholders for any valid template text, +and may include interpolated variables or other conditionals. +The \f[C]$else$\f[] section may be omitted. +.PP +When variables can have multiple values (for example, \f[C]author\f[] in +a multi\-author document), you can use the \f[C]$for$\f[] keyword: +.IP +.nf +\f[C] +$for(author)$ +<meta\ name="author"\ content="$author$"\ /> +$endfor$ +\f[] +.fi +.PP +You can optionally specify a separator to be used between consecutive +items: +.IP +.nf +\f[C] +$for(author)$$author$$sep$,\ $endfor$ +\f[] +.fi +.PP +A dot can be used to select a field of a variable that takes an object +as its value. +So, for example: +.IP +.nf +\f[C] +$author.name$\ ($author.affiliation$) +\f[] +.fi +.PP +If you use custom templates, you may need to revise them as pandoc +changes. +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 +Pandoc understands an extended and slightly revised version of John +Gruber'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. +.SS Philosophy +.PP +Markdown is designed to be easy to write, and, even more importantly, +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 +.RE +.PP +This principle has guided pandoc'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. +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, +and provides other, non\-HTMLish ways of representing important document +elements like definition lists, tables, mathematics, and footnotes. +.SS Paragraphs +.PP +A paragraph is one or more lines of text followed by one or more blank +lines. +Newlines are treated as spaces, so you can reflow your paragraphs as you +like. +If you need a hard line break, put two or more spaces at the end of a +line. +.SS Extension: \f[C]escaped_line_breaks\f[] +.PP +A backslash followed by a newline is also a hard line break. +Note: in multiline and grid table cells, this is the only way to create +a hard line break, since trailing spaces in the cells are ignored. +.SS Headers +.PP +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 +level two header): +.IP +.nf +\f[C] +A\ level\-one\ header +================== + +A\ level\-two\ header +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\f[] +.fi +.PP +The header text can contain inline formatting, such as emphasis (see +Inline formatting, below). +.SS ATX\-style headers +.PP +An ATX\-style header consists of one to six \f[C]#\f[] signs and a line +of text, optionally followed by any number of \f[C]#\f[] signs. +The number of \f[C]#\f[] signs at the beginning of the line is the +header level: +.IP +.nf +\f[C] +##\ A\ level\-two\ header + +###\ A\ level\-three\ header\ ### +\f[] +.fi +.PP +As with setext\-style headers, the header text can contain formatting: +.IP +.nf +\f[C] +#\ A\ level\-one\ header\ with\ a\ [link](/url)\ and\ *emphasis* +\f[] +.fi +.SS Extension: \f[C]blank_before_header\f[] +.PP +Standard Markdown syntax does not require a blank line before a header. +Pandoc does require this (except, of course, at the beginning of the +document). +The reason for the requirement is that it is all too easy for a +\f[C]#\f[] to end up at the beginning of a line by accident (perhaps +through line wrapping). +Consider, for example: +.IP +.nf +\f[C] +I\ like\ several\ of\ their\ flavors\ of\ ice\ cream: +#22,\ for\ example,\ and\ #5. +\f[] +.fi +.SS Header identifiers +.SS Extension: \f[C]header_attributes\f[] +.PP +Headers can be assigned attributes using this syntax at the end of the +line containing the header text: +.IP +.nf +\f[C] +{#identifier\ .class\ .class\ key=value\ key=value} +\f[] +.fi +.PP +Thus, for example, the following headers will all be assigned the +identifier \f[C]foo\f[]: +.IP +.nf +\f[C] +#\ My\ header\ {#foo} + +##\ My\ header\ ##\ \ \ \ {#foo} + +My\ other\ header\ \ \ {#foo} +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\f[] +.fi +.PP +(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 +information. +Identifiers, classes, and key/value attributes are used in HTML and +HTML\-based formats such as EPUB and slidy. +Identifiers are used for labels and link anchors in the LaTeX, ConTeXt, +Textile, and AsciiDoc writers. +.PP +Headers with the class \f[C]unnumbered\f[] will not be numbered, even if +\f[C]\-\-number\-sections\f[] is specified. +A single hyphen (\f[C]\-\f[]) in an attribute context is equivalent to +\f[C]\&.unnumbered\f[], and preferable in non\-English documents. +So, +.IP +.nf +\f[C] +#\ My\ header\ {\-} +\f[] +.fi +.PP +is just the same as +.IP +.nf +\f[C] +#\ 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. +So, to link to a header +.IP +.nf +\f[C] +#\ Header\ identifiers\ in\ HTML +\f[] +.fi +.PP +you can simply write +.IP +.nf +\f[C] +[Header\ identifiers\ in\ HTML] +\f[] +.fi +.PP +or +.IP +.nf +\f[C] +[Header\ identifiers\ in\ HTML][] +\f[] +.fi +.PP +or +.IP +.nf +\f[C] +[the\ section\ on\ header\ identifiers][header\ identifiers\ in +HTML] +\f[] +.fi +.PP +instead of giving the identifier explicitly: +.IP +.nf +\f[C] +[Header\ identifiers\ in\ HTML](#header\-identifiers\-in\-html) +\f[] +.fi +.PP +If there are multiple headers with identical text, the corresponding +reference will link to the first one only, and you will need to use +explicit links to link to the others, as described above. +.PP +Like regular reference links, these references are case\-insensitive. +.PP +Explicit link reference definitions always take priority over implicit +header references. +So, in the following example, the link will point to \f[C]bar\f[], not +to \f[C]#foo\f[]: +.IP +.nf +\f[C] +#\ Foo + +[foo]:\ bar + +See\ [foo] +\f[] +.fi +.SS Block quotations +.PP +Markdown uses email conventions for quoting blocks of text. +A block quotation is one or more paragraphs or other block elements +(such as lists or headers), with each line preceded by a \f[C]>\f[] +character and an optional space. +(The \f[C]>\f[] need not start at the left margin, but it should not be +indented more than three spaces.) +.IP +.nf +\f[C] +>\ This\ is\ a\ block\ quote.\ This +>\ paragraph\ has\ two\ lines. +> +>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote. +>\ 2.\ Second\ item. +\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: +.IP +.nf +\f[C] +>\ This\ is\ a\ block\ quote.\ This +paragraph\ has\ two\ lines. + +>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote. +2.\ Second\ item. +\f[] +.fi +.PP +Among the block elements that can be contained in a block quote are +other block quotes. +That is, block quotes can be nested: +.IP +.nf +\f[C] +>\ This\ is\ a\ block\ quote. +> +>\ >\ A\ block\ quote\ within\ a\ block\ quote. +\f[] +.fi +.PP +If the \f[C]>\f[] character is followed by an optional space, that space +will be considered part of the block quote marker and not part of the +indentation of the contents. +Thus, to put an indented code block in a block quote, you need five +spaces after the \f[C]>\f[]: +.IP +.nf +\f[C] +>\ \ \ \ \ code +\f[] +.fi +.SS Extension: \f[C]blank_before_blockquote\f[] +.PP +Standard Markdown syntax does not require a blank line before a block +quote. +Pandoc does require this (except, of course, at the beginning of the +document). +The reason for the requirement is that it is all too easy for a +\f[C]>\f[] to end up at the beginning of a line by accident (perhaps +through line wrapping). +So, unless the \f[C]markdown_strict\f[] format is used, the following +does not produce a nested block quote in pandoc: +.IP +.nf +\f[C] +>\ This\ is\ a\ block\ quote. +>>\ Nested. +\f[] +.fi +.SS Verbatim (code) blocks +.SS Indented code blocks +.PP +A block of text indented four spaces (or one tab) is treated as verbatim +text: that is, special characters do not trigger special formatting, and +all spaces and line breaks are preserved. +For example, +.IP +.nf +\f[C] +\ \ \ \ if\ (a\ >\ 3)\ { +\ \ \ \ \ \ moveShip(5\ *\ gravity,\ DOWN); +\ \ \ \ } +\f[] +.fi +.PP +The initial (four space or one tab) indentation is not considered part +of the verbatim text, and is removed in the output. +.PP +Note: blank lines in the verbatim text need not begin with four spaces. +.SS Fenced code blocks +.SS Extension: \f[C]fenced_code_blocks\f[] +.PP +In addition to standard indented code blocks, pandoc supports +\f[I]fenced\f[] code blocks. +These begin with a row of three or more tildes (\f[C]~\f[]) and end with +a row of tildes that must be at least as long as the starting row. +Everything between these lines is treated as code. +No indentation is necessary: +.IP +.nf +\f[C] +~~~~~~~ +if\ (a\ >\ 3)\ { +\ \ moveShip(5\ *\ gravity,\ DOWN); +} +~~~~~~~ +\f[] +.fi +.PP +Like regular code blocks, fenced code blocks must be separated from +surrounding text by blank lines. +.PP +If the code itself contains a row of tildes or backticks, just use a +longer row of tildes or backticks at the start and end: +.IP +.nf +\f[C] +~~~~~~~~~~~~~~~~ +~~~~~~~~~~ +code\ including\ tildes +~~~~~~~~~~ +~~~~~~~~~~~~~~~~ +\f[] +.fi +.SS Extension: \f[C]backtick_code_blocks\f[] +.PP +Same as \f[C]fenced_code_blocks\f[], but uses backticks (\f[C]`\f[]) +instead of tildes (\f[C]~\f[]). +.SS Extension: \f[C]fenced_code_attributes\f[] +.PP +Optionally, you may attach attributes to fenced or backtick code block +using this syntax: +.IP +.nf +\f[C] +~~~~\ {#mycode\ .haskell\ .numberLines\ startFrom="100"} +qsort\ []\ \ \ \ \ =\ [] +qsort\ (x:xs)\ =\ qsort\ (filter\ (<\ x)\ xs)\ ++\ [x]\ ++ +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ qsort\ (filter\ (>=\ x)\ xs) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +\f[] +.fi +.PP +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. +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 +\f[C]pandoc\ \-\-list\-highlight\-languages\f[].) Otherwise, the code +block above will appear as follows: +.IP +.nf +\f[C] +<pre\ id="mycode"\ class="haskell\ numberLines"\ startFrom="100"> +\ \ <code> +\ \ ... +\ \ </code> +</pre> +\f[] +.fi +.PP +A shortcut form can also be used for specifying the language of the code +block: +.IP +.nf +\f[C] +```haskell +qsort\ []\ =\ [] +``` +\f[] +.fi +.PP +This is equivalent to: +.IP +.nf +\f[C] +```\ {.haskell} +qsort\ []\ =\ [] +``` +\f[] +.fi +.PP +If the \f[C]fenced_code_attributes\f[] extension is disabled, but input +contains class attribute(s) for the code block, the first class +attribute will be printed after the opening fence as a bare word. +.PP +To prevent all highlighting, use the \f[C]\-\-no\-highlight\f[] flag. +To set the highlighting style, use \f[C]\-\-highlight\-style\f[]. +For more information on highlighting, see Syntax highlighting, below. +.SS Line blocks +.SS Extension: \f[C]line_blocks\f[] +.PP +A line block is a sequence of lines beginning with a vertical bar +(\f[C]|\f[]) followed by a space. +The division into lines will be preserved in the output, as will any +leading spaces; otherwise, the lines will be formatted as Markdown. +This is useful for verse and addresses: +.IP +.nf +\f[C] +|\ The\ limerick\ packs\ laughs\ anatomical +|\ In\ space\ that\ is\ quite\ economical. +|\ \ \ \ But\ the\ good\ ones\ I\[aq]ve\ seen +|\ \ \ \ So\ seldom\ are\ clean +|\ And\ the\ clean\ ones\ so\ seldom\ are\ comical + +|\ 200\ Main\ St. +|\ Berkeley,\ CA\ 94718 +\f[] +.fi +.PP +The lines can be hard\-wrapped if needed, but the continuation line must +begin with a space. +.IP +.nf +\f[C] +|\ The\ Right\ Honorable\ Most\ Venerable\ and\ Righteous\ Samuel\ L. +\ \ Constable,\ Jr. +|\ 200\ Main\ St. +|\ Berkeley,\ CA\ 94718 +\f[] +.fi +.PP +This syntax is borrowed from reStructuredText. +.SS Lists +.SS Bullet lists +.PP +A bullet list is a list of bulleted list items. +A bulleted list item begins with a bullet (\f[C]*\f[], \f[C]+\f[], or +\f[C]\-\f[]). +Here is a simple example: +.IP +.nf +\f[C] +*\ one +*\ two +*\ three +\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 +paragraph, put spaces between the items: +.IP +.nf +\f[C] +*\ one + +*\ two + +*\ three +\f[] +.fi +.PP +The bullets need not be flush with the left margin; they may be indented +one, two, or three spaces. +The bullet must be followed by whitespace. +.PP +List items look best if subsequent lines are flush with the first line +(after the bullet): +.IP +.nf +\f[C] +*\ here\ is\ my\ first +\ \ list\ item. +*\ and\ my\ second. +\f[] +.fi +.PP +But Markdown also allows a \[lq]lazy\[rq] format: +.IP +.nf +\f[C] +*\ here\ is\ my\ first +list\ item. +*\ and\ my\ second. +\f[] +.fi +.SS The four\-space rule +.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: +.IP +.nf +\f[C] +\ \ *\ First\ paragraph. + +\ \ \ \ Continued. + +\ \ *\ Second\ paragraph.\ With\ a\ code\ block,\ which\ must\ be\ indented +\ \ \ \ eight\ spaces: + +\ \ \ \ \ \ \ \ {\ code\ } +\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: +.IP +.nf +\f[C] +*\ fruits +\ \ \ \ +\ apples +\ \ \ \ \ \ \ \ \-\ macintosh +\ \ \ \ \ \ \ \ \-\ red\ delicious +\ \ \ \ +\ pears +\ \ \ \ +\ peaches +*\ vegetables +\ \ \ \ +\ broccoli +\ \ \ \ +\ chard +\f[] +.fi +.PP +As noted above, Markdown allows you to write list items +\[lq]lazily,\[rq] 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 +.nf +\f[C] ++\ A\ lazy,\ lazy,\ list +item. + ++\ Another\ one;\ this\ looks +bad\ but\ is\ legal. + +\ \ \ \ Second\ paragraph\ of\ second +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 +with enumerators rather than bullets. +.PP +In standard Markdown, enumerators are decimal numbers followed by a +period and a space. +The numbers themselves are ignored, so there is no difference between +this list: +.IP +.nf +\f[C] +1.\ \ one +2.\ \ two +3.\ \ three +\f[] +.fi +.PP +and this one: +.IP +.nf +\f[C] +5.\ \ one +7.\ \ two +1.\ \ three +\f[] +.fi +.SS Extension: \f[C]fancy_lists\f[] +.PP +Unlike standard Markdown, pandoc allows ordered list items to be marked +with uppercase and lowercase letters and roman numerals, in addition to +Arabic numerals. +List markers may be enclosed in parentheses or followed by a single +right\-parentheses or period. +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: +.IP +.nf +\f[C] +#.\ one +#.\ two +\f[] +.fi +.SS Extension: \f[C]startnum\f[] +.PP +Pandoc also pays attention to the type of list marker used, and to the +starting number, and both of these are preserved where possible in the +output format. +Thus, the following yields a list with numbers followed by a single +parenthesis, starting with 9, and a sublist with lowercase roman +numerals: +.IP +.nf +\f[C] +\ 9)\ \ Ninth +10)\ \ Tenth +11)\ \ Eleventh +\ \ \ \ \ \ \ i.\ subone +\ \ \ \ \ \ ii.\ subtwo +\ \ \ \ \ iii.\ subthree +\f[] +.fi +.PP +Pandoc will start a new list each time a different type of list marker +is used. +So, the following will create three lists: +.IP +.nf +\f[C] +(2)\ Two +(5)\ Three +1.\ \ Four +*\ \ \ Five +\f[] +.fi +.PP +If default list markers are desired, use \f[C]#.\f[]: +.IP +.nf +\f[C] +#.\ \ one +#.\ \ two +#.\ \ three +\f[] +.fi +.SS Definition lists +.SS Extension: \f[C]definition_lists\f[] +.PP +Pandoc supports definition lists, using the syntax of PHP Markdown Extra +with some extensions. +.IP +.nf +\f[C] +Term\ 1 + +:\ \ \ Definition\ 1 + +Term\ 2\ with\ *inline\ markup* + +:\ \ \ Definition\ 2 + +\ \ \ \ \ \ \ \ {\ some\ code,\ part\ of\ Definition\ 2\ } + +\ \ \ \ Third\ paragraph\ of\ definition\ 2. +\f[] +.fi +.PP +Each term must fit on one line, which may optionally be followed by a +blank line, and must be followed by one or more definitions. +A definition begins with a colon or tilde, which may be indented one or +two spaces. +.PP +A term may have multiple definitions, and each definition may consist of +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: +.IP +.nf +\f[C] +Term\ 1 + +:\ \ \ Definition +with\ lazy\ continuation. + +\ \ \ \ Second\ paragraph\ of\ the\ definition. +\f[] +.fi +.PP +If you leave space before the definition (as in the example above), the +text of the definition will be treated as a paragraph. +In some output formats, this will mean greater spacing between +term/definition pairs. +For a more compact definition list, omit the space before the +definition: +.IP +.nf +\f[C] +Term\ 1 +\ \ ~\ Definition\ 1 + +Term\ 2 +\ \ ~\ Definition\ 2a +\ \ ~\ Definition\ 2b +\f[] +.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.) +.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 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: +.IP +.nf +\f[C] +(\@)\ \ My\ first\ example\ will\ be\ numbered\ (1). +(\@)\ \ My\ second\ example\ will\ be\ numbered\ (2). + +Explanation\ of\ examples. + +(\@)\ \ My\ third\ example\ will\ be\ numbered\ (3). +\f[] +.fi +.PP +Numbered examples can be labeled and referred to elsewhere in the +document: +.IP +.nf +\f[C] +(\@good)\ \ This\ is\ a\ good\ example. + +As\ (\@good)\ illustrates,\ ... +\f[] +.fi +.PP +The label can be any string of alphanumeric characters, underscores, or +hyphens. +.SS Compact and loose lists +.PP +Pandoc behaves differently from \f[C]Markdown.pl\f[] on some \[lq]edge +cases\[rq] involving lists. +Consider this source: +.IP +.nf +\f[C] ++\ \ \ First ++\ \ \ Second: +\ \ \ \ \-\ \ \ Fee +\ \ \ \ \-\ \ \ Fie +\ \ \ \ \-\ \ \ Foe + ++\ \ \ Third +\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 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. +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. +This behavior is consistent with the official Markdown syntax +description, even though it is different from that of +\f[C]Markdown.pl\f[].) +.SS Ending a list +.PP +What if you want to put an indented code block after a list? +.IP +.nf +\f[C] +\-\ \ \ item\ one +\-\ \ \ item\ two + +\ \ \ \ {\ my\ code\ block\ } +\f[] +.fi +.PP +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: +.IP +.nf +\f[C] +\-\ \ \ item\ one +\-\ \ \ item\ two + +<!\-\-\ end\ of\ list\ \-\-> + +\ \ \ \ {\ my\ code\ block\ } +\f[] +.fi +.PP +You can use the same trick if you want two consecutive lists instead of +one big list: +.IP +.nf +\f[C] +1.\ \ one +2.\ \ two +3.\ \ three + +<!\-\-\ \-\-> + +1.\ \ uno +2.\ \ dos +3.\ \ tres +\f[] +.fi +.SS Horizontal rules +.PP +A line containing a row of three or more \f[C]*\f[], \f[C]\-\f[], or +\f[C]_\f[] characters (optionally separated by spaces) produces a +horizontal rule: +.IP +.nf +\f[C] +*\ \ *\ \ *\ \ * + +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\f[] +.fi +.SS Tables +.PP +Four kinds of tables may be used. +The first three kinds presuppose the use of a fixed\-width font, such as +Courier. +The fourth kind can be used with proportionally spaced fonts, as it does +not require lining up columns. +.SS Extension: \f[C]table_captions\f[] +.PP +A caption may optionally be provided with all 4 kinds of tables (as +illustrated in the examples below). +A caption is a paragraph beginning with the string \f[C]Table:\f[] (or +just \f[C]:\f[]), which will be stripped off. +It may appear either before or after the table. +.SS Extension: \f[C]simple_tables\f[] +.PP +Simple tables look like this: +.IP +.nf +\f[C] +\ \ Right\ \ \ \ \ Left\ \ \ \ \ Center\ \ \ \ \ Default +\-\-\-\-\-\-\-\ \ \ \ \ \-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\ \ \ \-\-\-\-\-\-\- +\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ 12 +\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ 123 +\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ 1 + +Table:\ \ Demonstration\ of\ simple\ table\ syntax. +\f[] +.fi +.PP +The headers and table rows must each fit on one line. +Column alignments are determined by the position of the header text +relative to the dashed line below it: +.IP \[bu] 2 +If the dashed line is flush with the header text on the right side but +extends beyond it on the left, the column is right\-aligned. +.IP \[bu] 2 +If the dashed line is flush with the header text on the left side but +extends beyond it on the right, the column is left\-aligned. +.IP \[bu] 2 +If the dashed line extends beyond the header text on both sides, the +column is centered. +.IP \[bu] 2 +If the dashed line is flush with the header text on both sides, the +default alignment is used (in most cases, this will be left). +.PP +The table must end with a blank line, or a line of dashes followed by a +blank line. +.PP +The column headers may be omitted, provided a dashed line is used to end +the table. +For example: +.IP +.nf +\f[C] +\-\-\-\-\-\-\-\ \ \ \ \ \-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\ \ \ \-\-\-\-\-\-\- +\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ \ 12 +\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ \ 123 +\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ \ 1 +\-\-\-\-\-\-\-\ \ \ \ \ \-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\ \ \ \-\-\-\-\-\-\- +\f[] +.fi +.PP +When headers are omitted, column alignments are determined on the basis +of the first line of the table body. +So, in the tables above, the columns would be right, left, center, and +right aligned, respectively. +.SS Extension: \f[C]multiline_tables\f[] +.PP +Multiline tables allow headers and table rows to span multiple lines of +text (but cells that span multiple columns or rows of the table are not +supported). +Here is an example: +.IP +.nf +\f[C] +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ Centered\ \ \ Default\ \ \ \ \ \ \ \ \ \ \ Right\ Left +\ \ Header\ \ \ \ Aligned\ \ \ \ \ \ \ \ \ Aligned\ Aligned +\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines. + +\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows. +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + +Table:\ Here\[aq]s\ the\ caption.\ It,\ too,\ may\ span +multiple\ lines. +\f[] +.fi +.PP +These work like simple tables, but with the following differences: +.IP \[bu] 2 +They must begin with a row of dashes, before the header text (unless the +headers are omitted). +.IP \[bu] 2 +They must end with a row of dashes, then a blank line. +.IP \[bu] 2 +The rows must be separated by blank lines. +.PP +In multiline tables, the table parser pays attention to the widths of +the columns, and the writers try to reproduce these relative widths in +the output. +So, if you find that one of the columns is too narrow in the output, try +widening it in the Markdown source. +.PP +Headers may be omitted in multiline tables as well as simple tables: +.IP +.nf +\f[C] +\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines. + +\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows. +\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + +:\ Here\[aq]s\ a\ multiline\ table\ without\ headers. +\f[] +.fi +.PP +It is possible for a multiline table to have just one row, but the row +should be followed by a blank line (and then the row of dashes that ends +the table), or the table may be interpreted as a simple table. +.SS Extension: \f[C]grid_tables\f[] +.PP +Grid tables look like this: +.IP +.nf +\f[C] +:\ Sample\ grid\ table. + ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +|\ Fruit\ \ \ \ \ \ \ \ \ |\ Price\ \ \ \ \ \ \ \ \ |\ Advantages\ \ \ \ \ \ \ \ \ | ++===============+===============+====================+ +|\ Bananas\ \ \ \ \ \ \ |\ $1.34\ \ \ \ \ \ \ \ \ |\ \-\ built\-in\ wrapper\ | +|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \-\ bright\ color\ \ \ \ \ | ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +|\ Oranges\ \ \ \ \ \ \ |\ $2.10\ \ \ \ \ \ \ \ \ |\ \-\ cures\ scurvy\ \ \ \ \ | +|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \-\ tasty\ \ \ \ \ \ \ \ \ \ \ \ | ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\f[] +.fi +.PP +The row of \f[C]=\f[]s separates the header from the table body, and can +be omitted for a headerless table. +The cells of grid tables may contain arbitrary block elements (multiple +paragraphs, code blocks, lists, etc.). +Cells that span multiple columns or rows are not supported. +Grid tables can be created easily using Emacs table mode. +.PP +Alignments can be specified as with pipe tables, by putting colons at +the boundaries of the separator line after the header: +.IP +.nf +\f[C] ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +|\ Right\ \ \ \ \ \ \ \ \ |\ Left\ \ \ \ \ \ \ \ \ \ |\ Centered\ \ \ \ \ \ \ \ \ \ \ | ++==============:+:==============+:==================:+ +|\ Bananas\ \ \ \ \ \ \ |\ $1.34\ \ \ \ \ \ \ \ \ |\ built\-in\ wrapper\ \ \ | ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\f[] +.fi +.PP +For headerless tables, the colons go on the top line instead: +.IP +.nf +\f[C] ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-:+:\-\-\-\-\-\-\-\-\-\-\-\-\-\-+:\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-:+ +|\ Right\ \ \ \ \ \ \ \ \ |\ Left\ \ \ \ \ \ \ \ \ \ |\ Centered\ \ \ \ \ \ \ \ \ \ \ | ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\f[] +.fi +.SS Extension: \f[C]pipe_tables\f[] +.PP +Pipe tables look like this: +.IP +.nf +\f[C] +|\ Right\ |\ Left\ |\ Default\ |\ Center\ | +|\-\-\-\-\-\-:|:\-\-\-\-\-|\-\-\-\-\-\-\-\-\-|:\-\-\-\-\-\-:| +|\ \ \ 12\ \ |\ \ 12\ \ |\ \ \ \ 12\ \ \ |\ \ \ \ 12\ \ | +|\ \ 123\ \ |\ \ 123\ |\ \ \ 123\ \ \ |\ \ \ 123\ \ | +|\ \ \ \ 1\ \ |\ \ \ \ 1\ |\ \ \ \ \ 1\ \ \ |\ \ \ \ \ 1\ \ | + +\ \ :\ Demonstration\ of\ pipe\ table\ syntax. +\f[] +.fi +.PP +The syntax is identical to PHP Markdown Extra tables. +The beginning and ending pipe characters are optional, but pipes are +required between all columns. +The colons indicate column alignment as shown. +The header cannot be omitted. +To simulate a headerless table, include a header with blank cells. +.PP +Since the pipes indicate column boundaries, columns need not be +vertically aligned, as they are in the above example. +So, this is a perfectly legal (though ugly) pipe table: +.IP +.nf +\f[C] +fruit|\ price +\-\-\-\-\-|\-\-\-\-\-: +apple|2.05 +pear|1.37 +orange|3.09 +\f[] +.fi +.PP +The cells of pipe tables cannot contain block elements like paragraphs +and lists, and cannot span multiple lines. +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. +.PP +Note: pandoc also recognizes pipe tables of the following form, as can +be produced by Emacs' orgtbl\-mode: +.IP +.nf +\f[C] +|\ One\ |\ Two\ \ \ | +|\-\-\-\-\-+\-\-\-\-\-\-\-| +|\ my\ \ |\ table\ | +|\ is\ \ |\ nice\ \ | +\f[] +.fi +.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. +.SS Metadata blocks +.SS Extension: \f[C]pandoc_title_block\f[] +.PP +If the file begins with a title block +.IP +.nf +\f[C] +%\ title +%\ author(s)\ (separated\ by\ semicolons) +%\ date +\f[] +.fi +.PP +it will be parsed as bibliographic information, not regular text. +(It will be used, for example, in the title of standalone LaTeX or HTML +output.) The block may contain just a title, a title and an author, or +all three elements. +If you want to include an author but no title, or a title and a date but +no author, you need a blank line: +.IP +.nf +\f[C] +% +%\ Author + +%\ My\ title +% +%\ June\ 15,\ 2006 +\f[] +.fi +.PP +The title may occupy multiple lines, but continuation lines must begin +with leading space, thus: +.IP +.nf +\f[C] +%\ My\ title +\ \ on\ multiple\ lines +\f[] +.fi +.PP +If a document has multiple authors, the authors may be put on separate +lines with leading space, or separated by semicolons, or both. +So, all of the following are equivalent: +.IP +.nf +\f[C] +%\ Author\ One +\ \ Author\ Two + +%\ Author\ One;\ Author\ Two + +%\ Author\ One; +\ \ Author\ Two +\f[] +.fi +.PP +The date must fit on one line. +.PP +All three metadata fields may contain standard inline formatting +(italics, links, footnotes, etc.). +.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. +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. +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. +.PP +The man page writer extracts a title, man page section number, and other +header and footer information from the title line. +The title is assumed to be the first word on the title line, which may +optionally end with a (single\-digit) section number in parentheses. +(There should be no space between the title and the parentheses.) +Anything after this is assumed to be additional footer and header text. +A single pipe character (\f[C]|\f[]) should be used to separate the +footer text from the header text. +Thus, +.IP +.nf +\f[C] +%\ PANDOC(1) +\f[] +.fi +.PP +will yield a man page with the title \f[C]PANDOC\f[] and section 1. +.IP +.nf +\f[C] +%\ PANDOC(1)\ Pandoc\ User\ Manuals +\f[] +.fi +.PP +will also have \[lq]Pandoc User Manuals\[rq] in the footer. +.IP +.nf +\f[C] +%\ PANDOC(1)\ Pandoc\ User\ Manuals\ |\ Version\ 4.0 +\f[] +.fi +.PP +will also have \[lq]Version 4.0\[rq] 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 +three hyphens (\f[C]\-\-\-\f[]) at the top and a line of three hyphens +(\f[C]\-\-\-\f[]) or three dots (\f[C]\&...\f[]) at the bottom. +A YAML metadata block may occur anywhere in the document, but if it is +not at the beginning, it must be preceded by a blank line. +(Note that, because of the way pandoc concatenates input files when +several are provided, you may also keep the metadata in a separate YAML +file and pass it to pandoc as an argument, along with your Markdown +files: +.IP +.nf +\f[C] +pandoc\ chap1.md\ chap2.md\ chap3.md\ metadata.yaml\ \-s\ \-o\ book.html +\f[] +.fi +.PP +Just be sure that the YAML file begins with \f[C]\-\-\-\f[] and ends +with \f[C]\-\-\-\f[] or \f[C]\&...\f[].) +.PP +Metadata will be taken from the fields of the YAML object and added to +any existing document metadata. +Metadata can contain lists and objects (nested arbitrarily), but all +string scalars will be interpreted as Markdown. +Fields with names ending in an underscore will be ignored by pandoc. +(They may be given a role by external processors.) +.PP +A document may contain multiple metadata blocks. +The metadata fields will be combined through a \f[I]left\-biased +union\f[]: if two metadata blocks attempt to set the same field, the +value from the first block will be taken. +.PP +When pandoc is used with \f[C]\-t\ markdown\f[] to create a Markdown +document, a YAML metadata block will be produced only if the +\f[C]\-s/\-\-standalone\f[] option is used. +All of the metadata will appear in a single block at the beginning of +the document. +.PP +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: +.IP +.nf +\f[C] +\-\-\- +title:\ \ \[aq]This\ is\ the\ title:\ it\ contains\ a\ colon\[aq] +author: +\-\ Author\ One +\-\ Author\ Two +tags:\ [nothing,\ nothingness] +abstract:\ | +\ \ This\ is\ the\ abstract. + +\ \ It\ consists\ of\ two\ paragraphs. +\&... +\f[] +.fi +.PP +Template variables will be set automatically from the metadata. +Thus, for example, in writing HTML, the variable \f[C]abstract\f[] will +be set to the HTML equivalent of the Markdown in the \f[C]abstract\f[] +field: +.IP +.nf +\f[C] +<p>This\ is\ the\ abstract.</p> +<p>It\ consists\ of\ two\ paragraphs.</p> +\f[] +.fi +.PP +Variables can contain arbitrary YAML structures, but the template must +match this structure. +The \f[C]author\f[] variable in the default templates expects a simple +list or string, but can be changed to support more complicated +structures. +The following combination, for example, would add an affiliation to the +author if one is given: +.IP +.nf +\f[C] +\-\-\- +title:\ The\ document\ title +author: +\-\ name:\ Author\ One +\ \ affiliation:\ University\ of\ Somewhere +\-\ name:\ Author\ Two +\ \ affiliation:\ University\ of\ Nowhere +\&... +\f[] +.fi +.PP +To use the structured authors in the example above, you would need a +custom template: +.IP +.nf +\f[C] +$for(author)$ +$if(author.name)$ +$author.name$$if(author.affiliation)$\ ($author.affiliation$)$endif$ +$else$ +$author$ +$endif$ +$endfor$ +\f[] +.fi +.SS Backslash escapes +.SS Extension: \f[C]all_symbols_escapable\f[] +.PP +Except inside a code block or inline code, any punctuation or space +character preceded by a backslash will be treated literally, even if it +would normally indicate formatting. +Thus, for example, if one writes +.IP +.nf +\f[C] +*\\*hello\\** +\f[] +.fi +.PP +one will get +.IP +.nf +\f[C] +<em>*hello*</em> +\f[] +.fi +.PP +instead of +.IP +.nf +\f[C] +<strong>hello</strong> +\f[] +.fi +.PP +This rule is easier to remember than standard Markdown's rule, which +allows only the following characters to be backslash\-escaped: +.IP +.nf +\f[C] +\\`*_{}[]()>#+\-.! +\f[] +.fi +.PP +(However, if the \f[C]markdown_strict\f[] format is used, the standard +Markdown rule will be used.) +.PP +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. +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 +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 +To \f[I]emphasize\f[] some text, surround it with \f[C]*\f[]s or +\f[C]_\f[], like this: +.IP +.nf +\f[C] +This\ text\ is\ _emphasized\ with\ underscores_,\ and\ this +is\ *emphasized\ with\ asterisks*. +\f[] +.fi +.PP +Double \f[C]*\f[] or \f[C]_\f[] produces \f[B]strong emphasis\f[]: +.IP +.nf +\f[C] +This\ is\ **strong\ emphasis**\ and\ __with\ underscores__. +\f[] +.fi +.PP +A \f[C]*\f[] or \f[C]_\f[] character surrounded by spaces, or +backslash\-escaped, will not trigger emphasis: +.IP +.nf +\f[C] +This\ is\ *\ not\ emphasized\ *,\ and\ \\*neither\ is\ this\\*. +\f[] +.fi +.SS Extension: \f[C]intraword_underscores\f[] +.PP +Because \f[C]_\f[] is sometimes used inside words and identifiers, +pandoc does not interpret a \f[C]_\f[] surrounded by alphanumeric +characters as an emphasis marker. +If you want to emphasize just part of a word, use \f[C]*\f[]: +.IP +.nf +\f[C] +feas*ible*,\ not\ feas*able*. +\f[] +.fi +.SS Strikeout +.SS Extension: \f[C]strikeout\f[] +.PP +To strikeout a section of text with a horizontal line, begin and end it +with \f[C]~~\f[]. +Thus, for example, +.IP +.nf +\f[C] +This\ ~~is\ deleted\ text.~~ +\f[] +.fi +.SS Superscripts and subscripts +.SS Extension: \f[C]superscript\f[], \f[C]subscript\f[] +.PP +Superscripts may be written by surrounding the superscripted text by +\f[C]^\f[] characters; subscripts may be written by surrounding the +subscripted text by \f[C]~\f[] characters. +Thus, for example, +.IP +.nf +\f[C] +H~2~O\ is\ a\ liquid.\ \ 2^10^\ is\ 1024. +\f[] +.fi +.PP +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[]. +.SS Verbatim +.PP +To make a short span of text verbatim, put it inside backticks: +.IP +.nf +\f[C] +What\ is\ the\ difference\ between\ `>>=`\ and\ `>>`? +\f[] +.fi +.PP +If the verbatim text includes a backtick, use double backticks: +.IP +.nf +\f[C] +Here\ is\ a\ literal\ backtick\ ``\ `\ ``. +\f[] +.fi +.PP +(The spaces after the opening backticks and before the closing backticks +will be ignored.) +.PP +The general rule is that a verbatim span starts with a string of +consecutive backticks (optionally followed by a space) and ends with a +string of the same number of backticks (optionally preceded by a space). +.PP +Note that backslash\-escapes (and other Markdown constructs) do not work +in verbatim contexts: +.IP +.nf +\f[C] +This\ is\ a\ backslash\ followed\ by\ an\ asterisk:\ `\\*`. +\f[] +.fi +.SS Extension: \f[C]inline_code_attributes\f[] +.PP +Attributes can be attached to verbatim text, just as with fenced code +blocks: +.IP +.nf +\f[C] +`<$>`{.haskell} +\f[] +.fi +.SS Small caps +.PP +To write small caps, you can use an HTML span tag: +.IP +.nf +\f[C] +<span\ style="font\-variant:small\-caps;">Small\ caps</span> +\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. +.PP +Alternatively, you can also use the new \f[C]bracketed_spans\f[] syntax: +.IP +.nf +\f[C] +[Small\ caps]{style="font\-variant:small\-caps;"} +\f[] +.fi +.SS Math +.SS Extension: \f[C]tex_math_dollars\f[] +.PP +Anything between two \f[C]$\f[] characters will be treated as TeX math. +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. +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 +delimiters. +.PP +TeX math will be printed in all output formats. +How it is rendered depends on the output format: +.TP +.B Markdown, LaTeX, Emacs Org mode, ConTeXt, ZimWiki +It will appear verbatim between \f[C]$\f[] characters. +.RS +.RE +.TP +.B reStructuredText +It will be rendered using an interpreted text role \f[C]:math:\f[]. +.RS +.RE +.TP +.B AsciiDoc +It will be rendered as \f[C]latexmath:[...]\f[]. +.RS +.RE +.TP +.B Texinfo +It will be rendered inside a \f[C]\@math\f[] command. +.RS +.RE +.TP +.B groff man +It will be rendered verbatim without \f[C]$\f[]'s. +.RS +.RE +.TP +.B MediaWiki, DokuWiki +It will be rendered inside \f[C]<math>\f[] tags. +.RS +.RE +.TP +.B Textile +It will be rendered inside \f[C]<span\ class="math">\f[] tags. +.RS +.RE +.TP +.B RTF, OpenDocument, ODT +It will be rendered, if possible, using Unicode characters, and will +otherwise appear verbatim. +.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. +Otherwise it will be rendered, if possible, using Unicode characters. +.RS +.RE +.TP +.B Docx +It will be rendered using OMML math markup. +.RS +.RE +.TP +.B FictionBook2 +If the \f[C]\-\-webtex\f[] option is used, formulas are rendered as +images using CodeCogs or other compatible web service, downloaded and +embedded in the e\-book. +Otherwise, they will appear verbatim. +.RS +.RE +.TP +.B HTML, Slidy, DZSlides, S5, EPUB +The way math is rendered in HTML will depend on the command\-line +options selected: +.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[] +.PP +Markdown allows you to insert raw HTML (or DocBook) anywhere in a +document (except verbatim contexts, where \f[C]<\f[], \f[C]>\f[], and +\f[C]&\f[] are interpreted literally). +(Technically this is not an extension, since standard Markdown allows +it, but it has been made an extension so that it can be disabled if +desired.) +.PP +The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous, +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. +Within these blocks, everything is interpreted as HTML, not Markdown; so +(for example), \f[C]*\f[] does not signify emphasis. +.PP +Pandoc behaves this way when the \f[C]markdown_strict\f[] format is +used; but by default, pandoc interprets material between HTML block tags +as Markdown. +Thus, for example, pandoc will turn +.IP +.nf +\f[C] +<table> +<tr> +<td>*one*</td> +<td>[a\ link](http://google.com)</td> +</tr> +</table> +\f[] +.fi +.PP +into +.IP +.nf +\f[C] +<table> +<tr> +<td><em>one</em></td> +<td><a\ href="http://google.com">a\ link</a></td> +</tr> +</table> +\f[] +.fi +.PP +whereas \f[C]Markdown.pl\f[] will preserve it as is. +.PP +There is one exception to this rule: text between \f[C]<script>\f[] and +\f[C]<style>\f[] tags is not interpreted as Markdown. +.PP +This departure from standard Markdown should make it easier to mix +Markdown with HTML block elements. +For example, one can surround a block of Markdown text with +\f[C]<div>\f[] tags without preventing it from being interpreted as +Markdown. +.SS Extension: \f[C]native_divs\f[] +.PP +Use native pandoc \f[C]Div\f[] blocks for content inside \f[C]<div>\f[] +tags. +For the most part this should give the same output as +\f[C]markdown_in_html_blocks\f[], but it makes it easier to write pandoc +filters to manipulate groups of blocks. +.SS Extension: \f[C]native_spans\f[] +.PP +Use native pandoc \f[C]Span\f[] blocks for content inside +\f[C]<span>\f[] tags. +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 +included in a document. +Inline TeX commands will be preserved and passed unchanged to the LaTeX +and ConTeXt writers. +Thus, for example, you can use LaTeX to include BibTeX citations: +.IP +.nf +\f[C] +This\ result\ was\ proved\ in\ \\cite{jones.1967}. +\f[] +.fi +.PP +Note that in LaTeX environments, like +.IP +.nf +\f[C] +\\begin{tabular}{|l|l|}\\hline +Age\ &\ Frequency\ \\\\\ \\hline +18\-\-25\ \ &\ 15\ \\\\ +26\-\-35\ \ &\ 33\ \\\\ +36\-\-45\ \ &\ 22\ \\\\\ \\hline +\\end{tabular} +\f[] +.fi +.PP +the material between the begin and end tags will be interpreted as raw +LaTeX, not as Markdown. +.PP +Inline LaTeX is ignored in output formats other than Markdown, LaTeX, +Emacs Org mode, and ConTeXt. +.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. +So, for example, the following will work in all output formats, not just +LaTeX: +.IP +.nf +\f[C] +\\newcommand{\\tuple}[1]{\\langle\ #1\ \\rangle} + +$\\tuple{a,\ b,\ c}$ +\f[] +.fi +.PP +In LaTeX output, the \f[C]\\newcommand\f[] definition will simply be +passed unchanged to the output. +.SS Links +.PP +Markdown allows links to be specified in several ways. +.SS Automatic links +.PP +If you enclose a URL or email address in pointy brackets, it will become +a link: +.IP +.nf +\f[C] +<http://google.com> +<sam\@green.eggs.ham> +\f[] +.fi +.SS Inline links +.PP +An inline link consists of the link text in square brackets, followed by +the URL in parentheses. +(Optionally, the URL can be followed by a link title, in quotes.) +.IP +.nf +\f[C] +This\ is\ an\ [inline\ link](/url),\ and\ here\[aq]s\ [one\ with +a\ title](http://fsf.org\ "click\ here\ for\ a\ good\ time!"). +\f[] +.fi +.PP +There can be no space between the bracketed part and the parenthesized +part. +The link text can contain formatting (such as emphasis), but the title +cannot. +.PP +Email addresses in inline links are not autodetected, so they have to be +prefixed with \f[C]mailto\f[]: +.IP +.nf +\f[C] +[Write\ me!](mailto:sam\@green.eggs.ham) +\f[] +.fi +.SS Reference links +.PP +An \f[I]explicit\f[] reference link has two parts, the link itself and +the link definition, which may occur elsewhere in the document (either +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. +The label must not be parseable as a citation (assuming the +\f[C]citations\f[] extension is enabled): citations take precedence over +link labels. +.PP +Here are some examples: +.IP +.nf +\f[C] +[my\ label\ 1]:\ /foo/bar.html\ \ "My\ title,\ optional" +[my\ label\ 2]:\ /foo +[my\ label\ 3]:\ http://fsf.org\ (The\ free\ software\ foundation) +[my\ label\ 4]:\ /bar#special\ \ \[aq]A\ title\ in\ single\ quotes\[aq] +\f[] +.fi +.PP +The URL may optionally be surrounded by angle brackets: +.IP +.nf +\f[C] +[my\ label\ 5]:\ <http://foo.bar.baz> +\f[] +.fi +.PP +The title may go on the next line: +.IP +.nf +\f[C] +[my\ label\ 3]:\ http://fsf.org +\ \ "The\ free\ software\ foundation" +\f[] +.fi +.PP +Note that link labels are not case sensitive. +So, this will work: +.IP +.nf +\f[C] +Here\ is\ [my\ link][FOO] + +[Foo]:\ /bar/baz +\f[] +.fi +.PP +In an \f[I]implicit\f[] reference link, the second pair of brackets is +empty: +.IP +.nf +\f[C] +See\ [my\ website][]. + +[my\ website]:\ http://foo.bar.baz +\f[] +.fi +.PP +Note: In \f[C]Markdown.pl\f[] and most other Markdown implementations, +reference link definitions cannot occur in nested constructions such as +list items or block quotes. +Pandoc lifts this arbitrary seeming restriction. +So the following is fine in pandoc, though not in most other +implementations: +.IP +.nf +\f[C] +>\ My\ block\ [quote]. +> +>\ [quote]:\ /foo +\f[] +.fi +.SS Extension: \f[C]shortcut_reference_links\f[] +.PP +In a \f[I]shortcut\f[] reference link, the second pair of brackets may +be omitted entirely: +.IP +.nf +\f[C] +See\ [my\ website]. + +[my\ website]:\ http://foo.bar.baz +\f[] +.fi +.SS Internal links +.PP +To link to another section of the same document, use the automatically +generated identifier (see Header identifiers). +For example: +.IP +.nf +\f[C] +See\ the\ [Introduction](#introduction). +\f[] +.fi +.PP +or +.IP +.nf +\f[C] +See\ the\ [Introduction]. + +[Introduction]:\ #introduction +\f[] +.fi +.PP +Internal links are currently supported for HTML formats (including HTML +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: +.IP +.nf +\f[C] + + +![movie\ reel] + +[movie\ reel]:\ movie.gif +\f[] +.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. +.IP +.nf +\f[C] + +\f[] +.fi +.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)\\\ +\f[] +.fi +.SS Extension: \f[C]link_attributes\f[] +.PP +Attributes can be set on links and images: +.IP +.nf +\f[C] +An\ inline\ {#id\ .class\ width=30\ height=20px} +and\ a\ reference\ ![image][ref]\ with\ attributes. + +[ref]:\ foo.jpg\ "optional\ title"\ {#id\ .class\ key=val\ key2="val\ 2"} +\f[] +.fi +.PP +(This syntax is compatible with PHP Markdown Extra when only +\f[C]#id\f[] and \f[C]\&.class\f[] are used.) +.PP +For HTML and EPUB, all attributes except \f[C]width\f[] and +\f[C]height\f[] (but including \f[C]srcset\f[] and \f[C]sizes\f[]) are +passed through as is. +The other writers ignore attributes that are not supported by their +output format. +.PP +The \f[C]width\f[] and \f[C]height\f[] attributes on images are treated +specially. +When used without a unit, the unit is assumed to be pixels. +However, any of the following unit identifiers can be used: \f[C]px\f[], +\f[C]cm\f[], \f[C]mm\f[], \f[C]in\f[], \f[C]inch\f[] and \f[C]%\f[]. +There must not be any spaces between the number and the unit. +For example: +.IP +.nf +\f[C] +{\ width=50%\ } +\f[] +.fi +.IP \[bu] 2 +Dimensions are converted to inches for output in page\-based formats +like LaTeX. +Dimensions are converted to pixels for output in HTML\-like formats. +Use the \f[C]\-\-dpi\f[] option to specify the number of pixels per +inch. +The default is 96dpi. +.IP \[bu] 2 +The \f[C]%\f[] unit is generally relative to some available space. +For example the above example will render to +\f[C]<img\ href="file.jpg"\ style="width:\ 50%;"\ />\f[] (HTML), +\f[C]\\includegraphics[width=0.5\\textwidth]{file.jpg}\f[] (LaTeX), or +\f[C]\\externalfigure[file.jpg][width=0.5\\textwidth]\f[] (ConTeXt). +.IP \[bu] 2 +Some output formats have a notion of a class (ConTeXt) or a unique +identifier (LaTeX \f[C]\\caption\f[]), or both (HTML). +.IP \[bu] 2 +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 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: +.IP +.nf +\f[C] +[This\ is\ *some\ text*]{.class\ key="val"} +\f[] +.fi +.SS Footnotes +.SS Extension: \f[C]footnotes\f[] +.PP +Pandoc's Markdown allows footnotes, using the following syntax: +.IP +.nf +\f[C] +Here\ is\ a\ footnote\ reference,[^1]\ and\ another.[^longnote] + +[^1]:\ Here\ is\ the\ footnote. + +[^longnote]:\ Here\[aq]s\ one\ with\ multiple\ blocks. + +\ \ \ \ Subsequent\ paragraphs\ are\ indented\ to\ show\ that\ they +belong\ to\ the\ previous\ footnote. + +\ \ \ \ \ \ \ \ {\ some.code\ } + +\ \ \ \ The\ whole\ paragraph\ can\ be\ indented,\ or\ just\ the\ first +\ \ \ \ line.\ \ In\ this\ way,\ multi\-paragraph\ footnotes\ work\ like +\ \ \ \ multi\-paragraph\ list\ items. + +This\ paragraph\ won\[aq]t\ be\ part\ of\ the\ note,\ because\ it +isn\[aq]t\ indented. +\f[] +.fi +.PP +The identifiers in footnote references may not contain spaces, tabs, or +newlines. +These identifiers are used only to correlate the footnote reference with +the note itself; in the output, footnotes will be numbered sequentially. +.PP +The footnotes themselves need not be placed at the end of the document. +They may appear anywhere except inside other block elements (lists, +block quotes, tables, etc.). +Each footnote should be separated from surrounding content (including +other footnotes) by blank lines. +.SS Extension: \f[C]inline_notes\f[] +.PP +Inline footnotes are also allowed (though, unlike regular notes, they +cannot contain multiple paragraphs). +The syntax is as follows: +.IP +.nf +\f[C] +Here\ is\ an\ inline\ note.^[Inlines\ notes\ are\ easier\ to\ write,\ since +you\ don\[aq]t\ have\ to\ pick\ an\ identifier\ and\ move\ down\ to\ type\ the +note.] +\f[] +.fi +.PP +Inline and regular footnotes may be mixed freely. +.SS Citations +.SS Extension: \f[C]citations\f[] +.PP +Using an external filter, \f[C]pandoc\-citeproc\f[], pandoc can +automatically generate citations and a bibliography in a number of +styles. +Basic usage is +.IP +.nf +\f[C] +pandoc\ \-\-filter\ pandoc\-citeproc\ myinput.txt +\f[] +.fi +.PP +In order to use this feature, you will need to specify a bibliography +file using the \f[C]bibliography\f[] metadata field in a YAML metadata +section, or \f[C]\-\-bibliography\f[] command line argument. +You can supply multiple \f[C]\-\-bibliography\f[] arguments or set +\f[C]bibliography\f[] metadata field to YAML array, if you want to use +multiple bibliography files. +The bibliography may have any of these formats: +.PP +.TS +tab(@); +l l. +T{ +Format +T}@T{ +File extension +T} +_ +T{ +BibLaTeX +T}@T{ +\&.bib +T} +T{ +BibTeX +T}@T{ +\&.bibtex +T} +T{ +Copac +T}@T{ +\&.copac +T} +T{ +CSL JSON +T}@T{ +\&.json +T} +T{ +CSL YAML +T}@T{ +\&.yaml +T} +T{ +EndNote +T}@T{ +\&.enl +T} +T{ +EndNote XML +T}@T{ +\&.xml +T} +T{ +ISI +T}@T{ +\&.wos +T} +T{ +MEDLINE +T}@T{ +\&.medline +T} +T{ +MODS +T}@T{ +\&.mods +T} +T{ +RIS +T}@T{ +\&.ris +T} +.TE +.PP +Note that \f[C]\&.bib\f[] can be used with both BibTeX and BibLaTeX +files; use \f[C]\&.bibtex\f[] to force BibTeX. +.PP +Note that \f[C]pandoc\-citeproc\ \-\-bib2json\f[] and +\f[C]pandoc\-citeproc\ \-\-bib2yaml\f[] can produce \f[C]\&.json\f[] and +\f[C]\&.yaml\f[] files from any of the supported formats. +.PP +In\-field markup: In BibTeX and BibLaTeX databases, pandoc\-citeproc +parses a subset of LaTeX markup; in CSL YAML databases, pandoc Markdown; +and in CSL JSON databases, an HTML\-like markup: +.TP +.B \f[C]<i>...</i>\f[] +italics +.RS +.RE +.TP +.B \f[C]<b>...</b>\f[] +bold +.RS +.RE +.TP +.B \f[C]<span\ style="font\-variant:small\-caps;">...</span>\f[] or \f[C]<sc>...</sc>\f[] +small capitals +.RS +.RE +.TP +.B \f[C]<sub>...</sub>\f[] +subscript +.RS +.RE +.TP +.B \f[C]<sup>...</sup>\f[] +superscript +.RS +.RE +.TP +.B \f[C]<span\ class="nocase">...</span>\f[] +prevent a phrase from being capitalized as title case +.RS +.RE +.PP +\f[C]pandoc\-citeproc\ \-j\f[] and \f[C]\-y\f[] interconvert the CSL +JSON and CSL YAML formats as far as possible. +.PP +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. +The field should contain an array of YAML\-encoded references, for +example: +.IP +.nf +\f[C] +\-\-\- +references: +\-\ type:\ article\-journal +\ \ id:\ WatsonCrick1953 +\ \ author: +\ \ \-\ family:\ Watson +\ \ \ \ given:\ J.\ D. +\ \ \-\ family:\ Crick +\ \ \ \ given:\ F.\ H.\ C. +\ \ issued: +\ \ \ \ date\-parts: +\ \ \ \ \-\ \-\ 1953 +\ \ \ \ \ \ \-\ 4 +\ \ \ \ \ \ \-\ 25 +\ \ title:\ \[aq]Molecular\ structure\ of\ nucleic\ acids:\ a\ structure\ for\ deoxyribose +\ \ \ \ nucleic\ acid\[aq] +\ \ title\-short:\ Molecular\ structure\ of\ nucleic\ acids +\ \ container\-title:\ Nature +\ \ volume:\ 171 +\ \ issue:\ 4356 +\ \ page:\ 737\-738 +\ \ DOI:\ 10.1038/171737a0 +\ \ URL:\ http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html +\ \ language:\ en\-GB +\&... +\f[] +.fi +.PP +(\f[C]pandoc\-citeproc\ \-\-bib2yaml\f[] can produce these from a +bibliography file in one of the supported formats.) +.PP +Citations and references can be formatted using any style supported by +the Citation Style Language, listed in the Zotero Style Repository. +These files are specified using the \f[C]\-\-csl\f[] option or the +\f[C]csl\f[] metadata field. +By default, \f[C]pandoc\-citeproc\f[] will use the Chicago Manual of +Style author\-date format. +The CSL project provides further information on finding and editing +styles. +.PP +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 +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 +contain alphanumerics, \f[C]_\f[], and internal punctuation characters +(\f[C]:.#$%&\-+?<>~/\f[]). +Here are some examples: +.IP +.nf +\f[C] +Blah\ blah\ [see\ \@doe99,\ pp.\ 33\-35;\ also\ \@smith04,\ chap.\ 1]. + +Blah\ blah\ [\@doe99,\ pp.\ 33\-35,\ 38\-39\ and\ *passim*]. + +Blah\ blah\ [\@smith04;\ \@doe99]. +\f[] +.fi +.PP +\f[C]pandoc\-citeproc\f[] detects locator terms in the CSL locale files. +Either abbreviated or unabbreviated forms are accepted. +In the \f[C]en\-US\f[] locale, locator terms can be written in either +singular or plural forms, as \f[C]book\f[], \f[C]bk.\f[]/\f[C]bks.\f[]; +\f[C]chapter\f[], \f[C]chap.\f[]/\f[C]chaps.\f[]; \f[C]column\f[], +\f[C]col.\f[]/\f[C]cols.\f[]; \f[C]figure\f[], +\f[C]fig.\f[]/\f[C]figs.\f[]; \f[C]folio\f[], +\f[C]fol.\f[]/\f[C]fols.\f[]; \f[C]number\f[], +\f[C]no.\f[]/\f[C]nos.\f[]; \f[C]line\f[], \f[C]l.\f[]/\f[C]ll.\f[]; +\f[C]note\f[], \f[C]n.\f[]/\f[C]nn.\f[]; \f[C]opus\f[], +\f[C]op.\f[]/\f[C]opp.\f[]; \f[C]page\f[], \f[C]p.\f[]/\f[C]pp.\f[]; +\f[C]paragraph\f[], \f[C]para.\f[]/\f[C]paras.\f[]; \f[C]part\f[], +\f[C]pt.\f[]/\f[C]pts.\f[]; \f[C]section\f[], +\f[C]sec.\f[]/\f[C]secs.\f[]; \f[C]sub\ verbo\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. +.PP +A minus sign (\f[C]\-\f[]) before the \f[C]\@\f[] will suppress mention +of the author in the citation. +This can be useful when the author is already mentioned in the text: +.IP +.nf +\f[C] +Smith\ says\ blah\ [\-\@smith04]. +\f[] +.fi +.PP +You can also write an in\-text citation, as follows: +.IP +.nf +\f[C] +\@smith04\ says\ blah. + +\@smith04\ [p.\ 33]\ says\ blah. +\f[] +.fi +.PP +If the style calls for a list of works cited, it will be placed at the +end of the document. +Normally, you will want to end your document with an appropriate header: +.IP +.nf +\f[C] +last\ paragraph... + +#\ References +\f[] +.fi +.PP +The bibliography will be inserted after this header. +Note that the \f[C]unnumbered\f[] class will be added to this header, so +that the section will not be numbered. +.PP +If you want to include items in the bibliography without actually citing +them in the body text, you can define a dummy \f[C]nocite\f[] metadata +field and put the citations there: +.IP +.nf +\f[C] +\-\-\- +nocite:\ | +\ \ \@item1,\ \@item2 +\&... + +\@item3 +\f[] +.fi +.PP +In this example, the document will contain a citation for \f[C]item3\f[] +only, but the bibliography will contain entries for \f[C]item1\f[], +\f[C]item2\f[], and \f[C]item3\f[]. +.PP +It is possible to create a bibliography with all the citations, whether +or not they appear in the document, by using a wildcard: +.IP +.nf +\f[C] +\-\-\- +nocite:\ | +\ \ \@* +\&... +\f[] +.fi +.PP +For LaTeX or PDF output, you can also use \f[C]natbib\f[] or +\f[C]biblatex\f[] to render bibliography. +In order to do so, specify bibliography files as outlined above, and add +\f[C]\-\-natbib\f[] or \f[C]\-\-biblatex\f[] argument to \f[C]pandoc\f[] +invocation. +Bear in mind that bibliography files have to be in respective format +(either BibTeX or BibLaTeX). +.PP +For more information, see the pandoc\-citeproc man page. +.SS Non\-pandoc extensions +.PP +The following Markdown syntax extensions are not enabled by default in +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]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[]. +.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]hard_line_breaks\f[] +.PP +Causes all newlines within a paragraph to be interpreted as hard line +breaks instead of spaces. +.SS Extension: \f[C]ignore_line_breaks\f[] +.PP +Causes newlines within a paragraph to be ignored, rather than being +treated as spaces or as hard line breaks. +This option is intended for use with East Asian languages where spaces +are not used between words, but text is divided into lines for +readability. +.SS Extension: \f[C]east_asian_line_breaks\f[] +.PP +Causes newlines within a paragraph to be ignored, rather than being +treated as spaces or as hard line breaks, when they occur between two +East Asian wide characters. +This is a better choice than \f[C]ignore_line_breaks\f[] for texts that +include a mix of East Asian wide characters and other characters. +.SS Extension: \f[C]emoji\f[] +.PP +Parses textual emojis like \f[C]:smile:\f[] as Unicode emoticons. +.SS Extension: \f[C]tex_math_single_backslash\f[] +.PP +Causes anything between \f[C]\\(\f[] and \f[C]\\)\f[] to be interpreted +as inline TeX math, and anything between \f[C]\\[\f[] and \f[C]\\]\f[] +to be interpreted as display TeX math. +Note: a drawback of this extension is that it precludes escaping +\f[C](\f[] and \f[C][\f[]. +.SS Extension: \f[C]tex_math_double_backslash\f[] +.PP +Causes anything between \f[C]\\\\(\f[] and \f[C]\\\\)\f[] to be +interpreted as inline TeX math, and anything between \f[C]\\\\[\f[] and +\f[C]\\\\]\f[] to be interpreted as display TeX math. +.SS Extension: \f[C]markdown_attribute\f[] +.PP +By default, pandoc interprets material inside block\-level tags as +Markdown. +This extension changes the behavior so that Markdown is only parsed +inside block\-level tags if the tags have the attribute +\f[C]markdown=1\f[]. +.SS Extension: \f[C]mmd_title_block\f[] +.PP +Enables a MultiMarkdown style title block at the top of the document, +for example: +.IP +.nf +\f[C] +Title:\ \ \ My\ title +Author:\ \ John\ Doe +Date:\ \ \ \ September\ 1,\ 2008 +Comment:\ This\ is\ a\ sample\ mmd\ title\ block,\ with +\ \ \ \ \ \ \ \ \ a\ field\ spanning\ multiple\ lines. +\f[] +.fi +.PP +See the MultiMarkdown documentation for details. +If \f[C]pandoc_title_block\f[] or \f[C]yaml_metadata_block\f[] is +enabled, it will take precedence over \f[C]mmd_title_block\f[]. +.SS Extension: \f[C]abbreviations\f[] +.PP +Parses PHP Markdown Extra abbreviation keys, like +.IP +.nf +\f[C] +*[HTML]:\ Hypertext\ Markup\ Language +\f[] +.fi +.PP +Note that the pandoc document model does not support abbreviations, so +if this extension is enabled, abbreviation keys are simply skipped (as +opposed to being parsed as paragraphs). +.SS Extension: \f[C]autolink_bare_uris\f[] +.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 +references. +This extension should not be confused with the \f[C]link_attributes\f[] +extension. +.IP +.nf +\f[C] +This\ is\ a\ reference\ ![image][ref]\ with\ multimarkdown\ attributes. + +[ref]:\ http://path.to/image\ "Image\ title"\ width=20px\ height=30px +\ \ \ \ \ \ \ id=myId\ class="myClass1\ myClass2" +\f[] +.fi +.SS Extension: \f[C]mmd_header_identifiers\f[] +.PP +Parses multimarkdown style header identifiers (in square brackets, after +the header but before any trailing \f[C]#\f[]s in an ATX header). +.SS Extension: \f[C]compact_definition_lists\f[] +.PP +Activates the definition list syntax of pandoc 1.12.x and earlier. +This syntax differs from the one described above under Definition lists +in several respects: +.IP \[bu] 2 +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. +.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 +variants are supported: +.TP +.B \f[C]markdown_phpextra\f[] (PHP Markdown Extra) +\f[C]footnotes\f[], \f[C]pipe_tables\f[], \f[C]raw_html\f[], +\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[]. +.RS +.RE +.TP +.B \f[C]markdown_github\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 +.TP +.B \f[C]markdown_mmd\f[] (MultiMarkdown) +\f[C]pipe_tables\f[], \f[C]raw_html\f[], \f[C]markdown_attribute\f[], +\f[C]mmd_link_attributes\f[], \f[C]tex_math_double_backslash\f[], +\f[C]intraword_underscores\f[], \f[C]mmd_title_block\f[], +\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[]. +.RS +.RE +.TP +.B \f[C]markdown_strict\f[] (Markdown.pl) +\f[C]raw_html\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.) +.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[]. +.PP +Here's the Markdown source for a simple slide show, \f[C]habits.txt\f[]: +.IP +.nf +\f[C] +%\ Habits +%\ John\ Doe +%\ March\ 22,\ 2005 + +#\ In\ the\ morning + +##\ Getting\ up + +\-\ Turn\ off\ alarm +\-\ Get\ out\ of\ bed + +##\ Breakfast + +\-\ Eat\ eggs +\-\ Drink\ coffee + +#\ In\ the\ evening + +##\ Dinner + +\-\ Eat\ spaghetti +\-\ Drink\ wine + +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + + + +##\ Going\ to\ sleep + +\-\ Get\ in\ bed +\-\ Count\ sheep +\f[] +.fi +.PP +To produce an HTML/JavaScript slide show, simply type +.IP +.nf +\f[C] +pandoc\ \-t\ FORMAT\ \-s\ habits.txt\ \-o\ habits.html +\f[] +.fi +.PP +where \f[C]FORMAT\f[] is either \f[C]s5\f[], \f[C]slidy\f[], +\f[C]slideous\f[], \f[C]dzslides\f[], or \f[C]revealjs\f[]. +.PP +For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with +the \f[C]\-s/\-\-standalone\f[] option embeds a link to JavaScript and +CSS files, which are assumed to be available at the relative path +\f[C]s5/default\f[] (for S5), \f[C]slideous\f[] (for Slideous), +\f[C]reveal.js\f[] (for reveal.js), or at the Slidy website at +\f[C]w3.org\f[] (for Slidy). +(These paths can be changed by setting the \f[C]slidy\-url\f[], +\f[C]slideous\-url\f[], \f[C]revealjs\-url\f[], or \f[C]s5\-url\f[] +variables; see Variables for slides, above.) For DZSlides, the +(relatively short) JavaScript and CSS are included in the file by +default. +.PP +With all HTML slide formats, the \f[C]\-\-self\-contained\f[] option can +be used to produce a single file that contains all of the data necessary +to display the slide show, including linked scripts, stylesheets, +images, and videos. +.PP +To produce a PDF slide show using beamer, type +.IP +.nf +\f[C] +pandoc\ \-t\ beamer\ habits.txt\ \-o\ habits.pdf +\f[] +.fi +.PP +Note that a reveal.js slide show can also be converted to a PDF by +printing it to a file from the browser. +.SS Structuring the slide show +.PP +By default, the \f[I]slide level\f[] is the highest header level in the +hierarchy that is followed immediately by content, and not another +header, somewhere in the document. +In the example above, level 1 headers are always followed by level 2 +headers, which are followed by content, so 2 is the slide level. +This default can be overridden using the \f[C]\-\-slide\-level\f[] +option. +.PP +The document is carved up into slides according to the following rules: +.IP \[bu] 2 +A horizontal rule always starts a new slide. +.IP \[bu] 2 +A header at the slide level always starts a new slide. +.IP \[bu] 2 +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. +.IP \[bu] 2 +A title page is constructed automatically from the document'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 +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. +.PP +Note: in reveal.js slide shows, if slide level is 2, a two\-dimensional +layout will be produced, with level 1 headers building horizontally and +level 2 headers building vertically. +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 +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: +.IP +.nf +\f[C] +>\ \-\ Eat\ spaghetti +>\ \-\ Drink\ wine +\f[] +.fi +.PP +In this way incremental and nonincremental lists can 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: +.IP +.nf +\f[C] +#\ Slide\ with\ a\ pause + +content\ before\ the\ pause + +\&.\ .\ . + +content\ after\ the\ pause +\f[] +.fi +.SS Styling the slides +.PP +You can change the style of HTML slides by putting customized CSS files +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[]). +Pandoc will look there for any files it does not find in the user data +directory. +.PP +For dzslides, the CSS is included in the HTML file itself, and may be +modified there. +.PP +All reveal.js configuration options can be set through variables. +For example, themes can be used by setting the \f[C]theme\f[] variable: +.IP +.nf +\f[C] +\-V\ theme=moon +\f[] +.fi +.PP +Or you can specify a custom stylesheet using the \f[C]\-\-css\f[] +option. +.PP +To style beamer slides, you can specify a \f[C]theme\f[], +\f[C]colortheme\f[], \f[C]fonttheme\f[], \f[C]innertheme\f[], and +\f[C]outertheme\f[], using the \f[C]\-V\f[] option: +.IP +.nf +\f[C] +pandoc\ \-t\ beamer\ habits.txt\ \-V\ theme:Warsaw\ \-o\ habits.pdf +\f[] +.fi +.PP +Note that header attributes will turn into slide attributes (on a +\f[C]<div>\f[] or \f[C]<section>\f[]) in HTML slide formats, allowing +you to style individual slides. +In beamer, the only header attribute that affects slides is the +\f[C]allowframebreaks\f[] class, which sets the +\f[C]allowframebreaks\f[] option, causing multiple slides to be created +if the content overfills the frame. +This is recommended especially for bibliographies: +.IP +.nf +\f[C] +#\ References\ {.allowframebreaks} +\f[] +.fi +.SS Speaker notes +.PP +reveal.js has good support for speaker notes. +You can add notes to your Markdown document thus: +.IP +.nf +\f[C] +<div\ class="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. +Notes are not yet supported for other slide formats, but the notes will +not appear on the slides themselves. +.SS Frame attributes in beamer +.PP +Sometimes it is necessary to add the LaTeX \f[C][fragile]\f[] option to +a frame in beamer (for example, when using the \f[C]minted\f[] +environment). +This can be forced by adding the \f[C]fragile\f[] class to the header +introducing the slide: +.IP +.nf +\f[C] +#\ Fragile\ slide\ {.fragile} +\f[] +.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[], +\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 +.SS EPUB Metadata +.PP +EPUB metadata may be specified using the \f[C]\-\-epub\-metadata\f[] +option, but if the source document is Markdown, it is better to use a +YAML metadata block. +Here is an example: +.IP +.nf +\f[C] +\-\-\- +title: +\-\ type:\ main +\ \ text:\ My\ Book +\-\ type:\ subtitle +\ \ text:\ An\ investigation\ of\ metadata +creator: +\-\ role:\ author +\ \ text:\ John\ Smith +\-\ role:\ editor +\ \ text:\ Sarah\ Jones +identifier: +\-\ scheme:\ DOI +\ \ text:\ doi:10.234234.234/33 +publisher:\ \ My\ Press +rights:\ ©\ 2007\ John\ Smith,\ CC\ BY\-NC +\&... +\f[] +.fi +.PP +The following fields are recognized: +.TP +.B \f[C]identifier\f[] +Either a string value or an object with fields \f[C]text\f[] and +\f[C]scheme\f[]. +Valid values for \f[C]scheme\f[] are \f[C]ISBN\-10\f[], +\f[C]GTIN\-13\f[], \f[C]UPC\f[], \f[C]ISMN\-10\f[], \f[C]DOI\f[], +\f[C]LCCN\f[], \f[C]GTIN\-14\f[], \f[C]ISBN\-13\f[], +\f[C]Legal\ deposit\ number\f[], \f[C]URN\f[], \f[C]OCLC\f[], +\f[C]ISMN\-13\f[], \f[C]ISBN\-A\f[], \f[C]JP\f[], \f[C]OLCC\f[]. +.RS +.RE +.TP +.B \f[C]title\f[] +Either a string value, or an object with fields \f[C]file\-as\f[] and +\f[C]type\f[], or a list of such objects. +Valid values for \f[C]type\f[] are \f[C]main\f[], \f[C]subtitle\f[], +\f[C]short\f[], \f[C]collection\f[], \f[C]edition\f[], +\f[C]extended\f[]. +.RS +.RE +.TP +.B \f[C]creator\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. +.RS +.RE +.TP +.B \f[C]contributor\f[] +Same format as \f[C]creator\f[]. +.RS +.RE +.TP +.B \f[C]date\f[] +A string value in \f[C]YYYY\-MM\-DD\f[] format. +(Only the year is necessary.) Pandoc will attempt to convert other +common date formats. +.RS +.RE +.TP +.B \f[C]lang\f[] (or legacy: \f[C]language\f[]) +A string value in BCP 47 format. +Pandoc will default to the local language if nothing is specified. +.RS +.RE +.TP +.B \f[C]subject\f[] +A string value or a list of such values. +.RS +.RE +.TP +.B \f[C]description\f[] +A string value. +.RS +.RE +.TP +.B \f[C]type\f[] +A string value. +.RS +.RE +.TP +.B \f[C]format\f[] +A string value. +.RS +.RE +.TP +.B \f[C]relation\f[] +A string value. +.RS +.RE +.TP +.B \f[C]coverage\f[] +A string value. +.RS +.RE +.TP +.B \f[C]rights\f[] +A string value. +.RS +.RE +.TP +.B \f[C]cover\-image\f[] +A string value (path to cover image). +.RS +.RE +.TP +.B \f[C]stylesheet\f[] +A string value (path to CSS stylesheet). +.RS +.RE +.TP +.B \f[C]page\-progression\-direction\f[] +Either \f[C]ltr\f[] or \f[C]rtl\f[]. +Specifies the \f[C]page\-progression\-direction\f[] attribute for the +\f[C]spine\f[] element. +.RS +.RE +.SS Linked media +.PP +By default, pandoc will download linked media (including audio and +video) and include it in the EPUB container, yielding a completely +self\-contained EPUB. +If you want to link to external media resources instead, use raw HTML in +your source and add \f[C]data\-external="1"\f[] to the tag with the +\f[C]src\f[] attribute. +For example: +.IP +.nf +\f[C] +<audio\ controls="1"> +\ \ <source\ src="http://example.com/music/toccata.mp3" +\ \ \ \ \ \ \ \ \ \ data\-external="1"\ type="audio/mpeg"> +\ \ </source> +</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. +To see a list of language names that pandoc will recognize, type +\f[C]pandoc\ \-\-list\-highlight\-languages\f[]. +.PP +The color scheme can be selected using the \f[C]\-\-highlight\-style\f[] +option. +The default color scheme is \f[C]pygments\f[], which imitates the +default color scheme used by the Python library pygments (though +pygments is not actually used to do the highlighting). +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 +.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 +formatting (italics, bold) for inlines. +This will work for most purposes, especially alongside a +\f[C]reference.docx\f[] file. +However, if you need to apply your own styles to blocks, or match a +preexisting set of styles, pandoc allows you to define custom styles for +blocks and text using \f[C]div\f[]s and \f[C]span\f[]s, respectively. +.PP +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, +.IP +.nf +\f[C] +<span\ custom\-style="Emphatically">Get\ out,</span>\ he\ said. +\f[] +.fi +.PP +would produce a docx file with \[lq]Get out,\[rq] styled with character +style \f[C]Emphatically\f[]. +Similarly, +.IP +.nf +\f[C] +Dickinson\ starts\ the\ poem\ simply: + +<div\ custom\-style="Poetry"> +|\ A\ Bird\ came\ down\ the\ Walk\-\-\- +|\ He\ did\ not\ know\ I\ saw\-\-\- +</div> +\f[] +.fi +.PP +would style the two contained lines with the \f[C]Poetry\f[] paragraph +style. +.PP +If the styles are not yet in your reference.docx, they will be defined +in the output file as inheriting from normal text. +If they are already defined, pandoc will not alter the definition. +.PP +This feature allows for greatest customization in conjunction with +pandoc filters. +If you want all paragraphs after block quotes to be indented, you can +write a filter to apply the styles necessary. +If you want all italics to be transformed to the \f[C]Emphasis\f[] +character style (perhaps to change their color), you can write a filter +which will transform all italicized inlines to inlines within an +\f[C]Emphasis\f[] custom\-style \f[C]span\f[]. +.SH CUSTOM WRITERS +.PP +Pandoc can be extended with custom writers written in lua. +(Pandoc includes a lua interpreter, so lua need not be installed +separately.) +.PP +To use a custom writer, simply specify the path to the lua script in +place of the output format. +For example: +.IP +.nf +\f[C] +pandoc\ \-t\ data/sample.lua +\f[] +.fi +.PP +Creating a custom writer requires writing a lua function for each +possible element in a pandoc document. +To get a documented example which you can modify according to your +needs, do +.IP +.nf +\f[C] +pandoc\ \-\-print\-default\-data\-file\ sample.lua +\f[] +.fi +.SH AUTHORS +.PP +© 2006\-2016 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. +.PP +The Pandoc source code and all documentation may be downloaded +from <http://pandoc.org>. diff --git a/man/pandoc.1.template b/man/pandoc.1.template new file mode 100644 index 000000000..6a1c26a52 --- /dev/null +++ b/man/pandoc.1.template @@ -0,0 +1,10 @@ +$if(has-tables)$ +.\"t +$endif$ +.TH PANDOC 1 "$date$" "$version$" +.SH NAME +pandoc - general markup converter +$body$ +.PP +The Pandoc source code and all documentation may be downloaded +from <http://pandoc.org>. diff --git a/man/removeLinks.hs b/man/removeLinks.hs new file mode 100644 index 000000000..52414ebd0 --- /dev/null +++ b/man/removeLinks.hs @@ -0,0 +1,9 @@ +import Text.Pandoc.JSON + +main :: IO () +main = toJSONFilter removeLinks + +removeLinks :: Inline -> [Inline] +removeLinks (Link _ l _) = l +removeLinks x = [x] + diff --git a/man/removeNotes.hs b/man/removeNotes.hs new file mode 100644 index 000000000..e61cb932a --- /dev/null +++ b/man/removeNotes.hs @@ -0,0 +1,9 @@ +import Text.Pandoc.JSON + +main :: IO () +main = toJSONFilter removeNotes + +removeNotes :: Inline -> Inline +removeNotes (Note _) = Str "" +removeNotes x = x + |