Regenerate man page.

MANUAL.txt

@@ -1,7 +1,7 @@
 ---
 title: Pandoc User's Guide
 author: John MacFarlane
-date: May 13, 2021
+date: May 21, 2021
 ---
 
 # Synopsis

man/pandoc.1

@@ -1,7 +1,7 @@
 '\" t
-.\" Automatically generated by Pandoc 2.13
+.\" Automatically generated by Pandoc 2.14
 .\"
-.TH "Pandoc User\[cq]s Guide" "" "May 13, 2021" "pandoc 2.14" ""
+.TH "Pandoc User\[cq]s Guide" "" "May 21, 2021" "pandoc 2.14" ""
 .hy
 .SH NAME
 pandoc - general markup converter
@@ -2591,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
@@ -2613,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
@@ -4793,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
@@ -5775,27 +5780,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]smith04; \[at]doe99].
+Blah blah [\[at]doe99; \[at]smith2000; \[at]smith2004].
 \f[R]
 .fi
 .PP
-\f[C]pandoc\f[R] detects locator terms in the CSL locale files.
+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]
+
+[\[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
+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],
@@ -5817,9 +5865,8 @@ 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:
 .IP
 .nf
 \f[C]
@@ -5838,7 +5885,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]
@@ -5847,6 +5895,20 @@ You can also write an in-text citation, as follows:
 \[at]smith04 [p. 33] says blah.
 \f[R]
 .fi
+.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-pandoc extensions
 .PP
 The following Markdown syntax extensions are not enabled by default in
@@ -6626,6 +6688,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