Merge branch 'master' of https://github.com/jgm/pandoc

2 files changed, 418 insertions, 102 deletions

diff --git a/man/pandoc.1 b/man/pandoc.1
index 5a4c833d2..c77ab93bd 100644
--- a/man/pandoc.1
+++ b/man/pandoc.1
@@ -1,7 +1,7 @@
 '\" t
-.\" Automatically generated by Pandoc 2.11.2
+.\" Automatically generated by Pandoc 2.14.0.1
 .\"
-.TH "Pandoc User\[cq]s Guide" "" "November 19, 2020" "pandoc 2.11.2" ""
+.TH "Pandoc User\[cq]s Guide" "" "June 20, 2021" "pandoc 2.14.0.3" ""
 .hy
 .SH NAME
 pandoc - general markup converter
@@ -172,13 +172,12 @@ You can then test it with \f[C]pdflatex test.tex\f[R].
 When using LaTeX, the following packages need to be available (they are
 included with all recent versions of TeX Live): \f[C]amsfonts\f[R],
 \f[C]amsmath\f[R], \f[C]lm\f[R], \f[C]unicode-math\f[R],
-\f[C]ifxetex\f[R], \f[C]ifluatex\f[R], \f[C]listings\f[R] (if the
-\f[C]--listings\f[R] option is used), \f[C]fancyvrb\f[R],
-\f[C]longtable\f[R], \f[C]booktabs\f[R], \f[C]graphicx\f[R] (if the
-document contains images), \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]).
+\f[C]iftex\f[R], \f[C]listings\f[R] (if the \f[C]--listings\f[R] option
+is used), \f[C]fancyvrb\f[R], \f[C]longtable\f[R], \f[C]booktabs\f[R],
+\f[C]graphicx\f[R] (if the document contains images),
+\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]).
 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].
@@ -320,6 +319,10 @@ Specify output format.
 .IP \[bu] 2
 \f[C]beamer\f[R] (LaTeX beamer slide show)
 .IP \[bu] 2
+\f[C]bibtex\f[R] (BibTeX bibliography)
+.IP \[bu] 2
+\f[C]biblatex\f[R] (BibLaTeX bibliography)
+.IP \[bu] 2
 \f[C]commonmark\f[R] (CommonMark Markdown)
 .IP \[bu] 2
 \f[C]commonmark_x\f[R] (CommonMark Markdown with extensions)
@@ -454,16 +457,15 @@ On *nix and macOS systems this will be the \f[C]pandoc\f[R] subdirectory
 of the XDG data directory (by default, \f[C]$HOME/.local/share\f[R],
 overridable by setting the \f[C]XDG_DATA_HOME\f[R] environment
 variable).
-If that directory does not exist, \f[C]$HOME/.pandoc\f[R] will be used
-(for backwards compatibility).
-In Windows the default user data directory is
+If that directory does not exist and \f[C]$HOME/.pandoc\f[R] exists, it
+will be used (for backwards compatibility).
+On Windows the default user data directory is
 \f[C]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R].
 You can find the default user data directory on your system by looking
 at the output of \f[C]pandoc --version\f[R].
-A \f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
-\f[C]templates\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R], or
-\f[C]s5\f[R] directory placed in this directory will override
-pandoc\[cq]s normal defaults.
+Data files placed in this directory (for example,
+\f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
+\f[C]templates\f[R]) will override pandoc\[cq]s normal defaults.
 .TP
 \f[B]\f[CB]-d\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--defaults=\f[B]\f[R]\f[I]FILE\f[R]
 Specify a set of default option settings.
@@ -623,8 +625,8 @@ above).
 .IP "3." 3
 \f[C]$PATH\f[R] (executable only)
 .PP
-Filters and Lua-filters are applied in the order specified on the
-command line.
+Filters, Lua-filters, and citeproc processing are applied in the order
+specified on the command line.
 .RE
 .TP
 \f[B]\f[CB]-L\f[B]\f[R] \f[I]SCRIPT\f[R], \f[B]\f[CB]--lua-filter=\f[B]\f[R]\f[I]SCRIPT\f[R]
@@ -641,29 +643,17 @@ The \f[C]pandoc\f[R] Lua module provides helper functions for element
 creation.
 It is always loaded into the script\[cq]s Lua environment.
 .PP
