From 04fce40cd69846a57196e8cd55a4dafcf9dfbfda Mon Sep 17 00:00:00 2001
From: John MacFarlane <jgm@berkeley.edu>
Date: Sun, 16 Sep 2018 11:18:41 -0700
Subject: Update manual date and man page.

---
 man/pandoc.1 | 210 ++++++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 187 insertions(+), 23 deletions(-)

(limited to 'man')

diff --git a/man/pandoc.1 b/man/pandoc.1
index 910f80825..5ba57f79f 100644
--- a/man/pandoc.1
+++ b/man/pandoc.1
@@ -1,5 +1,5 @@
 .\"t
-.TH PANDOC 1 "August 7, 2018" "pandoc 2.2.3.2"
+.TH PANDOC 1 "September 16, 2018" "pandoc 2.3"
 .SH NAME
 pandoc - general markup converter
 .SH SYNOPSIS
@@ -658,6 +658,17 @@ escaped when inserted into the template.
 .RS
 .RE
 .TP
+.B \f[C]\-\-metadata\-file=\f[]\f[I]FILE\f[]
+Read metadata from the supplied YAML (or JSON) file.
+This option can be used with every input format, but string scalars in
+the YAML file will always be parsed as Markdown.
+Generally, the input will be handled the same as in YAML metadata
+blocks.
+Metadata values specified inside the document, or by using \f[C]\-M\f[],
+overwrite values specified with this option.
+.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
@@ -921,6 +932,11 @@ directory must be explicitly listed or it will not be searched.
 For example: \f[C]\-\-resource\-path=.:test\f[] will search the working
 directory and the \f[C]test\f[] subdirectory, in that order.
 .RS
+.PP
+\f[C]\-\-resource\-path\f[] only has an effect if (a) the output format
+embeds images (for example, \f[C]docx\f[], \f[C]pdf\f[], or
+\f[C]html\f[] with \f[C]\-\-self\-contained\f[]) or (b) it is used
+together with \f[C]\-\-extract\-media\f[].
 .RE
 .TP
 .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[].
 .RE
 .TP
 .B \f[C]\-\-listings\f[]
-Use the \f[C]listings\f[] package for LaTeX code blocks
+Use the \f[C]listings\f[] package for LaTeX code blocks.
+The package does not support multi\-byte encoding for source code.
+To handle UTF\-8 you would need to use a custom template.
+This issue is fully documented here: Encoding issue with the listings
+package.
 .RS
 .RE
 .TP
@@ -1404,19 +1424,13 @@ without native math support.
 .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[] is the base URL for the KaTeX library.
+That directory should contain a \f[C]katex.min.js\f[] and a
+\f[C]katex.min.css\f[] file.
 If a \f[I]URL\f[] is not provided, a link to the KaTeX CDN will be
 inserted.
 .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
-.TP
 .B \f[C]\-\-gladtex\f[]
 Enclose TeX math in \f[C]<eq>\f[] tags in HTML output.
 The resulting HTML can then be processed by GladTeX to produce images of
@@ -1596,7 +1610,7 @@ specified
 .TP
 .B \f[C]toc\-title\f[]
 title of table of contents (works only with EPUB, opendocument, odt,
-docx, pptx)
+docx, pptx, beamer, LaTeX)
 .RS
 .RE
 .TP
@@ -1827,15 +1841,16 @@ options to pass to the microtype package
 .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
+\f[C]linkcolor\f[], \f[C]filecolor\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 options allowed by \f[C]xcolor\f[], including
-the \f[C]dvipsnames\f[], \f[C]svgnames\f[], and \f[C]x11names\f[] lists
+.B \f[C]linkcolor\f[], \f[C]filecolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], \f[C]toccolor\f[]
+color for internal links, external links, citation links, linked URLs,
+and links in table of contents, respectively: uses options allowed by
+\f[C]xcolor\f[], including the \f[C]dvipsnames\f[], \f[C]svgnames\f[],
+and \f[C]x11names\f[] lists
 .RS
 .RE
 .TP
@@ -2360,7 +2375,8 @@ This extension can be enabled/disabled for the following formats (in
 addition to \f[C]markdown\f[]):
 .TP
 .B input formats
-\f[C]latex\f[], \f[C]org\f[], \f[C]textile\f[]
+\f[C]latex\f[], \f[C]org\f[], \f[C]textile\f[], \f[C]html\f[]
+(environments, \f[C]\\ref\f[], and \f[C]\\eqref\f[] only)
 .RS
 .RE
 .TP
@@ -3772,7 +3788,10 @@ pandoc\ chap1.md\ chap2.md\ chap3.md\ metadata.yaml\ \-s\ \-o\ book.html
 .fi
 .PP
 Just be sure that the YAML file begins with \f[C]\-\-\-\f[] and ends
