From a14e7b0c6ded03c1b022d7d359b99bec92545bb1 Mon Sep 17 00:00:00 2001
From: John MacFarlane <jgm@berkeley.edu>
Date: Wed, 3 Aug 2022 21:16:43 -0700
Subject: [PATCH] Update date on manual.
---
MANUAL.txt | 2 +-
man/pandoc.1 | 143 ++++++++++++++++++++++++++++++++++-----------------
2 files changed, 97 insertions(+), 48 deletions(-)
diff --git a/MANUAL.txt b/MANUAL.txt
index 86e013a97..9c3b2956a 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -1,7 +1,7 @@
---
title: Pandoc User's Guide
author: John MacFarlane
-date: April 4, 2022
+date: August 3, 2022
---
# Synopsis
diff --git a/man/pandoc.1 b/man/pandoc.1
index 62f390ed4..077f2412a 100644
--- a/man/pandoc.1
+++ b/man/pandoc.1
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 2.17.1.1
+.\" Automatically generated by Pandoc 2.18
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
@@ -14,7 +14,7 @@
. ftr VB CB
. ftr VBI CBI
.\}
-.TH "Pandoc User\[cq]s Guide" "" "April 4, 2022" "pandoc 2.18" ""
+.TH "Pandoc User\[cq]s Guide" "" "August 3, 2022" "pandoc 2.19" ""
.hy
.SH NAME
pandoc - general markup converter
@@ -412,9 +412,9 @@ markup)
.IP \[bu] 2
\f[V]ms\f[R] (roff ms)
.IP \[bu] 2
-\f[V]muse\f[R] (Muse),
+\f[V]muse\f[R] (Muse)
.IP \[bu] 2
-\f[V]native\f[R] (native Haskell),
+\f[V]native\f[R] (native Haskell)
.IP \[bu] 2
\f[V]odt\f[R] (OpenOffice text document)
.IP \[bu] 2
@@ -426,7 +426,7 @@ markup)
.IP \[bu] 2
\f[V]pdf\f[R] (PDF)
.IP \[bu] 2
-\f[V]plain\f[R] (plain text),
+\f[V]plain\f[R] (plain text)
.IP \[bu] 2
\f[V]pptx\f[R] (PowerPoint slide show)
.IP \[bu] 2
@@ -442,7 +442,7 @@ markup)
.IP \[bu] 2
\f[V]slidy\f[R] (Slidy HTML and JavaScript slide show)
.IP \[bu] 2
-\f[V]dzslides\f[R] (DZSlides HTML5 + JavaScript slide show),
+\f[V]dzslides\f[R] (DZSlides HTML5 + JavaScript slide show)
.IP \[bu] 2
\f[V]revealjs\f[R] (reveal.js HTML5 + JavaScript slide show)
.IP \[bu] 2
@@ -642,13 +642,13 @@ JavaScript/node.js.
.PP
In order of preference, pandoc will look for filters in
.IP "1." 3
-a specified full or relative path (executable or non-executable)
+a specified full or relative path (executable or non-executable),
.IP "2." 3
\f[V]$DATADIR/filters\f[R] (executable or non-executable) where
\f[V]$DATADIR\f[R] is the user data directory (see \f[V]--data-dir\f[R],
-above).
+above),
.IP "3." 3
-\f[V]$PATH\f[R] (executable only)
+\f[V]$PATH\f[R] (executable only).
.PP
Filters, Lua-filters, and citeproc processing are applied in the order
specified on the command line.
@@ -672,7 +672,7 @@ 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
+a specified full or relative path,
.IP "2." 3
\f[V]$DATADIR/filters\f[R] where \f[V]$DATADIR\f[R] is the user data
directory (see \f[V]--data-dir\f[R], above).
@@ -805,6 +805,16 @@ production of PDF documents.
But it does offer security against, for example, disclosure of files
through the use of \f[V]include\f[R] directives.
Anyone using pandoc on untrusted user input should use this option.
+.RS
+.PP
+Note: some readers and writers (e.g., \f[V]docx\f[R]) need access to
+data files.
+If these are stored on the file system, then pandoc will not be able to
+find them when run in \f[V]--sandbox\f[R] mode and will raise an error.
+For these applications, we recommend using a pandoc binary compiled with
+the \f[V]embed_data_files\f[R] option, which causes the data files to be
+baked into the binary instead of being stored on the file system.
+.RE
.TP
\f[V]-D\f[R] \f[I]FORMAT\f[R], \f[V]--print-default-template=\f[R]\f[I]FORMAT\f[R]
Print the system default template for an output \f[I]FORMAT\f[R].
@@ -985,10 +995,13 @@ signed).
.SS Options affecting specific writers
.TP
\f[V]--self-contained\f[R]
+\f[I]Deprecated synonym for
+\f[VI]--embed-resources --standalone\f[I].\f[R]
+.TP
+\f[V]--embed-resources\f[R]
Produce a standalone HTML file with no external dependencies, using
\f[V]data:\f[R] URIs to incorporate the contents of linked scripts,
stylesheets, images, and videos.
-Implies \f[V]--standalone\f[R].
The resulting file should be \[lq]self-contained,\[rq] in the sense that
it needs no external files and no net access to be displayed properly by
a browser.
@@ -1220,6 +1233,8 @@ Heading 9
.IP \[bu] 2
Block Text
.IP \[bu] 2
+Source Code
+.IP \[bu] 2
Footnote Text
.IP \[bu] 2
Definition Term
@@ -1438,8 +1453,7 @@ depending on the output format specified using \f[V]-t/--to\f[R]:
.IP \[bu] 2
\f[V]-t html\f[R]: \f[V]wkhtmltopdf\f[R] (other options:
\f[V]prince\f[R], \f[V]weasyprint\f[R], \f[V]pagedjs-cli\f[R]; see
-print-css.rocks for a good introduction to PDF generation from
-HTML/CSS.)
+print-css.rocks for a good introduction to PDF generation from HTML/CSS)
.IP \[bu] 2
\f[V]-t ms\f[R]: \f[V]pdfroff\f[R]
.RE
@@ -2161,7 +2175,7 @@ So, for example, \f[V]employee.salary\f[R] will return the value of the
\f[V]salary\f[R] field of the object that is the value of the
\f[V]employee\f[R] field.
.IP \[bu] 2
-If the value of the variable is simple value, it will be rendered
+If the value of the variable is a simple value, it will be rendered
verbatim.
(Note that no escaping is done; the assumption is that the calling
program will escape the strings appropriately for the output format.)
@@ -2228,7 +2242,7 @@ $endif$
.PP
A for loop begins with \f[V]for(variable)\f[R] (enclosed in matched
delimiters) and ends with \f[V]endfor\f[R] (enclosed in matched
-delimiters.
+delimiters).
.IP \[bu] 2
If \f[V]variable\f[R] is an array, the material inside the loop will be
evaluated repeatedly, with \f[V]variable\f[R] being set to each value of
@@ -2494,7 +2508,7 @@ This can be used to get lettered enumeration from array indices.
To get uppercase letters, chain with \f[V]uppercase\f[R].
.IP \[bu] 2
\f[V]roman\f[R]: Converts textual values that can be read as an integer
-into lowercase roman numerials.
+into lowercase roman numerals.
This can be used to get lettered enumeration from array indices.
To get uppercase roman, chain with \f[V]uppercase\f[R].
.IP \[bu] 2
@@ -2718,7 +2732,7 @@ when using KaTeX, you can render display math equations flush left using
YAML metadata or with \f[V]-M classoption=fleqn\f[R].
.SS Variables for HTML slides
.PP
-These affect HTML output when [producing slide shows with pandoc].
+These affect HTML output when producing slide shows with pandoc.
.TP
\f[V]institute\f[R]
author affiliations: can be a list when there are multiple authors
@@ -2739,7 +2753,7 @@ base URL for Slideous documents (defaults to \f[V]slideous\f[R])
.TP
\f[V]title-slide-attributes\f[R]
additional attributes for the title slide of reveal.js slide shows.
-See [background in reveal.js and beamer] for an example.
+See background in reveal.js, beamer, and pptx 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
@@ -2976,6 +2990,10 @@ add color to link text; automatically enabled if any of
\f[V]linkcolor\f[R], \f[V]filecolor\f[R], \f[V]citecolor\f[R],
\f[V]urlcolor\f[R], or \f[V]toccolor\f[R] are set
.TP
+\f[V]boxlinks\f[R]
+add visible box around links (has no effect if \f[V]colorlinks\f[R] is
+set)
+.TP
\f[V]linkcolor\f[R], \f[V]filecolor\f[R], \f[V]citecolor\f[R], \f[V]urlcolor\f[R], \f[V]toccolor\f[R]
color for internal links, external links, citation links, linked URLs,
and links in table of contents, respectively: uses options allowed by
@@ -3007,11 +3025,11 @@ list of options for biblatex
.TP
\f[V]biblio-style\f[R]
bibliography style, when used with \f[V]--natbib\f[R] and
-\f[V]--biblatex\f[R].
+\f[V]--biblatex\f[R]
.TP
\f[V]biblio-title\f[R]
bibliography title, when used with \f[V]--natbib\f[R] and
-\f[V]--biblatex\f[R].
+\f[V]--biblatex\f[R]
.TP
\f[V]bibliography\f[R]
bibliography to use for resolving references
@@ -3080,7 +3098,7 @@ Using \f[V]--variable=pdfa\f[R] without specified value is not
supported.
To successfully generate PDF/A the required ICC color profiles have to
be available and the content and all included files (such as images)
-have to be standard conforming.
+have to be standard-conforming.
The ICC profiles and output intent may be specified using the variables
\f[V]pdfaiccprofile\f[R] and \f[V]pdfaintent\f[R].
See also ConTeXt PDFA for more details.
@@ -3171,7 +3189,7 @@ The recognized formats for \f[V]date\f[R] are: \f[V]mm/dd/yyyy\f[R],
\f[V]dd MM yyyy\f[R] (e.g.\ either \f[V]02 Apr 2018\f[R] or
\f[V]02 April 2018\f[R]), \f[V]MM dd, yyyy\f[R]
(e.g.\ \f[V]Apr. 02, 2018\f[R] or
-\f[V]April 02, 2018),\f[R]yyyy[mm[dd]]]\f[V](e.g.\f[R]20180402,
+\f[V]April 02, 2018),\f[R]yyyy[mm[dd]]\f[V](e.g.\f[R]20180402,
\f[V]201804\f[R] or \f[V]2018\f[R]).
.TP
\f[V]header-includes\f[R]
@@ -3241,8 +3259,8 @@ without footnotes or pipe tables.
.PP
The markdown reader and writer make by far the most use of extensions.
Extensions only used by them are therefore covered in the section
-Pandoc\[cq]s Markdown below (See Markdown variants for
-\f[V]commonmark\f[R] and \f[V]gfm\f[R].)
+Pandoc\[cq]s Markdown below (see Markdown variants for
+\f[V]commonmark\f[R] and \f[V]gfm\f[R]).
In the following, extensions that also work for other formats are
covered.
.PP
@@ -4015,7 +4033,7 @@ Here \f[V]mycode\f[R] is an identifier, \f[V]haskell\f[R] and
\f[V]numberLines\f[R] are classes, and \f[V]startFrom\f[R] is an
attribute with value \f[V]100\f[R].
Some output formats can use this information to do syntax highlighting.
-Currently, the only output formats that uses this information are HTML,
+Currently, the only output formats that use this information are HTML,
LaTeX, Docx, Ms, and PowerPoint.
If highlighting is supported for your output format and language, then
the code block above will appear highlighted, with numbered lines.
@@ -4262,7 +4280,7 @@ Unlike original Markdown, pandoc allows ordered list items to be marked
with uppercase and lowercase letters and roman numerals, in addition to
Arabic numerals.
List markers may be enclosed in parentheses or followed by a single
-right-parentheses or period.
+right-parenthesis or period.
They must be separated from the text that follows by at least one space,
and, if the list marker is a capital letter with a period, by at least
two spaces.
@@ -4502,6 +4520,11 @@ horizontal rule:
---------------
\f[R]
.fi
+.PP
+We strongly recommend that horizontal rules be separated from
+surrounding text by blank lines.
+If a horizontal rule is not followed by a blank line, pandoc may try to
+interpret the lines that follow as a YAML metadata block or a table.
.SS Tables
.PP
Four kinds of tables may be used.
@@ -4881,9 +4904,11 @@ will also have \[lq]Version 4.0\[rq] in the header.
A YAML metadata block is a valid YAML object, delimited by a line of
three hyphens (\f[V]---\f[R]) at the top and a line of three hyphens
(\f[V]---\f[R]) or three dots (\f[V]...\f[R]) at the bottom.
+The initial line \f[V]---\f[R] must not be followed by a blank line.
A YAML metadata block may occur anywhere in the document, but if it is
not at the beginning, it must be preceded by a blank line.
-(Note that, because of the way pandoc concatenates input files when
+.PP
+Note that, because of the way pandoc concatenates input files when
several are provided, you may also keep the metadata in a separate YAML
file and pass it to pandoc as an argument, along with your Markdown
files:
@@ -4895,7 +4920,7 @@ pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
.fi
.PP
Just be sure that the YAML file begins with \f[V]---\f[R] and ends with
-\f[V]---\f[R] or \f[V]...\f[R].)
+\f[V]---\f[R] or \f[V]...\f[R].
Alternatively, you can use the \f[V]--metadata-file\f[R] option.
Using that approach however, you cannot reference content (like
footnotes) from the main markdown input document.
@@ -5008,7 +5033,7 @@ $endfor$
Raw content to include in the document\[cq]s header may be specified
using \f[V]header-includes\f[R]; however, it is important to mark up
this content as raw code for a particular output format, using the
-\f[V]raw_attribute\f[R] extension), or it will be interpreted as
+\f[V]raw_attribute\f[R] extension, or it will be interpreted as
markdown.
For example:
.IP
@@ -5136,10 +5161,30 @@ If you want to emphasize just part of a word, use \f[V]*\f[R]:
feas*ible*, not feas*able*.
\f[R]
.fi
+.SS Highlighting
+.PP
+To highlight text, use the \f[V]mark\f[R] class:
+.IP
+.nf
+\f[C]
+[Mark]{.mark}
+\f[R]
+.fi
+.PP
+Or, without the \f[V]bracketed_spans\f[R] extension (but with
+\f[V]native_spans\f[R]):
+.IP
+.nf
+\f[C]
+<span class=\[dq]mark\[dq]>Mark</span>
+\f[R]
+.fi
+.PP
+This will work in html output.
.SS Strikeout
.SS Extension: \f[V]strikeout\f[R]
.PP
-To strikeout a section of text with a horizontal line, begin and end it
+To strike out a section of text with a horizontal line, begin and end it
with \f[V]\[ti]\[ti]\f[R].
Thus, for example,
.IP
@@ -5302,7 +5347,7 @@ AsciiDoc
For AsciiDoc output format (\f[V]-t asciidoc\f[R]) it will appear
verbatim surrounded by \f[V]latexmath:[$...$]\f[R] (for inline math) or
\f[V][latexmath]++++\[rs][...\[rs]]+++\f[R] (for display math).
-For AsciiDoctor output format (\f[V]-t asciidoctor\f[R]) the LaTex
+For AsciiDoctor output format (\f[V]-t asciidoctor\f[R]) the LaTeX
delimiters (\f[V]$..$\f[R] and \f[V]\[rs][..\[rs]]\f[R]) are omitted.
.TP
Texinfo
@@ -5329,7 +5374,7 @@ If the \f[V]--mathml\f[R] flag is used, it will be rendered using MathML
in an \f[V]inlineequation\f[R] or \f[V]informalequation\f[R] tag.
Otherwise it will be rendered, if possible, using Unicode characters.
.TP
-Docx
+Docx and PowerPoint
It will be rendered using OMML math markup.
.TP
FictionBook2
@@ -5608,7 +5653,7 @@ Here are some examples:
\f[C]
[my label 1]: /foo/bar.html \[dq]My title, optional\[dq]
[my label 2]: /foo
-[my label 3]: https://fsf.org (The free software foundation)
+[my label 3]: https://fsf.org (The Free Software Foundation)
[my label 4]: /bar#special \[aq]A title in single quotes\[aq]
\f[R]
.fi
@@ -5626,7 +5671,7 @@ The title may go on the next line:
.nf
\f[C]
[my label 3]: https://fsf.org
- \[dq]The free software foundation\[dq]
+ \[dq]The Free Software Foundation\[dq]
\f[R]
.fi
.PP
@@ -5655,7 +5700,7 @@ See [my website][].
Note: In \f[V]Markdown.pl\f[R] and most other Markdown implementations,
reference link definitions cannot occur in nested constructions such as
list items or block quotes.
-Pandoc lifts this arbitrary seeming restriction.
+Pandoc lifts this arbitrary-seeming restriction.
So the following is fine in pandoc, though not in most other
implementations:
.IP
@@ -5927,7 +5972,7 @@ The syntax is as follows:
.IP
.nf
\f[C]
-Here is an inline note.\[ha][Inlines notes are easier to write, since
+Here is an inline note.\[ha][Inline notes are easier to write, since
you don\[aq]t have to pick an identifier and move down to type the
note.]
\f[R]
@@ -5972,7 +6017,7 @@ Susan Smith, \[dq]Bees,\[dq] *Journal of Insects* (2004).
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[V]_\f[R], and
+Unless a citation key starts with a letter, digit, or \f[V]_\f[R], and
contains only alphanumerics and single internal punctuation characters
(\f[V]:.#$%&-+?<>\[ti]/\f[R]), it must be surrounded by curly braces,
which are not considered part of the key.
@@ -5995,7 +6040,7 @@ Blah blah [see \[at]doe99, pp. 33-35 and *passim*; \[at]smith04, chap. 1].
\f[R]
.fi
.PP
-The first item (\f[V]doe99\f[R]) has prefix \f[V]see\f[R], locator
+the first item (\f[V]doe99\f[R]) has prefix \f[V]see\f[R], locator
\f[V]pp. 33-35\f[R], and suffix \f[V]and *passim*\f[R].
The second item (\f[V]smith04\f[R]) has locator \f[V]chap. 1\f[R] and no
prefix or suffix.
@@ -6086,7 +6131,7 @@ containing file, relative to the working directory, and prepend the
resulting path to the link or image path.
.PP
The use of this extension is best understood by example.
-Suppose you have a a subdirectory for each chapter of a book,
+Suppose you have a subdirectory for each chapter of a book,
\f[V]chap1\f[R], \f[V]chap2\f[R], \f[V]chap3\f[R].
Each contains a file \f[V]text.md\f[R] and a number of images used in
the chapter.
@@ -6372,7 +6417,7 @@ To use this feature, you will need to have
a document containing citations (see Extension: \f[V]citations\f[R]);
.IP \[bu] 2
a source of bibliographic data: either an external bibliography file or
-a list of \f[V]references\f[R] in the document\[cq]s YAML metadata
+a list of \f[V]references\f[R] in the document\[cq]s YAML metadata;
.IP \[bu] 2
optionally, a CSL citation style.
.SS Specifying bibliographic data
@@ -6817,7 +6862,7 @@ that can be viewed via a web browser.
There are five ways to do this, using S5, DZSlides, Slidy, Slideous, or
reveal.js.
You can also produce a PDF slide show using LaTeX \f[V]beamer\f[R], or
-slides shows in Microsoft PowerPoint format.
+slide shows in Microsoft PowerPoint format.
.PP
Here\[cq]s the Markdown source for a simple slide show,
\f[V]habits.txt\f[R]:
@@ -6897,7 +6942,7 @@ pandoc -t beamer habits.txt -o habits.pdf
Note that a reveal.js slide show can also be converted to a PDF by
printing it to a file from the browser.
.PP
-To produce a Powerpoint slide show, type
+To produce a PowerPoint slide show, type
.IP
.nf
\f[C]
@@ -7028,7 +7073,7 @@ or
\f[R]
.fi
.PP
-While using \f[V]incremental\f[R] and \f[V]nonincremental\f[R] divs are
+While using \f[V]incremental\f[R] and \f[V]nonincremental\f[R] divs is
the recommended method of setting incremental lists on a per-case basis,
an older method is also supported: putting lists inside a blockquote
will depart from the document default (that is, it will display
@@ -7418,7 +7463,7 @@ A string value.
.TP
\f[V]belongs-to-collection\f[R]
A string value.
-identifies the name of a collection to which the EPUB Publication
+Identifies the name of a collection to which the EPUB Publication
belongs.
.TP
\f[V]group-position\f[R]
@@ -7542,7 +7587,7 @@ If the input format already is HTML then
Similarly, for Markdown, external images can be declared with
\f[V]{external=1}\f[R].
Note that this only works for images; the other media elements have no
-native representation in pandoc\[cq]s AST and requires the use of raw
+native representation in pandoc\[cq]s AST and require the use of raw
HTML.
.SS EPUB styling
.PP
@@ -7725,7 +7770,7 @@ pandoc --highlight-style my.theme
\f[R]
.fi
.PP
-If you are not satisfied with the built-in highlighting, or you want
+If you are not satisfied with the built-in highlighting, or you want to
highlight a language that isn\[cq]t supported, you can use the
\f[V]--syntax-definition\f[R] option to load a KDE-style XML syntax
definition file.
@@ -7863,6 +7908,10 @@ pandoc -f my_custom_markup_language.lua -t latex -s
\f[R]
.fi
.PP
+If the script is not found relative to the working directory, it will be
+sought in the \f[V]readers\f[R] or \f[V]writers\f[R] subdirectory of the
+user data directory (see \f[V]--data-dir\f[R]).
+.PP
A custom reader is a Lua script that defines one function, Reader, which
takes a string as input and returns a Pandoc AST.
See the Lua filters documentation for documentation of the functions
@@ -7906,7 +7955,7 @@ even if the source does not.
To avoid this, set the \f[V]SOURCE_DATE_EPOCH\f[R] environment variable,
and the timestamp will be taken from it instead of the current time.
\f[V]SOURCE_DATE_EPOCH\f[R] should contain an integer unix timestamp
-(specifying the number of second since midnight UTC January 1, 1970).
+(specifying the number of seconds since midnight UTC January 1, 1970).
.PP
Some document formats also include a unique identifier.
For EPUB, this can be set explicitly by setting the \f[V]identifier\f[R]