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: [PATCH] Update README and man page.
---
MANUAL.txt | 2 +-
README.md | 2 ++
man/pandoc.1 | 97 +++++++++++++++++++++++++++++++++++++---------------
3 files changed, 73 insertions(+), 28 deletions(-)
diff --git a/MANUAL.txt b/MANUAL.txt
index 93b7c4a81..d113ea59f 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -1,7 +1,7 @@
---
title: Pandoc User's Guide
author: John MacFarlane
-date: December 29, 2020
+date: January 21, 2021
---
# Synopsis
diff --git a/README.md b/README.md
index 9317438fc..744c52f52 100644
--- a/README.md
+++ b/README.md
@@ -95,6 +95,8 @@ It can convert *to*
- `asciidoc` ([AsciiDoc](https://www.methods.co.nz/asciidoc/)) or
`asciidoctor` ([AsciiDoctor](https://asciidoctor.org/))
- `beamer` ([LaTeX beamer](https://ctan.org/pkg/beamer) slide show)
+- `bibtex` ([BibTeX](https://ctan.org/pkg/bibtex) bibliography)
+- `biblatex` ([BibLaTeX](https://ctan.org/pkg/biblatex) bibliography)
- `commonmark` ([CommonMark](https://commonmark.org) Markdown)
- `commonmark_x` ([CommonMark](https://commonmark.org) Markdown with
extensions)
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