-with \f[C]\-\-\-\f[] or \f[C]\&...\f[].)
+with \f[C]\-\-\-\f[] or \f[C]\&...\f[].) Alternatively, you can use the
+\f[C]\-\-metadata\-file\f[] option.
+Using that approach however, you cannot reference content (like
+footnotes) from the main markdown input document.
 .PP
 Metadata will be taken from the fields of the YAML object and added to
 any existing document metadata.
@@ -5027,8 +5046,8 @@ 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.
+For LaTeX output, you can also use \f[C]natbib\f[] or \f[C]biblatex\f[]
+to render the 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.
@@ -5765,6 +5784,123 @@ iBooks\-specific metadata, with the following fields:
 \f[C]scroll\-axis\f[]:
 \f[C]vertical\f[]|\f[C]horizontal\f[]|\f[C]default\f[]
 .RE
+.SS The \f[C]epub:type\f[] attribute
+.PP
+You can mark up the header that corresponds to an EPUB chapter using the
+\f[C]epub:type\f[] attribute.
+For example, to set the attribute to the value \f[C]prologue\f[], use
+this markdown:
+.IP
+.nf
+\f[C]
+#\ My\ chapter\ {epub:type=prologue}
+\f[]
+.fi
+.PP
+Which will result in:
+.IP
+.nf
+\f[C]
+<body\ epub:type="frontmatter">
+\ \ <section\ epub:type="prologue">
+\ \ \ \ <h1>My\ chapter</h1>
+\f[]
+.fi
+.PP
+Pandoc will output \f[C]<body\ epub:type="bodymatter">\f[], unless you
+use one of the following values, in which case either
+\f[C]frontmatter\f[] or \f[C]backmatter\f[] will be output.
+.PP
+.TS
+tab(@);
+l l.
+T{
+\f[C]epub:type\f[] of first section
+T}@T{
+\f[C]epub:type\f[] of body
+T}
+_
+T{
+prologue
+T}@T{
+frontmatter
+T}
+T{
+abstract
+T}@T{
+frontmatter
+T}
+T{
+acknowledgments
+T}@T{
+frontmatter
+T}
+T{
+copyright\-page
+T}@T{
+frontmatter
+T}
+T{
+dedication
+T}@T{
+frontmatter
+T}
+T{
+foreword
+T}@T{
+frontmatter
+T}
+T{
+halftitle,
+T}@T{
+frontmatter
+T}
+T{
+introduction
+T}@T{
+frontmatter
+T}
+T{
+preface
+T}@T{
+frontmatter
+T}
+T{
+seriespage
+T}@T{
+frontmatter
+T}
+T{
+titlepage
+T}@T{
+frontmatter
+T}
+T{
+afterword
+T}@T{
+backmatter
+T}
+T{
+appendix
+T}@T{
+backmatter
+T}
+T{
+colophon
+T}@T{
+backmatter
+T}
+T{
+conclusion
+T}@T{
+backmatter
+T}
+T{
+epigraph
+T}@T{
+backmatter
+T}
+.TE
 .SS Linked media
 .PP
 By default, pandoc will download media referenced from any
@@ -5789,8 +5925,9 @@ For example:
 .PP
 Pandoc will automatically highlight syntax in fenced code blocks that
 are marked with a language name.
-The Haskell library skylighting is used for highlighting, which works in
-HTML, Docx, Ms, and LaTeX/PDF output.
+The Haskell library skylighting is used for highlighting.
+Currently highlighting is supported only for HTML, EPUB, Docx, Ms, and
+LaTeX/PDF output.
 To see a list of language names that pandoc will recognize, type
 \f[C]pandoc\ \-\-list\-highlight\-languages\f[].
 .PP
@@ -5802,6 +5939,33 @@ 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
+If you are not satisfied with the predefined styles, you can use
+\f[C]\-\-print\-highlight\-style\f[] to generate a JSON
+\f[C]\&.theme\f[] file which can be modified and used as the argument to
+\f[C]\-\-highlight\-style\f[].
+To get a JSON version of the \f[C]pygments\f[] style, for example:
+.IP
+.nf
+\f[C]
+pandoc\ \-\-print\-highlight\-style\ pygments\ >\ my.theme
+\f[]
+.fi
+.PP
+Then edit \f[C]my.theme\f[] and use it like this:
+.IP
+.nf
+\f[C]
+pandoc\ \-\-highlight\-style\ my.theme
+\f[]
+.fi
+.PP
+If you are not satisfied with the built\-in highlighting, or you want
+highlight a language that isn\[aq]t supported, you can use the
+\f[C]\-\-syntax\-definition\f[] option to load a KDE\-style XML syntax
+definition file.
+Before writing your own, have a look at KDE\[aq]s repository of syntax
+definitions.
+.PP
 To disable highlighting, use the \f[C]\-\-no\-highlight\f[] option.
 .SH CUSTOM STYLES IN DOCX
 .SS Input
-- 
cgit v1.2.3