From b220165462a825aebf56d1fcc74174b721ce5e09 Mon Sep 17 00:00:00 2001
From: John MacFarlane <jgm@berkeley.edu>
Date: Thu, 17 Dec 2020 11:19:10 -0800
Subject: [PATCH] Update man page.
---
MANUAL.txt | 2 +-
man/pandoc.1 | 75 ++++++++++++++++++++++++++++++++++++++++++----------
2 files changed, 62 insertions(+), 15 deletions(-)
diff --git a/MANUAL.txt b/MANUAL.txt
index b8ddeab5e..047841d22 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -1,7 +1,7 @@
---
title: Pandoc User's Guide
author: John MacFarlane
-date: November 19, 2020
+date: December 17, 2020
---
# Synopsis
diff --git a/man/pandoc.1 b/man/pandoc.1
index 5a4c833d2..588c942ad 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.11.3
.\"
-.TH "Pandoc User\[cq]s Guide" "" "November 19, 2020" "pandoc 2.11.2" ""
+.TH "Pandoc User\[cq]s Guide" "" "December 17, 2020" "pandoc 2.11.3" ""
.hy
.SH NAME
pandoc - general markup converter
@@ -933,13 +933,6 @@ 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
.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 +1027,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 +1420,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 +1430,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 +1441,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.
@@ -3376,6 +3375,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
@@ -5920,6 +5956,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 +6121,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