@@ -1,5 +1,5 @@
11.\"t
2−.TH PANDOC 1 "August 7, 2018" "pandoc 2.2.3.2"
2+.TH PANDOC 1 "September 16, 2018" "pandoc 2.3"
33.SH NAME
44pandoc - general markup converter
55.SH SYNOPSIS
@@ -658,6 +658,17 @@ escaped when inserted into the template.
658658.RS
659659.RE
660660.TP
661+.B \f[C]\-\-metadata\-file=\f[]\f[I]FILE\f[]
662+Read metadata from the supplied YAML (or JSON) file.
663+This option can be used with every input format, but string scalars in
664+the YAML file will always be parsed as Markdown.
665+Generally, the input will be handled the same as in YAML metadata
666+blocks.
667+Metadata values specified inside the document, or by using \f[C]\-M\f[],
668+overwrite values specified with this option.
669+.RS
670+.RE
671+.TP
661672.B \f[C]\-p\f[], \f[C]\-\-preserve\-tabs\f[]
662673Preserve tabs instead of converting them to spaces (the default).
663674Note that this will only affect tabs in literal code spans and code
@@ -921,6 +932,11 @@ directory must be explicitly listed or it will not be searched.
921932For example: \f[C]\-\-resource\-path=.:test\f[] will search the working
922933directory and the \f[C]test\f[] subdirectory, in that order.
923934.RS
935+.PP
936+\f[C]\-\-resource\-path\f[] only has an effect if (a) the output format
937+embeds images (for example, \f[C]docx\f[], \f[C]pdf\f[], or
938+\f[C]html\f[] with \f[C]\-\-self\-contained\f[]) or (b) it is used
939+together with \f[C]\-\-extract\-media\f[].
924940.RE
925941.TP
926942.B \f[C]\-\-request\-header=\f[]\f[I]NAME\f[]\f[C]:\f[]\f[I]VAL\f[]
@@ -1039,7 +1055,11 @@ Implies \f[C]\-\-number\-sections\f[].
10391055.RE
10401056.TP
10411057.B \f[C]\-\-listings\f[]
1042−Use the \f[C]listings\f[] package for LaTeX code blocks
1058+Use the \f[C]listings\f[] package for LaTeX code blocks.
1059+The package does not support multi\-byte encoding for source code.
1060+To handle UTF\-8 you would need to use a custom template.
1061+This issue is fully documented here: Encoding issue with the listings
1062+package.
10431063.RS
10441064.RE
10451065.TP
@@ -1404,19 +1424,13 @@ without native math support.
14041424.B \f[C]\-\-katex\f[][\f[C]=\f[]\f[I]URL\f[]]
14051425Use KaTeX to display embedded TeX math in HTML output.
14061426The \f[I]URL\f[] is the base URL for the KaTeX library.
1427+That directory should contain a \f[C]katex.min.js\f[] and a
1428+\f[C]katex.min.css\f[] file.
14071429If a \f[I]URL\f[] is not provided, a link to the KaTeX CDN will be
14081430inserted.
14091431.RS
14101432.RE
14111433.TP
1412−.B \f[C]\-\-katex\-stylesheet=\f[]\f[I]URL\f[]
1413−The \f[I]URL\f[] should point to the \f[C]katex.css\f[] stylesheet.
1414−If this option is not specified, a link to the KaTeX CDN will be
1415−inserted.
1416−Note that this option does not imply \f[C]\-\-katex\f[].
1417−.RS
1418−.RE
1419−.TP
14201434.B \f[C]\-\-gladtex\f[]
14211435Enclose TeX math in \f[C]<eq>\f[] tags in HTML output.
14221436The resulting HTML can then be processed by GladTeX to produce images of
@@ -1596,7 +1610,7 @@ specified
15961610.TP
15971611.B \f[C]toc\-title\f[]
15981612title of table of contents (works only with EPUB, opendocument, odt,
1599−docx, pptx)
1613+docx, pptx, beamer, LaTeX)
16001614.RS
16011615.RE
16021616.TP
@@ -1827,15 +1841,16 @@ options to pass to the microtype package
18271841.TP
18281842.B \f[C]colorlinks\f[]
18291843add color to link text; automatically enabled if any of
1830−\f[C]linkcolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], or
1831−\f[C]toccolor\f[] are set
1844+\f[C]linkcolor\f[], \f[C]filecolor\f[], \f[C]citecolor\f[],
1845+\f[C]urlcolor\f[], or \f[C]toccolor\f[] are set
18321846.RS
18331847.RE
18341848.TP
1835−.B \f[C]linkcolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], \f[C]toccolor\f[]
1836−color for internal links, citation links, external links, and links in
1837−table of contents: uses options allowed by \f[C]xcolor\f[], including
1838−the \f[C]dvipsnames\f[], \f[C]svgnames\f[], and \f[C]x11names\f[] lists
1849+.B \f[C]linkcolor\f[], \f[C]filecolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], \f[C]toccolor\f[]
1850+color for internal links, external links, citation links, linked URLs,
1851+and links in table of contents, respectively: uses options allowed by
1852+\f[C]xcolor\f[], including the \f[C]dvipsnames\f[], \f[C]svgnames\f[],
1853+and \f[C]x11names\f[] lists
18391854.RS
18401855.RE
18411856.TP
@@ -2360,7 +2375,8 @@ This extension can be enabled/disabled for the following formats (in
23602375addition to \f[C]markdown\f[]):
23612376.TP
23622377.B input formats
2363−\f[C]latex\f[], \f[C]org\f[], \f[C]textile\f[]
2378+\f[C]latex\f[], \f[C]org\f[], \f[C]textile\f[], \f[C]html\f[]
2379+(environments, \f[C]\\ref\f[], and \f[C]\\eqref\f[] only)
23642380.RS
23652381.RE
23662382.TP
@@ -3772,7 +3788,10 @@ pandoc\ chap1.md\ chap2.md\ chap3.md\ metadata.yaml\ \-s\ \-o\ book.html
37723788.fi
37733789.PP
37743790Just be sure that the YAML file begins with \f[C]\-\-\-\f[] and ends
3775−with \f[C]\-\-\-\f[] or \f[C]\&...\f[].)
3791+with \f[C]\-\-\-\f[] or \f[C]\&...\f[].) Alternatively, you can use the
3792+\f[C]\-\-metadata\-file\f[] option.
3793+Using that approach however, you cannot reference content (like
3794+footnotes) from the main markdown input document.
37763795.PP
37773796Metadata will be taken from the fields of the YAML object and added to
37783797any existing document metadata.
@@ -5027,8 +5046,8 @@ nocite:\ |
50275046\f[]
50285047.fi
50295048.PP
5030−For LaTeX or PDF output, you can also use \f[C]natbib\f[] or
5031−\f[C]biblatex\f[] to render bibliography.
5049+For LaTeX output, you can also use \f[C]natbib\f[] or \f[C]biblatex\f[]
5050+to render the bibliography.
50325051In order to do so, specify bibliography files as outlined above, and add
50335052\f[C]\-\-natbib\f[] or \f[C]\-\-biblatex\f[] argument to \f[C]pandoc\f[]
50345053invocation.
@@ -5765,6 +5784,123 @@ iBooks\-specific metadata, with the following fields:
57655784\f[C]scroll\-axis\f[]:
57665785\f[C]vertical\f[]|\f[C]horizontal\f[]|\f[C]default\f[]
57675786.RE
5787+.SS The \f[C]epub:type\f[] attribute
5788+.PP
5789+You can mark up the header that corresponds to an EPUB chapter using the
5790+\f[C]epub:type\f[] attribute.
5791+For example, to set the attribute to the value \f[C]prologue\f[], use
5792+this markdown:
5793+.IP
5794+.nf
5795+\f[C]
5796+#\ My\ chapter\ {epub:type=prologue}
5797+\f[]
5798+.fi
5799+.PP
5800+Which will result in:
5801+.IP
5802+.nf
5803+\f[C]
5804+<body\ epub:type="frontmatter">
5805+\ \ <section\ epub:type="prologue">
5806+\ \ \ \ <h1>My\ chapter</h1>
5807+\f[]
5808+.fi
5809+.PP
5810+Pandoc will output \f[C]<body\ epub:type="bodymatter">\f[], unless you
5811+use one of the following values, in which case either
5812+\f[C]frontmatter\f[] or \f[C]backmatter\f[] will be output.
5813+.PP
5814+.TS
5815+tab(@);
5816+l l.
5817+T{
5818+\f[C]epub:type\f[] of first section
5819+T}@T{
5820+\f[C]epub:type\f[] of body
5821+T}
5822+_
5823+T{
5824+prologue
5825+T}@T{
5826+frontmatter
5827+T}
5828+T{
5829+abstract
5830+T}@T{
5831+frontmatter
5832+T}
5833+T{
5834+acknowledgments
5835+T}@T{
5836+frontmatter
5837+T}
5838+T{
5839+copyright\-page
5840+T}@T{
5841+frontmatter
5842+T}
5843+T{
5844+dedication
5845+T}@T{
5846+frontmatter
5847+T}
5848+T{
5849+foreword
5850+T}@T{
5851+frontmatter
5852+T}
5853+T{
5854+halftitle,
5855+T}@T{
5856+frontmatter
5857+T}
5858+T{
5859+introduction
5860+T}@T{
5861+frontmatter
5862+T}
5863+T{
5864+preface
5865+T}@T{
5866+frontmatter
5867+T}
5868+T{
5869+seriespage
5870+T}@T{
5871+frontmatter
5872+T}
5873+T{
5874+titlepage
5875+T}@T{
5876+frontmatter
5877+T}
5878+T{
5879+afterword
5880+T}@T{
5881+backmatter
5882+T}
5883+T{
5884+appendix
5885+T}@T{
5886+backmatter
5887+T}
5888+T{
5889+colophon
5890+T}@T{
5891+backmatter
5892+T}
5893+T{
5894+conclusion
5895+T}@T{
5896+backmatter
5897+T}
5898+T{
5899+epigraph
5900+T}@T{
5901+backmatter
5902+T}
5903+.TE
57685904.SS Linked media
57695905.PP
57705906By default, pandoc will download media referenced from any
@@ -5789,8 +5925,9 @@ For example:
57895925.PP
57905926Pandoc will automatically highlight syntax in fenced code blocks that
57915927are marked with a language name.
5792−The Haskell library skylighting is used for highlighting, which works in
5793−HTML, Docx, Ms, and LaTeX/PDF output.
5928+The Haskell library skylighting is used for highlighting.
5929+Currently highlighting is supported only for HTML, EPUB, Docx, Ms, and
5930+LaTeX/PDF output.
57945931To see a list of language names that pandoc will recognize, type
57955932\f[C]pandoc\ \-\-list\-highlight\-languages\f[].
57965933.PP
@@ -5802,6 +5939,33 @@ pygments is not actually used to do the highlighting).
58025939To see a list of highlight styles, type
58035940\f[C]pandoc\ \-\-list\-highlight\-styles\f[].
58045941.PP
5942+If you are not satisfied with the predefined styles, you can use
5943+\f[C]\-\-print\-highlight\-style\f[] to generate a JSON
5944+\f[C]\&.theme\f[] file which can be modified and used as the argument to
5945+\f[C]\-\-highlight\-style\f[].
5946+To get a JSON version of the \f[C]pygments\f[] style, for example:
5947+.IP
5948+.nf
5949+\f[C]
5950+pandoc\ \-\-print\-highlight\-style\ pygments\ >\ my.theme
5951+\f[]
5952+.fi
5953+.PP
5954+Then edit \f[C]my.theme\f[] and use it like this:
5955+.IP
5956+.nf
5957+\f[C]
5958+pandoc\ \-\-highlight\-style\ my.theme
5959+\f[]
5960+.fi
5961+.PP
5962+If you are not satisfied with the built\-in highlighting, or you want
5963+highlight a language that isn\[aq]t supported, you can use the
5964+\f[C]\-\-syntax\-definition\f[] option to load a KDE\-style XML syntax
5965+definition file.
5966+Before writing your own, have a look at KDE\[aq]s repository of syntax
5967+definitions.
5968+.PP
58055969To disable highlighting, use the \f[C]\-\-no\-highlight\f[] option.
58065970.SH CUSTOM STYLES IN DOCX
58075971.SS Input