From 51e1a8601f10d2ebed2d4ff66c39959ac56996a7 Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Fri, 22 Oct 2021 22:15:37 -0700 Subject: Bump to 2.15, updaet man page. --- man/pandoc.1 | 218 ++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 163 insertions(+), 55 deletions(-) (limited to 'man') diff --git a/man/pandoc.1 b/man/pandoc.1 index e901f60b3..0cec5d967 100644 --- a/man/pandoc.1 +++ b/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 -.PP -Background images can be added to self-contained reveal.js slideshows -and to beamer slideshows. -.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.) -.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. -.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). +.SS Background in reveal.js, beamer, and pptx +.PP +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 +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 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 +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. -- cgit v1.2.3