@@ -1,5 +1,5 @@
11.\"t
2−.TH PANDOC 1 "June 11, 2019" "pandoc 2.7.3"
2+.TH PANDOC 1 "November 16, 2019" "pandoc 2.8"
33.SH NAME
44pandoc - general markup converter
55.SH SYNOPSIS
@@ -183,9 +183,8 @@ set).
183183If the \f[C]mathspec\f[R] variable is set, \f[C]xelatex\f[R] will use
184184\f[C]mathspec\f[R] instead of \f[C]unicode-math\f[R].
185185The \f[C]upquote\f[R] and \f[C]microtype\f[R] packages are used if
186−available, and \f[C]csquotes\f[R] will be used for typography if
187−\f[C]\[rs]usepackage{csquotes}\f[R] is present in the template or
188−included via \f[C]/H/--include-in-header\f[R].
186+available, and \f[C]csquotes\f[R] will be used for typography if the
187+\f[C]csquotes\f[R] variable or metadata field is set to a true value.
189188The \f[C]natbib\f[R], \f[C]biblatex\f[R], \f[C]bibtex\f[R], and
190189\f[C]biber\f[R] packages can optionally be used for citation rendering.
191190The following packages will be used to improve output quality if
@@ -371,6 +370,8 @@ HTML5/XHTML polyglot markup)
371370.IP \[bu] 2
372371\f[C]org\f[R] (Emacs Org mode)
373372.IP \[bu] 2
373+\f[C]pdf\f[R] (PDF)
374+.IP \[bu] 2
374375\f[C]plain\f[R] (plain text),
375376.IP \[bu] 2
376377\f[C]pptx\f[R] (PowerPoint slide show)
@@ -401,8 +402,9 @@ HTML5/XHTML polyglot markup)
401402.IP \[bu] 2
402403the path of a custom lua writer, see Custom writers below
403404.PP
404−Note that \f[C]odt\f[R], \f[C]docx\f[R], and \f[C]epub\f[R] output will
405−not be directed to \f[I]stdout\f[R] unless forced with \f[C]-o -\f[R].
405+Note that \f[C]odt\f[R], \f[C]docx\f[R], \f[C]epub\f[R], and
406+\f[C]pdf\f[R] output will not be directed to \f[I]stdout\f[R] unless
407+forced with \f[C]-o -\f[R].
406408.PP
407409Extensions can be individually enabled or disabled by appending
408410\f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name.
@@ -436,6 +438,20 @@ A \f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
436438\f[C]s5\f[R] directory placed in this directory will override
437439pandoc\[aq]s normal defaults.
438440.TP
441+\f[B]\f[CB]-d\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--defaults=\f[B]\f[R]\f[I]FILE\f[R]
442+Specify a set of default option settings.
443+\f[I]FILE\f[R] is a YAML file whose fields correspond to command-line
444+option settings.
445+All options for document conversion, including input and output files,
446+can be set using a defaults file.
447+The file will be searched for first in the working directory, and then
448+in the \f[C]defaults\f[R] subdirectory of the user data directory (see
449+\f[C]--data-dir\f[R]).
450+The \f[C].yaml\f[R] extension may be omitted.
451+See the section Default files for more information on the file format.
452+Settings from the defaults file may be overridden or extended by
453+subsequent options on the command line.
454+.TP
439455\f[B]\f[CB]--bash-completion\f[B]\f[R]
440456Generate a bash completion script.
441457To enable bash completion with pandoc, add this to your
@@ -471,9 +487,9 @@ List supported input formats, one per line.
471487List supported output formats, one per line.
472488.TP
473489\f[B]\f[CB]--list-extensions\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]FORMAT\f[R]]
474−List supported extensions, one per line, preceded by a \f[C]+\f[R] or
475−\f[C]-\f[R] indicating whether it is enabled by default in
476−\f[I]FORMAT\f[R].
490+List supported extensions for \f[I]FORMAT\f[R], one per line, preceded
491+by a \f[C]+\f[R] or \f[C]-\f[R] indicating whether it is enabled by
492+default in \f[I]FORMAT\f[R].
477493If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[aq]s Markdown
478494are given.
479495.TP
@@ -490,8 +506,29 @@ Print version.
490506\f[B]\f[CB]-h\f[B]\f[R], \f[B]\f[CB]--help\f[B]\f[R]
491507Show usage message.
492508.SS Reader options
509+.PP
510+\f[C]--shift-heading-level-by=\f[R]\f[I]NUMBER\f[R]
511+.IP
512+.nf
513+\f[C]
514+Shift heading levels by a positive or negative integer.
515+For example, with \[ga]--shift-heading-level-by=-1\[ga], level 2
516+headings become level 1 headings, and level 3 headings
517+become level 2 headings. Headings cannot have a level
518+less than 1, so a heading that would be shifted below level 1
519+becomes a regular paragraph. Exception: with a shift of -1,
520+a level-1 heading at the beginning of the document
521+replaces the metadata title. Conversely, with a shift
522+of +1, a nonempty metadata title becomes a level-1 heading at
523+the beginning of the document. \[ga]--shift-heading-level-by=-1\[ga]
524+is a good choice when converting HTML or Markdown documents that
525+use an initial level-1 heading for the document title and
526+level-2+ headings for sections.
527+\f[R]
528+.fi
493529.TP
494530\f[B]\f[CB]--base-header-level=\f[B]\f[R]\f[I]NUMBER\f[R]
531+\f[I]Deprecated. Use \f[CI]--shift-heading-level-by\f[I] instead.\f[R]
495532Specify the base level for headings (defaults to 1).
496533.TP
497534\f[B]\f[CB]--strip-empty-paragraphs\f[B]\f[R]
@@ -567,7 +604,7 @@ Filters and lua-filters are applied in the order specified on the
567604command line.
568605.RE
569606.TP
570−\f[B]\f[CB]--lua-filter=\f[B]\f[R]\f[I]SCRIPT\f[R]
607+\f[B]\f[CB]-L\f[B]\f[R] \f[I]SCRIPT\f[R], \f[B]\f[CB]--lua-filter=\f[B]\f[R]\f[I]SCRIPT\f[R]
571608Transform the document in a similar fashion as JSON filters (see
572609\f[C]--filter\f[R]), but use pandoc\[aq]s build-in lua filtering system.
573610The given lua script is expected to return a list of lua filters which
@@ -625,13 +662,18 @@ This option can be used with every input format, but string scalars in
625662the YAML file will always be parsed as Markdown.
626663Generally, the input will be handled the same as in YAML metadata
627664blocks.
665+This option can be used repeatedly to include multiple metadata files;
666+values in files specified later on the command line will be preferred
667+over those specified in earlier files.
628668Metadata values specified inside the document, or by using \f[C]-M\f[R],
629669overwrite values specified with this option.
630670.TP
631671\f[B]\f[CB]-p\f[B]\f[R], \f[B]\f[CB]--preserve-tabs\f[B]\f[R]
632−Preserve tabs instead of converting them to spaces (the default).
672+Preserve tabs instead of converting them to spaces.
673+(By default, pandoc converts tabs to spaces before parsing its input.)
633674Note that this will only affect tabs in literal code spans and code
634−blocks; tabs in regular text will be treated as spaces.
675+blocks.
676+Tabs in regular text are always treated as spaces.
635677.TP
636678\f[B]\f[CB]--tab-stop=\f[B]\f[R]\f[I]NUMBER\f[R]
637679Specify the number of spaces per tab (default is 4).
@@ -705,9 +747,6 @@ output format will be used (see \f[C]-D/--print-default-template\f[R]).
705747\f[B]\f[CB]-V\f[B]\f[R] \f[I]KEY\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]VAL\f[R]], \f[B]\f[CB]--variable=\f[B]\f[R]\f[I]KEY\f[R][\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]]
706748Set the template variable \f[I]KEY\f[R] to the value \f[I]VAL\f[R] when
707749rendering the document in standalone mode.
708−This is generally only useful when the \f[C]--template\f[R] option is
709−used to specify a custom template, since pandoc automatically sets the
710−variables used in the default templates.
711750If no \f[I]VAL\f[R] is specified, the key will be given the value
712751\f[C]true\f[R].
713752.TP
@@ -718,6 +757,13 @@ in the user data directory are ignored.
718757This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect
719758output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before
720759\f[C]--print-default-template\f[R] on the command line.
760+.RS
761+.PP
762+Note that some of the default templates use partials, for example
763+\f[C]styles.html\f[R].
764+To print the partials, use \f[C]--print-default-data-file\f[R]: for
765+example, \f[C]--print-default-data-file=templates/styles.html\f[R].
766+.RE
721767.TP
722768\f[B]\f[CB]--print-default-data-file=\f[B]\f[R]\f[I]FILE\f[R]
723769Print a system default data file.
@@ -733,10 +779,12 @@ OS on which pandoc is being run).
733779The default is \f[C]native\f[R].
734780.TP
735781\f[B]\f[CB]--dpi\f[B]\f[R]=\f[I]NUMBER\f[R]
736−Specify the dpi (dots per inch) value for conversion from pixels to
737−inch/centimeters and vice versa.
738−The default is 96dpi.
739−Technically, the correct term would be ppi (pixels per inch).
782+Specify the default dpi (dots per inch) value for conversion from pixels
783+to inch/centimeters and vice versa.
784+(Technically, the correct term would be ppi: pixels per inch.) The
785+default is 96dpi.
786+When images contain information about dpi internally, the encoded value
787+is used instead of the default specified by this option.
740788.TP
741789\f[B]\f[CB]--wrap=auto\f[B]\f[R]|\f[B]\f[CB]none\f[B]\f[R]|\f[B]\f[CB]preserve\f[B]\f[R]
742790Determine how text is wrapped in the output (the source code, not the
@@ -823,6 +871,7 @@ Instructs pandoc to load a KDE XML syntax definition file, which will be
823871used for syntax highlighting of appropriately marked code blocks.
824872This can be used to add support for new languages or to use altered
825873syntax definitions for existing languages.
874+This option may be repeated to add multiple syntax definitions.
826875.TP
827876\f[B]\f[CB]-H\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--include-in-header=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
828877Include contents of \f[I]FILE\f[R], verbatim, at the end of the header.
@@ -943,7 +992,7 @@ The hierarchy order is part, chapter, then section; all headings are
943992shifted such that the top-level heading becomes the specified type.
944993The default behavior is to determine the best division type via
945994heuristics: unless other conditions apply, \f[C]section\f[R] is chosen.
946−When the LaTeX document class is set to \f[C]report\f[R],
995+When the \f[C]documentclass\f[R] variable is set to \f[C]report\f[R],
947996\f[C]book\f[R], or \f[C]memoir\f[R] (unless the \f[C]article\f[R] option
948997is specified), \f[C]chapter\f[R] is implied as the setting for this
949998option.
@@ -1443,6 +1492,321 @@ pandoc -o foo.html -s
14431492\f[R]
14441493.fi
14451494.RE
1495+.SH EXIT CODES
1496+.PP
1497+If pandoc completes successfully, it will return exit code 0.
1498+Nonzero exit codes have the following meanings:
1499+.PP
1500+.TS
1501+tab(@);
1502+r l.
1503+T{
1504+Code
1505+T}@T{
1506+Error
1507+T}
1508+_
1509+T{
1510+3
1511+T}@T{
1512+PandocFailOnWarningError
1513+T}
1514+T{
1515+4
1516+T}@T{
1517+PandocAppError
1518+T}
1519+T{
1520+5
1521+T}@T{
1522+PandocTemplateError
1523+T}
1524+T{
1525+6
1526+T}@T{
1527+PandocOptionError
1528+T}
1529+T{
1530+21
1531+T}@T{
1532+PandocUnknownReaderError
1533+T}
1534+T{
1535+22
1536+T}@T{
1537+PandocUnknownWriterError
1538+T}
1539+T{
1540+23
1541+T}@T{
1542+PandocUnsupportedExtensionError
1543+T}
1544+T{
1545+31
1546+T}@T{
1547+PandocEpubSubdirectoryError
1548+T}
1549+T{
1550+43
1551+T}@T{
1552+PandocPDFError
1553+T}
1554+T{
1555+47
1556+T}@T{
1557+PandocPDFProgramNotFoundError
1558+T}
1559+T{
1560+61
1561+T}@T{
1562+PandocHttpError
1563+T}
1564+T{
1565+62
1566+T}@T{
1567+PandocShouldNeverHappenError
1568+T}
1569+T{
1570+63
1571+T}@T{
1572+PandocSomeError
1573+T}
1574+T{
1575+64
1576+T}@T{
1577+PandocParseError
1578+T}
1579+T{
1580+65
1581+T}@T{
1582+PandocParsecError
1583+T}
1584+T{
1585+66
1586+T}@T{
1587+PandocMakePDFError
1588+T}
1589+T{
1590+67
1591+T}@T{
1592+PandocSyntaxMapError
1593+T}
1594+T{
1595+83
1596+T}@T{
1597+PandocFilterError
1598+T}
1599+T{
1600+91
1601+T}@T{
1602+PandocMacroLoop
1603+T}
1604+T{
1605+92
1606+T}@T{
1607+PandocUTF8DecodingError
1608+T}
1609+T{
1610+93
1611+T}@T{
1612+PandocIpynbDecodingError
1613+T}
1614+T{
1615+97
1616+T}@T{
1617+PandocCouldNotFindDataFileError
1618+T}
1619+T{
1620+99
1621+T}@T{
1622+PandocResourceNotFound
1623+T}
1624+.TE
1625+.SH DEFAULT FILES
1626+.PP
1627+The \f[C]--defaults\f[R] option may be used to specify a package of
1628+options.
1629+Here is a sample defaults file demonstrating all of the fields that may
1630+be used:
1631+.IP
1632+.nf
1633+\f[C]
1634+from: markdown+emoji
1635+# reader: may be used instead of from:
1636+to: html5
1637+# writer: may be used instead of to:
1638+
1639+# leave blank for output to stdout:
1640+output-file:
1641+# leave blank for input from stdin, use [] for no input:
1642+input-files:
1643+- preface.md
1644+- content.md
1645+# or you may use input-file: with a single value
1646+
1647+template: letter
1648+standalone: true
1649+self-contained: false
1650+
1651+# note that structured variables may be specified:
1652+variables:
1653+ documentclass: book
1654+ classoption:
1655+ - twosides
1656+ - draft
1657+
1658+# metadata values specified here are parsed as literal
1659+# string text, not markdown:
1660+metadata:
1661+ author:
1662+ - Sam Smith
1663+ - Julie Liu
1664+metadata-files:
1665+- boilerplate.yaml
1666+# or you may use metadata-file: with a single value
1667+
1668+# Note that these take files, not their contents:
1669+include-before-body: []
1670+include-after-body: []
1671+include-in-header: []
1672+resource-path: [\[dq].\[dq]]
1673+
1674+# filters will be assumed to be lua filters if they have
1675+# the .lua extension, and json filters otherwise. But
1676+# the filter type can also be specified explicitly, as shown:
1677+filters:
1678+- pandoc-citeproc
1679+- wordcount.lua
1680+- type: json
1681+ path: foo.lua
1682+
1683+file-scope: false
1684+
1685+data-dir:
1686+
1687+# ERROR, WARNING, or INFO
1688+verbosity: INFO
1689+log-file: log.json
1690+
1691+# citeproc, natbib, or biblatex
1692+cite-method: citeproc
1693+# part, chapter, section, or default:
1694+top-level-division: chapter
1695+abbreviations:
1696+
1697+pdf-engine: pdflatex
1698+pdf-engine-opts:
1699+- \[dq]-shell-escape\[dq]
1700+# you may also use pdf-engine-opt: with a single option
1701+# pdf-engine-opt: \[dq]-shell-escape\[dq]
1702+
1703+# auto, preserve, or none
1704+wrap: auto
1705+columns: 78
1706+dpi: 72
1707+
1708+extract-media: mediadir
1709+
1710+table-of-contents: true
1711+toc-depth: 2
1712+number-sections: false
1713+# a list of offsets at each heading level
1714+number-offset: [0,0,0,0,0,0]
1715+# toc: may also be used instead of table-of-contents:
1716+shift-heading-level-by: 1
1717+section-divs: true
1718+identifier-prefix: foo
1719+title-prefix: \[dq]\[dq]
1720+strip-empty-paragraphs: true
1721+# lf, crlf, or native
1722+eol: lf
1723+strip-comments: false
1724+indented-code-classes: []
1725+ascii: true
1726+default-image-extension: \[dq].jpg\[dq]
1727+
1728+# either a style name of a style definition file:
1729+highlight-style: pygments
1730+syntax-definitions:
1731+- c.xml
1732+# or you may use syntax-definition: with a single value
1733+listings: false
1734+
1735+reference-doc: myref.docx
1736+
1737+# method is plain, webtex, gladtex, mathml, mathjax, katex
1738+# you may specify a url with webtex, mathjax, katex
1739+html-math-method:
1740+ method: mathjax
1741+ url: \[dq]https://cdn.jsdelivr.net/npm/mathjax\[at]3/es5/tex-mml-chtml.js\[dq]
1742+# none, references, or javascript
1743+email-obfuscation: javascript
1744+
1745+tab-stop: 8
1746+preserve-tabs: true
1747+
1748+incremental: false
1749+slide-level: 2
1750+
1751+epub-subdirectory: EPUB
1752+epub-metadata: meta.xml
1753+epub-fonts:
1754+- foobar.otf
1755+epub-chapter-level: 1
1756+epub-cover-image: cover.jpg
1757+
1758+reference-links: true
1759+# block, section, or document
1760+reference-location: block
1761+atx-headers: false
1762+
1763+# accept, reject, or all
1764+track-changes: accept
1765+
1766+html-q-tags: false
1767+css:
1768+- site.css
1769+
1770+# none, all, or best
1771+ipynb-output: best
1772+
1773+# A list of two-element lists
1774+request-headers:
1775+- [\[dq]User-Agent\[dq], \[dq]Mozilla/5.0\[dq]]
1776+
1777+fail-if-warnings: false
1778+dump-args: false
1779+ignore-args: false
1780+trace: false
1781+\f[R]
1782+.fi
1783+.PP
1784+Fields that are omitted will just have their regular default values.
1785+So a defaults file can be as simple as one line:
1786+.IP
1787+.nf
1788+\f[C]
1789+verbosity: INFO
1790+\f[R]
1791+.fi
1792+.PP
1793+Default files can be placed in the \f[C]defaults\f[R] subdirectory of
1794+the user data directory and used from any directory.
1795+For example, one could create a file specifying defaults for writing
1796+letters, save it as \f[C]letter.yaml\f[R] in the \f[C]defaults\f[R]
1797+subdirectory of the user data directory, and then invoke these defaults
1798+from any directory using \f[C]pandoc --defaults letter\f[R] or
1799+\f[C]pandoc -dletter\f[R].
1800+.PP
1801+When multiple defaults are used, their contents will be combined.
1802+.PP
1803+Note that, where command-line arguments may be repeated
1804+(\f[C]--metadata-file\f[R], \f[C]--css\f[R],
1805+\f[C]--include-in-header\f[R], \f[C]--include-before-body\f[R],
1806+\f[C]--include-after-body\f[R], \f[C]--variable\f[R],
1807+\f[C]--metadata\f[R], \f[C]--syntax-definition\f[R]), the values
1808+specified on the command line will combine with values specified in the
1809+defaults file, rather than replacing them.
14461810.SH TEMPLATES
14471811.PP
14481812When the \f[C]-s/--standalone\f[R] option is used, pandoc uses a
@@ -1482,8 +1846,389 @@ arbitrary information at any point in the file.
14821846They may be set at the command line using the \f[C]-V/--variable\f[R]
14831847option.
14841848If a variable is not set, pandoc will look for the key in the
1485−document\[aq]s metadata \[en] which can be set using either YAML
1486−metadata blocks or with the \f[C]-M/--metadata\f[R] option.
1849+document\[aq]s metadata, which can be set using either YAML metadata
1850+blocks or with the \f[C]-M/--metadata\f[R] option.
1851+In addition, some variables are given default values by pandoc.
1852+See Variables below for a list of variables used in pandoc\[aq]s default
1853+templates.
1854+.PP
1855+If you use custom templates, you may need to revise them as pandoc
1856+changes.
1857+We recommend tracking the changes in the default templates, and
1858+modifying your custom templates accordingly.
1859+An easy way to do this is to fork the pandoc-templates repository and
1860+merge in changes after each pandoc release.
1861+.SS Template syntax
1862+.SS Comments
1863+.PP
1864+Anything between the sequence \f[C]$--\f[R] and the end of the line will
1865+be treated as a comment and omitted from the output.
1866+.SS Delimiters
1867+.PP
1868+To mark variables and control structures in the template, either
1869+\f[C]$\f[R]...\f[C]$\f[R] or \f[C]${\f[R]...\f[C]}\f[R] may be used as
1870+delimiters.
1871+The styles may also be mixed in the same template, but the opening and
1872+closing delimiter must match in each case.
1873+The opening delimiter may be followed by one or more spaces or tabs,
1874+which will be ignored.
1875+The closing delimiter may be followed by one or more spaces or tabs,
1876+which will be ignored.
1877+.PP
1878+To include a literal \f[C]$\f[R] in the document, use \f[C]$$\f[R].
1879+.SS Interpolated variables
1880+.PP
1881+A slot for an interpolated variable is a variable name surrounded by
1882+matched delimiters.
1883+Variable names must begin with a letter and can contain letters,
1884+numbers, \f[C]_\f[R], \f[C]-\f[R], and \f[C].\f[R].
1885+The keywords \f[C]it\f[R], \f[C]if\f[R], \f[C]else\f[R],
1886+\f[C]endif\f[R], \f[C]for\f[R], \f[C]sep\f[R], and \f[C]endfor\f[R] may
1887+not be used as variable names.
1888+Examples:
1889+.IP
1890+.nf
1891+\f[C]
1892+$foo$
1893+$foo.bar.baz$
1894+$foo_bar.baz-bim$
1895+$ foo $
1896+${foo}
1897+${foo.bar.baz}
1898+${foo_bar.baz-bim}
1899+${ foo }
1900+\f[R]
1901+.fi
1902+.PP
1903+Variable names with periods are used to get at structured variable
1904+values.
1905+So, for example, \f[C]employee.salary\f[R] will return the value of the
1906+\f[C]salary\f[R] field of the object that is the value of the
1907+\f[C]employee\f[R] field.
1908+.IP \[bu] 2
1909+If the value of the variable is simple value, it will be rendered
1910+verbatim.
1911+(Note that no escaping is done; the assumption is that the calling
1912+program will escape the strings appropriately for the output format.)
1913+.IP \[bu] 2
1914+If the value is a list, the values will be concatenated.
1915+.IP \[bu] 2
1916+If the value is a map, the string \f[C]true\f[R] will be rendered.
1917+.IP \[bu] 2
1918+Every other value will be rendered as the empty string.
1919+.SS Conditionals
1920+.PP
1921+A conditional begins with \f[C]if(variable)\f[R] (enclosed in matched
1922+delimiters) and ends with \f[C]endif\f[R] (enclosed in matched
1923+delimiters).
1924+It may optionally contain an \f[C]else\f[R] (enclosed in matched
1925+delimiters).
1926+The \f[C]if\f[R] section is used if \f[C]variable\f[R] has a non-empty
1927+value, otherwise the \f[C]else\f[R] section is used (if present).
1928+Examples:
1929+.IP
1930+.nf
1931+\f[C]
1932+$if(foo)$bar$endif$
1933+
1934+$if(foo)$
1935+ $foo$
1936+$endif$
1937+
1938+$if(foo)$
1939+part one
1940+$else$
1941+part two
1942+$endif$
1943+
1944+${if(foo)}bar${endif}
1945+
1946+${if(foo)}
1947+ ${foo}
1948+${endif}
1949+
1950+${if(foo)}
1951+${ foo.bar }
1952+${else}
1953+no foo!
1954+${endif}
1955+\f[R]
1956+.fi
1957+.PP
1958+The keyword \f[C]elseif\f[R] may be used to simplify complex nested
1959+conditionals:
1960+.IP
1961+.nf
1962+\f[C]
1963+$if(foo)$
1964+XXX
1965+$elseif(bar)$
1966+YYY
1967+$else$
1968+ZZZ
1969+$endif$
1970+\f[R]
1971+.fi
1972+.SS For loops
1973+.PP
1974+A for loop begins with \f[C]for(variable)\f[R] (enclosed in matched
1975+delimiters) and ends with \f[C]endfor\f[R] (enclosed in matched
1976+delimiters.
1977+.IP \[bu] 2
1978+If \f[C]variable\f[R] is an array, the material inside the loop will be
1979+evaluated repeatedly, with \f[C]variable\f[R] being set to each value of
1980+the array in turn, and concatenated.
1981+.IP \[bu] 2
1982+If the value of the associated variable is not an array or a map, a
1983+single iteration will be performed on its value.
1984+.PP
1985+Examples:
1986+.IP
1987+.nf
1988+\f[C]
1989+$for(foo)$$foo$$sep$, $endfor$
1990+
1991+$for(foo)$
1992+ - $foo.last$, $foo.first$
1993+$endfor$
1994+
1995+${ for(foo.bar) }
1996+ - ${ foo.bar.last }, ${ foo.bar.first }
1997+${ endfor }
1998+\f[R]
1999+.fi
2000+.PP
2001+You may optionally specify a separator between consecutive values using
2002+\f[C]sep\f[R] (enclosed in matched delimiters).
2003+The material between \f[C]sep\f[R] and the \f[C]endfor\f[R] is the
2004+separator.
2005+.IP
2006+.nf
2007+\f[C]
2008+${ for(foo) }${ foo }${ sep }, ${ endfor }
2009+\f[R]
2010+.fi
2011+.PP
2012+Instead of using \f[C]variable\f[R] inside the loop, the special
2013+anaphoric keyword \f[C]it\f[R] may be used.
2014+.IP
2015+.nf
2016+\f[C]
2017+${ for(foo.bar) }
2018+ - ${ it.last }, ${ it.first }
2019+${ endfor }
2020+\f[R]
2021+.fi
2022+.SS Partials
2023+.PP
2024+Partials (subtemplates stored in different files) may be included using
2025+the syntax
2026+.IP
2027+.nf
2028+\f[C]
2029+${ boilerplate() }
2030+\f[R]
2031+.fi
2032+.PP
2033+Partials will be sought in the directory containing the main template,
2034+and will be assumed to have the same extension as the main template if
2035+they lack an explicit extension.
2036+(If the partials are not found here, they will also be sought in the
2037+\f[C]templates\f[R] subdirectory of the user data directory.)
2038+.PP
2039+Partials may optionally be applied to variables using a colon:
2040+.IP
2041+.nf
2042+\f[C]
2043+${ date:fancy() }
2044+
2045+${ articles:bibentry() }
2046+\f[R]
2047+.fi
2048+.PP
2049+If \f[C]articles\f[R] is an array, this will iterate over its values,
2050+applying the partial \f[C]bibentry()\f[R] to each one.
2051+So the second example above is equivalent to
2052+.IP
2053+.nf
2054+\f[C]
2055+${ for(articles) }
2056+${ it:bibentry() }
2057+${ endfor }
2058+\f[R]
2059+.fi
2060+.PP
2061+Note that the anaphoric keyword \f[C]it\f[R] must be used when iterating
2062+over partials.
2063+In the above examples, the \f[C]bibentry\f[R] partial should contain
2064+\f[C]it.title\f[R] (and so on) instead of \f[C]articles.title\f[R].
2065+.PP
2066+Final newlines are omitted from included partials.
2067+.PP
2068+Partials may include other partials.
2069+.PP
2070+A separator between values of an array may be specified in square
2071+brackets, immediately after the variable name or partial:
2072+.IP
2073+.nf
2074+\f[C]
2075+${months[, ]}$
2076+
2077+${articles:bibentry()[; ]$
2078+\f[R]
2079+.fi
2080+.PP
2081+The separator in this case is literal and (unlike with \f[C]sep\f[R] in
2082+an explicit \f[C]for\f[R] loop) cannot contain interpolated variables or
2083+other template directives.
2084+.SS Nesting
2085+.PP
2086+To ensure that content is \[dq]nested,\[dq] that is, subsequent lines
2087+indented, use the \f[C]\[ha]\f[R] directive:
2088+.IP
2089+.nf
2090+\f[C]
2091+$item.number$ $\[ha]$$item.description$ ($item.price$)
2092+\f[R]
2093+.fi
2094+.PP
2095+In this example, if \f[C]item.description\f[R] has multiple lines, they
2096+will all be indented to line up with the first line:
2097+.IP
2098+.nf
2099+\f[C]
2100+00123 A fine bottle of 18-year old
2101+ Oban whiskey. ($148)
2102+\f[R]
2103+.fi
2104+.PP
2105+To nest multiple lines to the same level, align them with the
2106+\f[C]\[ha]\f[R] directive in the template.
2107+For example:
2108+.IP
2109+.nf
2110+\f[C]
2111+$item.number$ $\[ha]$$item.description$ ($item.price$)
2112+ (Available til $item.sellby$.)
2113+\f[R]
2114+.fi
2115+.PP
2116+will produce
2117+.IP
2118+.nf
2119+\f[C]
2120+00123 A fine bottle of 18-year old
2121+ Oban whiskey. ($148)
2122+ (Available til March 30, 2020.)
2123+\f[R]
2124+.fi
2125+.PP
2126+If a variable occurs by itself on a line, preceded by whitespace and not
2127+followed by further text or directives on the same line, and the
2128+variable\[aq]s value contains multiple lines, it will be nested
2129+automatically.
2130+.SS Breakable spaces
2131+.PP
2132+Normally, spaces in the template itself (as opposed to values of the
2133+interpolated variables) are not breakable, but they can be made
2134+breakable in part of the template by using the \f[C]\[ti]\f[R] keyword
2135+(ended with another \f[C]\[ti]\f[R]).
2136+.IP
2137+.nf
2138+\f[C]
2139+$\[ti]$This long line may break if the document is rendered
2140+with a short line length.$\[ti]$
2141+\f[R]
2142+.fi
2143+.SS Filters
2144+.PP
2145+A filter transforms the value of a variable.
2146+Filters are specified using a slash (\f[C]/\f[R]) between the variable
2147+name and the filter name.
2148+They may go anywhere a variable can go.
2149+Example:
2150+.IP
2151+.nf
2152+\f[C]
2153+$for(name)$
2154+$name/uppercase$
2155+$endfor$
2156+
2157+$for(metadata/pairs)$
2158+- $it.key$: $it.value$
2159+$endfor$
2160+\f[R]
2161+.fi
2162+.PP
2163+Filters may be chained:
2164+.IP
2165+.nf
2166+\f[C]
2167+$for(employees/pairs)$
2168+$it.key/alpha/uppercase$. $it.name$
2169+$endfor$
2170+\f[R]
2171+.fi
2172+.PP
2173+Some filters take parameters:
2174+.IP
2175+.nf
2176+\f[C]
2177+|----------------------|------------|
2178+$for(employee)$
2179+$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$
2180+$endfor$
2181+|----------------------|------------|
2182+\f[R]
2183+.fi
2184+.PP
2185+Currently the following filters are predefined:
2186+.IP \[bu] 2
2187+\f[C]pairs\f[R]: Converts a map or array to an array of maps, each with
2188+\f[C]key\f[R] and \f[C]value\f[R] fields.
2189+If the original value was an array, the \f[C]key\f[R] will be the array
2190+index, starting with 1.
2191+.IP \[bu] 2
2192+\f[C]uppercase\f[R]: Converts a textual value to uppercase, and has no
2193+effect on other values.
2194+.IP \[bu] 2
2195+\f[C]lowercase\f[R]: Converts a textual value to lowercase, and has no
2196+effect on other values.
2197+.IP \[bu] 2
2198+\f[C]length\f[R]: Returns the length of the value: number of characters
2199+for a textual value, number of elements for a map or array.
2200+.IP \[bu] 2
2201+\f[C]reverse\f[R]: Reverses a textual value or array, and has no effect
2202+on other values.
2203+.IP \[bu] 2
2204+\f[C]alpha\f[R]: Converts a textual value that can be read as an integer
2205+into a lowercase alphabetic character \f[C]a..z\f[R] (mod 26), and has
2206+no effect on other values.
2207+This can be used to get lettered enumeration from array indices.
2208+To get uppercase letters, chain with \f[C]uppercase\f[R].
2209+.IP \[bu] 2
2210+\f[C]roman\f[R]: Converts a textual value that can be read as an integer
2211+into a lowercase roman numerial, and has no effect on other values.
2212+This can be used to get lettered enumeration from array indices.
2213+To get uppercase roman, chain with \f[C]uppercase\f[R].
2214+.IP \[bu] 2
2215+\f[C]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a
2216+textual value in a block of width \f[C]n\f[R], aligned to the left, with
2217+an optional left and right border.
2218+Has no effect on other values.
2219+This can be used to align material in tables.
2220+Widths are positive integers indicating the number of characters.
2221+Borders are strings inside double quotes; literal \f[C]\[dq]\f[R] and
2222+\f[C]\[rs]\f[R] characters must be backslash-escaped.
2223+.IP \[bu] 2
2224+\f[C]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a
2225+textual value in a block of width \f[C]n\f[R], aligned to the right, and
2226+has no effect on other values.
2227+.IP \[bu] 2
2228+\f[C]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a
2229+textual value in a block of width \f[C]n\f[R], aligned to the center,
2230+and has no effect on other values.
2231+.SS Variables
14872232.SS Metadata variables
14882233.TP
14892234\f[B]\f[CB]title\f[B]\f[R], \f[B]\f[CB]author\f[B]\f[R], \f[B]\f[CB]date\f[B]\f[R]
@@ -1605,10 +2350,18 @@ Algorithm.
16052350When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[R]
16062351engine is fully supported (use \f[C]--pdf-engine=xelatex\f[R]).
16072352.RE
2353+.SS Variables for HTML math
2354+.TP
2355+\f[B]\f[CB]classoption\f[B]\f[R]
2356+when using KaTeX, you can render display math equations flush left using
2357+YAML metadata or with \f[C]-M classoption=fleqn\f[R].
16082358.SS Variables for HTML slides
16092359.PP
16102360These affect HTML output when producing slide shows with pandoc.
2361+.PP
16112362All reveal.js configuration options are available as variables.
2363+To turn off boolean flags that default to true in reveal.js, use
2364+\f[C]0\f[R].
16122365.TP
16132366\f[B]\f[CB]revealjs-url\f[B]\f[R]
16142367base URL for reveal.js documents (defaults to \f[C]reveal.js\f[R])
@@ -1653,14 +2406,14 @@ navigation symbols; other valid values are \f[C]frame\f[R],
16532406enables \[dq]title pages\[dq] for new sections (default is true)
16542407.TP
16552408\f[B]\f[CB]theme\f[B]\f[R], \f[B]\f[CB]colortheme\f[B]\f[R], \f[B]\f[CB]fonttheme\f[B]\f[R], \f[B]\f[CB]innertheme\f[B]\f[R], \f[B]\f[CB]outertheme\f[B]\f[R]
1656−beamer themes:
2409+beamer themes
16572410.TP
16582411\f[B]\f[CB]themeoptions\f[B]\f[R]
16592412options for LaTeX beamer themes (a list).
16602413.TP
16612414\f[B]\f[CB]titlegraphic\f[B]\f[R]
16622415image for title slide
1663−.SS Variables for PowerPoint slide shows
2416+.SS Variables for PowerPoint
16642417.PP
16652418These variables control the visual aspects of a slide show that are not
16662419easily controled via templates.
@@ -1740,6 +2493,23 @@ geometry:
17402493.fi
17412494.RE
17422495.TP
2496+\f[B]\f[CB]hyperrefoptions\f[B]\f[R]
2497+option for \f[C]hyperref\f[R] package, e.g.
2498+\f[C]linktoc=all\f[R]; repeat for multiple options:
2499+.RS
2500+.IP
2501+.nf
2502+\f[C]
2503+---
2504+hyperrefoptions:
2505+- linktoc=all
2506+- pdfwindowui
2507+- pdfpagemode=FullScreen
2508+\&...
2509+\f[R]
2510+.fi
2511+.RE
2512+.TP
17432513\f[B]\f[CB]indent\f[B]\f[R]
17442514uses document class settings for indentation (the default LaTeX template
17452515otherwise removes indentation and adds space between paragraphs)
@@ -1935,13 +2705,38 @@ paper size, e.g.
19352705Setup); repeat for multiple options
19362706.TP
19372707\f[B]\f[CB]pdfa\f[B]\f[R]
1938−adds to the preamble the setup necessary to generate PDF/A-1b:2005.
2708+adds to the preamble the setup necessary to generate PDF/A of the type
2709+specified, e.g.
2710+\f[C]1a:2005\f[R], \f[C]2a\f[R].
2711+If no type is specified (i.e.
2712+the value is set to True, by e.g.
2713+\f[C]--metadata=pdfa\f[R] or \f[C]pdfa: true\f[R] in a YAML metadata
2714+block), \f[C]1b:2005\f[R] will be used as default, for reasons of
2715+backwards compatibility.
2716+Using \f[C]--variable=pdfa\f[R] without specified value is not
2717+supported.
19392718To successfully generate PDF/A the required ICC color profiles have to
19402719be available and the content and all included files (such as images)
19412720have to be standard conforming.
1942−The ICC profiles can be obtained from ConTeXt ICC Profiles.
2721+The ICC profiles and output intent may be specified using the variables
2722+\f[C]pdfaiccprofile\f[R] and \f[C]pdfaintent\f[R].
19432723See also ConTeXt PDFA for more details.
19442724.TP
2725+\f[B]\f[CB]pdfaiccprofile\f[B]\f[R]
2726+when used in conjunction with \f[C]pdfa\f[R], specifies the ICC profile
2727+to use in the PDF, e.g.
2728+\f[C]default.cmyk\f[R].
2729+If left unspecified, \f[C]sRGB.icc\f[R] is used as default.
2730+May be repeated to include multiple profiles.
2731+Note that the profiles have to be available on the system.
2732+They can be obtained from ConTeXt ICC Profiles.
2733+.TP
2734+\f[B]\f[CB]pdfaintent\f[B]\f[R]
2735+when used in conjunction with \f[C]pdfa\f[R], specifies the output
2736+intent for the colors, e.g.
2737+\f[C]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If left
2738+unspecified, \f[C]sRGB IEC61966-2.1\f[R] is used as default.
2739+.TP
19452740\f[B]\f[CB]toc\f[B]\f[R]
19462741include table of contents (can also be set using
19472742\f[C]--toc/--table-of-contents\f[R])
@@ -1949,6 +2744,9 @@ include table of contents (can also be set using
19492744\f[B]\f[CB]whitespace\f[B]\f[R]
19502745spacing between paragraphs, e.g.
19512746\f[C]none\f[R], \f[C]small\f[R] (using \f[C]setupwhitespace\f[R])
2747+.TP
2748+\f[B]\f[CB]includesource\f[B]\f[R]
2749+include all source documents as file attachments in the PDF file
19522750.SS Variables for \f[C]wkhtmltopdf\f[R]
19532751.PP
19542752Pandoc uses these variables when creating a PDF with
@@ -1997,7 +2795,7 @@ line height (e.g.
19972795\f[B]\f[CB]pointsize\f[B]\f[R]
19982796point size (e.g.
19992797\f[C]10p\f[R])
2000−.SS Structural variables
2798+.SS Variables set automatically
20012799.PP
20022800Pandoc sets these variables automatically in response to options or
20032801document contents; users can also modify them.
@@ -2073,104 +2871,6 @@ non-null value if \f[C]--toc/--table-of-contents\f[R] was specified
20732871\f[B]\f[CB]toc-title\f[B]\f[R]
20742872title of table of contents (works only with EPUB, opendocument, odt,
20752873docx, pptx, beamer, LaTeX)
2076−.SS Using variables in templates
2077−.PP
2078−Variable names are sequences of alphanumerics, \f[C]-\f[R], and
2079−\f[C]_\f[R], starting with a letter.
2080−A variable name surrounded by \f[C]$\f[R] signs will be replaced by its
2081−value.
2082−For example, the string \f[C]$title$\f[R] in
2083−.IP
2084−.nf
2085−\f[C]
2086−<title>$title$</title>
2087−\f[R]
2088−.fi
2089−.PP
2090−will be replaced by the document title.
2091−.PP
2092−To write a literal \f[C]$\f[R] in a template, use \f[C]$$\f[R].
2093−.PP
2094−Templates may contain conditionals.
2095−The syntax is as follows:
2096−.IP
2097−.nf
2098−\f[C]
2099−$if(variable)$
2100−X
2101−$else$
2102−Y
2103−$endif$
2104−\f[R]
2105−.fi
2106−.PP
2107−This will include \f[C]X\f[R] in the template if \f[C]variable\f[R] has
2108−a truthy value; otherwise it will include \f[C]Y\f[R].
2109−Here a truthy value is any of the following:
2110−.IP \[bu] 2
2111−a string that is not entirely white space,
2112−.IP \[bu] 2
2113−a non-empty array where the first value is truthy,
2114−.IP \[bu] 2
2115−any number (including zero),
2116−.IP \[bu] 2
2117−any object,
2118−.IP \[bu] 2
2119−the boolean \f[C]true\f[R] (to specify the boolean \f[C]true\f[R] value
2120−using YAML metadata or the \f[C]--metadata\f[R] flag, use
2121−\f[C]true\f[R], \f[C]True\f[R], or \f[C]TRUE\f[R]; with the
2122−\f[C]--variable\f[R] flag, simply omit a value for the variable, e.g.
2123−\f[C]--variable draft\f[R]).
2124−.PP
2125−\f[C]X\f[R] and \f[C]Y\f[R] are placeholders for any valid template
2126−text, and may include interpolated variables or other conditionals.
2127−The \f[C]$else$\f[R] section may be omitted.
2128−.PP
2129−When variables can have multiple values (for example, \f[C]author\f[R]
2130−in a multi-author document), you can use the \f[C]$for$\f[R] keyword:
2131−.IP
2132−.nf
2133−\f[C]
2134−$for(author)$
2135−<meta name=\[dq]author\[dq] content=\[dq]$author$\[dq] />
2136−$endfor$
2137−\f[R]
2138−.fi
2139−.PP
2140−You can optionally specify a separator to be used between consecutive
2141−items:
2142−.IP
2143−.nf
2144−\f[C]
2145−$for(author)$$author$$sep$, $endfor$
2146−\f[R]
2147−.fi
2148−.PP
2149−Note that the separator needs to be specified immediately before the
2150−\f[C]$endfor\f[R] keyword.
2151−.PP
2152−A dot can be used to select a field of a variable that takes an object
2153−as its value.
2154−So, for example:
2155−.IP
2156−.nf
2157−\f[C]
2158−$author.name$ ($author.affiliation$)
2159−\f[R]
2160−.fi
2161−.PP
2162−The value of a variable will be indented to the same level as the
2163−variable.
2164−.PP
2165−If you use custom templates, you may need to revise them as pandoc
2166−changes.
2167−We recommend tracking the changes in the default templates, and
2168−modifying your custom templates accordingly.
2169−An easy way to do this is to fork the pandoc-templates repository and
2170−merge in changes after each pandoc release.
2171−.PP
2172−Templates may contain comments: anything on a line after \f[C]$--\f[R]
2173−will be treated as a comment and ignored.
21742874.SH EXTENSIONS
21752875.PP
21762876The behavior of some of the readers and writers can be adjusted by
@@ -2352,6 +3052,7 @@ GitHub\[aq]s method.
23523052Spaces are converted to dashes (\f[C]-\f[R]), uppercase characters to
23533053lowercase characters, and punctuation characters other than \f[C]-\f[R]
23543054and \f[C]_\f[R] are removed.
3055+Emojis are replaced by their names.
23553056.SS Math Input
23563057.PP
23573058The extensions \f[C]tex_math_dollars\f[R],
@@ -2499,6 +3200,15 @@ input formats
24993200.TP
25003201output formats
25013202\f[C]docx\f[R], \f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]html\f[R]
3203+.SS Extension: \f[C]native_numbering\f[R]
3204+.PP
3205+Enables native numbering of figures and tables.
3206+Enumeration starts at 1.
3207+.PP
3208+This extension can be enabled/disabled for the following formats:
3209+.TP
3210+output formats
3211+\f[C]odt\f[R], \f[C]opendocument\f[R]
25023212.SS Extension: \f[C]styles\f[R]
25033213.PP
25043214When converting from docx, read all docx styles as divs (for paragraph
@@ -2693,6 +3403,12 @@ is just the same as
26933403# My heading {.unnumbered}
26943404\f[R]
26953405.fi
3406+.PP
3407+If the \f[C]unlisted\f[R] class is present in addition to
3408+\f[C]unnumbered\f[R], the heading will not be included in a table of
3409+contents.
3410+(Currently this feature is only implemented for certain formats: those
3411+based on LaTeX and HTML, PowerPoint, and RTF.)
26963412.SS Extension: \f[C]implicit_header_references\f[R]
26973413.PP
26983414Pandoc behaves as if reference links have been defined for each heading.
@@ -3577,7 +4293,8 @@ can be omitted for a headerless table.
35774293The cells of grid tables may contain arbitrary block elements (multiple
35784294paragraphs, code blocks, lists, etc.).
35794295Cells that span multiple columns or rows are not supported.
3580−Grid tables can be created easily using Emacs table mode.
4296+Grid tables can be created easily using Emacs\[aq] table-mode
4297+(\f[C]M-x table-insert\f[R]).
35814298.PP
35824299Alignments can be specified as with pipe tables, by putting colons at
35834300the boundaries of the separator line after the header:
@@ -3818,9 +4535,8 @@ be interpretable as YAML numbers or boolean values (so, for example,
38184535names).
38194536.PP
38204537A document may contain multiple metadata blocks.
3821−The metadata fields will be combined through a \f[I]left-biased
3822−union\f[R]: if two metadata blocks attempt to set the same field, the
3823−value from the first block will be taken.
4538+If two metadata blocks attempt to set the same field, the value from the
4539+second block will be taken.
38244540.PP
38254541When pandoc is used with \f[C]-t markdown\f[R] to create a Markdown
38264542document, a YAML metadata block will be produced only if the
@@ -4038,12 +4754,15 @@ H\[ti]2\[ti]O is a liquid. 2\[ha]10\[ha] is 1024.
40384754\f[R]
40394755.fi
40404756.PP
4757+The text between \f[C]\[ha]...\[ha]\f[R] or \f[C]\[ti]...\[ti]\f[R] may
4758+not contain spaces or newlines.
40414759If the superscripted or subscripted text contains spaces, these spaces
40424760must be escaped with backslashes.
40434761(This is to prevent accidental superscripting and subscripting through
4044−the ordinary use of \f[C]\[ti]\f[R] and \f[C]\[ha]\f[R].) Thus, if you
4045−want the letter P with \[aq]a cat\[aq] in subscripts, use
4046−\f[C]P\[ti]a\[rs] cat\[ti]\f[R], not \f[C]P\[ti]a cat\[ti]\f[R].
4762+the ordinary use of \f[C]\[ti]\f[R] and \f[C]\[ha]\f[R], and also bad
4763+interactions with footnotes.) Thus, if you want the letter P with \[aq]a
4764+cat\[aq] in subscripts, use \f[C]P\[ti]a\[rs] cat\[ti]\f[R], not
4765+\f[C]P\[ti]a cat\[ti]\f[R].
40474766.SS Verbatim
40484767.PP
40494768To make a short span of text verbatim, put it inside backticks:
@@ -4386,8 +5105,11 @@ When \f[C]latex_macros\f[R] is disabled, the raw LaTeX and math will not
43865105have macros applied.
43875106This is usually a better approach when you are targeting LaTeX or PDF.
43885107.PP
4389−Whether or not \f[C]latex_macros\f[R] is enabled, the macro definitions
4390−will still be passed through as raw LaTeX.
5108+Macro definitions in LaTeX will be passed through as raw LaTeX only if
5109+\f[C]latex_macros\f[R] is not enabled.
5110+Macro definitions in Markdown source (or other formats allowing
5111+\f[C]raw_tex\f[R]) will be passed through regardless of whether
5112+\f[C]latex_macros\f[R] is enabled.
43915113.SS Links
43925114.PP
43935115Markdown allows links to be specified in several ways.
@@ -5241,6 +5963,11 @@ affect anything.
52415963.IP \[bu] 2
52425964Lazy wrapping of paragraphs is not allowed: the entire definition must
52435965be indented four spaces.
5966+.SS Extension: \f[C]gutenberg\f[R]
5967+.PP
5968+Use Project Gutenberg conventions for \f[C]plain\f[R] output: all-caps
5969+for strong emphasis, surround by underscores for regular emphasis, add
5970+extra blank space around headings.
52445971.SS Markdown variants
52455972.PP
52465973In addition to pandoc\[aq]s extended Markdown, the following Markdown
@@ -5484,6 +6211,9 @@ incrementally without the \f[C]-i\f[R] option and all at once with the
54846211.PP
54856212Both methods allow incremental and nonincremental lists to be mixed in a
54866213single document.
6214+.PP
6215+Note: Neither the \f[C]-i/--incremental\f[R] option nor any of the
6216+methods described here currently works for PowerPoint output.
54876217.SS Inserting pauses
54886218.PP
54896219You can add \[dq]pauses\[dq] within a slide by including a paragraph
@@ -5500,6 +6230,8 @@ content before the pause
55006230content after the pause
55016231\f[R]
55026232.fi
6233+.PP
6234+Note: this feature is not yet implemented for PowerPoint output.
55036235.SS Styling the slides
55046236.PP
55056237You can change the style of HTML slides by putting customized CSS files
@@ -6146,8 +6878,9 @@ blocks and text using \f[C]div\f[R]s and \f[C]span\f[R]s, respectively.
61466878.PP
61476879If you define a \f[C]div\f[R] or \f[C]span\f[R] with the attribute
61486880\f[C]custom-style\f[R], pandoc will apply your specified style to the
6149−contained elements.
6150−So, for example using the \f[C]bracketed_spans\f[R] syntax,
6881+contained elements (with the exception of elements whose function
6882+depends on a style, like headings, code blocks, block quotes, or links).
6883+So, for example, using the \f[C]bracketed_spans\f[R] syntax,
61516884.IP
61526885.nf
61536886\f[C]
@@ -6223,17 +6956,17 @@ And with the extension:
62236956\f[C]
62246957$ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
62256958
6226−::: {custom-style=\[dq]FirstParagraph\[dq]}
6959+::: {custom-style=\[dq]First Paragraph\[dq]}
62276960This is some text.
62286961:::
62296962
6230−::: {custom-style=\[dq]BodyText\[dq]}
6963+::: {custom-style=\[dq]Body Text\[dq]}
62316964This is text with an [emphasized]{custom-style=\[dq]Emphatic\[dq]} text style.
62326965And this is text with a [strengthened]{custom-style=\[dq]Strengthened\[dq]}
62336966text style.
62346967:::
62356968
6236−::: {custom-style=\[dq]MyBlockStyle\[dq]}
6969+::: {custom-style=\[dq]My Block Style\[dq]}
62376970> Here is a styled paragraph that inherits from Block Text.
62386971:::
62396972\f[R]
@@ -6268,6 +7001,13 @@ needs, do
62687001pandoc --print-default-data-file sample.lua
62697002\f[R]
62707003.fi
7004+.PP
7005+Note that custom writers have no default template.
7006+If you want to use \f[C]--standalone\f[R] with a custom writer, you will
7007+need to specify a template manually using \f[C]--template\f[R] or add a
7008+new default template with the name
7009+\f[C]default.NAME_OF_CUSTOM_WRITER.lua\f[R] to the \f[C]templates\f[R]
7010+subdirectory of your user data directory (see Templates).
62717011.SH A NOTE ON SECURITY
62727012.PP
62737013If you use pandoc to convert user-contributed content in a web