-The following is an example Lua script for macro-expansion:
-.IP
-.nf
-\f[C]
-function expand_hello_world(inline)
-  if inline.c == \[aq]{{helloworld}}\[aq] then
-    return pandoc.Emph{ pandoc.Str \[dq]Hello, World\[dq] }
-  else
-    return inline
-  end
-end
-
-return {{Str = expand_hello_world}}
-\f[R]
-.fi
+See the Lua filters documentation for further details.
 .PP
 In order of preference, pandoc will look for Lua filters in
 .IP "1." 3
-a specified full or relative path (executable or non-executable)
+a specified full or relative path
 .IP "2." 3
-\f[C]$DATADIR/filters\f[R] (executable or non-executable) where
-\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
-above).
+\f[C]$DATADIR/filters\f[R] where \f[C]$DATADIR\f[R] is the user data
+directory (see \f[C]--data-dir\f[R], above).
+.PP
+Filters, Lua filters, and citeproc processing are applied in the order
+specified on the command line.
 .RE
 .TP
 \f[B]\f[CB]-M\f[B]\f[R] \f[I]KEY\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]VAL\f[R]], \f[B]\f[CB]--metadata=\f[B]\f[R]\f[I]KEY\f[R][\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]]
@@ -726,11 +716,11 @@ Extract images and other media contained in or linked from the source
 document to the path \f[I]DIR\f[R], creating it if necessary, and adjust
 the images references in the document so they point to the extracted
 files.
-If the source format is a binary container (docx, epub, or odt), the
-media is extracted from the container and the original filenames are
-used.
-Otherwise the media is read from the file system or downloaded, and new
-filenames are constructed based on SHA1 hashes of the contents.
+Media are downloaded, read from the file system, or extracted from a
+binary container (e.g.\ docx), as needed.
+The original file paths are used if they are relative paths not
+containing \f[C]..\f[R].
+Otherwise filenames are constructed from the SHA1 hash of the contents.
 .TP
 \f[B]\f[CB]--abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
 Specifies a custom abbreviations file, with abbreviations one to a line.
@@ -740,9 +730,9 @@ system default.
 To see the system default, use
 \f[C]pandoc --print-default-data-file=abbreviations\f[R].
 The only use pandoc makes of this list is in the Markdown reader.
-Strings ending in a period that are found in this list will be followed
-by a nonbreaking space, so that the period will not produce
-sentence-ending space in formats like LaTeX.
+Strings found in this list will be followed by a nonbreaking space, and
+the period will not produce sentence-ending space in formats like LaTeX.
+The strings may not contain spaces.
 .SS General writer options
 .TP
 \f[B]\f[CB]-s\f[B]\f[R], \f[B]\f[CB]--standalone\f[B]\f[R]
@@ -933,13 +923,11 @@ Note that, if \f[C]--resource-path\f[R] is specified, the working
 directory must be explicitly listed or it will not be searched.
 For example: \f[C]--resource-path=.:test\f[R] will search the working
 directory and the \f[C]test\f[R] subdirectory, in that order.
-.RS
-.PP
-\f[C]--resource-path\f[R] only has an effect if (a) the output format
-embeds images (for example, \f[C]docx\f[R], \f[C]pdf\f[R], or
-\f[C]html\f[R] with \f[C]--self-contained\f[R]) or (b) it is used
-together with \f[C]--extract-media\f[R].
-.RE
+This option can be used repeatedly.
+Search path components that come later on the command line will be
+searched before those that come earlier, so
+\f[C]--resource-path foo:bar --resource-path baz:bim\f[R] is equivalent
+to \f[C]--resource-path baz:bim:foo:bar\f[R].
 .TP
 \f[B]\f[CB]--request-header=\f[B]\f[R]\f[I]NAME\f[R]\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]
 Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when
@@ -1034,7 +1022,8 @@ become \f[C]\[rs]part{..}\f[R], while second-level headings remain as
 their default type.
 .TP
 \f[B]\f[CB]-N\f[B]\f[R], \f[B]\f[CB]--number-sections\f[B]\f[R]
-Number section headings in LaTeX, ConTeXt, HTML, Docx, or EPUB output.
+Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB
+output.
 By default, sections are not numbered.
 Sections with class \f[C]unnumbered\f[R] will never be numbered, even if
 \f[C]--number-sections\f[R] is specified.
@@ -1426,6 +1415,9 @@ Set the \f[C]bibliography\f[R] field in the document\[cq]s metadata to
 \f[I]FILE\f[R], overriding any value set in the metadata.
 If you supply this argument multiple times, each \f[I]FILE\f[R] will be
 added to bibliography.
