aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohn MacFarlane <jgm@berkeley.edu>2021-10-31 09:39:56 -0700
committerJohn MacFarlane <jgm@berkeley.edu>2021-10-31 09:39:56 -0700
commitd4058468735f6acb7badbb09e682f454b4763768 (patch)
tree875cb12444e07e9c46a79d77e03723aac02201fd
parent3de8f4fdc552c7ba103ec30ef79ea42ec674a8cc (diff)
downloadpandoc-d4058468735f6acb7badbb09e682f454b4763768.tar.gz
Regenerate man page.
-rw-r--r--man/pandoc.1125
1 files changed, 68 insertions, 57 deletions
diff --git a/man/pandoc.1 b/man/pandoc.1
index 0cec5d967..e8f455e57 100644
--- a/man/pandoc.1
+++ b/man/pandoc.1
@@ -1,7 +1,7 @@
'\" t
-.\" Automatically generated by Pandoc 2.14.2
+.\" Automatically generated by Pandoc 2.16
.\"
-.TH "Pandoc User\[cq]s Guide" "" "October 22, 2021" "pandoc 2.15" ""
+.TH "Pandoc User\[cq]s Guide" "" "October 30, 2021" "pandoc 2.16" ""
.hy
.SH NAME
pandoc - general markup converter
@@ -554,13 +554,14 @@ Markdown documents that use level-1 headings for sections to HTML, since
pandoc uses a level-1 heading to render the document title.
.TP
\f[B]\f[CB]--base-header-level=\f[B]\f[R]\f[I]NUMBER\f[R]
-\f[I]Deprecated. Use \f[CI]--shift-heading-level-by\f[I]=X instead,
-where X = NUMBER - 1.\f[R] Specify the base level for headings (defaults
-to 1).
+\f[I]Deprecated.
+Use \f[CI]--shift-heading-level-by\f[I]=X instead, where X = NUMBER -
+1.\f[R] Specify the base level for headings (defaults to 1).
.TP
\f[B]\f[CB]--strip-empty-paragraphs\f[B]\f[R]
-\f[I]Deprecated. Use the \f[CI]+empty_paragraphs\f[I] extension
-instead.\f[R] Ignore paragraphs with no content.
+\f[I]Deprecated.
+Use the \f[CI]+empty_paragraphs\f[I] extension instead.\f[R] Ignore
+paragraphs with no content.
This option is useful for converting word processing documents where
users have used empty paragraphs to create inter-paragraph space.
.TP
@@ -776,8 +777,8 @@ Anyone using pandoc on untrusted user input should use this option.
.TP
\f[B]\f[CB]-D\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]--print-default-template=\f[B]\f[R]\f[I]FORMAT\f[R]
Print the system default template for an output \f[I]FORMAT\f[R].
-(See \f[C]-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.) Templates
-in the user data directory are ignored.
+(See \f[C]-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.)
+Templates in the user data directory are ignored.
This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect
output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before
\f[C]--print-default-template\f[R] on the command line.
@@ -805,8 +806,8 @@ The default is \f[C]native\f[R].
\f[B]\f[CB]--dpi\f[B]\f[R]=\f[I]NUMBER\f[R]
Specify the default dpi (dots per inch) value for conversion from pixels
to inch/centimeters and vice versa.
-(Technically, the correct term would be ppi: pixels per inch.) The
-default is 96dpi.
+(Technically, the correct term would be ppi: pixels per inch.)
+The default is 96dpi.
When images contain information about dpi internally, the encoded value
is used instead of the default specified by this option.
.TP
@@ -1012,8 +1013,8 @@ Currently this option only affects the \f[C]markdown\f[R],
\f[B]\f[CB]--markdown-headings=setext\f[B]\f[R]|\f[B]\f[CB]atx\f[B]\f[R]
Specify whether to use ATX-style (\f[C]#\f[R]-prefixed) or Setext-style
(underlined) headings for level 1 and 2 headings in Markdown output.
-(The default is \f[C]atx\f[R].) ATX-style headings are always used for
-levels 3+.
+(The default is \f[C]atx\f[R].)
+ATX-style headings are always used for levels 3+.
This option also affects Markdown cells in \f[C]ipynb\f[R] output.
.TP
\f[B]\f[CB]--atx-headers\f[B]\f[R]
@@ -1433,10 +1434,11 @@ list of citations in CSL YAML format with Markdown formatting.
The style is controlled by a CSL stylesheet specified using the
\f[C]--csl\f[R] option or the \f[C]csl\f[R] field in metadata.
(If no stylesheet is specified, the \f[C]chicago-author-date\f[R] style
-will be used by default.) The citation processing transformation may be
-applied before or after filters or Lua filters (see \f[C]--filter\f[R],
-\f[C]--lua-filter\f[R]): these transformations are applied in the order
-they appear on the command line.
+will be used by default.)
+The citation processing transformation may be applied before or after
+filters or Lua filters (see \f[C]--filter\f[R], \f[C]--lua-filter\f[R]):
+these transformations are applied in the order they appear on the
+command line.
For more information, see the section on Citations.
.TP
\f[B]\f[CB]--bibliography=\f[B]\f[R]\f[I]FILE\f[R]
@@ -1451,8 +1453,8 @@ will be sought in the resource path (see \f[C]--resource-path\f[R]).
\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
\f[I]FILE\f[R], overriding any value set in the metadata.
-(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.
+(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 (see \f[C]--resource-path\f[R]) and
finally in the \f[C]csl\f[R] subdirectory of the pandoc user data
@@ -1462,8 +1464,8 @@ directory.
Set the \f[C]citation-abbreviations\f[R] field in the document\[cq]s
metadata to \f[I]FILE\f[R], overriding any value set in the metadata.
(This is equivalent to
-\f[C]--metadata citation-abbreviations=FILE\f[R].) If \f[I]FILE\f[R] is
-a URL, it will be fetched via HTTP.
+\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 (see \f[C]--resource-path\f[R]) and
finally in the \f[C]csl\f[R] subdirectory of the pandoc user data
@@ -2451,8 +2453,9 @@ including a title block in the document itself, you can set the
\f[C]title-meta\f[R], \f[C]author-meta\f[R], and \f[C]date-meta\f[R]
variables.
(By default these are set automatically, based on \f[C]title\f[R],
-\f[C]author\f[R], and \f[C]date\f[R].) The page title in HTML is set by
-\f[C]pagetitle\f[R], which is equal to \f[C]title\f[R] by default.
+\f[C]author\f[R], and \f[C]date\f[R].)
+The page title in HTML is set by \f[C]pagetitle\f[R], which is equal to
+\f[C]title\f[R] by default.
.RE
.TP
\f[B]\f[CB]subtitle\f[B]\f[R]
@@ -3148,8 +3151,9 @@ without footnotes or pipe tables.
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[C]commonmark\f[R] and \f[C]gfm\f[R].) In the following, extensions
-that also work for other formats are covered.
+\f[C]commonmark\f[R] and \f[C]gfm\f[R].)
+In the following, extensions that also work for other formats are
+covered.
.PP
Note that markdown extensions added to the \f[C]ipynb\f[R] format affect
Markdown cells in Jupyter notebooks (as do command-line options like
@@ -3932,8 +3936,8 @@ 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.
(To see which languages are supported, type
-\f[C]pandoc --list-highlight-languages\f[R].) Otherwise, the code block
-above will appear as follows:
+\f[C]pandoc --list-highlight-languages\f[R].)
+Otherwise, the code block above will appear as follows:
.IP
.nf
\f[C]
@@ -4365,7 +4369,8 @@ What if you want to put an indented code block after a list?
\f[R]
.fi
.PP
-Trouble! Here pandoc (like other Markdown implementations) will treat
+Trouble!
+Here pandoc (like other Markdown implementations) will treat
\f[C]{ my code block }\f[R] as the second paragraph of item two, and not
as a code block.
.PP
@@ -4645,9 +4650,10 @@ full text width and the cell contents will wrap, with the relative cell
widths determined by the number of dashes in the line separating the
table header from the table body.
(For example \f[C]---|-\f[R] would make the first column 3/4 and the
-second column 1/4 of the full text width.) On the other hand, if no
-lines are wider than column width, then cell contents will not be
-wrapped, and the cells will be sized to their contents.
+second column 1/4 of the full text width.)
+On the other hand, if no lines are wider than column width, then cell
+contents will not be wrapped, and the cells will be sized to their
+contents.
.PP
Note: pandoc also recognizes pipe tables of the following form, as can
be produced by Emacs\[cq] orgtbl-mode:
@@ -4680,8 +4686,9 @@ If the file begins with a title block
.PP
it will be parsed as bibliographic information, not regular text.
(It will be used, for example, in the title of standalone LaTeX or HTML
-output.) The block may contain just a title, a title and an author, or
-all three elements.
+output.)
+The block may contain just a title, a title and an author, or all three
+elements.
If you want to include an author but no title, or a title and a date but
no author, you need a blank line:
.IP
@@ -4804,8 +4811,8 @@ 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[C]---\f[R] and ends with
-\f[C]---\f[R] or \f[C]...\f[R].) Alternatively, you can use the
-\f[C]--metadata-file\f[R] option.
+\f[C]---\f[R] or \f[C]...\f[R].)
+Alternatively, you can use the \f[C]--metadata-file\f[R] option.
Using that approach however, you cannot reference content (like
footnotes) from the main markdown input document.
.PP
@@ -4814,10 +4821,10 @@ any existing document metadata.
Metadata can contain lists and objects (nested arbitrarily), but all
string scalars will be interpreted as Markdown.
Fields with names ending in an underscore will be ignored by pandoc.
-(They may be given a role by external processors.) Field names must not
-be interpretable as YAML numbers or boolean values (so, for example,
-\f[C]yes\f[R], \f[C]True\f[R], and \f[C]15\f[R] cannot be used as field
-names).
+(They may be given a role by external processors.)
+Field names must not be interpretable as YAML numbers or boolean values
+(so, for example, \f[C]yes\f[R], \f[C]True\f[R], and \f[C]15\f[R] cannot
+be used as field names).
.PP
A document may contain multiple metadata blocks.
If two metadata blocks attempt to set the same field, the value from the
@@ -5077,9 +5084,9 @@ If the superscripted or subscripted text contains spaces, these spaces
must be escaped with backslashes.
(This is to prevent accidental superscripting and subscripting through
the ordinary use of \f[C]\[ti]\f[R] and \f[C]\[ha]\f[R], and also bad
-interactions with footnotes.) Thus, if you want the letter P with `a
-cat' in subscripts, use \f[C]P\[ti]a\[rs] cat\[ti]\f[R], not
-\f[C]P\[ti]a cat\[ti]\f[R].
+interactions with footnotes.)
+Thus, if you want the letter P with `a cat' in subscripts, use
+\f[C]P\[ti]a\[rs] cat\[ti]\f[R], not \f[C]P\[ti]a cat\[ti]\f[R].
.SS Verbatim
.PP
To make a short span of text verbatim, put it inside backticks:
@@ -5503,10 +5510,10 @@ before or after the link).
The link consists of link text in square brackets, followed by a label
in square brackets.
(There cannot be space between the two unless the
-\f[C]spaced_reference_links\f[R] extension is enabled.) The link
-definition consists of the bracketed label, followed by a colon and a
-space, followed by the URL, and optionally (after a space) a link title
-either in quotes or in parentheses.
+\f[C]spaced_reference_links\f[R] extension is enabled.)
+The link definition consists of the bracketed label, followed by a colon
+and a space, followed by the URL, and optionally (after a space) a link
+title either in quotes or in parentheses.
The label must not be parseable as a citation (assuming the
\f[C]citations\f[R] extension is enabled): citations take precedence
over link labels.
@@ -6516,8 +6523,9 @@ These files are specified using the \f[C]--csl\f[R] option or the
By default, pandoc will use the Chicago Manual of Style author-date
format.
(You can override this default by copying a CSL style of your choice to
-\f[C]default.csl\f[R] in your user data directory.) The CSL project
-provides further information on finding and editing styles.
+\f[C]default.csl\f[R] in your user data directory.)
+The CSL project provides further information on finding and editing
+styles.
.PP
The \f[C]--citation-abbreviations\f[R] option (or the
\f[C]citation-abbreviations\f[R] metadata field) may be used to specify
@@ -6564,7 +6572,8 @@ 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:
+(A comma will be added if appropriate.)
+Thus:
.IP
.nf
\f[C]
@@ -6677,7 +6686,8 @@ If true, DOIs, PMCIDs, PMID, and URLs in bibliographies will be rendered
as hyperlinks.
(If an entry contains a DOI, PMCID, PMID, or URL, but none of these
fields are rendered by the style, then the title, or in the absence of a
-title the whole entry, will be hyperlinked.) Defaults to true.
+title the whole entry, will be hyperlinked.)
+Defaults to true.
.TP
\f[B]\f[CB]lang\f[B]\f[R]
The \f[C]lang\f[R] field will affect how the style is localized, for
@@ -6780,9 +6790,9 @@ files, which are assumed to be available at the relative path
\f[C]w3.org\f[R] (for Slidy).
(These paths can be changed by setting the \f[C]slidy-url\f[R],
\f[C]slideous-url\f[R], \f[C]revealjs-url\f[R], or \f[C]s5-url\f[R]
-variables; see Variables for HTML slides, above.) For DZSlides, the
-(relatively short) JavaScript and CSS are included in the file by
-default.
+variables; see Variables for HTML slides, above.)
+For DZSlides, the (relatively short) JavaScript and CSS are included in
+the file by default.
.PP
With all HTML slide formats, the \f[C]--self-contained\f[R] option can
be used to produce a single file that contains all of the data necessary
@@ -7258,8 +7268,8 @@ Same format as \f[C]creator\f[R].
.TP
\f[B]\f[CB]date\f[B]\f[R]
A string value in \f[C]YYYY-MM-DD\f[R] format.
-(Only the year is necessary.) Pandoc will attempt to convert other
-common date formats.
+(Only the year is necessary.)
+Pandoc will attempt to convert other common date formats.
.TP
\f[B]\f[CB]lang\f[B]\f[R] (or legacy: \f[B]\f[CB]language\f[B]\f[R])
A string value in BCP 47 format.
@@ -7904,8 +7914,9 @@ sanitizer.
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
-of contributors, see the file AUTHORS.md in the pandoc source code.
+(See COPYRIGHT for full copyright and warranty notices.)
+For a full list of contributors, see the file AUTHORS.md in the pandoc
+source code.
.PP
The Pandoc source code and all documentation may be downloaded
from <https://pandoc.org>.