Bump to 2.15, updaet man page.

MANUAL.txt

@@ -1,7 +1,7 @@
 ---
 title: Pandoc User's Guide
 author: John MacFarlane
-date: August 20, 2021
+date: October 22, 2021
 ---
 
 # Synopsis

man/pandoc.1

@@ -1,7 +1,7 @@
 '\" t
-.\" Automatically generated by Pandoc 2.14.1
+.\" Automatically generated by Pandoc 2.14.2
 .\"
-.TH "Pandoc User\[cq]s Guide" "" "July 18, 2021" "pandoc 2.14.2" ""
+.TH "Pandoc User\[cq]s Guide" "" "October 22, 2021" "pandoc 2.15" ""
 .hy
 .SH NAME
 pandoc - general markup converter
@@ -178,11 +178,11 @@ is used), \f[C]fancyvrb\f[R], \f[C]longtable\f[R], \f[C]booktabs\f[R],
 \f[C]hyperref\f[R], \f[C]xcolor\f[R], \f[C]ulem\f[R], \f[C]geometry\f[R]
 (with the \f[C]geometry\f[R] variable set), \f[C]setspace\f[R] (with
 \f[C]linestretch\f[R]), and \f[C]babel\f[R] (with \f[C]lang\f[R]).
+If \f[C]CJKmainfont\f[R] is set, \f[C]xeCJK\f[R] is needed.
 The use of \f[C]xelatex\f[R] or \f[C]lualatex\f[R] as the PDF engine
 requires \f[C]fontspec\f[R].
 \f[C]lualatex\f[R] uses \f[C]selnolig\f[R].
-\f[C]xelatex\f[R] uses \f[C]polyglossia\f[R] (with \f[C]lang\f[R]),
+\f[C]xelatex\f[R] uses \f[C]bidi\f[R] (with the \f[C]dir\f[R] variable
-\f[C]xecjk\f[R], and \f[C]bidi\f[R] (with the \f[C]dir\f[R] variable
 set).
 If the \f[C]mathspec\f[R] variable is set, \f[C]xelatex\f[R] will use
 \f[C]mathspec\f[R] instead of \f[C]unicode-math\f[R].
@@ -765,6 +765,15 @@ rendering the document in standalone mode.
 If no \f[I]VAL\f[R] is specified, the key will be given the value
 \f[C]true\f[R].
 .TP
+\f[B]\f[CB]--sandbox\f[B]\f[R]
+Run pandoc in a sandbox, limiting IO operations in readers and writers
+to reading the files specified on the command line.
+Note that this option does not limit IO operations by filters or in the
+production of PDF documents.
+But it does offer security against, for example, disclosure of files
+through the use of \f[C]include\f[R] directives.
+Anyone using pandoc on untrusted user input should use this option.
+.TP
 \f[B]\f[CB]-D\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]--print-default-template=\f[B]\f[R]\f[I]FORMAT\f[R]
 Print the system default template for an output \f[I]FORMAT\f[R].
 (See \f[C]-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.) Templates
@@ -995,7 +1004,10 @@ Specify whether footnotes (and references, if \f[C]reference-links\f[R]
 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[R].
-Currently only affects the markdown and HTML writers.
+Currently this option only affects the \f[C]markdown\f[R],
+\f[C]muse\f[R], \f[C]html\f[R], \f[C]epub\f[R], \f[C]slidy\f[R],
+\f[C]s5\f[R], \f[C]slideous\f[R], \f[C]dzslides\f[R], and
+\f[C]revealjs\f[R] writers.
 .TP
 \f[B]\f[CB]--markdown-headings=setext\f[B]\f[R]|\f[B]\f[CB]atx\f[B]\f[R]
 Specify whether to use ATX-style (\f[C]#\f[R]-prefixed) or Setext-style
@@ -1249,11 +1261,18 @@ Title and Content
 Section Header
 .IP \[bu] 2
 Two Content
+.IP \[bu] 2
+Comparison
+.IP \[bu] 2
+Content with Caption
+.IP \[bu] 2
+Blank
 .PP
 For each name, the first layout found with that name will be used.
 If no layout is found with one of the names, pandoc will output a
 warning and use the layout with that name from the default reference doc
 instead.
+(How these layouts are used is described in PowerPoint layout choice.)
 .PP
 All templates included with a recent version of MS PowerPoint will fit
 these criteria.
@@ -1263,7 +1282,7 @@ check.)
 You can also modify the default \f[C]reference.pptx\f[R]: first run
 \f[C]pandoc -o custom-reference.pptx --print-default-data-file reference.pptx\f[R],
 and then modify \f[C]custom-reference.pptx\f[R] in MS PowerPoint (pandoc
-will use the first four layout slides, as mentioned above).
+will use the layouts with the names listed above).
 .RE
 .RE
 .TP
