diff options
Diffstat (limited to 'pandoc-cli/man/pandoc.1')
| -rw-r--r-- | pandoc-cli/man/pandoc.1 | 166 |
1 files changed, 118 insertions, 48 deletions
diff --git a/pandoc-cli/man/pandoc.1 b/pandoc-cli/man/pandoc.1 index 7a2dd7f7c..7d2153ed6 100644 --- a/pandoc-cli/man/pandoc.1 +++ b/pandoc-cli/man/pandoc.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.7.0.2 +.\" Automatically generated by Pandoc 3.8 .\" -.TH "pandoc" "1" "2025\-05\-28" "pandoc 3.7.0.2" "Pandoc User\[cq]s Guide" +.TH "pandoc" "1" "2025\-09\-06" "pandoc 3.8" "Pandoc User\[cq]s Guide" .SH NAME pandoc - general markup converter .SH SYNOPSIS @@ -174,6 +174,8 @@ available, and \f[CR]csquotes\f[R] will be used for typography if the \f[CR]csquotes\f[R] variable or metadata field is set to a true value. The \f[CR]natbib\f[R], \f[CR]biblatex\f[R], \f[CR]bibtex\f[R], and \f[CR]biber\f[R] packages can optionally be used for citation rendering. +If math with \f[CR]\(rscancel\f[R], \f[CR]\(rsbcancel\f[R], or +\f[CR]\(rsxcancel\f[R] is used, the \f[CR]cancel\f[R] package is needed. The following packages will be used to improve output quality if present, but pandoc does not require them to be present: \f[CR]upquote\f[R] (for straight quotes in verbatim environments), @@ -298,6 +300,8 @@ if you need extensions not supported in \f[CR]gfm\f[R]. .IP \(bu 2 \f[CR]vimwiki\f[R] (Vimwiki) .IP \(bu 2 +\f[CR]xml\f[R] (XML version of native AST) +.IP \(bu 2 the path of a custom Lua reader, see Custom readers and writers below .PP Extensions can be individually enabled or disabled by appending @@ -438,6 +442,8 @@ markup) .IP \(bu 2 \f[CR]typst\f[R] (typst) .IP \(bu 2 +\f[CR]xml\f[R] (XML version of native AST) +.IP \(bu 2 \f[CR]xwiki\f[R] (XWiki markup) .IP \(bu 2 \f[CR]zimwiki\f[R] (ZimWiki markup) @@ -544,7 +550,7 @@ List supported languages for syntax highlighting, one per line. .TP \f[CR]\-\-list\-highlight\-styles\f[R] List supported styles for syntax highlighting, one per line. -See \f[CR]\-\-highlight\-style\f[R]. +See \f[CR]\-\-syntax\-highlighting\f[R]. .TP \f[CR]\-v\f[R], \f[CR]\-\-version\f[R] Print version. @@ -943,19 +949,35 @@ passing them on to Markdown, Textile or HTML output as raw HTML. This does not apply to HTML comments inside raw HTML blocks when the \f[CR]markdown_in_html_blocks\f[R] extension is not set. .TP -\f[CR]\-\-no\-highlight\f[R] -Disables syntax highlighting for code blocks and inlines, even when a -language attribute is given. -.TP -\f[CR]\-\-highlight\-style=\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R] -Specifies the coloring style to be used in highlighted source code. -Options are \f[CR]pygments\f[R] (the default), \f[CR]kate\f[R], +\f[CR]\-\-syntax\-highlighting=\(dqdefault\(dq|\(dqnone\(dq|\(dqidiomatic\(dq|\f[R]\f[I]STYLE\f[R]\f[CR]|\f[R]\f[I]FILE\f[R] +The method to use for code syntax highlighting. +Setting a specific \f[I]STYLE\f[R] causes highlighting to be performed +with the internal highlighting engine, using KDE syntax definitions and +styles. +The \f[CR]\(dqidiomatic\(dq\f[R] method uses a format\-specific +highlighter if one is available, or the default style if the target +format has no idiomatic highlighting method. +Setting this option to \f[CR]none\f[R] disables all syntax highlighting. +The \f[CR]\(dqdefault\(dq\f[R] method uses a format\-specific default. +.RS +.PP +The default for HTML, EPUB, Docx, Ms, Man, and LaTeX output is to use +the internal highlighter with the default style; Typst output relies on +Typst\(cqs own syntax highlighting system by default. +.PP +The \f[CR]listings\f[R] LaTeX package is used for idiomatic highlighting +in LaTeX. +The package does not support multi\-byte encoding for source code. +To handle UTF\-8 you would need to use a custom template. +This issue is fully documented here: Encoding issue with the listings +package. +.PP +Style options are \f[CR]pygments\f[R] (the default), \f[CR]kate\f[R], \f[CR]monochrome\f[R], \f[CR]breezeDark\f[R], \f[CR]espresso\f[R], \f[CR]zenburn\f[R], \f[CR]haddock\f[R], and \f[CR]tango\f[R]. For more information on syntax highlighting in pandoc, see Syntax highlighting, below. See also \f[CR]\-\-list\-highlight\-styles\f[R]. -.RS .PP Instead of a \f[I]STYLE\f[R] name, a JSON file with extension \f[CR].theme\f[R] may be supplied. @@ -966,10 +988,28 @@ To generate the JSON version of an existing style, use \f[CR]\-\-print\-highlight\-style\f[R]. .RE .TP +\f[CR]\-\-no\-highlight\f[R] +\f[I]Deprecated, use \f[CI]\-\-syntax\-highlighting=none\f[I] +instead.\f[R] +.RS +.PP +Disables syntax highlighting for code blocks and inlines, even when a +language attribute is given. +.RE +.TP +\f[CR]\-\-highlight\-style=\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R] +\f[I]Deprecated, use +\f[CI]\-\-syntax\-highlighting=\f[I]\f[R]STYLE\f[I]|\f[R]FILE\f[I] +instead.\f[R] +.RS +.PP +Specifies the coloring style to be used in highlighted source code. +.RE +.TP \f[CR]\-\-print\-highlight\-style=\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R] Prints a JSON version of a highlighting style, which can be modified, saved with a \f[CR].theme\f[R] extension, and used with -\f[CR]\-\-highlight\-style\f[R]. +\f[CR]\-\-syntax\-highlighting\f[R]. This option may be used with \f[CR]\-o\f[R]/\f[CR]\-\-output\f[R] to redirect output to a file, but \f[CR]\-o\f[R]/\f[CR]\-\-output\f[R] must come before \f[CR]\-\-print\-highlight\-style\f[R] on the command line. @@ -1191,11 +1231,16 @@ Implies \f[CR]\-\-number\-sections\f[R]. Currently this feature only affects HTML and Docx output. .TP \f[CR]\-\-listings[=true|false]\f[R] +*Deprecated, use \f[CR]\-\-syntax\-highlighting=idiomatic\f[R] or +\f[CR]\-\-syntax\-highlighting=default\f[R] instead. +.RS +.PP Use the \f[CR]listings\f[R] package for LaTeX code blocks. The package does not support multi\-byte encoding for source code. To handle UTF\-8 you would need to use a custom template. This issue is fully documented here: Encoding issue with the listings package. +.RE .TP \f[CR]\-i\f[R], \f[CR]\-\-incremental[=true|false]\f[R] Make list items in slide shows display incrementally (one by one). @@ -1794,6 +1839,7 @@ Nonzero exit codes have the following meanings: 92 PandocUTF8DecodingError 93 PandocIpynbDecodingError 94 PandocUnsupportedCharsetError + 95 PandocInputNotTextError 97 PandocCouldNotFindDataFileError 98 PandocCouldNotFindMetadataFileError 99 PandocResourceNotFound @@ -2004,9 +2050,9 @@ or \f[CR]{type: citeproc}\f[R]. \-\-strip\-comments strip\-comments: true - \-\-no\-highlight highlight\-style: null + \-\-no\-highlight syntax\-highlighting: \(aqnone\(aq - \-\-highlight\-style kate highlight\-style: kate + \-\-syntax\-highlighting kate syntax\-highlighting: kate \-\-syntax\-definition mylang.xml syntax\-definitions: \- mylang.xml @@ -2639,7 +2685,6 @@ author: \- Peter Abelard \&... .EE -.PP Note that if you just want to set PDF or HTML metadata, without including a title block in the document itself, you can set the \f[CR]title\-meta\f[R], \f[CR]author\-meta\f[R], and @@ -2659,7 +2704,7 @@ document summary, included in HTML, LaTeX, ConTeXt, AsciiDoc, and docx documents .TP \f[CR]abstract\-title\f[R] -title of abstract, currently used only in HTML, EPUB, and docx. +title of abstract, currently used only in HTML, EPUB, docx, and Typst. This will be set automatically to a localized value, depending on \f[CR]lang\f[R], but can be manually overridden. .TP @@ -2711,7 +2756,6 @@ This affects most formats, and controls hyphenation in PDF output when using LaTeX (through \f[CR]babel\f[R] and \f[CR]polyglossia\f[R]) or ConTeXt. .RS -.PP Use native pandoc Divs and Spans with the \f[CR]lang\f[R] attribute to switch the language: .IP @@ -2734,7 +2778,6 @@ More text in English. [\(aqZitat auf Deutsch.\(aq]{lang=de} the base script direction, either \f[CR]rtl\f[R] (right\-to\-left) or \f[CR]ltr\f[R] (left\-to\-right). .RS -.PP For bidirectional documents, native pandoc \f[CR]span\f[R]s and \f[CR]div\f[R]s with the \f[CR]dir\f[R] attribute (value \f[CR]rtl\f[R] or \f[CR]ltr\f[R]) can be used to override the base direction in some @@ -2742,7 +2785,6 @@ output formats. This may not always be necessary if the final renderer (e.g.\ the browser, when generating HTML) supports the Unicode Bidirectional Algorithm. -.PP When using LaTeX for bidirectional documents, only the \f[CR]xelatex\f[R] engine is fully supported (use \f[CR]\-\-pdf\-engine=xelatex\f[R]). @@ -3103,7 +3145,6 @@ mainfontfallback: \- \(dqNotoColorEmoji:mode=harf\(dq \&... .EE -.PP Font fallbacks currently only work with \f[CR]lualatex\f[R]. .RE .TP @@ -3181,6 +3222,16 @@ bibliography to use for resolving references .TP \f[CR]natbiboptions\f[R] list of options for natbib +.SS Other +.TP +\f[CR]pdf\-trailer\-id\f[R] +the PDF trailer ID; must be two PDF byte strings if set, conventionally +with 16 bytes each. +E.g., +\f[CR]<00112233445566778899aabbccddeeff> <00112233445566778899aabbccddeeff>\f[R]. +.RS +See the section on reproducible builds. +.RE .SS Variables for ConTeXt Pandoc uses these variables when creating a PDF with ConTeXt. .TP @@ -3345,6 +3396,19 @@ or an empty string to omit page numbering. .TP \f[CR]columns\f[R] Number of columns for body text. +.TP +\f[CR]thanks\f[R] +contents of acknowledgments footnote after document title +.TP +\f[CR]mathfont\f[R], \f[CR]codefont\f[R] +Name of system font to use for math and code, respectively. +.TP +\f[CR]linestretch\f[R] +adjusts line spacing, e.g.\ \f[CR]1.25\f[R], \f[CR]1.5\f[R] +.TP +\f[CR]linkcolor\f[R], \f[CR]filecolor\f[R], \f[CR]citecolor\f[R] +color for external links, internal links, and citation links, +respectively: expects a hexadecimal color code .SS Variables for ms .TP \f[CR]fontfamily\f[R] @@ -3421,10 +3485,8 @@ $else$ (stdin) $endif$ .EE -.PP Similarly, \f[CR]outputfile\f[R] can be \f[CR]\-\f[R] if output goes to the terminal. -.PP If you need absolute paths, use e.g.\ \f[CR]$curdir$/$sourcefile$\f[R]. .RE .TP @@ -3485,7 +3547,7 @@ input formats .TP output formats \f[CR]markdown\f[R], \f[CR]latex\f[R], \f[CR]context\f[R], -\f[CR]rst\f[R] +\f[CR]org\f[R], \f[CR]rst\f[R] .TP enabled by default in \f[CR]markdown\f[R], \f[CR]latex\f[R], \f[CR]context\f[R] (both input @@ -3831,6 +3893,19 @@ In the \f[CR]context\f[R] output format this enables the use of Natural Tables (TABLE) instead of the default Extreme Tables (xtables). Natural tables allow more fine\-grained global customization but come at a performance penalty compared to extreme tables. +.SS Extension: \f[CR]smart_quotes\f[R] (org) +Interpret straight quotes as curly quotes during parsing. +When \f[I]writing\f[R] Org, then the \f[CR]smart_quotes\f[R] extension +has the reverse effect: what would have been curly quotes comes out +straight. +.PP +This extension is implied if \f[CR]smart\f[R] is enabled. +.SS Extension: \f[CR]special_strings\f[R] (org) +Interpret \f[CR]\-\-\-\f[R] as em\-dashes, \f[CR]\-\-\f[R] as +en\-dashes, \f[CR]\(rs\-\f[R] as shy hyphen, and \f[CR]...\f[R] as +ellipses. +.PP +This extension is implied if \f[CR]smart\f[R] is enabled. .SS Extension: \f[CR]tagging\f[R] Enabling this extension with \f[CR]context\f[R] output will produce markup suitable for the production of tagged PDFs. @@ -4227,8 +4302,10 @@ If the \f[CR]fenced_code_attributes\f[R] extension is disabled, but input contains class attribute(s) for the code block, the first class attribute will be printed after the opening fence as a bare word. .PP -To prevent all highlighting, use the \f[CR]\-\-no\-highlight\f[R] flag. -To set the highlighting style, use \f[CR]\-\-highlight\-style\f[R]. +To prevent all highlighting, use the +\f[CR]\-\-syntax\-highlighting=none\f[R] option. +To set the highlighting style or method, use +\f[CR]\-\-syntax\-highlighting\f[R]. For more information on highlighting, see Syntax highlighting, below. .SS Line blocks .SS Extension: \f[CR]line_blocks\f[R] @@ -4515,9 +4592,6 @@ Term 2 .EE .PP Note that space between items in a definition list is required. -(A variant that loosens this requirement, but disallows \(lqlazy\(rq -hard wrapping, can be activated with the -\f[CR]compact_definition_lists\f[R] extension.) .SS Numbered example lists .SS Extension: \f[CR]example_lists\f[R] The special list marker \f[CR]\(at\f[R] can be used for sequentially @@ -5748,6 +5822,12 @@ How this is rendered depends on the output format. Some output formats (e.g.\ RTF) do not yet support figures. In those formats, you\(cqll just get an image in a paragraph by itself, with no caption. +For LaTeX output, you can specify a figure\(cqs positioning by adding +the \f[CR]latex\-placement\f[R] attribute. +.IP +.EX +{latex\-placement=\(dqht\(dq} +.EE .PP If you just want a regular inline image, just make sure it is not the only thing in the paragraph. @@ -6255,20 +6335,6 @@ This is a reference ![image][ref] with MultiMarkdown attributes. Parses MultiMarkdown\-style heading identifiers (in square brackets, after the heading but before any trailing \f[CR]#\f[R]s in an ATX heading). -.SS Extension: \f[CR]compact_definition_lists\f[R] -Activates the definition list syntax of pandoc 1.12.x and earlier. -This syntax differs from the one described above under Definition lists -in several respects: -.IP \(bu 2 -No blank line is required between consecutive items of the definition -list. -.IP \(bu 2 -To get a \(lqtight\(rq or \(lqcompact\(rq list, omit space between -consecutive items; the space between a term and its definition does not -affect anything. -.IP \(bu 2 -Lazy wrapping of paragraphs is not allowed: the entire definition must -be indented four spaces. .SS Extension: \f[CR]gutenberg\f[R] Use Project Gutenberg conventions for \f[CR]plain\f[R] output: all\-caps for strong emphasis, surround by underscores for regular emphasis, add @@ -6706,7 +6772,6 @@ the way items are sorted. (For backwards compatibility, \f[CR]locale\f[R] may be used instead of \f[CR]lang\f[R], but this use is deprecated.) .RS -.PP A BCP 47 language tag is expected: for example, \f[CR]en\f[R], \f[CR]de\f[R], \f[CR]en\-US\f[R], \f[CR]fr\-CA\f[R], \f[CR]ug\-Cyrl\f[R]. @@ -7615,7 +7680,7 @@ To see a list of language names that pandoc will recognize, type \f[CR]pandoc \-\-list\-highlight\-languages\f[R]. .PP The color scheme can be selected using the -\f[CR]\-\-highlight\-style\f[R] option. +\f[CR]\-\-syntax\-highlighting\f[R] option. The default color scheme is \f[CR]pygments\f[R], which imitates the default color scheme used by the Python library pygments (though pygments is not actually used to do the highlighting). @@ -7625,7 +7690,7 @@ To see a list of highlight styles, type If you are not satisfied with the predefined styles, you can use \f[CR]\-\-print\-highlight\-style\f[R] to generate a JSON \f[CR].theme\f[R] file which can be modified and used as the argument to -\f[CR]\-\-highlight\-style\f[R]. +\f[CR]\-\-syntax\-highlighting\f[R]. To get a JSON version of the \f[CR]pygments\f[R] style, for example: .IP .EX @@ -7635,7 +7700,7 @@ pandoc \-o my.theme \-\-print\-highlight\-style pygments Then edit \f[CR]my.theme\f[R] and use it like this: .IP .EX -pandoc \-\-highlight\-style my.theme +pandoc \-\-syntax\-highlighting my.theme .EE .PP If you are not satisfied with the built\-in highlighting, or you want to @@ -7649,7 +7714,7 @@ If you receive an error that pandoc \(lqCould not read highlighting theme\(rq, check that the JSON file is encoded with UTF\-8 and has no Byte\-Order Mark (BOM). .PP -To disable highlighting, use the \f[CR]\-\-no\-highlight\f[R] option. +To disable highlighting, use \f[CR]\-\-syntax\-highlighting=none\f[R]. .SH CUSTOM STYLES Custom styles can be used in the docx, odt and ICML formats. .SS Output @@ -7810,6 +7875,11 @@ time. \f[CR]SOURCE_DATE_EPOCH\f[R] should contain an integer unix timestamp (specifying the number of seconds since midnight UTC January 1, 1970). .PP +For reproducible builds with LaTeX, you can either specify the +\f[CR]pdf\-trailer\-id\f[R] in the metadata or leave it undefined, in +which case pandoc will create a trailer\-id based on a hash of the +\f[CR]SOURCE_DATE_EPOCH\f[R] and the document\(cqs contents. +.PP Some document formats also include a unique identifier. For EPUB, this can be set explicitly by setting the \f[CR]identifier\f[R] metadata field (see EPUB Metadata, above). @@ -7865,7 +7935,7 @@ pandoc \-\-pdf\-engine=weasyprint \(rs The feature is experimental and standard compliance should not be assumed. .SS Prince XML -The non\-free HTML\-to\-PDf converter \f[CR]prince\f[R] has extensive +The non\-free HTML\-to\-PDF converter \f[CR]prince\f[R] has extensive support for various PDF standards as well as tagging. E.g.: .IP |