From 54d8c6959cc53e78cfea2093b33504672f81ed74 Mon Sep 17 00:00:00 2001
From: John MacFarlane <jgm@berkeley.edu>
Date: Fri, 22 Jan 2021 21:37:29 -0800
Subject: Update README and man page.

---
 man/pandoc.1 | 97 +++++++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 70 insertions(+), 27 deletions(-)

(limited to 'man')

diff --git a/man/pandoc.1 b/man/pandoc.1
index 8af64c17b..491e24278 100644
--- a/man/pandoc.1
+++ b/man/pandoc.1
@@ -1,7 +1,7 @@
 '\" t
-.\" Automatically generated by Pandoc 2.11.3.1
+.\" Automatically generated by Pandoc 2.11.4
 .\"
-.TH "Pandoc User\[cq]s Guide" "" "December 29, 2020" "pandoc 2.11.3.2" ""
+.TH "Pandoc User\[cq]s Guide" "" "January 21, 2021" "pandoc 2.11.4" ""
 .hy
 .SH NAME
 pandoc - general markup converter
@@ -320,6 +320,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)
@@ -623,8 +627,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 +645,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]]
@@ -1714,6 +1706,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
@@ -3437,6 +3439,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
@@ -6137,13 +6145,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
@@ -6272,6 +6280,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
@@ -7445,7 +7488,7 @@ 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
-- 
cgit v1.2.3