diff options
Diffstat (limited to 'man/pandoc.1')
| -rw-r--r-- | man/pandoc.1 | 493 |
1 files changed, 361 insertions, 132 deletions
diff --git a/man/pandoc.1 b/man/pandoc.1 index c77ab93bd..cbc100841 100644 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -1,7 +1,7 @@ '\" t -.\" Automatically generated by Pandoc 2.14.0.1 +.\" Automatically generated by Pandoc 2.16.1 .\" -.TH "Pandoc User\[cq]s Guide" "" "June 20, 2021" "pandoc 2.14.0.3" "" +.TH "Pandoc User\[cq]s Guide" "" "November 20, 2021" "pandoc 2.16.2" "" .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]. @@ -291,6 +291,8 @@ if you need extensions not supported in \f[C]gfm\f[R]. .IP \[bu] 2 \f[C]org\f[R] (Emacs Org mode) .IP \[bu] 2 +\f[C]rtf\f[R] (Rich Text Format) +.IP \[bu] 2 \f[C]rst\f[R] (reStructuredText) .IP \[bu] 2 \f[C]t2t\f[R] (txt2tags) @@ -302,6 +304,8 @@ if you need extensions not supported in \f[C]gfm\f[R]. \f[C]twiki\f[R] (TWiki markup) .IP \[bu] 2 \f[C]vimwiki\f[R] (Vimwiki) +.IP \[bu] 2 +the path of a custom Lua reader, see Custom readers and writers below .PP Extensions can be individually enabled or disabled by appending \f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name. @@ -430,7 +434,7 @@ markup) .IP \[bu] 2 \f[C]zimwiki\f[R] (ZimWiki markup) .IP \[bu] 2 -the path of a custom Lua writer, see Custom writers below +the path of a custom Lua writer, see Custom readers and writers below .PP Note that \f[C]odt\f[R], \f[C]docx\f[R], \f[C]epub\f[R], and \f[C]pdf\f[R] output will not be directed to \f[I]stdout\f[R] unless @@ -552,13 +556,14 @@ Markdown documents that use level-1 headings for sections to HTML, since pandoc uses a level-1 heading to render the document title. .TP \f[B]\f[CB]--base-header-level=\f[B]\f[R]\f[I]NUMBER\f[R] -\f[I]Deprecated. Use \f[CI]--shift-heading-level-by\f[I]=X instead, -where X = NUMBER - 1.\f[R] Specify the base level for headings (defaults -to 1). +\f[I]Deprecated. +Use \f[CI]--shift-heading-level-by\f[I]=X instead, where X = NUMBER - +1.\f[R] Specify the base level for headings (defaults to 1). .TP \f[B]\f[CB]--strip-empty-paragraphs\f[B]\f[R] -\f[I]Deprecated. Use the \f[CI]+empty_paragraphs\f[I] extension -instead.\f[R] Ignore paragraphs with no content. +\f[I]Deprecated. +Use the \f[CI]+empty_paragraphs\f[I] extension instead.\f[R] Ignore +paragraphs with no content. This option is useful for converting word processing documents where users have used empty paragraphs to create inter-paragraph space. .TP @@ -763,10 +768,19 @@ 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 -in the user data directory are ignored. +(See \f[C]-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.) +Templates in the user data directory are ignored. This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before \f[C]--print-default-template\f[R] on the command line. @@ -794,8 +808,8 @@ The default is \f[C]native\f[R]. \f[B]\f[CB]--dpi\f[B]\f[R]=\f[I]NUMBER\f[R] Specify the default dpi (dots per inch) value for conversion from pixels to inch/centimeters and vice versa. -(Technically, the correct term would be ppi: pixels per inch.) The -default is 96dpi. +(Technically, the correct term would be ppi: pixels per inch.) +The default is 96dpi. When images contain information about dpi internally, the encoded value is used instead of the default specified by this option. .TP @@ -993,13 +1007,16 @@ 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 writer. +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 (underlined) headings for level 1 and 2 headings in Markdown output. -(The default is \f[C]atx\f[R].) ATX-style headings are always used for -levels 3+. +(The default is \f[C]atx\f[R].) +ATX-style headings are always used for levels 3+. This option also affects Markdown cells in \f[C]ipynb\f[R] output. .TP \f[B]\f[CB]--atx-headers\f[B]\f[R] @@ -1059,10 +1076,13 @@ Specifies that headings with the specified level create slides (for Headings above this level in the hierarchy are used to divide the slide show into sections; headings below this level create subheads within a slide. -Note that content that is not contained under slide-level headings will -not appear in the slide show. -The default is to set the slide level based on the contents of the -document; see Structuring the slide show. +Valid values are 0-6. +If a slide level of 0 is specified, slides will not be split +automatically on headings, and horizontal rules must be used to indicate +slide boundaries. +If a slide level is not specified explicitly, the slide level will be +set automatically based on the contents of the document; see Structuring +the slide show. .TP \f[B]\f[CB]--section-divs\f[B]\f[R] Wrap sections in \f[C]<section>\f[R] tags (or \f[C]<div>\f[R] tags for @@ -1234,16 +1254,28 @@ Templates included with Microsoft PowerPoint 2013 (either with most templates derived from these. .RS .PP -The specific requirement is that the template should begin with the -following first four layouts: -.IP "1." 3 +The specific requirement is that the template should contain layouts +with the following names (as seen within PowerPoint): +.IP \[bu] 2 Title Slide -.IP "2." 3 +.IP \[bu] 2 Title and Content -.IP "3." 3 +.IP \[bu] 2 Section Header -.IP "4." 3 +.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. @@ -1253,7 +1285,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 @@ -1404,10 +1436,11 @@ list of citations in CSL YAML format with Markdown formatting. The style is controlled by a CSL stylesheet specified using the \f[C]--csl\f[R] option or the \f[C]csl\f[R] field in metadata. (If no stylesheet is specified, the \f[C]chicago-author-date\f[R] style -will be used by default.) The citation processing transformation may be -applied before or after filters or Lua filters (see \f[C]--filter\f[R], -\f[C]--lua-filter\f[R]): these transformations are applied in the order -they appear on the command line. +will be used by default.) +The citation processing transformation may be applied before or after +filters or Lua filters (see \f[C]--filter\f[R], \f[C]--lua-filter\f[R]): +these transformations are applied in the order they appear on the +command line. For more information, see the section on Citations. .TP \f[B]\f[CB]--bibliography=\f[B]\f[R]\f[I]FILE\f[R] @@ -1422,8 +1455,8 @@ will be sought in the resource path (see \f[C]--resource-path\f[R]). \f[B]\f[CB]--csl=\f[B]\f[R]\f[I]FILE\f[R] Set the \f[C]csl\f[R] field in the document\[cq]s metadata to \f[I]FILE\f[R], overriding any value set in the metadata. -(This is equivalent to \f[C]--metadata csl=FILE\f[R].) If \f[I]FILE\f[R] -is a URL, it will be fetched via HTTP. +(This is equivalent to \f[C]--metadata csl=FILE\f[R].) +If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP. If \f[I]FILE\f[R] is not found relative to the working directory, it will be sought in the resource path (see \f[C]--resource-path\f[R]) and finally in the \f[C]csl\f[R] subdirectory of the pandoc user data @@ -1433,8 +1466,8 @@ directory. Set the \f[C]citation-abbreviations\f[R] field in the document\[cq]s metadata to \f[I]FILE\f[R], overriding any value set in the metadata. (This is equivalent to -\f[C]--metadata citation-abbreviations=FILE\f[R].) If \f[I]FILE\f[R] is -a URL, it will be fetched via HTTP. +\f[C]--metadata citation-abbreviations=FILE\f[R].) +If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP. If \f[I]FILE\f[R] is not found relative to the working directory, it will be sought in the resource path (see \f[C]--resource-path\f[R]) and finally in the \f[C]csl\f[R] subdirectory of the pandoc user data @@ -1567,6 +1600,11 @@ Error T} _ T{ +1 +T}@T{ +PandocIOError +T} +T{ 3 T}@T{ PandocFailOnWarningError @@ -1607,6 +1645,11 @@ T}@T{ PandocCiteprocError T} T{ +25 +T}@T{ +PandocBibliographyError +T} +T{ 31 T}@T{ PandocEpubSubdirectoryError @@ -1667,6 +1710,11 @@ T}@T{ PandocFilterError T} T{ +84 +T}@T{ +PandocLuaError +T} +T{ 91 T}@T{ PandocMacroLoop @@ -2417,8 +2465,9 @@ including a title block in the document itself, you can set the \f[C]title-meta\f[R], \f[C]author-meta\f[R], and \f[C]date-meta\f[R] variables. (By default these are set automatically, based on \f[C]title\f[R], -\f[C]author\f[R], and \f[C]date\f[R].) The page title in HTML is set by -\f[C]pagetitle\f[R], which is equal to \f[C]title\f[R] by default. +\f[C]author\f[R], and \f[C]date\f[R].) +The page title in HTML is set by \f[C]pagetitle\f[R], which is equal to +\f[C]title\f[R] by default. .RE .TP \f[B]\f[CB]subtitle\f[B]\f[R] @@ -2434,7 +2483,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. @@ -2611,7 +2660,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 @@ -3097,8 +3146,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 @@ -3114,8 +3163,9 @@ without footnotes or pipe tables. The markdown reader and writer make by far the most use of extensions. Extensions only used by them are therefore covered in the section Pandoc\[cq]s Markdown below (See Markdown variants for -\f[C]commonmark\f[R] and \f[C]gfm\f[R].) In the following, extensions -that also work for other formats are covered. +\f[C]commonmark\f[R] and \f[C]gfm\f[R].) +In the following, extensions that also work for other formats are +covered. .PP Note that markdown extensions added to the \f[C]ipynb\f[R] format affect Markdown cells in Jupyter notebooks (as do command-line options like @@ -3427,7 +3477,7 @@ Enumeration starts at 1. This extension can be enabled/disabled for the following formats: .TP output formats -\f[C]odt\f[R], \f[C]opendocument\f[R] +\f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]docx\f[R] .SS Extension: \f[C]xrefs_name\f[R] .PP Links to headings, figures and tables inside the document are @@ -3898,8 +3948,8 @@ LaTeX, Docx, Ms, and PowerPoint. If highlighting is supported for your output format and language, then the code block above will appear highlighted, with numbered lines. (To see which languages are supported, type -\f[C]pandoc --list-highlight-languages\f[R].) Otherwise, the code block -above will appear as follows: +\f[C]pandoc --list-highlight-languages\f[R].) +Otherwise, the code block above will appear as follows: .IP .nf \f[C] @@ -4237,8 +4287,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: @@ -4331,7 +4381,8 @@ What if you want to put an indented code block after a list? \f[R] .fi .PP -Trouble! Here pandoc (like other Markdown implementations) will treat +Trouble! +Here pandoc (like other Markdown implementations) will treat \f[C]{ my code block }\f[R] as the second paragraph of item two, and not as a code block. .PP @@ -4611,9 +4662,10 @@ full text width and the cell contents will wrap, with the relative cell widths determined by the number of dashes in the line separating the table header from the table body. (For example \f[C]---|-\f[R] would make the first column 3/4 and the -second column 1/4 of the full text width.) On the other hand, if no -lines are wider than column width, then cell contents will not be -wrapped, and the cells will be sized to their contents. +second column 1/4 of the full text width.) +On the other hand, if no lines are wider than column width, then cell +contents will not be wrapped, and the cells will be sized to their +contents. .PP Note: pandoc also recognizes pipe tables of the following form, as can be produced by Emacs\[cq] orgtbl-mode: @@ -4646,8 +4698,9 @@ If the file begins with a title block .PP it will be parsed as bibliographic information, not regular text. (It will be used, for example, in the title of standalone LaTeX or HTML -output.) The block may contain just a title, a title and an author, or -all three elements. +output.) +The block may contain just a title, a title and an author, or all three +elements. If you want to include an author but no title, or a title and a date but no author, you need a blank line: .IP @@ -4770,8 +4823,8 @@ 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[R] and ends with -\f[C]---\f[R] or \f[C]...\f[R].) Alternatively, you can use the -\f[C]--metadata-file\f[R] option. +\f[C]---\f[R] or \f[C]...\f[R].) +Alternatively, you can use the \f[C]--metadata-file\f[R] option. Using that approach however, you cannot reference content (like footnotes) from the main markdown input document. .PP @@ -4780,15 +4833,20 @@ any existing document metadata. Metadata can contain lists and objects (nested arbitrarily), but all string scalars will be interpreted as Markdown. Fields with names ending in an underscore will be ignored by pandoc. -(They may be given a role by external processors.) Field names must not -be interpretable as YAML numbers or boolean values (so, for example, -\f[C]yes\f[R], \f[C]True\f[R], and \f[C]15\f[R] cannot be used as field -names). +(They may be given a role by external processors.) +Field names must not be interpretable as YAML numbers or boolean values +(so, for example, \f[C]yes\f[R], \f[C]True\f[R], and \f[C]15\f[R] cannot +be used as field names). .PP A document may contain multiple metadata blocks. If two metadata blocks attempt to set the same field, the value from the second block will be taken. .PP +Each metadata block is handled internally as an independent YAML +document. +This means, for example, that any YAML anchors defined in a block cannot +be referenced in another block. +.PP When pandoc is used with \f[C]-t markdown\f[R] to create a Markdown document, a YAML metadata block will be produced only if the \f[C]-s/--standalone\f[R] option is used. @@ -5038,9 +5096,9 @@ If the superscripted or subscripted text contains spaces, these spaces must be escaped with backslashes. (This is to prevent accidental superscripting and subscripting through the ordinary use of \f[C]\[ti]\f[R] and \f[C]\[ha]\f[R], and also bad -interactions with footnotes.) Thus, if you want the letter P with `a -cat' in subscripts, use \f[C]P\[ti]a\[rs] cat\[ti]\f[R], not -\f[C]P\[ti]a cat\[ti]\f[R]. +interactions with footnotes.) +Thus, if you want the letter P with `a cat' in subscripts, use +\f[C]P\[ti]a\[rs] cat\[ti]\f[R], not \f[C]P\[ti]a cat\[ti]\f[R]. .SS Verbatim .PP To make a short span of text verbatim, put it inside backticks: @@ -5084,6 +5142,26 @@ blocks: \[ga]<$>\[ga]{.haskell} \f[R] .fi +.SS Underline +.PP +To underline text, use the \f[C]underline\f[R] class: +.IP +.nf +\f[C] +[Underline]{.underline} +\f[R] +.fi +.PP +Or, without the \f[C]bracketed_spans\f[R] extension (but with +\f[C]native_spans\f[R]): +.IP +.nf +\f[C] +<span class=\[dq]underline\[dq]>Underline</span> +\f[R] +.fi +.PP +This will work in all output formats that support underline. .SS Small caps .PP To write small caps, use the \f[C]smallcaps\f[R] class: @@ -5444,10 +5522,10 @@ before or after the link). The link consists of link text in square brackets, followed by a label in square brackets. (There cannot be space between the two unless the -\f[C]spaced_reference_links\f[R] extension is enabled.) The link -definition consists of the bracketed label, followed by a colon and a -space, followed by the URL, and optionally (after a space) a link title -either in quotes or in parentheses. +\f[C]spaced_reference_links\f[R] extension is enabled.) +The link definition consists of the bracketed label, followed by a colon +and a space, followed by the URL, and optionally (after a space) a link +title either in quotes or in parentheses. The label must not be parseable as a citation (assuming the \f[C]citations\f[R] extension is enabled): citations take precedence over link labels. @@ -5823,14 +5901,16 @@ See the CSL user documentation for more information about CSL styles and how they affect rendering. .PP Unless a citation key start with a letter, digit, or \f[C]_\f[R], and -contains only alphanumerics and internal punctuation characters +contains only alphanumerics and single internal punctuation characters (\f[C]:.#$%&-+?<>\[ti]/\f[R]), it must be surrounded by curly braces, which are not considered part of the key. -In \f[C]\[at]Foo_bar.baz.\f[R], the key is \f[C]Foo_bar.baz\f[R]. -The final period is not \f[I]internal\f[R] punctuation, so it is not +In \f[C]\[at]Foo_bar.baz.\f[R], the key is \f[C]Foo_bar.baz\f[R] because +the final period is not \f[I]internal\f[R] punctuation, so it is not included in the key. In \f[C]\[at]{Foo_bar.baz.}\f[R], the key is \f[C]Foo_bar.baz.\f[R], including the final period. +In \f[C]\[at]Foo_bar--baz\f[R], the key is \f[C]Foo_bar\f[R] because the +repeated internal punctuation characters terminate the key. The curly braces are recommended if you use URLs as keys: \f[C][\[at]{https://example.com/bib?name=foobar&date=2000}, p. 33]\f[R]. .PP @@ -5964,7 +6044,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 @@ -6147,6 +6228,26 @@ Include source position attributes when parsing \f[C]commonmark\f[R]. For elements that accept attributes, a \f[C]data-pos\f[R] attribute is added; other elements are placed in a surrounding Div or Span elemnet with a \f[C]data-pos\f[R] attribute. +.SS Extension: \f[C]short_subsuperscripts\f[R] +.PP +Parse multimarkdown style subscripts and superscripts, which start with +a `\[ti]' or `\[ha]' character, respectively, and include the +alphanumeric sequence that follows. +For example: +.IP +.nf +\f[C] +x\[ha]2 = 4 +\f[R] +.fi +.PP +or +.IP +.nf +\f[C] +Oxygen is O\[ti]2. +\f[R] +.fi .SS Markdown variants .PP In addition to pandoc\[cq]s extended Markdown, the following Markdown @@ -6434,8 +6535,9 @@ These files are specified using the \f[C]--csl\f[R] option or the By default, pandoc will use the Chicago Manual of Style author-date format. (You can override this default by copying a CSL style of your choice to -\f[C]default.csl\f[R] in your user data directory.) The CSL project -provides further information on finding and editing styles. +\f[C]default.csl\f[R] in your user data directory.) +The CSL project provides further information on finding and editing +styles. .PP The \f[C]--citation-abbreviations\f[R] option (or the \f[C]citation-abbreviations\f[R] metadata field) may be used to specify @@ -6482,7 +6584,8 @@ Normal citations in footnotes (such as \f[C][\[at]foo, p. 33]\f[R]) will be rendered in parentheses. In-text citations (such as \f[C]\[at]foo [p. 33]\f[R]) will be rendered without parentheses. -(A comma will be added if appropriate.) Thus: +(A comma will be added if appropriate.) +Thus: .IP .nf \f[C] @@ -6588,6 +6691,15 @@ A few other metadata fields affect bibliography formatting: \f[B]\f[CB]link-citations\f[B]\f[R] If true, citations will be hyperlinked to the corresponding bibliography entries (for author-date and numerical styles only). +Defaults to false. +.TP +\f[B]\f[CB]link-bibliography\f[B]\f[R] +If true, DOIs, PMCIDs, PMID, and URLs in bibliographies will be rendered +as hyperlinks. +(If an entry contains a DOI, PMCID, PMID, or URL, but none of these +fields are rendered by the style, then the title, or in the absence of a +title the whole entry, will be hyperlinked.) +Defaults to true. .TP \f[B]\f[CB]lang\f[B]\f[R] The \f[C]lang\f[R] field will affect how the style is localized, for @@ -6690,9 +6802,9 @@ files, which are assumed to be available at the relative path \f[C]w3.org\f[R] (for Slidy). (These paths can be changed by setting the \f[C]slidy-url\f[R], \f[C]slideous-url\f[R], \f[C]revealjs-url\f[R], or \f[C]s5-url\f[R] -variables; see Variables for HTML slides, above.) For DZSlides, the -(relatively short) JavaScript and CSS are included in the file by -default. +variables; see Variables for HTML slides, above.) +For DZSlides, the (relatively short) JavaScript and CSS are included in +the file by default. .PP With all HTML slide formats, the \f[C]--self-contained\f[R] option can be used to produce a single file that contains all of the data necessary @@ -6754,15 +6866,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 @@ -6814,9 +6969,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 @@ -6992,48 +7144,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 @@ -7044,7 +7213,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] @@ -7111,15 +7280,23 @@ Same format as \f[C]creator\f[R]. .TP \f[B]\f[CB]date\f[B]\f[R] A string value in \f[C]YYYY-MM-DD\f[R] format. -(Only the year is necessary.) Pandoc will attempt to convert other -common date formats. +(Only the year is necessary.) +Pandoc will attempt to convert other common date formats. .TP \f[B]\f[CB]lang\f[B]\f[R] (or legacy: \f[B]\f[CB]language\f[B]\f[R]) 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. @@ -7303,6 +7480,11 @@ T}@T{ frontmatter T} T{ +frontispiece +T}@T{ +frontmatter +T} +T{ appendix T}@T{ backmatter @@ -7343,6 +7525,15 @@ For example: </audio> \f[R] .fi +.PP +If the input format already is HTML then +\f[C]data-external=\[dq]1\[dq]\f[R] will work as expected for +\f[C]<img>\f[R] elements. +Similarly, for Markdown, external images can be declared with +\f[C]{external=1}\f[R]. +Note that this only works for images; the other media elements have no +native representation in pandoc\[cq]s AST and requires the use of raw +HTML. .SH JUPYTER NOTEBOOKS .PP When creating a Jupyter notebook, pandoc will try to infer the notebook @@ -7631,26 +7822,44 @@ text style. With these custom styles, you can use your input document as a reference-doc while creating docx output (see below), and maintain the same styles in your input and output files. -.SH CUSTOM WRITERS +.SH CUSTOM READERS AND WRITERS .PP -Pandoc can be extended with custom writers written in Lua. +Pandoc can be extended with custom readers and writers written in Lua. (Pandoc includes a Lua interpreter, so Lua need not be installed separately.) .PP -To use a custom writer, simply specify the path to the Lua script in -place of the output format. +To use a custom reader or writer, simply specify the path to the Lua +script in place of the input or output format. For example: .IP .nf \f[C] pandoc -t data/sample.lua +pandoc -f my_custom_markup_language.lua -t latex -s +\f[R] +.fi +.PP +A custom reader is a Lua script that defines one function, Reader, which +takes a string as input and returns a Pandoc AST. +See the Lua filters documentation for documentation of the functions +that are available for creating pandoc AST elements. +For parsing, the lpeg parsing library is available by default. +To see a sample custom reader: +.IP +.nf +\f[C] +pandoc --print-default-data-file creole.lua \f[R] .fi .PP -Creating a custom writer requires writing a Lua function for each -possible element in a pandoc document. -To get a documented example which you can modify according to your -needs, do +If you want your custom reader to have access to reader options +(e.g.\ the tab stop setting), you give your Reader function a second +\f[C]options\f[R] parameter. +.PP +A custom writer is a Lua script that defines a function that specifies +how to render each element in a Pandoc AST. +To see a documented example which you can modify according to your +needs: .IP .nf \f[C] @@ -7690,12 +7899,27 @@ principle do anything on your file system. Please audit filters and custom writers very carefully before using them. .IP "2." 3 +Several input formats (including HTML, Org, and RST) support +\f[C]include\f[R] directives that allow the contents of a file to be +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 "3." 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 @@ -7703,7 +7927,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 "4." 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. @@ -7716,8 +7944,9 @@ sanitizer. Copyright 2006\[en]2021 John MacFarlane (jgm\[at]berkeley.edu). Released under the GPL, version 2 or greater. This software carries no warranty of any kind. -(See COPYRIGHT for full copyright and warranty notices.) For a full list -of contributors, see the file AUTHORS.md in the pandoc source code. +(See COPYRIGHT for full copyright and warranty notices.) +For a full list of contributors, see the file AUTHORS.md in the pandoc +source code. .PP The Pandoc source code and all documentation may be downloaded from <https://pandoc.org>. |