Update man pages.

2026-08-28 17:20:47 +08:00 · 2026-02-02 17:28:34 +01:00
parent 9a32653165
commit 350ca0b663
3 changed files with 140 additions and 35 deletions
@@ -1,6 +1,6 @@
-.\" Automatically generated by Pandoc 3.8.3
+.\" Automatically generated by Pandoc 3.9
 .\"
-.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.8.3" "Pandoc User\[cq]s Guide"
+.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.9" "Pandoc User\[cq]s Guide"
 .SH SYNOPSIS
 \f[CR]pandoc\-lua\f[R] [\f[I]options\f[R]] [\f[I]script\f[R]
 [\f[I]args\f[R]]]
@@ -1,6 +1,6 @@
-.\" Automatically generated by Pandoc 3.8.3
+.\" Automatically generated by Pandoc 3.9
 .\"
-.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.8.3" "Pandoc User\[cq]s Guide"
+.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.9" "Pandoc User\[cq]s Guide"
 .SH SYNOPSIS
 \f[CR]pandoc\-server\f[R] [\f[I]options\f[R]]
 .SH DESCRIPTION
@@ -1,6 +1,6 @@
-.\" Automatically generated by Pandoc 3.8.3
+.\" Automatically generated by Pandoc 3.9
 .\"
-.TH "pandoc" "1" "2025\-12\-01" "pandoc 3.8.3" "Pandoc User\[cq]s Guide"
+.TH "pandoc" "1" "2025\-02\-02" "pandoc 3.9" "Pandoc User\[cq]s Guide"
 .SH NAME
 pandoc - general markup converter
 .SH SYNOPSIS