@@ -1617,6 +1636,11 @@ T}@T{
 PandocCiteprocError
 T}
 T{
+25
+T}@T{
+PandocBibliographyError
+T}
+T{
 31
 T}@T{
 PandocEpubSubdirectoryError
@@ -2444,7 +2468,7 @@ list of keywords to be included in HTML, PDF, ODT, pptx, docx and
 AsciiDoc metadata; repeat as for \f[C]author\f[R], above
 .TP
 \f[B]\f[CB]subject\f[B]\f[R]
-document subject, included in ODT, PDF, docx and pptx metadata
+document subject, included in ODT, PDF, docx, EPUB, and pptx metadata
 .TP
 \f[B]\f[CB]description\f[B]\f[R]
 document description, included in ODT, docx and pptx metadata.
@@ -2621,7 +2645,7 @@ base URL for Slideous documents (defaults to \f[C]slideous\f[R])
 .TP
 \f[B]\f[CB]title-slide-attributes\f[B]\f[R]
 additional attributes for the title slide of reveal.js slide shows.
-See background in reveal.js and beamer for an example.
+See [background in reveal.js and beamer] for an example.
 .PP
 All reveal.js configuration options are available as variables.
 To turn off boolean flags that default to true in reveal.js, use
@@ -3107,8 +3131,8 @@ working directory from which pandoc is run.
 non-null value if \f[C]--toc/--table-of-contents\f[R] was specified
 .TP
 \f[B]\f[CB]toc-title\f[B]\f[R]
-title of table of contents (works only with EPUB, HTML, opendocument,
+title of table of contents (works only with EPUB, HTML, revealjs,
-odt, docx, pptx, beamer, LaTeX)
+opendocument, odt, docx, pptx, beamer, LaTeX)
 .SH EXTENSIONS
 .PP
 The behavior of some of the readers and writers can be adjusted by
@@ -4247,8 +4271,8 @@ two spaces.
 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
+The body of the definition (not including the first line) should be
-colon or tilde) should be indented four spaces.
+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:
@@ -6001,7 +6025,8 @@ relative to the file containing the link reference definition, not the
 file containing the reference link or image itself, if these differ.
 .SS Extension: \f[C]attributes\f[R]
 .PP
-Allows attributes to be attached to any inline or block-level element.
+Allows attributes to be attached to any inline or block-level element
+when parsing \f[C]commonmark\f[R].
 The syntax for the attributes is the same as that used in
 \f[C]header_attributes\f[R].
 .IP \[bu] 2
@@ -6819,15 +6844,58 @@ lines in the default template.)
 .PP
 These rules are designed to support many different styles of slide show.
 If you don\[cq]t care about structuring your slides into sections and
-subsections, you can just use level-1 headings for all each slide.
+subsections, you can either just use level-1 headings for all slides (in
-(In that case, level-1 will be the slide level.) But you can also
+that case, level 1 will be the slide level) or you can set
-structure the slide show into sections, as in the example above.
+\f[C]--slide-level=0\f[R].
 .PP
 Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
 layout will be produced, with level-1 headings building horizontally and
 level-2 headings building vertically.
 It is not recommended that you use deeper nesting of section levels with
-reveal.js.
+reveal.js unless you set \f[C]--slide-level=0\f[R] (which lets reveal.js
+produce a one-dimensional layout and only interprets horizontal rules as
+slide boundaries).
+.SS PowerPoint layout choice
+.PP
+When creating slides, the pptx writer chooses from a number of
+pre-defined layouts, based on the content of the slide:
+.TP
+Title Slide
+This layout is used for the initial slide, which is generated and filled
+from the metadata fields \f[C]date\f[R], \f[C]author\f[R], and
+\f[C]title\f[R], if they are present.
+.TP
+Section Header
+This layout is used for what pandoc calls \[lq]title slides\[rq], i.e.
+slides which start with a header which is above the slide level in the
+hierarchy.
+.TP
+Two Content
+This layout is used for two-column slides, i.e.\ slides containing a div
+with class \f[C]columns\f[R] which contains at least two divs with class
+\f[C]column\f[R].
+.TP
+Comparison
+This layout is used instead of \[lq]Two Content\[rq] for any two-column
+slides in which at least one column contains text followed by non-text
+(e.g.\ an image or a table).
+.TP
+Content with Caption
+This layout is used for any non-two-column slides which contain text
+followed by non-text (e.g.\ an image or a table).
+.TP
+Blank
+This layout is used for any slides which only contain blank content,
+e.g.\ a slide containing only speaker notes, or a slide containing only
+a non-breaking space.
+.TP
+Title and Content
+This layout is used for all slides which do not match the criteria for
+another layout.
+.PP
+These layouts are chosen from the default pptx reference doc included
+with pandoc, unless an alternative reference doc is specified using
+\f[C]--reference-doc\f[R].
 .SS Incremental lists
 .PP
 By default, these writers produce lists that display \[lq]all at
