Bump to 2.15, updaet man page.
This commit is contained in:
John MacFarlane
parent
42396cb23f
commit
51e1a8601f
3 changed files with 161 additions and 53 deletions
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Pandoc User's Guide
|
||||
author: John MacFarlane
|
||||
date: August 20, 2021
|
||||
date: October 22, 2021
|
||||
---
|
||||
|
||||
# Synopsis
|
||||
|
|
|
|||
210
man/pandoc.1
210
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]xecjk\f[R], and \f[C]bidi\f[R] (with the \f[C]dir\f[R] variable
|
||||
\f[C]xelatex\f[R] uses \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,
|
||||
odt, docx, pptx, beamer, LaTeX)
|
||||
title of table of contents (works only with EPUB, HTML, revealjs,
|
||||
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
|
||||
colon or tilde) should be indented four spaces.
|
||||
The body of the definition (not including the first line) 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:
|
||||
|
|
@ -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.
|
||||
(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.
|
||||
subsections, you can either just use level-1 headings for all slides (in
|
||||
that case, level 1 will be the slide level) or you can set
|
||||
\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
|
||||
and to beamer slideshows.
|
||||
Background images can be added to self-contained reveal.js slide shows,
|
||||
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
|
||||
\f[C]background-image\f[R] either in the YAML metadata block or as a
|
||||
command-line variable.
|
||||
(There are no other options in beamer and the rest of this section
|
||||
concerns reveal.js slideshows.)
|
||||
With beamer and reveal.js, the configuration option
|
||||
\f[C]background-image\f[R] can be used either in the YAML metadata block
|
||||
or as a command-line variable to get the same image on every slide.
|
||||
.PP
|
||||
For reveal.js, you can instead use the reveal.js-native option
|
||||
\f[C]parallaxBackgroundImage\f[R].
|
||||
You can also set \f[C]parallaxBackgroundHorizontal\f[R] and
|
||||
\f[C]parallaxBackgroundVertical\f[R] the same way and must also set
|
||||
\f[C]parallaxBackgroundSize\f[R] to have your values take effect.
|
||||
For pptx, you can use a reference doc in which background images have
|
||||
been set on the relevant layouts.
|
||||
.SS \f[C]parallaxBackgroundImage\f[R] (reveal.js)
|
||||
.PP
|
||||
To set an image for a particular reveal.js slide, add
|
||||
\f[C]{data-background-image=\[dq]/path/to/image\[dq]}\f[R] to the first
|
||||
slide-level heading on the slide (which may even be empty).
|
||||
For reveal.js, there is also the reveal.js-native option
|
||||
\f[C]parallaxBackgroundImage\f[R], which can be used instead of
|
||||
\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,
|
||||
including \f[C]data-background-size\f[R],
|
||||
\f[C]data-background-repeat\f[R], \f[C]data-background-color\f[R],
|
||||
\f[C]data-transition\f[R], and \f[C]data-transition-speed\f[R].
|
||||
To set an image for a particular reveal.js or pptx slide, add
|
||||
\f[C]{background-image=\[dq]/path/to/image\[dq]}\f[R] to the first
|
||||
slide-level heading on the slide (which may even be empty).
|
||||
.PP
|
||||
To add a background image to the automatically generated title slide,
|
||||
use the \f[C]title-slide-attributes\f[R] variable in the YAML metadata
|
||||
block.
|
||||
As the HTML writers pass unknown attributes through, other reveal.js
|
||||
background settings also work on individual slides, including
|
||||
\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.
|
||||
.PP
|
||||
For example in reveal.js:
|
||||
For pptx, pass a reference doc with the background image set on the
|
||||
\[lq]Title Slide\[rq] layout.
|
||||
.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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue