From 4b229e59556e633e5ed5034c66a68490ca354ad2 Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Fri, 21 May 2021 11:41:37 -0700 Subject: Regenerate man page. --- man/pandoc.1 | 117 ++++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 92 insertions(+), 25 deletions(-) (limited to 'man') diff --git a/man/pandoc.1 b/man/pandoc.1 index 795271b36..ac5479414 100644 --- a/man/pandoc.1 +++ b/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]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 +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 -\f[C]pandoc\f[R] detects locator terms in the CSL locale files. +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 -- cgit v1.2.3