+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]).
 .TP
 \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
@@ -1433,8 +1425,9 @@ Set the \f[C]csl\f[R] field in the document\[cq]s metadata to
 (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 and finally in the \f[C]csl\f[R]
-subdirectory of the pandoc user data directory.
+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
+directory.
 .TP
 \f[B]\f[CB]--citation-abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
 Set the \f[C]citation-abbreviations\f[R] field in the document\[cq]s
@@ -1443,8 +1436,9 @@ metadata to \f[I]FILE\f[R], overriding any value set in the metadata.
 \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 and finally in the \f[C]csl\f[R]
-subdirectory of the pandoc user data directory.
+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
+directory.
 .TP
 \f[B]\f[CB]--natbib\f[B]\f[R]
 Use \f[C]natbib\f[R] for citations in LaTeX output.
@@ -1510,16 +1504,16 @@ inserted.
 .TP
 \f[B]\f[CB]--gladtex\f[B]\f[R]
 Enclose TeX math in \f[C]<eq>\f[R] tags in HTML output.
-The resulting HTML can then be processed by GladTeX to produce images of
-the typeset formulas and an HTML file with links to these images.
-So, the procedure is:
+The resulting HTML can then be processed by GladTeX to produce SVG
+images of the typeset formulas and an HTML file with these images
+embedded.
 .RS
 .IP
 .nf
 \f[C]
 pandoc -s --gladtex input.md -o myfile.htex
-gladtex -d myfile-images myfile.htex
-# produces myfile.html and images in myfile-images
+gladtex -d image_dir myfile.htex
+# produces myfile.html and images in image_dir
 \f[R]
 .fi
 .RE
@@ -1623,6 +1617,11 @@ T}@T{
 PandocPDFError
 T}
 T{
+44
+T}@T{
+PandocXMLError
+T}
+T{
 47
 T}@T{
 PandocPDFProgramNotFoundError
@@ -1683,6 +1682,11 @@ T}@T{
 PandocIpynbDecodingError
 T}
 T{
+94
+T}@T{
+PandocUnsupportedCharsetError
+T}
+T{
 97
 T}@T{
 PandocCouldNotFindDataFileError
@@ -1715,6 +1719,16 @@ input-files:
 - content.md
 # or you may use input-file: with a single value
 
+# Include options from the specified defaults files.
+# The files will be searched for first in the working directory
+# and then in the defaults subdirectory of the user data directory.
+# The files are included in the same order in which they appear in
+# the list. Options specified in this defaults file always have
+# priority over the included ones.
+defaults:
+- defsA
+- defsB
+
 template: letter
 standalone: true
 self-contained: false
@@ -1772,8 +1786,11 @@ data-dir:
 verbosity: INFO
 log-file: log.json
 
-# citeproc, natbib, or biblatex
+# citeproc, natbib, or biblatex. This only affects LaTeX
+# output.  If you want to use citeproc to format citations,
+# you should also set \[aq]citeproc: true\[aq] (see above).
 cite-method: citeproc
+
 # part, chapter, section, or default:
 top-level-division: chapter
 abbreviations:
@@ -1874,6 +1891,38 @@ verbosity: INFO
 \f[R]
 .fi
 .PP
+In fields that expect a file path (or list of file paths), the following
+syntax may be used to interpolate environment variables:
+.IP
+.nf
+\f[C]
+csl:  ${HOME}/mycsldir/special.csl
+\f[R]
+.fi
+.PP
+\f[C]${USERDATA}\f[R] may also be used; this will always resolve to the
+user data directory that is current when the defaults file is parsed,
+regardless of the setting of the environment variable
+\f[C]USERDATA\f[R].
+.PP
+\f[C]${.}\f[R] will resolve to the directory containing the default file
+itself.
+This allows you to refer to resources contained in that directory:
+.IP
+.nf
+\f[C]
+epub-cover-image: ${.}/cover.jpg
+epub-metadata: ${.}/meta.xml
+resource-path:
+- .             # the working directory from which pandoc is run
+- ${.}/images   # the images subdirectory of the directory
+                # containing this defaults file
+\f[R]
+.fi
+.PP
+This environment variable interpolation syntax \f[I]only\f[R] works in
+fields that expect file paths.
+.PP
 Default files can be placed in the \f[C]defaults\f[R] subdirectory of
 the user data directory and used from any directory.
 For example, one could create a file specifying defaults for writing
@@ -2133,9 +2182,9 @@ ${ styles.html() }
 \f[R]
 .fi
 .PP
-(If a partial is not found in the directory of the template, it will
-also be sought in the \f[C]templates\f[R] subdirectory of the user data
-directory.)
+(If a partial is not found in the directory of the template and the
+template path is given as a relative path, it will also be sought in the
+\f[C]templates\f[R] subdirectory of the user data directory.)
 .PP
 Partials may optionally be applied to variables using a colon:
 .IP
@@ -2542,10 +2591,9 @@ YAML metadata or with \f[C]-M classoption=fleqn\f[R].
 .SS Variables for HTML slides
 .PP
 These affect HTML output when [producing slide shows with pandoc].
-.PP
-All reveal.js configuration options are available as variables.
-To turn off boolean flags that default to true in reveal.js, use
-\f[C]0\f[R].
+.TP
+\f[B]\f[CB]institute\f[B]\f[R]
+author affiliations: can be a list when there are multiple authors
 .TP
 \f[B]\f[CB]revealjs-url\f[B]\f[R]
 base URL for reveal.js documents (defaults to
@@ -2564,6 +2612,10 @@ base URL for Slideous documents (defaults to \f[C]slideous\f[R])
 \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.
+.PP
+All reveal.js configuration options are available as variables.
+To turn off boolean flags that default to true in reveal.js, use
+\f[C]0\f[R].
 .SS Variables for Beamer slides
 .PP
 These variables change the appearance of PDF slides using
@@ -3376,6 +3428,43 @@ This extension can be enabled/disabled for the following formats:
 .TP
 output formats
 \f[C]odt\f[R], \f[C]opendocument\f[R]
+.SS Extension: \f[C]xrefs_name\f[R]
+.PP
+Links to headings, figures and tables inside the document are
+substituted with cross-references that will use the name or caption of
+the referenced item.
+The original link text is replaced once the generated document is
+refreshed.
+This extension can be combined with \f[C]xrefs_number\f[R] in which case
+numbers will appear before the name.
+.PP
+Text in cross-references is only made consistent with the referenced
+item once the document has been refreshed.
+.PP
+This extension can be enabled/disabled for the following formats:
+.TP
+output formats
+\f[C]odt\f[R], \f[C]opendocument\f[R]
+.SS Extension: \f[C]xrefs_number\f[R]
+.PP
+Links to headings, figures and tables inside the document are
+substituted with cross-references that will use the number of the
+referenced item.
+The original link text is discarded.
+This extension can be combined with \f[C]xrefs_name\f[R] in which case
+the name or caption numbers will appear after the number.
+.PP
+For the \f[C]xrefs_number\f[R] to be useful heading numbers must be
+enabled in the generated document, also table and figure captions must
+be enabled using for example the \f[C]native_numbering\f[R] extension.
+.PP
+Numbers in cross-references are only visible in the final document once
+it has been refreshed.
+.PP
+This extension can be enabled/disabled for the following formats:
+.TP
+output formats
+\f[C]odt\f[R], \f[C]opendocument\f[R]
 .SS Extension: \f[C]styles\f[R]
 .PP
 When converting from docx, read all docx styles as divs (for paragraph
@@ -3401,6 +3490,12 @@ output format.
 .PP
 Some aspects of Pandoc\[cq]s Markdown citation syntax are also accepted
 in \f[C]org\f[R] input.
+.SS Extension: \f[C]element_citations\f[R]
+.PP
+In the \f[C]jats\f[R] output formats, this causes reference items to be
+replaced with \f[C]<element-citation>\f[R] elements.
+These elements are not influenced by CSL styles, but all information on
+the item is included in tags.
 .SS Extension: \f[C]ntb\f[R]
 .PP
 In the \f[C]context\f[R] output format this enables the use of Natural
@@ -3884,6 +3979,9 @@ begin with a space.
 \f[R]
 .fi
 .PP
+Inline formatting (such as emphasis) is allowed in the content, but not
+block-level formatting (such as block quotes or lists).
+.PP
 This syntax is borrowed from reStructuredText.
 .SS Lists
 .SS Bullet lists
@@ -4177,7 +4275,7 @@ Term 2
 Note that space between items in a definition list is required.
 (A variant that loosens this requirement, but disallows \[lq]lazy\[rq]
 hard wrapping, can be activated with \f[C]compact_definition_lists\f[R]:
-see Non-pandoc extensions, below.)
+see Non-default extensions, below.)
 .SS Numbered example lists
 .SS Extension: \f[C]example_lists\f[R]
 .PP
@@ -4698,7 +4796,9 @@ All of the metadata will appear in a single block at the beginning of
 the document.
 .PP
 Note that YAML escaping rules must be followed.
-Thus, for example, if a title contains a colon, it must be quoted.
+Thus, for example, if a title contains a colon, it must be quoted, and
+if it contains a backslash escape, then it must be ensured that it is
+not treated as a YAML escape sequence.
 The pipe character (\f[C]|\f[R]) can be used to begin an indented block
 that will be interpreted literally, without need for escaping.
 This form is necessary when the field contains blank lines or
@@ -4720,6 +4820,13 @@ abstract: |
 \f[R]
 .fi
 .PP
+The literal block after the \f[C]|\f[R] must be indented relative to the
+line containing the \f[C]|\f[R].
+If it is not, the YAML will be invalid and pandoc will not interpret it
+as metadata.
+For an overview of the complex rules governing YAML, see the Wikipedia
+entry on YAML syntax.
+.PP
 Template variables will be set automatically from the metadata.
 Thus, for example, in writing HTML, the variable \f[C]abstract\f[R] will
 be set to the HTML equivalent of the Markdown in the \f[C]abstract\f[R]
@@ -4785,6 +4892,21 @@ header-includes:
   \[ga]\[ga]\[ga]
 \f[R]
 .fi
+.PP
+Note: the \f[C]yaml_metadata_block\f[R] extension works with
+\f[C]commonmark\f[R] as well as \f[C]markdown\f[R] (and it is enabled by
+default in \f[C]gfm\f[R] and \f[C]commonmark_x\f[R]).
+However, in these formats the following restrictions apply:
+.IP \[bu] 2
+The YAML metadata block must occur at the beginning of the document (and
+there can be only one).
+If multiple files are given as arguments to pandoc, only the first can
+be a YAML metadata block.
+.IP \[bu] 2
+The leaf nodes of the YAML structure are parsed in isolation from each
+other and from the rest of the document.
+So, for example, you can\[cq]t use a reference link in these contexts if
+the link definition is somewhere else in the document.
 .SS Backslash escapes
 .SS Extension: \f[C]all_symbols_escapable\f[R]
 .PP
@@ -5004,7 +5126,9 @@ delimiters.
 .PP
 For display math, use \f[C]$$\f[R] delimiters.
 (In this case, the delimiters may be separated from the formula by
-whitespace.)
+whitespace.
+However, there can be no blank lines betwen the opening and closing
+\f[C]$$\f[R] delimiters.)
 .PP
 TeX math will be printed in all output formats.
 How it is rendered depends on the output format:
@@ -5130,8 +5254,9 @@ into
 .PP
 whereas \f[C]Markdown.pl\f[R] will preserve it as is.
 .PP
-There is one exception to this rule: text between \f[C]<script>\f[R] and
-\f[C]<style>\f[R] tags is not interpreted as Markdown.
+There is one exception to this rule: text between \f[C]<script>\f[R],
+\f[C]<style>\f[R], and \f[C]<textarea>\f[R] tags is not interpreted as
+Markdown.
 .PP
 This departure from standard Markdown should make it easier to mix
 Markdown with HTML block elements.
@@ -5662,27 +5787,70 @@ Inline and regular footnotes may be mixed freely.
 .SS Citation syntax
 .SS Extension: \f[C]citations\f[R]
 .PP
-Markdown citations go inside square brackets and are separated by
-semicolons.
-Each citation must have a key, composed of `\[at]' + the citation
-identifier from the database, and may optionally have a prefix, a
-locator, and a suffix.
-The citation key must begin with a letter, digit, or \f[C]_\f[R], and
-may contain alphanumerics, \f[C]_\f[R], and internal punctuation
-characters (\f[C]:.#$%&-+?<>\[ti]/\f[R]).
-Here are some examples:
+To cite a bibliographic item with an identifier foo, use the syntax
+\f[C]\[at]foo\f[R].
+Normal citations should be included in square brackets, with semicolons
+separating distinct items:
 .IP
 .nf
 \f[C]
-Blah blah [see \[at]doe99, pp. 33-35; also \[at]smith04, chap. 1].
-
-Blah blah [\[at]doe99, pp. 33-35, 38-39 and *passim*].
+Blah blah [\[at]doe99; \[at]smith2000; \[at]smith2004].
+\f[R]
+.fi
+.PP
+How this is rendered depends on the citation style.
+In an author-date style, it might render as
+.IP
+.nf
+\f[C]
+Blah blah (Doe 1999, Smith 2000, 2004).
+\f[R]
+.fi
+.PP
+In a footnote style, it might render as
+.IP
+.nf
+\f[C]
+Blah blah.[\[ha]1]
 
-Blah blah [\[at]smith04; \[at]doe99].
+[\[ha]1]:  John Doe, \[dq]Frogs,\[dq] *Journal of Amphibians* 44 (1999);
+Susan Smith, \[dq]Flies,\[dq] *Journal of Insects* (2000);
+Susan Smith, \[dq]Bees,\[dq] *Journal of Insects* (2004).
 \f[R]
 .fi
 .PP
-\f[C]pandoc\f[R] detects locator terms in the CSL locale files.
+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
+(\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
+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.
+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
+Citation items may optionally include a prefix, a locator, and a suffix.
+In
+.IP
+.nf
+\f[C]
+Blah blah [see \[at]doe99, pp. 33-35 and *passim*; \[at]smith04, chap. 1].
+\f[R]
+.fi
+.PP
+The first item (\f[C]doe99\f[R]) has prefix \f[C]see\f[R], locator
+\f[C]pp.  33-35\f[R], and suffix \f[C]and *passim*\f[R].
+The second item (\f[C]smith04\f[R]) has locator \f[C]chap. 1\f[R] and no
+prefix or suffix.
+.PP
+Pandoc uses some heuristics to separate the locator from the rest of the
+subject.
+It is sensitive to the locator terms defined in the CSL locale files.
 Either abbreviated or unabbreviated forms are accepted.
 In the \f[C]en-US\f[R] locale, locator terms can be written in either
 singular or plural forms, as \f[C]book\f[R],
@@ -5704,14 +5872,15 @@ singular or plural forms, as \f[C]book\f[R],
 \f[C]\[sc]\f[R]/\f[C]\[sc]\[sc]\f[R].
 If no locator term is used, \[lq]page\[rq] is assumed.
 .PP
-\f[C]pandoc\f[R] will use heuristics to distinguish the locator from the
-suffix.
-In complex cases, the locator can be enclosed in curly braces:
+In complex cases, you can force something to be treated as a locator by
+enclosing it in curly braces or prevent parsing the suffix as locator by
+prepending curly braces:
 .IP
 .nf
 \f[C]
 [\[at]smith{ii, A, D-Z}, with a suffix]
 [\[at]smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
+[\[at]smith{}, 99 years later]
 \f[R]
 .fi
 .PP
@@ -5725,7 +5894,8 @@ Smith says blah [-\[at]smith04].
 \f[R]
 .fi
 .PP
-You can also write an in-text citation, as follows:
+You can also write an author-in-text citation, by omitting the square
+brackets:
 .IP
 .nf
 \f[C]
@@ -5734,13 +5904,64 @@ You can also write an in-text citation, as follows:
 \[at]smith04 [p. 33] says blah.
 \f[R]
 .fi
-.SS Non-pandoc extensions
+.PP
+This will cause the author\[cq]s name to be rendered, followed by the
+bibliographical details.
+Use this form when you want to make the citation the subject of a
+sentence.
+.PP
+When you are using a note style, it is usually better to let citeproc
+create the footnotes from citations rather than writing an explicit
+note.
+If you do write an explicit note that contains a citation, note that
+normal citations will be put in parentheses, while author-in-text
+citations will not.
+For this reason, it is sometimes preferable to use the author-in-text
+style inside notes when using a note style.
+.SS Non-default extensions
 .PP
 The following Markdown syntax extensions are not enabled by default in
 pandoc, but may be enabled by adding \f[C]+EXTENSION\f[R] to the format
 name, where \f[C]EXTENSION\f[R] is the name of the extension.
 Thus, for example, \f[C]markdown+hard_line_breaks\f[R] is Markdown with
 hard line breaks.
+.SS Extension: \f[C]rebase_relative_paths\f[R]
+.PP
+Rewrite relative paths for Markdown links and images, depending on the
+path of the file containing the link or image link.
+For each link or image, pandoc will compute the directory of the
+containing file, relative to the working directory, and prepend the
+resulting path to the link or image path.
+.PP
+The use of this extension is best understood by example.
+Suppose you have a a subdirectory for each chapter of a book,
+\f[C]chap1\f[R], \f[C]chap2\f[R], \f[C]chap3\f[R].
+Each contains a file \f[C]text.md\f[R] and a number of images used in
+the chapter.
+You would like to have \f[C]![image](spider.jpg)\f[R] in
+\f[C]chap1/text.md\f[R] refer to \f[C]chap1/spider.jpg\f[R] and
+\f[C]![image](spider.jpg)\f[R] in \f[C]chap2/text.md\f[R] refer to
+\f[C]chap2/spider.jpg\f[R].
+To do this, use
+.IP
+.nf
+\f[C]
+pandoc chap*/*.md -f markdown+rebase_relative_paths
+\f[R]
+.fi
+.PP
+Without this extension, you would have to use
+\f[C]![image](chap1/spider.jpg)\f[R] in \f[C]chap1/text.md\f[R] and
+\f[C]![image](chap2/spider.jpg)\f[R] in \f[C]chap2/text.md\f[R].
+Links with relative paths will be rewritten in the same way as images.
+.PP
+Absolute paths and URLs are not changed.
+Neither are empty paths or paths consisting entirely of a fragment,
+e.g., \f[C]#foo\f[R].
+.PP
+Note that relative paths in reference links and images will be rewritten
+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.
@@ -5920,6 +6141,12 @@ be indented four spaces.
 Use Project Gutenberg conventions for \f[C]plain\f[R] output: all-caps
 for strong emphasis, surround by underscores for regular emphasis, add
 extra blank space around headings.
+.SS Extension: \f[C]sourcepos\f[R]
+.PP
+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 Markdown variants
 .PP
 In addition to pandoc\[cq]s extended Markdown, the following Markdown
@@ -6079,6 +6306,11 @@ references:
 \f[R]
 .fi
 .PP
+If both an external bibliography and inline (YAML metadata) references
+are provided, both will be used.
+In case of conflicting \f[C]id\f[R]s, the inline references will take
+precedence.
+.PP
 Note that \f[C]pandoc\f[R] can be used to produce such a YAML metadata
 section from a BibTeX, BibLaTeX, or CSL JSON bibliography:
 .IP
@@ -6089,13 +6321,13 @@ pandoc chem.json -s -f csljson -t markdown
 \f[R]
 .fi
 .PP
-\f[C]pandoc\f[R] can also be used to produce CSL JSON bibliography from
-BibTeX, BibLaTeX, or markdown YAML:
+Indeed, \f[C]pandoc\f[R] can convert between any of these citation
+formats:
 .IP
 .nf
 \f[C]
 pandoc chem.bib -s -f biblatex -t csljson
-pandoc chem.yaml -s -f markdown -t csljson
+pandoc chem.yaml -s -f markdown -t biblatex
 \f[R]
 .fi
 .PP
@@ -6224,6 +6456,41 @@ The format of the file can be illustrated with an example:
 }
 \f[R]
 .fi
+.SS Citations in note styles
+.PP
+Pandoc\[cq]s citation processing is designed to allow you to move
+between author-date, numerical, and note styles without modifying the
+markdown source.
+When you\[cq]re using a note style, avoid inserting footnotes manually.
+Instead, insert citations just as you would in an author-date
+style\[em]for example,
+.IP
+.nf
+\f[C]
+Blah blah [\[at]foo, p. 33].
+\f[R]
+.fi
+.PP
+The footnote will be created automatically.
+Pandoc will take care of removing the space and moving the note before
+or after the period, depending on the setting of
+\f[C]notes-after-punctuation\f[R], as described below in Other relevant
+metadata fields.
+.PP
+In some cases you may need to put a citation inside a regular footnote.
+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:
+.IP
+.nf
+\f[C]
+[\[ha]1]:  Some studies [\[at]foo; \[at]bar, p. 33] show that
+frubulicious zoosnaps are quantical.  For a survey
+of the literature, see \[at]baz [chap. 1].
+\f[R]
+.fi
 .SS Raw content in a style
 .PP
 To include raw content in a prefix, suffix, delimiter, or term, surround
@@ -6324,9 +6591,29 @@ entries (for author-date and numerical styles only).
 .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
-example in the translation of labels and the use of quotation marks.
+example in the translation of labels, the use of quotation marks, and
+the way items are sorted.
 (For backwards compatibility, \f[C]locale\f[R] may be used instead of
 \f[C]lang\f[R], but this use is deprecated.)
+.RS
+.PP
+A BCP 47 language tag is expected: for example, \f[C]en\f[R],
+\f[C]de\f[R], \f[C]en-US\f[R], \f[C]fr-CA\f[R], \f[C]ug-Cyrl\f[R].
+The unicode extension syntax (after \f[C]-u-\f[R]) may be used to
+specify options for collation (sorting) more precisely.
+Here are some examples:
+.IP \[bu] 2
+\f[C]zh-u-co-pinyin\f[R] \[en] Chinese with the Pinyin collation.
+.IP \[bu] 2
+\f[C]es-u-co-trad\f[R] \[en] Spanish with the traditional collation
+(with \f[C]Ch\f[R] sorting after \f[C]C\f[R]).
+.IP \[bu] 2
+\f[C]fr-u-kb\f[R] \[en] French with \[lq]backwards\[rq] accent sorting
+(with \f[C]cot\['e]\f[R] sorting after \f[C]c\[^o]te\f[R]).
+.IP \[bu] 2
+\f[C]en-US-u-kf-upper\f[R] \[en] English with uppercase letters sorting
+before lower (default is lower before upper).
+.RE
 .TP
 \f[B]\f[CB]notes-after-punctuation\f[B]\f[R]
 If true (the default), pandoc will put footnote citations after
@@ -6447,6 +6734,11 @@ A heading at the slide level always starts a new slide.
 .IP \[bu] 2
 Headings \f[I]below\f[R] the slide level in the hierarchy create
 headings \f[I]within\f[R] a slide.
+(In beamer, a \[lq]block\[rq] will be created.
+If the heading has the class \f[C]example\f[R], an
+\f[C]exampleblock\f[R] environment will be used; if it has the class
+\f[C]alert\f[R], an \f[C]alertblock\f[R] will be used; otherwise a
+regular \f[C]block\f[R] will be used.)
 .IP \[bu] 2
 Headings \f[I]above\f[R] the slide level in the hierarchy create
 \[lq]title slides,\[rq] which just contain the section title and help to
@@ -6847,6 +7139,16 @@ A string value.
 \f[B]\f[CB]rights\f[B]\f[R]
 A string value.
 .TP
+\f[B]\f[CB]belongs-to-collection\f[B]\f[R]
+A string value.
+identifies the name of a collection to which the EPUB Publication
+belongs.
+.TP
+\f[B]\f[CB]group-position\f[B]\f[R]
+The \f[C]group-position\f[R] field indicates the numeric position in
+which the EPUB Publication belongs relative to other works belonging to
+the same \f[C]belongs-to-collection\f[R] field.
+.TP
 \f[B]\f[CB]cover-image\f[B]\f[R]
 A string value (path to cover image).
 .TP
@@ -7362,6 +7664,20 @@ need to specify a template manually using \f[C]--template\f[R] or add a
 new default template with the name
 \f[C]default.NAME_OF_CUSTOM_WRITER.lua\f[R] to the \f[C]templates\f[R]
 subdirectory of your user data directory (see Templates).
+.SH REPRODUCIBLE BUILDS
+.PP
+Some of the document formats pandoc targets (such as EPUB, docx, and
+ODT) include build timestamps in the generated document.
+That means that the files generated on successive builds will differ,
+even if the source does not.
+To avoid this, set the \f[C]SOURCE_DATE_EPOCH\f[R] environment variable,
+and the timestamp will be taken from it instead of the current time.
+\f[C]SOURCE_DATE_EPOCH\f[R] should contain an integer unix timestamp
+(specifying the number of second since midnight UTC January 1, 1970).
+.PP
+Some document formats also include a unique identifier.
+For EPUB, this can be set explicitly by setting the \f[C]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
@@ -7392,16 +7708,16 @@ 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.
 Even if \f[C]raw_html\f[R] is disabled, users can include dangerous
-content in attributes for headings, spans, and code blocks.
+content in URLs and attributes.
 To be safe, you should run all the generated HTML through an HTML
 sanitizer.
 .SH AUTHORS
 .PP
-Copyright 2006\[en]2020 John MacFarlane (jgm\[at]berkeley.edu).
+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.
 .PP
 The Pandoc source code and all documentation may be downloaded
-from <http://pandoc.org>.
+from <https://pandoc.org>.
diff --git a/man/pandoc.1.after b/man/pandoc.1.after
index e5eabb670..7cd7a93f0 100644
--- a/man/pandoc.1.after
+++ b/man/pandoc.1.after
@@ -1,3 +1,3 @@
 .PP
 The Pandoc source code and all documentation may be downloaded
-from <http://pandoc.org>.
+from <https://pandoc.org>.