@@ -6879,9 +6947,6 @@ incrementally without the \f[C]-i\f[R] option and all at once with the
 .PP
 Both methods allow incremental and nonincremental lists to be mixed in a
 single document.
-.PP
-Note: Neither the \f[C]-i/--incremental\f[R] option nor any of the
-methods described here currently works for PowerPoint output.
 .SS Inserting pauses
 .PP
 You can add \[lq]pauses\[rq] within a slide by including a paragraph
@@ -7057,48 +7122,65 @@ User\[cq]s Guide may also be used: \f[C]allowdisplaybreaks\f[R],
 \f[C]allowframebreaks\f[R], \f[C]b\f[R], \f[C]c\f[R], \f[C]t\f[R],
 \f[C]environment\f[R], \f[C]label\f[R], \f[C]plain\f[R],
 \f[C]shrink\f[R], \f[C]standout\f[R], \f[C]noframenumbering\f[R].
-.SS Background in reveal.js and beamer
+.SS Background in reveal.js, beamer, and pptx
 .PP
-Background images can be added to self-contained reveal.js slideshows
+Background images can be added to self-contained reveal.js slide shows,
-and to beamer slideshows.
+beamer slide shows, and pptx slide shows.
+.SS On all slides (beamer, reveal.js, pptx)
 .PP
-For the same image on every slide, use the configuration option
+With beamer and reveal.js, the configuration option
-\f[C]background-image\f[R] either in the YAML metadata block or as a
+\f[C]background-image\f[R] can be used either in the YAML metadata block
-command-line variable.
+or as a command-line variable to get the same image on every slide.
-(There are no other options in beamer and the rest of this section
-concerns reveal.js slideshows.)
 .PP
-For reveal.js, you can instead use the reveal.js-native option
+For pptx, you can use a reference doc in which background images have
-\f[C]parallaxBackgroundImage\f[R].
+been set on the relevant layouts.
-You can also set \f[C]parallaxBackgroundHorizontal\f[R] and
+.SS \f[C]parallaxBackgroundImage\f[R] (reveal.js)
-\f[C]parallaxBackgroundVertical\f[R] the same way and must also set
-\f[C]parallaxBackgroundSize\f[R] to have your values take effect.
 .PP
-To set an image for a particular reveal.js slide, add
+For reveal.js, there is also the reveal.js-native option
-\f[C]{data-background-image=\[dq]/path/to/image\[dq]}\f[R] to the first
+\f[C]parallaxBackgroundImage\f[R], which can be used instead of
-slide-level heading on the slide (which may even be empty).
+\f[C]background-image\f[R] to produce a parallax scrolling background.
+You must also set \f[C]parallaxBackgroundSize\f[R], and can optionally
+set \f[C]parallaxBackgroundHorizontal\f[R] and
+\f[C]parallaxBackgroundVertical\f[R] to configure the scrolling
+behaviour.
+See the reveal.js documentation for more details about the meaning of
+these options.
 .PP
 In reveal.js\[cq]s overview mode, the parallaxBackgroundImage will show
 up only on the first slide.
+.SS On individual slides (reveal.js, pptx)
 .PP
-Other reveal.js background settings also work on individual slides,
+To set an image for a particular reveal.js or pptx slide, add
-including \f[C]data-background-size\f[R],
+\f[C]{background-image=\[dq]/path/to/image\[dq]}\f[R] to the first
-\f[C]data-background-repeat\f[R], \f[C]data-background-color\f[R],
+slide-level heading on the slide (which may even be empty).
-\f[C]data-transition\f[R], and \f[C]data-transition-speed\f[R].
 .PP
-To add a background image to the automatically generated title slide,
+As the HTML writers pass unknown attributes through, other reveal.js
-use the \f[C]title-slide-attributes\f[R] variable in the YAML metadata
+background settings also work on individual slides, including
-block.
+\f[C]background-size\f[R], \f[C]background-repeat\f[R],
+\f[C]background-color\f[R], \f[C]transition\f[R], and
+\f[C]transition-speed\f[R].
+(The \f[C]data-\f[R] prefix will automatically be added.)
+.PP
+Note: \f[C]data-background-image\f[R] is also supported in pptx for
+consistency with reveal.js \[en] if \f[C]background-image\f[R] isn\[cq]t
+found, \f[C]data-background-image\f[R] will be checked.
+.SS On the title slide (reveal.js, pptx)
+.PP
+To add a background image to the automatically generated title slide for
+reveal.js, use the \f[C]title-slide-attributes\f[R] variable in the YAML
+metadata block.
 It must contain a map of attribute names and values.
