MANUAL: wrap some overly long lines.

This commit is contained in:
John MacFarlane 2020-11-14 21:49:12 -08:00
parent b5d066f167
commit c4029dcfed

View file

@ -914,7 +914,7 @@ header when requesting a document from a URL:
`--no-check-certificate` `--no-check-certificate`
: Disable the certificate verification to allow access to : Disable the certificate verification to allow access to
unsecure HTTP resources (for example when the certificate unsecure HTTP resources (for example when the certificate
is no longer valid or self signed). is no longer valid or self signed).
@ -984,16 +984,19 @@ header when requesting a document from a URL:
`--top-level-division=default`|`section`|`chapter`|`part` `--top-level-division=default`|`section`|`chapter`|`part`
: Treat top-level headings as the given division type in LaTeX, ConTeXt, : Treat top-level headings as the given division type in
DocBook, and TEI output. The hierarchy order is part, chapter, then section; LaTeX, ConTeXt, DocBook, and TEI output. The hierarchy
all headings are shifted such that the top-level heading becomes the specified order is part, chapter, then section; all headings are
type. The default behavior is to determine the best division type via shifted such that the top-level heading becomes the
heuristics: unless other conditions apply, `section` is chosen. When the specified type. The default behavior is to determine the
`documentclass` variable is set to `report`, `book`, or `memoir` (unless the best division type via heuristics: unless other conditions
`article` option is specified), `chapter` is implied as the setting for this apply, `section` is chosen. When the `documentclass`
option. If `beamer` is the output format, specifying either `chapter` or variable is set to `report`, `book`, or `memoir` (unless the
`part` will cause top-level headings to become `\part{..}`, while `article` option is specified), `chapter` is implied as the
second-level headings remain as their default type. setting for this option. If `beamer` is the output format,
specifying either `chapter` or `part` will cause top-level
headings to become `\part{..}`, while second-level headings
remain as their default type.
`-N`, `--number-sections` `-N`, `--number-sections`
@ -1355,23 +1358,26 @@ header when requesting a document from a URL:
`--natbib` `--natbib`
: Use [`natbib`] for citations in LaTeX output. This option is not for use : Use [`natbib`] for citations in LaTeX output. This option
with the `--citeproc` option or with PDF output. It is intended for is not for use with the `--citeproc` option or with PDF
use in producing a LaTeX file that can be processed with [`bibtex`]. output. It is intended for use in producing a LaTeX file
that can be processed with [`bibtex`].
`--biblatex` `--biblatex`
: Use [`biblatex`] for citations in LaTeX output. This option is not for use : Use [`biblatex`] for citations in LaTeX output. This option
with the `--citeproc` option or with PDF output. It is intended for is not for use with the `--citeproc` option or with PDF
use in producing a LaTeX file that can be processed with [`bibtex`] or [`biber`]. output. It is intended for use in producing a LaTeX file
that can be processed with [`bibtex`] or [`biber`].
## Math rendering in HTML {.options} ## Math rendering in HTML {.options}
The default is to render TeX math as far as possible using Unicode characters. The default is to render TeX math as far as possible using
Formulas are put inside a `span` with `class="math"`, so that they may be styled Unicode characters. Formulas are put inside a `span` with
differently from the surrounding text if needed. However, this gives acceptable `class="math"`, so that they may be styled differently from the
results only for basic math, usually you will want to use `--mathjax` or another surrounding text if needed. However, this gives acceptable
of the following options. results only for basic math, usually you will want to use
`--mathjax` or another of the following options.
`--mathjax`[`=`*URL*] `--mathjax`[`=`*URL*]
@ -1385,10 +1391,11 @@ of the following options.
`--mathml` `--mathml`
: Convert TeX math to [MathML] (in `epub3`, `docbook4`, `docbook5`, `jats`, : Convert TeX math to [MathML] (in `epub3`, `docbook4`,
`html4` and `html5`). This is the default in `odt` output. Note that `docbook5`, `jats`, `html4` and `html5`). This is the
currently only Firefox and Safari (and select e-book readers) natively default in `odt` output. Note that currently only Firefox
support MathML. and Safari (and select e-book readers) natively support
MathML.
`--webtex`[`=`*URL*] `--webtex`[`=`*URL*]
@ -2178,15 +2185,16 @@ ODT or pptx.
: the base script direction, either `rtl` (right-to-left) : the base script direction, either `rtl` (right-to-left)
or `ltr` (left-to-right). or `ltr` (left-to-right).
For bidirectional documents, native pandoc `span`s and `div`s For bidirectional documents, native pandoc `span`s and
with the `dir` attribute (value `rtl` or `ltr`) can be used to `div`s with the `dir` attribute (value `rtl` or `ltr`) can
override the base direction in some output formats. be used to override the base direction in some output
This may not always be necessary if the final renderer formats. This may not always be necessary if the final
(e.g. the browser, when generating HTML) supports the renderer (e.g. the browser, when generating HTML) supports
[Unicode Bidirectional Algorithm]. the [Unicode Bidirectional Algorithm].
When using LaTeX for bidirectional documents, only the `xelatex` engine When using LaTeX for bidirectional documents, only the
is fully supported (use `--pdf-engine=xelatex`). `xelatex` engine is fully supported (use
`--pdf-engine=xelatex`).
[BCP 47]: https://tools.ietf.org/html/bcp47 [BCP 47]: https://tools.ietf.org/html/bcp47
[Unicode Bidirectional Algorithm]: https://www.w3.org/International/articles/inline-bidi-markup/uba-basics [Unicode Bidirectional Algorithm]: https://www.w3.org/International/articles/inline-bidi-markup/uba-basics
@ -2258,8 +2266,9 @@ To override or extend some [CSS] for just one document, include for example:
### Variables for HTML math ### Variables for HTML math
`classoption` `classoption`
: when using [KaTeX](#option--katex), you can render display math equations : when using [KaTeX](#option--katex), you can render display
flush left using [YAML metadata](#layout) or with `-M classoption=fleqn`. math equations flush left using [YAML metadata](#layout) or with
`-M classoption=fleqn`.
### Variables for HTML slides ### Variables for HTML slides
@ -2371,9 +2380,10 @@ Pandoc uses these variables when [creating a PDF] with a LaTeX engine.
... ...
`documentclass` `documentclass`
: document class: usually one of the standard classes, [`article`], [`book`], : document class: usually one of the standard classes,
and [`report`]; the [KOMA-Script] equivalents, `scrartcl`, `scrbook`, [`article`], [`book`], and [`report`]; the [KOMA-Script]
and `scrreprt`, which default to smaller margins; or [`memoir`] equivalents, `scrartcl`, `scrbook`, and `scrreprt`, which
default to smaller margins; or [`memoir`]
`geometry` `geometry`
: option for [`geometry`] package, e.g. `margin=1in`; : option for [`geometry`] package, e.g. `margin=1in`;
@ -2398,8 +2408,9 @@ Pandoc uses these variables when [creating a PDF] with a LaTeX engine.
... ...
`indent` `indent`
: if true, pandoc will use document class settings for indentation (the default LaTeX template : if true, pandoc will use document class settings for
otherwise removes indentation and adds space between paragraphs) indentation (the default LaTeX template otherwise removes
indentation and adds space between paragraphs)
`linestretch` `linestretch`
: adjusts line spacing using the [`setspace`] : adjusts line spacing using the [`setspace`]
@ -2424,8 +2435,8 @@ Pandoc uses these variables when [creating a PDF] with a LaTeX engine.
#### Fonts #### Fonts
`fontenc` `fontenc`
: allows font encoding to be specified through `fontenc` package (with `pdflatex`); : allows font encoding to be specified through `fontenc` package (with
default is `T1` (see [LaTeX font encodings guide]) `pdflatex`); default is `T1` (see [LaTeX font encodings guide])
`fontfamily` `fontfamily`
: font package for use with `pdflatex`: : font package for use with `pdflatex`:
@ -2495,7 +2506,8 @@ Pandoc uses these variables when [creating a PDF] with a LaTeX engine.
: contents of acknowledgments footnote after document title : contents of acknowledgments footnote after document title
`toc` `toc`
: include table of contents (can also be set using `--toc/--table-of-contents`) : include table of contents (can also be set using
`--toc/--table-of-contents`)
`toc-depth` `toc-depth`
: level of section to include in table of contents : level of section to include in table of contents
@ -2537,12 +2549,12 @@ Pandoc uses these variables when [creating a PDF] with ConTeXt.
: font size for body text (e.g. `10pt`, `12pt`) : font size for body text (e.g. `10pt`, `12pt`)
`headertext`, `footertext` `headertext`, `footertext`
: text to be placed in running header or footer (see [ConTeXt Headers and Footers]); : text to be placed in running header or footer (see [ConTeXt Headers and
repeat up to four times for different placement Footers]); repeat up to four times for different placement
`indenting` `indenting`
: controls indentation of paragraphs, e.g. `yes,small,next` (see [ConTeXt Indentation]); : controls indentation of paragraphs, e.g. `yes,small,next` (see
repeat for multiple options [ConTeXt Indentation]); repeat for multiple options
`interlinespace` `interlinespace`
: adjusts line spacing, e.g. `4ex` (using [`setupinterlinespace`]); : adjusts line spacing, e.g. `4ex` (using [`setupinterlinespace`]);
@ -2553,16 +2565,19 @@ Pandoc uses these variables when [creating a PDF] with ConTeXt.
repeat for multiple options repeat for multiple options
`linkcolor`, `contrastcolor` `linkcolor`, `contrastcolor`
: color for links outside and inside a page, e.g. `red`, `blue` (see [ConTeXt Color]) : color for links outside and inside a page, e.g. `red`, `blue` (see
[ConTeXt Color])
`linkstyle` `linkstyle`
: typeface style for links, e.g. `normal`, `bold`, `slanted`, `boldslanted`, `type`, `cap`, `small` : typeface style for links, e.g. `normal`, `bold`, `slanted`, `boldslanted`,
`type`, `cap`, `small`
`lof`, `lot` `lof`, `lot`
: include list of figures, list of tables : include list of figures, list of tables
`mainfont`, `sansfont`, `monofont`, `mathfont` `mainfont`, `sansfont`, `monofont`, `mathfont`
: font families: take the name of any system font (see [ConTeXt Font Switching]) : font families: take the name of any system font (see
[ConTeXt Font Switching])
`margin-left`, `margin-right`, `margin-top`, `margin-bottom` `margin-left`, `margin-right`, `margin-top`, `margin-bottom`
: sets margins, if `layout` is not used (otherwise `layout` : sets margins, if `layout` is not used (otherwise `layout`
@ -2577,16 +2592,18 @@ Pandoc uses these variables when [creating a PDF] with ConTeXt.
repeat for multiple options repeat for multiple options
`pdfa` `pdfa`
: adds to the preamble the setup necessary to generate PDF/A of the type : adds to the preamble the setup necessary to generate PDF/A
specified, e.g. `1a:2005`, `2a`. If no type is specified (i.e. the value of the type specified, e.g. `1a:2005`, `2a`. If no type is
is set to True, by e.g. `--metadata=pdfa` or `pdfa: true` in a YAML metadata specified (i.e. the value is set to True, by e.g.
block), `1b:2005` will be used as default, for reasons of backwards `--metadata=pdfa` or `pdfa: true` in a YAML metadata block),
compatibility. Using `--variable=pdfa` without specified value is not supported. `1b:2005` will be used as default, for reasons of backwards
To successfully generate PDF/A the required ICC color profiles have to compatibility. Using `--variable=pdfa` without specified value
be available and the content and all included files (such as images) is not supported. To successfully generate PDF/A the required
have to be standard conforming. The ICC profiles and output intent ICC color profiles have to be available and the content and all
may be specified using the variables `pdfaiccprofile` and `pdfaintent`. included files (such as images) have to be standard conforming.
See also [ConTeXt PDFA] for more details. The ICC profiles and output intent may be specified using the
variables `pdfaiccprofile` and `pdfaintent`. See also [ConTeXt
PDFA] for more details.
`pdfaiccprofile` `pdfaiccprofile`
: when used in conjunction with `pdfa`, specifies the ICC profile to use : when used in conjunction with `pdfa`, specifies the ICC profile to use
@ -2601,10 +2618,12 @@ Pandoc uses these variables when [creating a PDF] with ConTeXt.
If left unspecified, `sRGB IEC61966-2.1` is used as default. If left unspecified, `sRGB IEC61966-2.1` is used as default.
`toc` `toc`
: include table of contents (can also be set using `--toc/--table-of-contents`) : include table of contents (can also be set using
`--toc/--table-of-contents`)
`whitespace` `whitespace`
: spacing between paragraphs, e.g. `none`, `small` (using [`setupwhitespace`]) : spacing between paragraphs, e.g. `none`, `small` (using
[`setupwhitespace`])
`includesource` `includesource`
: include all source documents as file attachments in the PDF file : include all source documents as file attachments in the PDF file
@ -3033,8 +3052,8 @@ output format.
#### Extension: `citations` {#org-citations} #### Extension: `citations` {#org-citations}
Some aspects of [Pandoc's Markdown citation syntax](#citations) are also accepted Some aspects of [Pandoc's Markdown citation syntax](#citations)
in `org` input. are also accepted in `org` input.
#### Extension: `ntb` #### #### Extension: `ntb` ####
@ -3142,7 +3161,8 @@ pandoc does require the space.
### Heading identifiers ### ### Heading identifiers ###
See also the [`auto_identifiers` extension](#extension-auto_identifiers) above. See also the [`auto_identifiers`
extension](#extension-auto_identifiers) above.
#### Extension: `header_attributes` #### #### Extension: `header_attributes` ####
@ -3264,11 +3284,12 @@ block in a block quote, you need five spaces after the `>`:
#### Extension: `blank_before_blockquote` #### #### Extension: `blank_before_blockquote` ####
Standard Markdown syntax does not require a blank line before a block Standard Markdown syntax does not require a blank line before a
quote. Pandoc does require this (except, of course, at the beginning of the block quote. Pandoc does require this (except, of course, at
document). The reason for the requirement is that it is all too easy for a the beginning of the document). The reason for the requirement
`>` to end up at the beginning of a line by accident (perhaps through line is that it is all too easy for a `>` to end up at the beginning
wrapping). So, unless the `markdown_strict` format is used, the following does of a line by accident (perhaps through line wrapping). So,
unless the `markdown_strict` format is used, the following does
not produce a nested block quote in pandoc: not produce a nested block quote in pandoc:
> This is a block quote. > This is a block quote.
@ -3337,14 +3358,16 @@ this syntax:
qsort (filter (>= x) xs) qsort (filter (>= x) xs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here `mycode` is an identifier, `haskell` and `numberLines` are classes, and Here `mycode` is an identifier, `haskell` and `numberLines` are
`startFrom` is an attribute with value `100`. Some output formats can use this classes, and `startFrom` is an attribute with value `100`. Some
information to do syntax highlighting. Currently, the only output formats output formats can use this information to do syntax
that uses this information are HTML, LaTeX, Docx, Ms, and PowerPoint. If highlighting. Currently, the only output formats that uses this
highlighting is supported for your output format and language, then the code information are HTML, LaTeX, Docx, Ms, and PowerPoint. If
block above will appear highlighted, with numbered lines. (To see which highlighting is supported for your output format and language,
languages are supported, type `pandoc --list-highlight-languages`.) Otherwise, then the code block above will appear highlighted, with numbered
the code block above will appear as follows: lines. (To see which languages are supported, type `pandoc
--list-highlight-languages`.) Otherwise, the code block above
will appear as follows:
<pre id="mycode" class="haskell numberLines" startFrom="100"> <pre id="mycode" class="haskell numberLines" startFrom="100">
<code> <code>
@ -3610,11 +3633,12 @@ a blank line, and must be followed by one or more definitions.
A definition begins with a colon or tilde, which may be indented one A definition begins with a colon or tilde, which may be indented one
or two spaces. or two spaces.
A term may have multiple definitions, and each definition may consist of one or A term may have multiple definitions, and each definition may
more block elements (paragraph, code block, list, etc.), each indented four consist of one or more block elements (paragraph, code block,
spaces or one tab stop. The body of the definition (including the first line, list, etc.), each indented four spaces or one tab stop. The
aside from the colon or tilde) should be indented four spaces. However, body of the definition (including the first line, aside from the
as with other Markdown lists, you can "lazily" omit indentation except colon or tilde) should be indented four spaces. However, as with
other Markdown lists, you can "lazily" omit indentation except
at the beginning of a paragraph or other block element: at the beginning of a paragraph or other block element:
Term 1 Term 1
@ -3642,7 +3666,8 @@ Note that space between items in a definition list is required.
hard wrapping, can be activated with `compact_definition_lists`: see hard wrapping, can be activated with `compact_definition_lists`: see
[Non-pandoc extensions], below.) [Non-pandoc extensions], below.)
[^3]: I have been influenced by the suggestions of [David Wheeler](https://justatheory.com/2009/02/modest-markdown-proposal/). [^3]: I have been influenced by the suggestions of [David
Wheeler](https://justatheory.com/2009/02/modest-markdown-proposal/).
### Numbered example lists ### ### Numbered example lists ###
@ -5271,11 +5296,11 @@ The CSL project provides further information on [finding and
editing styles]. editing styles].
The `--citation-abbreviations` option (or the The `--citation-abbreviations` option (or the
`citation-abbreviations` metadata field) may be used to `citation-abbreviations` metadata field) may be used to specify
specify a JSON file containing abbreviations of journals a JSON file containing abbreviations of journals that should be
that should be used in formatted bibliographies when used in formatted bibliographies when `form="short"` is
`form="short"` is specified. The format of the file specified. The format of the file can be illustrated with an
can be illustrated with an example: example:
{ "default": { { "default": {
@ -5441,18 +5466,21 @@ To produce an HTML/JavaScript slide show, simply type
where `FORMAT` is either `s5`, `slidy`, `slideous`, `dzslides`, or `revealjs`. where `FORMAT` is either `s5`, `slidy`, `slideous`, `dzslides`, or `revealjs`.
For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with the For Slidy, Slideous, reveal.js, and S5, the file produced by
`-s/--standalone` option embeds a link to JavaScript and CSS files, which are pandoc with the `-s/--standalone` option embeds a link to
assumed to be available at the relative path `s5/default` (for S5), `slideous` JavaScript and CSS files, which are assumed to be available at
(for Slideous), `reveal.js` (for reveal.js), or at the Slidy website at the relative path `s5/default` (for S5), `slideous` (for
`w3.org` (for Slidy). (These paths can be changed by setting the `slidy-url`, Slideous), `reveal.js` (for reveal.js), or at the Slidy website
`slideous-url`, `revealjs-url`, or `s5-url` variables; see [Variables for HTML slides], at `w3.org` (for Slidy). (These paths can be changed by setting
above.) For DZSlides, the (relatively short) JavaScript and CSS are included in the `slidy-url`, `slideous-url`, `revealjs-url`, or `s5-url`
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.
With all HTML slide formats, the `--self-contained` option can be used to With all HTML slide formats, the `--self-contained` option can
produce a single file that contains all of the data necessary to display the be used to produce a single file that contains all of the data
slide show, including linked scripts, stylesheets, images, and videos. necessary to display the slide show, including linked scripts,
stylesheets, images, and videos.
To produce a PDF slide show using beamer, type To produce a PDF slide show using beamer, type