@@ -337,7 +337,7 @@ Specify output format.
 .IP \(bu 2
 \f[CR]bbcode_phpbb\f[R] BBCode (phpBB)
 .IP \(bu 2
-\f[CR]bbcode_steam\f[R] BBCode (Hubzilla)
+\f[CR]bbcode_steam\f[R] BBCode (Steam)
 .IP \(bu 2
 \f[CR]bbcode_hubzilla\f[R] BBCode (Hubzilla)
 .IP \(bu 2
@@ -515,14 +515,15 @@ need to create it yourself if you want to make use of it.)
 .TP
 \f[CR]\-d\f[R] \f[I]FILE\f[R], \f[CR]\-\-defaults=\f[R]\f[I]FILE\f[R]
 Specify a set of default option settings.
-\f[I]FILE\f[R] is a YAML file whose fields correspond to command\-line
-option settings.
+\f[I]FILE\f[R] is a YAML or JSON file whose fields correspond to
+command\-line option settings.
 All options for document conversion, including input and output files,
 can be set using a defaults file.
 The file will be searched for first in the working directory, and then
 in the \f[CR]defaults\f[R] subdirectory of the user data directory (see
 \f[CR]\-\-data\-dir\f[R]).
-The \f[CR].yaml\f[R] extension may be omitted.
+The \f[CR].yaml\f[R] extension will be added if \f[I]FILE\f[R] lacs an
+extension.
 See the section Defaults files for more information on the file format.
 Settings from the defaults file may be overridden or extended by
 subsequent options on the command line.
@@ -761,7 +762,7 @@ produces a span with the class
 the affected paragraph break.
 This option only affects the docx reader.
 .TP
-\f[CR]\-\-extract\-media=\f[R]\f[I]DIR\f[R]
+\f[CR]\-\-extract\-media=\f[R]\f[I]DIR\f[R]|\f[I]FILE\f[R]\f[CR].zip\f[R]
 Extract images and other media contained in or linked from the source
 document to the path \f[I]DIR\f[R], creating it if necessary, and adjust
 the images references in the document so they point to the extracted
@@ -771,6 +772,11 @@ binary container (e.g.\ docx), as needed.
 The original file paths are used if they are relative paths not
 containing \f[CR]..\f[R].
 Otherwise filenames are constructed from the SHA1 hash of the contents.
+.RS
+.PP
+If the path given ends in \f[CR].zip\f[R], then instead of creating a
+directory, pandoc will create a zip archive containing the media files.
+.RE
 .TP
 \f[CR]\-\-abbreviations=\f[R]\f[I]FILE\f[R]
 Specifies a custom abbreviations file, with abbreviations one to a line.
@@ -969,28 +975,21 @@ 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]\-\-syntax\-highlighting=\(dqdefault\(dq|\(dqnone\(dq|\(dqidiomatic\(dq|\f[R]\f[I]STYLE\f[R]\f[CR]|\f[R]\f[I]FILE\f[R]
+\f[CR]\-\-syntax\-highlighting=default|none|idiomatic|\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.
+The \f[CR]idiomatic\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.
+The \f[CR]default\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.
+the internal highlighter with the default style; for Typst it is to use
+Typst\(cqs own syntax highlighting system.
 .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],
@@ -1515,7 +1514,7 @@ In the template, \f[CR]%n\f[R] will be replaced by the chunk number
 (padded with leading 0s to 3 digits), \f[CR]%s\f[R] with the section
 number of the chunk, \f[CR]%h\f[R] with the heading text (with
 formatting removed), \f[CR]%i\f[R] with the section identifier.
-For example, \f[CR]%section\-%s\-%i.html\f[R] might be resolved to
+For example, \f[CR]section\-%s\-%i.html\f[R] might be resolved to
 \f[CR]section\-1.1\-introduction.html\f[R].
 The characters \f[CR]/\f[R] and \f[CR]\(rs\f[R] are not allowed in chunk
 templates and will be ignored.
@@ -1867,7 +1866,9 @@ Nonzero exit codes have the following meanings:
 .RE
 .SH DEFAULTS FILES
 The \f[CR]\-\-defaults\f[R] option may be used to specify a package of
-options, in the form of a YAML file.
+options, in the form of a YAML or JSON file.
+Examples in this section will be given in YAML, but the equivalent forms
+in JSON will also work.
 .PP
 Fields that are omitted will just have their regular default values.
 So a defaults file can be as simple as one line:
@@ -1876,6 +1877,12 @@ So a defaults file can be as simple as one line:
 verbosity\f[B]:\f[R] INFO
 .EE
 .PP
+or in JSON:
+.IP
+.EX
+{ \(dqverbosity\(dq: \(dqINFO\(dq }
+.EE
+.PP
 In fields that expect a file path (or list of file paths), the following
 syntax may be used to interpolate environment variables:
 .IP
@@ -2058,7 +2065,7 @@ or \f[CR]{type: citeproc}\f[R].

 \-\-dpi 300                           dpi: 300                          

- \-\-wrap 60                           wrap: 60                          
+ \-\-wrap preserve                     wrap: \(dqpreserve\(dq                  

 \-\-columns 72                        columns: 72                       

@@ -2907,6 +2914,12 @@ base URL for Slideous documents (defaults to \f[CR]slideous\f[R])
 \f[CR]title\-slide\-attributes\f[R]
 additional attributes for the title slide of reveal.js slide shows.
 See background in reveal.js, beamer, and pptx for an example.
+.TP
+\f[CR]highlightjs\-theme\f[R]
+highlight.js theme for code highlighting when using
+\f[CR]\-\-syntax\-highlighting=idiomatic\f[R] with reveal.js (defaults
+to \f[CR]monokai\f[R]).
+See the highlight.js demo page for available themes.
 .PP
 All reveal.js configuration options are available as variables.
 To turn off boolean flags that default to true in reveal.js, use
@@ -3257,6 +3270,23 @@ E.g.,
 .RS
 See the section on reproducible builds.
 .RE
+.TP
+\f[CR]pdfstandard\f[R]
+PDF standard(s) for the document, e.g.\ \f[CR]ua\-2\f[R],
+\f[CR]a\-4f\f[R].
+Supports PDF/A, PDF/X, and PDF/UA variants.
+Requires LuaLaTeX and LaTeX 2023+.
+Repeat for multiple standards:
+.RS
+.IP
+.EX
+\-\-\-
+pdfstandard:
+\- ua\-2
+\- a\-4f
+\&...
+.EE
+.RE
 .SS Variables for ConTeXt
 Pandoc uses these variables when creating a PDF with ConTeXt.
 .TP
@@ -6174,6 +6204,20 @@ normal citations will be put in parentheses, while author\-in\-text
 citations will not.
 For this reason, it is sometimes preferable to use the author\-in\-text
 style inside notes when using a note style.
+.PP
+Many CSL styles will format citations differently when the same source
+has been cited earlier.
+In documents with chapters, it is usually desirable to reset this
+position information at the beginning of every chapter.
+To do this, add the class \f[CR]reset\-citation\-positions\f[R] to the
+heading for each chapter:
+.IP
+.EX
+# The Beginning {.reset\-citation\-positions}
+.EE
+.PP
+Note that this class only has an effect when placed on top\-level
+headings; it is ignored in nested blocks.
 .SS Non\-default extensions
 The following Markdown syntax extensions are not enabled by default in
 pandoc, but may be enabled by adding \f[CR]+EXTENSION\f[R] to the format
@@ -6355,9 +6399,6 @@ Supports GitHub\-style Markdown alerts, like
 > [!TIP]
 > Helpful advice for doing things better or more easily.
 .EE
-.PP
-Note: This extension currently only works with commonmark:
-\f[CR]commonmark\f[R], \f[CR]gfm\f[R], \f[CR]commonmark_x\f[R].
 .SS Extension: \f[CR]autolink_bare_uris\f[R]
 Makes all absolute URIs into links, even when not surrounded by pointy
 braces \f[CR]<...>\f[R].
@@ -7150,6 +7191,25 @@ presenter view.
 .PP
 Notes are not yet supported for other slide formats, but the notes will
 not appear on the slides themselves.
+.SS Speaker notes on the title slide (PowerPoint)
+For PowerPoint output, the title slide is generated from the
+document\(cqs YAML metadata block.
+To add speaker notes to this slide, use a \f[CR]notes\f[R] field in the
+metadata:
+.IP
+.EX
+\-\-\-
+title: My Presentation
+author: Jane Doe
+notes: |
+  Welcome everyone to this presentation.
+
+  Remember to introduce yourself and mention the key topics.
+\-\-\-
+.EE
+.PP
+The \f[CR]notes\f[R] field can contain multiple paragraphs and Markdown
+formatting.
 .SS Columns
 To put material in side by side columns, you can use a native div
 container with class \f[CR]columns\f[R], containing two or more div
@@ -7858,6 +7918,29 @@ theme\(rq, check that the JSON file is encoded with UTF\-8 and has no
 Byte\-Order Mark (BOM).
 .PP
 To disable highlighting, use \f[CR]\-\-syntax\-highlighting=none\f[R].
+.PP
+To use a format\(cqs idiomatic syntax highlighting instead of
+pandoc\(cqs built\-in highlighting, use
+\f[CR]\-\-syntax\-highlighting=idiomatic\f[R].
+Currently, \f[CR]idiomatic\f[R] only affects the following formats:
+.IP \(bu 2
+In reveal.js, it causes reveal.js\(cqs highlighting plugin to be used
+for source code highlighting.
+The style may be customized by setting the \f[CR]highlightjs\-theme\f[R]
+variable.
+.IP \(bu 2
+In Typst, it causes Typst\(cqs built\-in highlighting to be used.
+(This is also the default for Typst.)
+.IP \(bu 2
+In LaTeX, it causes the \f[CR]listings\f[R] package to be used.
+Note that \f[CR]listings\f[R] 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.
+.IP \(bu 2
+In other formats, \f[CR]idiomatic\f[R] will have the same result as
+\f[CR]default\f[R].
 .SH CUSTOM STYLES
 Custom styles can be used in the docx, odt and ICML formats.
 .SS Output
@@ -8036,10 +8119,10 @@ However, it is possible to generate accessible PDFs, which use tagging
 to add semantic information to the document.
 .PP
 Pandoc defaults to LaTeX to generate PDF.
-Tagging support in LaTeX is in development and not readily available, so
-PDFs generated in this way will always be untagged and not accessible.
-This means that alternative engines must be used to generate accessible
-PDFs.
+LaTeX\(cqs \f[CR]\(rsDocumentMetadata\f[R] interface supports PDF
+standards and tagging when using LuaLaTeX; set the
+\f[CR]pdfstandard\f[R] variable to enable this (see below).
+For older LaTeX installations, alternative engines must be used.
 .PP
 The PDF standards PDF/A and PDF/UA define further restrictions intended
 to optimize PDFs for archiving and accessibility.
@@ -8050,6 +8133,28 @@ Note, however, that standard compliance depends on many things,
 including the colorspace of embedded images.
 Pandoc cannot check this, and external programs must be used to ensure
 that generated PDFs are in compliance.
+.SS LaTeX
+Set the \f[CR]pdfstandard\f[R] variable to produce tagged PDFs
+conforming to PDF/A, PDF/X, or PDF/UA standards.
+For example:
+.IP
+.EX
+pandoc \-V pdfstandard=ua\-2 \-\-pdf\-engine=lualatex doc.md \-o doc.pdf
+.EE
+.PP
+Multiple standards can be combined:
+.IP
+.EX
+\-\-\-
+pdfstandard:
+  \- ua\-2
+  \- a\-4f
+\-\-\-
+.EE
+.PP
+The required PDF version is inferred automatically.
+This feature requires LuaLaTeX in TeX Live 2025 with LaTeX kernel
+2025\-06\-01 or newer.
 .SS ConTeXt
 ConTeXt always produces tagged PDFs, but the quality depends on the
 input.