diff --git a/MANUAL.txt b/MANUAL.txt index c04008d66..512432211 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -1,7 +1,7 @@ --- title: Pandoc User's Guide author: John MacFarlane -date: January 30, 2022 +date: April 4, 2022 --- # Synopsis diff --git a/man/pandoc.1 b/man/pandoc.1 index 450c1c4eb..05bcfbad1 100644 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -1,5 +1,5 @@ '\" t -.\" Automatically generated by Pandoc 2.17.1 +.\" Automatically generated by Pandoc 2.17.1.1 .\" .\" Define V font for inline verbatim, using C font in formats .\" that render this, and otherwise B font. @@ -15,7 +15,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "Pandoc User\[cq]s Guide" "" "January 30, 2022" "pandoc 2.17.1.1" "" +.TH "Pandoc User\[cq]s Guide" "" "April 4, 2022" "pandoc 2.18" "" .hy .SH NAME pandoc - general markup converter @@ -260,6 +260,8 @@ Specify input format. .IP \[bu] 2 \f[V]dokuwiki\f[R] (DokuWiki markup) .IP \[bu] 2 +\f[V]endnotexml\f[R] (EndNote XML bibliography) +.IP \[bu] 2 \f[V]epub\f[R] (EPUB) .IP \[bu] 2 \f[V]fb2\f[R] (FictionBook2 e-book) @@ -304,6 +306,8 @@ if you need extensions not supported in \f[V]gfm\f[R]. .IP \[bu] 2 \f[V]org\f[R] (Emacs Org mode) .IP \[bu] 2 +\f[V]ris\f[R] (RIS bibliography) +.IP \[bu] 2 \f[V]rtf\f[R] (Rich Text Format) .IP \[bu] 2 \f[V]rst\f[R] (reStructuredText) @@ -693,8 +697,9 @@ escaped when inserted into the template. Read metadata from the supplied YAML (or JSON) file. This option can be used with every input format, but string scalars in the YAML file will always be parsed as Markdown. -Generally, the input will be handled the same as in YAML metadata -blocks. +(If the input format is Markdown or a Markdown variant, then the same +variant will be used to parse the metadata file; if it is a non-Markdown +format, pandoc\[cq]s default Markdown extensions will be used.) This option can be used repeatedly to include multiple metadata files; values in files specified later on the command line will be preferred over those specified in earlier files. @@ -998,9 +1003,8 @@ Elements with the attribute \f[V]data-external=\[dq]1\[dq]\f[R] will be left alone; the documents they link to will not be incorporated in the document. Limitation: resources that are loaded dynamically through JavaScript -cannot be incorporated; as a result, \f[V]--self-contained\f[R] does not -work with \f[V]--mathjax\f[R], and some advanced features (e.g.\ zoom or -speaker notes) may not work in an offline \[lq]self-contained\[rq] +cannot be incorporated; as a result, some advanced features (e.g.\ zoom +or speaker notes) may not work in an offline \[lq]self-contained\[rq] \f[V]reveal.js\f[R] slide show. .TP \f[V]--html-q-tags\f[R] @@ -4852,7 +4856,8 @@ This extension can be enabled/disabled for the following formats: .TP input formats \f[V]markdown\f[R], \f[V]commonmark\f[R], \f[V]latex\f[R], -\f[V]mediawiki\f[R], \f[V]org\f[R], \f[V]rst\f[R], \f[V]twiki\f[R] +\f[V]mediawiki\f[R], \f[V]org\f[R], \f[V]rst\f[R], \f[V]twiki\f[R], +\f[V]html\f[R] .TP output formats \f[V]markdown\f[R], \f[V]latex\f[R], \f[V]context\f[R], \f[V]rst\f[R] @@ -5208,8 +5213,15 @@ Use this only when you are targeting \f[V]ipynb\f[R] or a markdown-based output format. .SS Extension: \f[V]citations\f[R] .PP -Some aspects of Pandoc\[cq]s Markdown citation syntax are also accepted -in \f[V]org\f[R] input. +When the \f[V]citations\f[R] extension is enabled in \f[V]org\f[R], +org-cite and org-ref style citations will be parsed as native pandoc +citations. +.PP +When \f[V]citations\f[R] is enabled in \f[V]docx\f[R], citations +inserted by Zotero or Mendeley or EndNote plugins will be parsed as +native pandoc citations. +(Otherwise, the formatted citations generated by the bibliographic +software will be parsed as regular text.) .SS Extension: \f[V]fancy_lists\f[R] .PP Some aspects of Pandoc\[cq]s Markdown fancy lists are also accepted in @@ -8023,6 +8035,11 @@ CSL YAML T}@T{ \&.yaml T} +T{ +RIS +T}@T{ +\&.ris +T} .TE .PP Note that \f[V].bib\f[R] can be used with both BibTeX and BibLaTeX @@ -8324,6 +8341,23 @@ last paragraph... The bibliography will be inserted after this heading. Note that the \f[V]unnumbered\f[R] class will be added to this heading, so that the section will not be numbered. +.PP +If you want to put the bibliography into a variable in your template, +one way to do that is to put the div with id \f[V]refs\f[R] into a +metadata field, e.g. +.IP +.nf +\f[C] +--- +refs: | + ::: {#refs} + ::: +\&... +\f[R] +.fi +.PP +You can then put the variable \f[V]$refs$\f[R] into your template where +you want the bibliography to be placed. .SS Including uncited items in the bibliography .PP If you want to include items in the bibliography without actually citing @@ -8653,6 +8687,19 @@ incrementally without the \f[V]-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 +If you want to include a block-quoted list, you can work around this +behavior by putting the list inside a fenced div, so that it is not the +direct child of the block quote: +.IP +.nf +\f[C] +> ::: wrapper +> - a +> - list in a quote +> ::: +\f[R] +.fi .SS Inserting pauses .PP You can add \[lq]pauses\[rq] within a slide by including a paragraph @@ -9598,9 +9645,6 @@ Some document formats also include a unique identifier. For EPUB, this can be set explicitly by setting the \f[V]identifier\f[R] metadata field (see EPUB Metadata, above). .SH A NOTE ON SECURITY -.PP -If you use pandoc to convert user-contributed content in a web -application, here are some things to keep in mind: .IP "1." 3 Although pandoc itself will not create or modify any files other than those you explicitly ask it create (with the exception of temporary @@ -9629,6 +9673,8 @@ 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[V]PandocPure\f[R] monad. See the document Using the pandoc API for more details. +(This corresponds to the use of the \f[V]--sandbox\f[R] option on the +command line.) .IP "5." 3 Pandoc\[cq]s parsers can exhibit pathological performance on some corner cases. @@ -9647,8 +9693,8 @@ If \f[V]raw_html\f[R] is enabled for the Markdown input, users can inject arbitrary HTML. Even if \f[V]raw_html\f[R] is disabled, users can include dangerous content in URLs and attributes. -To be safe, you should run all the generated HTML through an HTML -sanitizer. +To be safe, you should run all HTML generated from untrusted user input +through an HTML sanitizer. .SH AUTHORS .PP Copyright 2006\[en]2022 John MacFarlane (jgm\[at]berkeley.edu).