+(Note that the \f[C]data-\f[R] prefix is required here, as it isn\[cq]t
+added automatically.)
 .PP
-See the reveal.js documentation for more details.
+For pptx, pass a reference doc with the background image set on the
-.PP
+\[lq]Title Slide\[rq] layout.
-For example in reveal.js:
+.SS Example (reveal.js)
 .IP
 .nf
 \f[C]
 ---
-title: My Slideshow
+title: My Slide Show
 parallaxBackgroundImage: /path/to/my/background_image.png
 title-slide-attributes:
     data-background-image: /path/to/title_image.png
@@ -7109,7 +7191,7 @@ title-slide-attributes:
 
 Slide 1 has background_image.png as its background.
 
-## {data-background-image=\[dq]/path/to/special_image.jpg\[dq]}
+## {background-image=\[dq]/path/to/special_image.jpg\[dq]}
 
 Slide 2 has a special image for its background, even though the heading has no content.
 \f[R]
@@ -7184,7 +7266,15 @@ A string value in BCP 47 format.
 Pandoc will default to the local language if nothing is specified.
 .TP
 \f[B]\f[CB]subject\f[B]\f[R]
-A string value or a list of such values.
+Either a string value, or an object with fields \f[C]text\f[R],
+\f[C]authority\f[R], and \f[C]term\f[R], or a list of such objects.
+Valid values for \f[C]authority\f[R] are either a reserved authority
+value (currently \f[C]AAT\f[R], \f[C]BIC\f[R], \f[C]BISAC\f[R],
+\f[C]CLC\f[R], \f[C]DDC\f[R], \f[C]CLIL\f[R], \f[C]EuroVoc\f[R],
+\f[C]MEDTOP\f[R], \f[C]LCSH\f[R], \f[C]NDC\f[R], \f[C]Thema\f[R],
+\f[C]UDC\f[R], and \f[C]WGS\f[R]) or an absolute IRI identifying a
+custom scheme.
+Valid values for \f[C]term\f[R] are defined by the scheme.
 .TP
 \f[B]\f[CB]description\f[B]\f[R]
 A string value.
@@ -7368,6 +7458,11 @@ T}@T{
 frontmatter
 T}
 T{
+frontispiece
+T}@T{
+frontmatter
+T}
+T{
 appendix
 T}@T{
 backmatter
@@ -7769,13 +7864,22 @@ Several input formats (including HTML, Org, and RST) support
 included in the output.
 An untrusted attacker could use these to view the contents of files on
 the file system.
+(Using the \f[C]--sandbox\f[R] option can protect against this threat.)
 .IP "3." 3
+Several output formats (including RTF, FB2, HTML with
+\f[C]--self-contained\f[R], EPUB, Docx, and ODT) will embed encoded or
+raw images into the output file.
+An untrusted attacker could exploit this to view the contents of
+non-image files on the file system.
+(Using the \f[C]--sandbox\f[R] option can protect against this threat,
+but will also prevent including images in these formats.)
+.IP "4." 3
 If your application uses pandoc as a Haskell library (rather than
 shelling out to the executable), it is possible to use it in a mode that
 fully isolates pandoc from your file system, by running the pandoc
 operations in the \f[C]PandocPure\f[R] monad.
 See the document Using the pandoc API for more details.
-.IP "4." 3
+.IP "5." 3
 Pandoc\[cq]s parsers can exhibit pathological performance on some corner
 cases.
 It is wise to put any pandoc operations under a timeout, to avoid DOS
@@ -7783,7 +7887,11 @@ attacks that exploit these issues.
 If you are using the pandoc executable, you can add the command line
 options \f[C]+RTS -M512M -RTS\f[R] (for example) to limit the heap size
 to 512MB.
-.IP "5." 3
+Note that the \f[C]commonmark\f[R] parser (including
+\f[C]commonmark_x\f[R] and \f[C]gfm\f[R]) is much less vulnerable to
+pathological performance than the \f[C]markdown\f[R] parser, so it is a
+better choice when processing untrusted input.
+.IP "6." 3
 The HTML generated by pandoc is not guaranteed to be safe.
 If \f[C]raw_html\f[R] is enabled for the Markdown input, users can
 inject arbitrary HTML.

pandoc.cabal

@@ -1,6 +1,6 @@
 cabal-version:   2.2
 name:            pandoc
-version:         2.14.2
+version:         2.15
 build-type:      Simple
 license:         GPL-2.0-or-later
 license-file:    COPYING.md