From 9b8a6917822da3dae933e9de74354fbe9484b2bd Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Fri, 20 Aug 2021 21:56:32 -0700 Subject: Update manual date and man page. --- man/pandoc.1 | 105 +++++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 88 insertions(+), 17 deletions(-) (limited to 'man') diff --git a/man/pandoc.1 b/man/pandoc.1 index 59888e26a..a0092b385 100644 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -1,7 +1,7 @@ '\" t .\" Automatically generated by Pandoc 2.14.1 .\" -.TH "Pandoc User\[cq]s Guide" "" "July 18, 2021" "pandoc 2.14.1" "" +.TH "Pandoc User\[cq]s Guide" "" "July 18, 2021" "pandoc 2.14.2" "" .hy .SH NAME pandoc - general markup converter @@ -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) @@ -1059,10 +1061,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]
\f[R] tags (or \f[C]
\f[R] tags for @@ -1234,17 +1239,22 @@ 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 .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. +.PP All templates included with a recent version of MS PowerPoint will fit these criteria. (You can click on \f[C]Layout\f[R] under the \f[C]Home\f[R] menu to @@ -3427,7 +3437,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 @@ -4789,6 +4799,11 @@ 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. @@ -5084,6 +5099,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] +Underline +\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: @@ -5823,14 +5858,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 @@ -6147,6 +6184,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_subsuperscript\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 @@ -6588,6 +6645,14 @@ 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 @@ -7699,12 +7764,18 @@ 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. +.IP "3." 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 "4." 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 @@ -7712,7 +7783,7 @@ 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 +.IP "5." 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