Script 'mail_helper' called by obssrc Hello community, here is the log from the commit of package pandoc-cli for openSUSE:Factory checked in at 2026-11-06 19:50:58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Comparing /work/SRC/openSUSE:Factory/pandoc-cli (Old) and /work/SRC/openSUSE:Factory/.pandoc-cli.new.3759290 (New) ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Package is "pandoc-cli" Fri Nov 6 19:50:58 2026 rev:26 rq:1395590 version:3.13 Changes: -------- --- /work/SRC/openSUSE:Factory/pandoc-cli/pandoc-cli.changes 2026-06-10 16:16:17.538251272 +0200 +++ /work/SRC/openSUSE:Factory/.pandoc-cli.new.3759290/pandoc-cli.changes 2026-11-06 19:58:11.971741056 +0100 @@ -1,0 +2,30 @@ +Mon Oct 26 20:46:24 UTC 2026 - Peter Simons <[email protected]> + +- Update pandoc-cli to version 3.13. + Upstream does not provide a change log file. + +------------------------------------------------------------------- +Thu Oct 8 01:41:13 UTC 2026 - Peter Simons <[email protected]> + +- Update pandoc-cli to version 3.12.1. + Upstream does not provide a change log file. + +------------------------------------------------------------------- +Sat Aug 29 00:44:05 UTC 2026 - Peter Simons <[email protected]> + +- Update pandoc-cli to version 3.11. + Upstream does not provide a change log file. + +------------------------------------------------------------------- +Wed Aug 12 18:57:18 UTC 2026 - Peter Simons <[email protected]> + +- Update pandoc-cli to version 3.10.2. + Upstream does not provide a change log file. + +------------------------------------------------------------------- +Wed Jul 22 17:02:12 UTC 2026 - Peter Simons <[email protected]> + +- Update pandoc-cli to version 3.10.1. + Upstream does not provide a change log file. + +------------------------------------------------------------------- Old: ---- pandoc-cli-3.10.tar.gz New: ---- pandoc-cli-3.13.tar.gz ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Other differences: ------------------ ++++++ pandoc-cli.spec ++++++ --- /var/tmp/diff_new_pack.uTQisT/_old 2026-11-06 19:58:13.254794766 +0100 +++ /var/tmp/diff_new_pack.uTQisT/_new 2026-11-06 19:58:13.259794975 +0100 @@ -17,7 +17,7 @@ Name: pandoc-cli -Version: 3.10 +Version: 3.13 Release: 0 Summary: Conversion between documentation formats License: GPL-2.0-or-later ++++++ pandoc-cli-3.10.tar.gz -> pandoc-cli-3.13.tar.gz ++++++ diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/pandoc-cli-3.10/COPYING.md new/pandoc-cli-3.13/COPYING.md --- old/pandoc-cli-3.10/COPYING.md 2001-09-09 03:46:40.000000000 +0200 +++ new/pandoc-cli-3.13/COPYING.md 2001-09-09 03:46:40.000000000 +0200 @@ -2,9 +2,9 @@ Version 2, June 1991 - Copyright (C) 1989, 1991 Free Software Foundation, Inc. + Copyright (C) 1989, 1991 Free Software Foundation, Inc. <https://fsf.org/> - + Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @@ -96,17 +96,17 @@ distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: - + **a)** You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. - + **b)** You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. - + **c)** If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement @@ -143,12 +143,12 @@ under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: - + **a)** Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, - + **b)** Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable @@ -156,7 +156,7 @@ terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, - + **c)** Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the @@ -317,7 +317,7 @@ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. - + You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>. @@ -330,7 +330,7 @@ Gnomovision version 69, Copyright (C) year name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome - to redistribute it under certain conditions; type `show c' + to redistribute it under certain conditions; type `show c' for details. The hypothetical commands \`show w' and \`show c' should show the @@ -345,7 +345,7 @@ Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' - (which makes passes at compilers) written + (which makes passes at compilers) written by James Hacker. signature of Ty Coon, 1 April 1989 diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/pandoc-cli-3.10/man/pandoc-lua.1 new/pandoc-cli-3.13/man/pandoc-lua.1 --- old/pandoc-cli-3.10/man/pandoc-lua.1 2001-09-09 03:46:40.000000000 +0200 +++ new/pandoc-cli-3.13/man/pandoc-lua.1 2001-09-09 03:46:40.000000000 +0200 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.10 +.\" Automatically generated by Pandoc 3.13 .\" -.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.10" "Pandoc User\[cq]s Guide" +.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.13" "Pandoc User\[cq]s Guide" .SH NAME pandoc\-lua \- Lua interface to pandoc API .SH SYNOPSIS diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/pandoc-cli-3.10/man/pandoc-server.1 new/pandoc-cli-3.13/man/pandoc-server.1 --- old/pandoc-cli-3.10/man/pandoc-server.1 2001-09-09 03:46:40.000000000 +0200 +++ new/pandoc-cli-3.13/man/pandoc-server.1 2001-09-09 03:46:40.000000000 +0200 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.10 +.\" Automatically generated by Pandoc 3.13 .\" -.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.10" "Pandoc User\[cq]s Guide" +.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.13" "Pandoc User\[cq]s Guide" .SH NAME pandoc\-server \- web server exposing pandoc API .SH SYNOPSIS @@ -250,7 +250,7 @@ cause the first section to be numbered \(lq1\(rq and the first subsection \(lq1.2.\(rq .TP -\f[CR]html\-math\-method\f[R] (\f[CR]\(dqplain\(dq|\(dqwebtex\(dq|\(dqgladtex\(dq|\(dqmathml\(dq|\(dqmathjax\(dq|\(dqkatex\(dq\f[R]) +\f[CR]math\-method\f[R] (\f[CR]\(dqplain\(dq|\(dqwebtex\(dq|\(dqgladtex\(dq|\(dqmathml\(dq|\(dqmathjax\(dq|\(dqkatex\(dq\f[R]) Determines how math is represented in HTML. .TP \f[CR]listings\f[R] (boolean, default false) diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/pandoc-cli-3.10/man/pandoc.1 new/pandoc-cli-3.13/man/pandoc.1 --- old/pandoc-cli-3.10/man/pandoc.1 2001-09-09 03:46:40.000000000 +0200 +++ new/pandoc-cli-3.13/man/pandoc.1 2001-09-09 03:46:40.000000000 +0200 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.10 +.\" Automatically generated by Pandoc 3.13 .\" -.TH "pandoc" "1" "2026\-06\-03" "pandoc 3.10" "Pandoc User\[cq]s Guide" +.TH "pandoc" "1" "2026\-10\-25" "pandoc 3.13" "Pandoc User\[cq]s Guide" .SH NAME pandoc - general markup converter .SH SYNOPSIS @@ -152,17 +152,18 @@ \f[CR]amsmath\f[R], \f[CR]lm\f[R], \f[CR]unicode\-math\f[R], \f[CR]iftex\f[R], \f[CR]listings\f[R] (if the \f[CR]\-\-listings\f[R] option is used), \f[CR]fancyvrb\f[R], \f[CR]longtable\f[R], -\f[CR]booktabs\f[R], \f[CR]multirow\f[R] (if the document contains a -table with cells that cross multiple rows), \f[CR]graphicx\f[R] (if the -document contains images), \f[CR]bookmark\f[R], \f[CR]xcolor\f[R], -\f[CR]soul\f[R], \f[CR]geometry\f[R] (with the \f[CR]geometry\f[R] -variable set), \f[CR]setspace\f[R] (with \f[CR]linestretch\f[R]), and -\f[CR]babel\f[R] (with \f[CR]lang\f[R]). +\f[CR]caption\f[R], \f[CR]booktabs\f[R], \f[CR]multirow\f[R] (if the +document contains a table with cells that cross multiple rows), +\f[CR]graphicx\f[R] (if the document contains images), +\f[CR]bookmark\f[R], \f[CR]xcolor\f[R], \f[CR]soul\f[R], +\f[CR]geometry\f[R] (with the \f[CR]geometry\f[R] variable set), +\f[CR]setspace\f[R] (with \f[CR]linestretch\f[R]), and \f[CR]babel\f[R] +(with \f[CR]lang\f[R]). If \f[CR]CJKmainfont\f[R] is set, \f[CR]xeCJK\f[R] is needed if \f[CR]xelatex\f[R] is used, else \f[CR]luatexja\f[R] is needed if \f[CR]lualatex\f[R] is used. \f[CR]framed\f[R] is required if code is highlighted in a scheme that -use a colored background. +uses a colored background. The use of \f[CR]xelatex\f[R] or \f[CR]lualatex\f[R] as the PDF engine requires \f[CR]fontspec\f[R]. \f[CR]lualatex\f[R] uses \f[CR]selnolig\f[R] and \f[CR]lua\-ul\f[R]. @@ -240,6 +241,8 @@ .IP \(bu 2 \f[CR]fb2\f[R] (FictionBook2 e\-book) .IP \(bu 2 +\f[CR]fodt\f[R] (flat OpenDocument text document) +.IP \(bu 2 \f[CR]gfm\f[R] (GitHub\-Flavored Markdown), or the deprecated and less accurate \f[CR]markdown_github\f[R]; use \f[CR]markdown_github\f[R] only if you need extensions not supported in \f[CR]gfm\f[R]. @@ -324,7 +327,7 @@ .IP \(bu 2 \f[CR]ansi\f[R] (text with ANSI escape codes, for terminal viewing) .IP \(bu 2 -\f[CR]asciidoc\f[R] (modern AsciiDoc as interpreted by AsciiDoctor) +\f[CR]asciidoc\f[R] (modern AsciiDoc as interpreted by Asciidoctor) .IP \(bu 2 \f[CR]asciidoc_legacy\f[R] (AsciiDoc as interpreted by \f[CR]asciidoc\-py\f[R]). @@ -375,6 +378,8 @@ .IP \(bu 2 \f[CR]fb2\f[R] (FictionBook2 e\-book) .IP \(bu 2 +\f[CR]fodt\f[R] (flat OpenDocument text document) +.IP \(bu 2 \f[CR]gfm\f[R] (GitHub\-Flavored Markdown), or the deprecated and less accurate \f[CR]markdown_github\f[R]; use \f[CR]markdown_github\f[R] only if you need extensions not supported in \f[CR]gfm\f[R]. @@ -446,6 +451,8 @@ .IP \(bu 2 \f[CR]textile\f[R] (Textile) .IP \(bu 2 +\f[CR]t2t\f[R] (txt2tags) +.IP \(bu 2 \f[CR]slideous\f[R] (Slideous HTML and JavaScript slide show) .IP \(bu 2 \f[CR]slidy\f[R] (Slidy HTML and JavaScript slide show) @@ -522,23 +529,45 @@ 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 will be added if \f[I]FILE\f[R] lacs an -extension. +If \f[I]FILE\f[R] lacks an extension, pandoc will also try adding the +\f[CR].yaml\f[R] extension if \f[I]FILE\f[R] is not found. 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. .TP -\f[CR]\-\-bash\-completion\f[R] -Generate a bash completion script. -To enable bash completion with pandoc, add this to your -\f[CR].bashrc\f[R]: +\f[CR]\-\-completion=\f[R]\f[I]SHELL\f[R] +Generate a shell completion script for the given shell, one of +\f[CR]bash\f[R], \f[CR]zsh\f[R], or \f[CR]fish\f[R]. +To enable completion with pandoc, evaluate the output of this command in +your shell\(cqs startup file. +For example, for bash, add this to your \f[CR].bashrc\f[R]: .RS .IP .EX -eval \(dq$(pandoc \-\-bash\-completion)\(dq +eval \(dq$(pandoc \-\-completion=bash)\(dq +.EE +.PP +For zsh, you will need to create a directory to store zsh completions +(e.g., \f[CR]\(ti/.local/share/zsh/site\-functions\f[R]) or use one of +the existing directories listed by \f[CR]zsh \-\-pathdirs\f[R]. +Create the pandoc completion script in that directory: +.IP +.EX +pandoc \-\-completion=zsh > \(ti/.local/share/zsh/site\-functions/_pandoc +.EE +.PP +Then add these lines to your \f[CR].zshrc\f[R]: +.IP +.EX +fpath=(\(ti/.local/share/zsh $fpath) +autoload \-Uz compinit && compinit .EE .RE .TP +\f[CR]\-\-bash\-completion\f[R] +\f[I]Deprecated. +Use \f[CI]\-\-completion=bash\f[I] instead.\f[R] +.TP \f[CR]\-\-sandbox[=true|false]\f[R] Run pandoc in a sandbox, limiting IO operations in readers and writers to reading the files specified on the command line. @@ -773,7 +802,7 @@ in spans with \f[CR]insertion\f[R], \f[CR]deletion\f[R], \f[CR]comment\-start\f[R], and \f[CR]comment\-end\f[R] classes, respectively. -The author and time of change is included. +The author and time of change are included. \f[CR]all\f[R] is useful for scripting: only accepting changes from a certain reviewer, say, or before a certain date. If a paragraph is inserted or deleted, \f[CR]track\-changes=all\f[R] @@ -785,7 +814,7 @@ \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 +the image references in the document so they point to the extracted files. Media are downloaded, read from the file system, or extracted from a binary container (e.g.\ docx), as needed. @@ -952,6 +981,11 @@ contents will appear at the end of the document. If you would prefer it to be at the beginning of the document, before the title, you can use \f[CR]\-\-pdf\-engine=pdfroff\f[R]. +.PP +Because the entries in a table of contents need heading identifiers to +link to, this option forces the \f[CR]auto_identifiers\f[R] extension on +for the input format, even when it is off by default (as it is for +\f[CR]typst\f[R]). .RE .TP \f[CR]\-\-toc\-depth=\f[R]\f[I]NUMBER\f[R] @@ -1138,9 +1172,9 @@ document. Limitation: resources that are loaded dynamically through JavaScript cannot be incorporated; as a result, fonts may be missing when -\f[CR]\-\-mathjax\f[R] is used, and some advanced features (e.g.\ zoom -or speaker notes) may not work in an offline \(lqself\-contained\(rq -\f[CR]reveal.js\f[R] slide show. +\f[CR]\-\-math\-method=mathjax\f[R] is used, and some advanced features +(e.g.\ zoom or speaker notes) may not work in an offline +\(lqself\-contained\(rq \f[CR]reveal.js\f[R] slide show. .RS .PP For SVG images, \f[CR]img\f[R] tags with \f[CR]data:\f[R] URIs are used, @@ -1153,7 +1187,11 @@ .TP \f[CR]\-\-link\-images[=true|false]\f[R] Include links to images instead of embedding the images in ODT. -(This option currently only affects ODT output.) +(This option currently only affects \f[CR]odt\f[R] and \f[CR]fodt\f[R] +output.) +This is worth considering for \f[CR]fodt\f[R], where images have to be +base64\-encoded and so take about a third more space than in the +compressed \f[CR]odt\f[R] package. .TP \f[CR]\-\-html\-q\-tags[=true|false]\f[R] Use \f[CR]<q>\f[R] tags for quotes in HTML. @@ -1255,8 +1293,8 @@ 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. +\f[I]Deprecated, use \f[CI]\-\-syntax\-highlighting=idiomatic\f[I] or +\f[CI]\-\-syntax\-highlighting=default\f[I] instead.\f[R] .RS .PP Use the \f[CR]listings\f[R] package for LaTeX code blocks. @@ -1457,6 +1495,12 @@ \f[CR]pandoc \-o custom\-reference.odt \-\-print\-default\-data\-file reference.odt\f[R]. Then open \f[CR]custom\-reference.odt\f[R] in LibreOffice, modify the styles as you wish, and save the file. +.PP +\f[CR]fodt\f[R] output uses the same reference documents as +\f[CR]odt\f[R]; the reference is still a zipped \f[CR].odt\f[R], which +is flattened along with the generated content. +Note that an automatic style of the reference document is dropped, with +a warning, if the generated content defines a style of the same name. .RE .TP PowerPoint @@ -1555,8 +1599,8 @@ \f[CR]<dc:title>\f[R] (from the document title), \f[CR]<dc:creator>\f[R] (from the document authors), \f[CR]<dc:date>\f[R] (from the document date, which should be in ISO 8601 format), \f[CR]<dc:language>\f[R] -(from the \f[CR]lang\f[R] variable, or, if is not set, the locale), and -\f[CR]<dc:identifier id=\(dqBookId\(dq>\f[R] (a randomly generated +(from the \f[CR]lang\f[R] variable, or, if it is not set, the locale), +and \f[CR]<dc:identifier id=\(dqBookId\(dq>\f[R] (a randomly generated UUID). Any of these may be overridden by elements in the metadata file. .PP @@ -1697,7 +1741,7 @@ Set the \f[CR]bibliography\f[R] field in the document\(cqs metadata to \f[I]FILE\f[R], overriding any value set in the metadata. If you supply this argument multiple times, each \f[I]FILE\f[R] will be -added to bibliography. +added to the bibliography. 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[CR]\-\-resource\-path\f[R]). @@ -1736,18 +1780,21 @@ with PDF output. It is intended for use in producing a LaTeX file that can be processed with \f[CR]bibtex\f[R] or \f[CR]biber\f[R]. -.SS Math rendering in HTML -The default is to render TeX math as far as possible using Unicode -characters. -Formulas are put inside a \f[CR]span\f[R] with -\f[CR]class=\(dqmath\(dq\f[R], so that they may be styled differently -from the surrounding text if needed. -However, this gives acceptable results only for basic math, usually you -will want to use \f[CR]\-\-mathjax\f[R] or another of the following -options. +.SS Math rendering .TP -\f[CR]\-\-mathjax\f[R][\f[CR]=\f[R]\f[I]URL\f[R]] -Use MathJax to display embedded TeX math in HTML output. +\f[CR]\-\-math\-method\f[R]=\f[I]METHOD\f[R][\f[CR]:\f[R]\f[I]URL\f[R]] +Specify the method used to display TeX math. +The following methods are possible (some take an optional URL, separated +from the method name by a colon). +The default value is \f[CR]mathml\f[R]. +.RS +.TP +\f[CR]plain\f[R] +Render math using Unicode characters, to the extent possible. +When this is not possible, fall back to plain TeX. +.TP +\f[CR]mathjax\f[R][\f[CR]:\f[R]\f[I]URL\f[R]] +Render math using MathJax. TeX math will be put between \f[CR]\(rs(...\(rs)\f[R] (for inline math) or \f[CR]\(rs[...\(rs]\f[R] (for display math) and wrapped in \f[CR]<span>\f[R] tags with class \f[CR]math\f[R]. @@ -1755,36 +1802,36 @@ The \f[I]URL\f[R] should point to the \f[CR]MathJax.js\f[R] load script. If a \f[I]URL\f[R] is not provided, a link to the Cloudflare CDN will be inserted. +This method works in HTML and HTML\-derived formats. .TP -\f[CR]\-\-mathml\f[R] -Convert TeX math to MathML (in \f[CR]epub3\f[R], \f[CR]docbook4\f[R], -\f[CR]docbook5\f[R], \f[CR]jats\f[R], \f[CR]html4\f[R] and -\f[CR]html5\f[R]). -This is the default in \f[CR]odt\f[R] output. -MathML is supported natively by the main web browsers and select e\-book +\f[CR]mathml\f[R] +Convert TeX math to MathML. +MathML is supported natively by the main web browsers and most e\-book readers. +This option works in HTML and XML formats. .TP -\f[CR]\-\-webtex\f[R][\f[CR]=\f[R]\f[I]URL\f[R]] +\f[CR]webtex\f[R][\f[CR]:\f[R]\f[I]URL\f[R]] Convert TeX formulas to \f[CR]<img>\f[R] tags that link to an external script that converts formulas to images. The formula will be URL\-encoded and concatenated with the URL provided. For SVG images you can for example use -\f[CR]\-\-webtex https://latex.codecogs.com/svg.latex?\f[R]. +\f[CR]\-\-math\-method=webtex:https://latex.codecogs.com/svg.latex?\f[R]. If no URL is specified, the CodeCogs URL generating PNGs will be used (\f[CR]https://latex.codecogs.com/png.latex?\f[R]). -Note: the \f[CR]\-\-webtex\f[R] option will affect Markdown output as -well as HTML, which is useful if you\(cqre targeting a version of -Markdown without native math support. +Note: this method works not just in HTML but in Markdown, which is +useful if you\(cqre targeting a version of Markdown without native math +support. .TP -\f[CR]\-\-katex\f[R][\f[CR]=\f[R]\f[I]URL\f[R]] +\f[CR]katex\f[R][\f[CR]:\f[R]\f[I]URL\f[R]] Use KaTeX to display embedded TeX math in HTML output. The \f[I]URL\f[R] is the base URL for the KaTeX library. That directory should contain a \f[CR]katex.min.js\f[R] and a \f[CR]katex.min.css\f[R] file. If a \f[I]URL\f[R] is not provided, a link to the KaTeX CDN will be inserted. +This method works in HTML and HTML\-derived formats. .TP -\f[CR]\-\-gladtex\f[R] +\f[CR]gladtex\f[R] Enclose TeX math in \f[CR]<eq>\f[R] tags in HTML output. The resulting HTML can then be processed by GladTeX to produce SVG images of the typeset formulas and an HTML file with these images @@ -1792,11 +1839,35 @@ .RS .IP .EX -pandoc \-s \-\-gladtex input.md \-o myfile.htex +pandoc \-s \-\-math\-method=gladtex input.md \-o myfile.htex gladtex \-d image_dir myfile.htex # produces myfile.html and images in image_dir .EE .RE +.RE +.TP +\f[CR]\-\-mathjax\f[R][\f[CR]=\f[R]\f[I]URL\f[R]] +\f[I]Deprecated. +Use \f[CI]\-\-math\-method=mathjax\f[I][\f[CI]:\f[I]\f[R]URL\f[I]] +instead.\f[R] +.TP +\f[CR]\-\-mathml\f[R] +\f[I]Deprecated. +Use \f[CI]\-\-math\-method=mathml\f[I] instead.\f[R] +.TP +\f[CR]\-\-webtex\f[R][\f[CR]=\f[R]\f[I]URL\f[R]] +\f[I]Deprecated. +Use \f[CI]\-\-math\-method=webtex\f[I][\f[CI]:\f[I]\f[R]URL\f[I]] +instead.\f[R] +.TP +\f[CR]\-\-katex\f[R][\f[CR]=\f[R]\f[I]URL\f[R]] +\f[I]Deprecated. +Use \f[CI]\-\-math\-method=katex\f[I][\f[CI]:\f[I]\f[R]URL\f[I]] +instead.\f[R] +.TP +\f[CR]\-\-gladtex\f[R] +\f[I]Deprecated. +Use \f[CI]\-\-math\-method=gladtex\f[I] instead.\f[R] .SS Options for wrapper scripts .TP \f[CR]\-\-dump\-args[=true|false]\f[R] @@ -1908,9 +1979,9 @@ epub\-cover\-image\f[B]:\f[R] ${.}/cover.jpg epub\-metadata\f[B]:\f[R] ${.}/meta.xml resource\-path\f[B]:\f[R] -\f[B]\-\f[R] .\f[I] # the working directory from which pandoc is run\f[R] -\f[B]\-\f[R] ${.}/images\f[I] # the images subdirectory of the directory\f[R] -\f[I] # containing this defaults file\f[R] +\f[B]\- \f[R]. # the working directory from which pandoc is run +\f[B]\- \f[R]${.}/images # the images subdirectory of the directory + \f[I]# containing this defaults file\f[R] .EE .PP This environment variable interpolation syntax \f[I]only\f[R] works in @@ -2238,29 +2309,21 @@ command line defaults file \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- - \-\-mathjax html\-math\-method: + \-\-math\-method=mathjax math\-method : method: mathjax - \-\-mathml html\-math\-method: - method: mathml - - \-\-webtex html\-math\-method: + \-\-math\-method=webtex:URL math\-method: method: webtex + url: mathjax - \-\-katex html\-math\-method: - method: katex - - \-\-gladtex html\-math\-method: - method: gladtex + \-\-math\-method=mathml math\-method: + method: mathml .EE .RE .PP -In addition to the values listed above, \f[CR]method\f[R] can have the -value \f[CR]plain\f[R]. -.PP -If the command line option accepts a URL argument, an \f[CR]url:\f[R] -field can be added to \f[CR]html\-math\-method:\f[R]. +If the command line option accepts a URL argument, a \f[CR]url:\f[R] +field can be added to \f[CR]math\-method:\f[R]. .SS Options for wrapper scripts .RS -14n .IP @@ -2684,7 +2747,7 @@ .IP \(bu 2 \f[CR]roman\f[R]: Converts textual values that can be read as an integer into lowercase roman numerals. -This can be used to get lettered enumeration from array indices. +This can be used to get roman\-numeral enumeration from array indices. To get uppercase roman, chain with \f[CR]uppercase\f[R]. .IP \(bu 2 \f[CR]left n \(dqleftborder\(dq \(dqrightborder\(dq\f[R]: Renders a @@ -2843,19 +2906,27 @@ e.g.\ \f[CR]20px\f[R], but it also accepts \f[CR]pt\f[R] (12pt = 16px in most browsers). .TP -\f[CR]fontcolor\f[R] +\f[CR]fontcolor\f[R], \f[CR]fontcolordark\f[R] sets the CSS \f[CR]color\f[R] property on the \f[CR]html\f[R] element. .TP -\f[CR]linkcolor\f[R] +\f[CR]linkcolor\f[R], \f[CR]linkcolordark\f[R] sets the CSS \f[CR]color\f[R] property on all links. .TP -\f[CR]monofont\f[R] -sets the CSS \f[CR]font\-family\f[R] property on \f[CR]code\f[R] +\f[CR]quotebordercolor\f[R], \f[CR]quotebordercolordark\f[R] +sets the CSS \f[CR]border\-color\f[R] property for the left\-border of +\f[CR]blockquote\f[R] elements. +.TP +\f[CR]quotecolor\f[R], \f[CR]quotecolordark\f[R] +sets the CSS \f[CR]color\f[R] property for \f[CR]blockquote\f[R] elements. .TP -\f[CR]monobackgroundcolor\f[R] +\f[CR]monofont\f[R] +sets the CSS \f[CR]font\-family\f[R] property on \f[CR]code\f[R] and +\f[CR]pre\f[R] elements. +.TP +\f[CR]monobackgroundcolor\f[R], \f[CR]monobackgroundcolordark\f[R] sets the CSS \f[CR]background\-color\f[R] property on \f[CR]code\f[R] -elements and adds extra padding. +and \f[CR]pre\f[R] elements and adds extra padding. .TP \f[CR]linestretch\f[R] sets the CSS \f[CR]line\-height\f[R] property on the \f[CR]html\f[R] @@ -2864,7 +2935,7 @@ \f[CR]maxwidth\f[R] sets the CSS \f[CR]max\-width\f[R] property (default is 36em). .TP -\f[CR]backgroundcolor\f[R] +\f[CR]backgroundcolor\f[R], \f[CR]backgroundcolordark\f[R] sets the CSS \f[CR]background\-color\f[R] property on the \f[CR]html\f[R] element. .TP @@ -2894,11 +2965,54 @@ </style> \-\-\- .EE +.SS Note on \f[CR]color\-scheme\f[R] +By default, the browser\(cqs chosen \f[CR]color\-scheme\f[R] (either +\f[CR]light\f[R] or \f[CR]dark\f[R]) will affect the color of various +unstyled elements like input fields, which are generally only applicable +if your document is specifically targeting HTML. +.PP +By default, Pandoc emits \f[CR]color\-scheme: light dark\f[R] to allow +the system to choose between a default light\-mode or dark\-mode scheme, +but it alters this if variables specifically override colors, under the +assumption that the user wishes for that scheme to always be used. +.PP +Currently, this is only per a basic heuristic that checks whether the +following variables are provided: +.IP \(bu 2 +\f[CR]fontcolor\f[R] +.IP \(bu 2 +\f[CR]fontcolordark\f[R] +.IP \(bu 2 +\f[CR]backgroundcolor\f[R] +.IP \(bu 2 +\f[CR]backgroundcolordark\f[R] +.PP +And if only one \(lqmode\(rq is provided (light or dark), +\f[CR]color\-scheme\f[R] is set so that this chosen mode is used always, +regardless of the system\(cqs preference for light or dark mode. +.PP +Note that there are a few caveats to this, namely that: +.IP \(bu 2 +If the browser does not support \f[CR]light\-dark\f[R] (older than +\(ti2024), then it will always choose light mode, regardless of this +override. +.IP \(bu 2 +When printing, light mode is always chosen, and color variables are +ignored. +.IP \(bu 2 +Syntax highlighting is currently unaffected by color scheme. +.PP +In general, if you wish to override the theming for a single scheme, you +should choose to override either the normal \f[CR]*color\f[R] variables +(light mode) or the \f[CR]*colordark\f[R] variables (dark mode) to +ensure that the styles do not conflict with other styles added by new +versions of Pandoc or the browser itself. .SS Variables for HTML math .TP \f[CR]classoption\f[R] -when using \f[CR]\-\-katex\f[R], you can render display math equations -flush left using YAML metadata or with \f[CR]\-M classoption=fleqn\f[R]. +when using \f[CR]\-\-math\-method=katex\f[R], you can render display +math equations flush left using YAML metadata or with +\f[CR]\-M classoption=fleqn\f[R]. .SS Variables for HTML slides These affect HTML output when producing slide shows with pandoc. .TP @@ -3382,8 +3496,8 @@ \f[CR]pdfaintent\f[R] when used in conjunction with \f[CR]pdfa\f[R], specifies the output intent for the colors, -e.g.\ \f[CR]ISO coated v2 300\(rsletterpercent\(rsspace (ECI)\f[R] If -left unspecified, \f[CR]sRGB IEC61966\-2.1\f[R] is used as default. +e.g.\ \f[CR]ISO coated v2 300\(rsletterpercent\(rsspace (ECI)\f[R]. +If left unspecified, \f[CR]sRGB IEC61966\-2.1\f[R] is used as default. .TP \f[CR]toc\f[R] include table of contents (can also be set using @@ -3465,7 +3579,9 @@ Number of columns for body text. .TP \f[CR]thanks\f[R] -contents of acknowledgments footnote after document title +contents of acknowledgments footnote after document title. +(Note: as of typst 0.15, this does not work properly, due to an upstream +issue; see jgm/pandoc#11807.) .TP \f[CR]mathfont\f[R], \f[CR]codefont\f[R] Name of system font to use for math and code, respectively. @@ -3476,10 +3592,22 @@ \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 +.TP +\f[CR]csl\-entry\-spacing\f[R] +entry spacing between citeproc\-generated bibliography entries (with a +unit, e.g.\ \f[CR]1em\f[R]). +This will be set automatically based on the CSL style but can be +overridden. +.TP +\f[CR]csl\-hanging\-indent\f[R] +amount of hanging indent in citeproc\-generated bibliography entries +(with a unit, e.g.\ \f[CR]1.5em\f[R]). +This will be set automatically based on the CSL style but can be +overridden. .SS Variables for ms .TP \f[CR]fontfamily\f[R] -\f[CR]A\f[R] (Avant Garde), \f[CR]B\f[R] (Bookman), \f[CR]C\f[R] +\f[CR]A\f[R] (Avant Garde), \f[CR]B\f[R] (Bookman), \f[CR]H\f[R] (Helvetica), \f[CR]HN\f[R] (Helvetica Narrow), \f[CR]P\f[R] (Palatino), or \f[CR]T\f[R] (Times New Roman). This setting does not affect source code, which is always displayed @@ -3497,6 +3625,10 @@ .TP \f[CR]pointsize\f[R] point size (e.g.\ \f[CR]10p\f[R]) +.SS Variables for RTF +.TP +\f[CR]fontsize\f[R] +font size for body text, e.g.\ \f[CR]12pt\f[R] or \f[CR]12.5pt\f[R]. .SS Variables set automatically Pandoc sets these variables automatically in response to options or document contents; users can also modify them. @@ -3513,9 +3645,9 @@ \f[CR]mm/dd/yy\f[R], \f[CR]yyyy\-mm\-dd\f[R] (ISO 8601), \f[CR]dd MM yyyy\f[R] (e.g.\ either \f[CR]02 Apr 2018\f[R] or \f[CR]02 April 2018\f[R]), \f[CR]MM dd, yyyy\f[R] -(e.g.\ \f[CR]Apr. 02, 2018\f[R] or -\f[CR]April 02, 2018),\f[R]yyyy[mm[dd]]\f[CR](e.g.\f[R]20180402, -\f[CR]201804\f[R] or \f[CR]2018\f[R]). +(e.g.\ \f[CR]Apr. 02, 2018\f[R] or \f[CR]April 02, 2018\f[R]), +\f[CR]yyyy[mm[dd]]\f[R] (e.g.\ \f[CR]20180402\f[R], \f[CR]201804\f[R] or +\f[CR]2018\f[R]). .TP \f[CR]header\-includes\f[R] contents specified by \f[CR]\-H/\-\-include\-in\-header\f[R] (may have @@ -3633,7 +3765,7 @@ these characters literally. In writing LaTeX, enabling \f[CR]smart\f[R] tells pandoc to use the ligatures when possible; if \f[CR]smart\f[R] is disabled pandoc will use -unicode quotation mark and dash characters. +Unicode quotation mark and dash characters. .SS Headings and sections .SS Extension: \f[CR]auto_identifiers\f[R] A heading without an explicitly specified identifier will be @@ -3643,7 +3775,8 @@ .TP input formats \f[CR]markdown\f[R], \f[CR]latex\f[R], \f[CR]rst\f[R], -\f[CR]mediawiki\f[R], \f[CR]textile\f[R], \f[CR]man\f[R] +\f[CR]mediawiki\f[R], \f[CR]textile\f[R], \f[CR]man\f[R], +\f[CR]typst\f[R] .TP output formats \f[CR]markdown\f[R], \f[CR]muse\f[R] @@ -3861,13 +3994,15 @@ \f[CR]docx\f[R], \f[CR]odt\f[R], \f[CR]opendocument\f[R], \f[CR]html\f[R], \f[CR]latex\f[R] .SS Extension: \f[CR]native_numbering\f[R] -Enables native numbering of figures and tables. -Enumeration starts at 1. -.PP +Enables numbering of figures and tables via counter fields specific to +the target format. This extension can be enabled/disabled for the following formats: .TP output formats \f[CR]odt\f[R], \f[CR]opendocument\f[R], \f[CR]docx\f[R] +.PP +If this extension is not enabled, tables and figures in these formats +will not be numbered. .SS Extension: \f[CR]xrefs_name\f[R] Links to headings, figures and tables inside the document are substituted with cross\-references that will use the name or caption of @@ -3890,11 +4025,12 @@ referenced item. The original link text is discarded. This extension can be combined with \f[CR]xrefs_name\f[R] in which case -the name or caption numbers will appear after the number. +the name or caption will appear after the number. .PP -For the \f[CR]xrefs_number\f[R] to be useful heading numbers must be -enabled in the generated document, also table and figure captions must -be enabled using for example the \f[CR]native_numbering\f[R] extension. +For the \f[CR]xrefs_number\f[R] extension to be useful, heading numbers +must be enabled in the generated document, also table and figure +captions must be enabled using for example the +\f[CR]native_numbering\f[R] extension. .PP Numbers in cross\-references are only visible in the final document once it has been refreshed. @@ -4295,7 +4431,7 @@ Same as \f[CR]fenced_code_blocks\f[R], but uses backticks (\f[CR]\(ga\f[R]) instead of tildes (\f[CR]\(ti\f[R]). .SS Extension: \f[CR]fenced_code_attributes\f[R] -Optionally, you may attach attributes to fenced or backtick code block +Optionally, you may attach attributes to a fenced or backtick code block using this syntax: .IP .EX @@ -4557,6 +4693,11 @@ .PP Note: the `\f[CR]#\f[R]' ordered list marker doesn\(cqt work with \f[CR]commonmark\f[R]. +.PP +As with \f[CR]commonmark\f[R], ordered sublists must start with +\f[CR]1\f[R] or the equivalent (e.g., \f[CR]i\f[R] or \f[CR]a\f[R]). +This helps avoid unintentional lists caused by things like parenthesized +dates. .SS Extension: \f[CR]startnum\f[R] Pandoc also pays attention to the type of list marker used, and to the starting number, and both of these are preserved where possible in the @@ -4626,7 +4767,7 @@ .PP A term may have multiple definitions, and each definition may consist of one or more indented block elements (paragraph, code block, list, etc.). -The blocks in the definition shoud be indented to the column of the +The blocks in the definition should be indented to the column of the first non\-space content after the \f[CR]:\f[R] or \f[CR]\(ti\f[R] marker, or (if the \f[CR]four_space_rule\f[R] extension is enabled) four spaces or one tab stop. @@ -4712,6 +4853,19 @@ This only works reliably, though, if the repeated item is in a list by itself, because each numbered example list will be numbered continuously from its starting number. +.PP +In a longer (book\-length) work, one might need to reset the example +list counter at the beginning of each chapter. +One can do that using the following syntax: +.IP +.EX +(1\(atfoo) This item will be numbered 1, and subsequent example + list items will be numbered 2, 3, etc. +.EE +.PP +Any number may be used instead of \f[CR]1\f[R]. +Note that if there are several example list items in a row, the number +only has an effect if placed on the first of them. .SS Ending a list What if you want to put an indented code block after a list? .IP @@ -4771,10 +4925,11 @@ interpret the lines that follow as a YAML metadata block or a table. .SS Tables Four kinds of tables may be used. -The first three kinds presuppose the use of a fixed\-width font, such as +The first three kinds (simple, multiline, and grid) require lining up +columns and thus presuppose the use of a fixed\-width font, such as Courier. -The fourth kind can be used with proportionally spaced fonts, as it does -not require lining up columns. +The fourth kind (pipe tables) can be used with proportionally spaced +fonts, as it does not require lining up columns. .SS Extension: \f[CR]table_captions\f[R] A caption may optionally be provided with all 4 kinds of tables (as illustrated in the examples below). @@ -5015,8 +5170,8 @@ header from the table body. (For example \f[CR]\-\-\-|\-\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 +On the other hand, if no lines are wider than the 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 @@ -5041,6 +5196,31 @@ .EX : Here\(aqs the caption. {#ident .class key=\(dqvalue\(dq} .EE +.SS Table placement in LaTeX +By default, pandoc will render tables in LaTeX using the +\f[CR]longtable\f[R] environment. +The tables will not \(lqfloat\(rq and they can span page boundaries. +If you prefer standard \(lqfloating\(rq tables (which are limited to +what can fit on one page), add the \f[CR]float\f[R] class to the +table\(cqs attributes (which can be specified after the caption). +Optionally, the \f[CR]latex\-placement\f[R] attribute may be used to +pass parameters affecting the float placement: +.IP +.EX +: The caption of the table. {#ident .float latex\-placement=\(dqht\(dq} +.EE +.PP +Note that \f[CR]longtable\f[R] does not work with two\-column layouts, +so if you are producing a two\-column document using LaTeX, you will +need to specify the \f[CR]float\f[R] class on every table, or use this +small Lua filter to add it automatically: +.IP +.EX +\f[B]function\f[R] Table(el) + el.classes:insert(\(dqfloat\(dq) + \f[B]return\f[R] el +\f[B]end\f[R] +.EE .SS Metadata blocks .SS Extension: \f[CR]pandoc_title_block\f[R] If the file begins with a title block @@ -5510,7 +5690,7 @@ It will appear verbatim surrounded by \f[CR]\(rs(...\(rs)\f[R] (for inline math) or \f[CR]\(rs[...\(rs]\f[R] (for display math). .TP -Markdown, Emacs Org mode, ConTeXt, ZimWiki +Markdown, Emacs Org mode, ConTeXt, Txt2Tags, ZimWiki It will appear verbatim surrounded by \f[CR]$...$\f[R] (for inline math) or \f[CR]$$...$$\f[R] (for display math). .TP @@ -5547,7 +5727,7 @@ It will be rendered, if possible, using MathML. .TP DocBook -If the \f[CR]\-\-mathml\f[R] flag is used, it will be rendered using +If \f[CR]\-\-math\-method=mathml\f[R] is used, it will be rendered using MathML in an \f[CR]inlineequation\f[R] or \f[CR]informalequation\f[R] tag. Otherwise it will be rendered, if possible, using Unicode characters. @@ -5556,8 +5736,8 @@ It will be rendered using OMML math markup. .TP FictionBook2 -If the \f[CR]\-\-webtex\f[R] option is used, formulas are rendered as -images using CodeCogs or other compatible web service, downloaded and +If \f[CR]\-\-math\-method=webtex\f[R] is used, formulas are rendered as +images using CodeCogs or another compatible web service, downloaded and embedded in the e\-book. Otherwise, they will appear verbatim. .TP @@ -5575,18 +5755,19 @@ desired.) .PP The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous, -DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile -output, and suppressed in other formats. +DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, Textile, and +Txt2Tags output, and suppressed in other formats. .PP For a more explicit way of including raw HTML in a Markdown document, see the \f[CR]raw_attribute\f[R] extension. .PP -In the CommonMark format, if \f[CR]raw_html\f[R] is enabled, -superscripts, subscripts, strikeouts and small capitals will be -represented as HTML. +In commonmark output, if \f[CR]raw_html\f[R] is enabled, superscripts, +subscripts, strikeouts and small capitals will be represented as HTML. Otherwise, plain\-text fallbacks will be used. -Note that even if \f[CR]raw_html\f[R] is disabled, tables will be -rendered with HTML syntax if they cannot use pipe syntax. +.PP +Disabling the \f[CR]raw_html\f[R] extension has no effect on +\f[CR]commonmark\f[R] (or \f[CR]gfm\f[R] or \f[CR]commonmark_x\f[R]) +\f[I]input\f[R]. .SS Extension: \f[CR]markdown_in_html_blocks\f[R] Original Markdown allows you to include HTML \(lqblocks\(rq: blocks of HTML between balanced tags that are separated from the surrounding text @@ -5637,7 +5818,7 @@ \f[CR]markdown_in_html_blocks\f[R], but it makes it easier to write pandoc filters to manipulate groups of blocks. .SS Extension: \f[CR]native_spans\f[R] -Use native pandoc \f[CR]Span\f[R] blocks for content inside +Use native pandoc \f[CR]Span\f[R] elements for content inside \f[CR]<span>\f[R] tags. For the most part this should give the same output as \f[CR]raw_html\f[R], but it makes it easier to write pandoc filters to @@ -5787,9 +5968,9 @@ in square brackets. (There cannot be space between the two unless the \f[CR]spaced_reference_links\f[R] extension is enabled.) -If the label is empty (\f[CR][]\f[R]), then it will be implicitly be -taken to be the same as the link text; thus \f[CR][foo][]\f[R] is -equivalent to \f[CR][foo][foo]\f[R]. +If the label is empty (\f[CR][]\f[R]), then it will implicitly be taken +to be the same as the link text; thus \f[CR][foo][]\f[R] is equivalent +to \f[CR][foo][foo]\f[R]. (If the \f[CR]shortcut_reference_links\f[R] extension is enabled, the empty \f[CR][]\f[R] may be omitted.) .PP @@ -5800,7 +5981,7 @@ \f[CR]citations\f[R] extension is enabled): citations take precedence over link labels. .PP -Here are some examples of reference links and link definitions; +Here are some examples of reference links and link definitions: .IP .EX See [the website *I* built][my website]. @@ -5881,7 +6062,8 @@ .SS Images A link immediately preceded by a \f[CR]!\f[R] will be treated as an image. -The link text will be used as the image\(cqs alt text: +The link text (the part in square brackets) will be used as the +image\(cqs alt text: .IP .EX  @@ -5975,7 +6157,7 @@ For example the above example will render to the following. .RS 2 .IP \(bu 2 -HTML: \f[CR]<img href=\(dqfile.jpg\(dq style=\(dqwidth: 50%;\(dq />\f[R] +HTML: \f[CR]<img src=\(dqfile.jpg\(dq style=\(dqwidth: 50%;\(dq />\f[R] .IP \(bu 2 LaTeX: \f[CR]\(rsincludegraphics[width=0.5\(rstextwidth,height=\(rstextheight]{file.jpg}\f[R] @@ -6183,8 +6365,8 @@ If no locator term is used, \(lqpage\(rq is assumed. .PP In complex cases, you can force something to be treated as a locator by -enclosing it in curly braces or prevent parsing the suffix as locator by -prepending curly braces: +enclosing it in curly braces or prevent parsing the suffix as a locator +by prepending curly braces: .IP .EX [\(atsmith{ii, A, D\-Z}, with a suffix] @@ -6277,8 +6459,7 @@ relative to the file containing the link reference definition, not the file containing the reference link or image itself, if these differ. .SS Extension: \f[CR]mark\f[R] -To highlight out a section of text, begin and end it with with -\f[CR]==\f[R]. +To highlight a section of text, begin and end it with \f[CR]==\f[R]. Thus, for example, .IP .EX @@ -6441,7 +6622,8 @@ for strong emphasis, surround by underscores for regular emphasis, add extra blank space around headings. .SS Extension: \f[CR]sourcepos\f[R] -Include source position attributes when parsing \f[CR]commonmark\f[R]. +Include source position attributes when parsing \f[CR]commonmark\f[R] or +\f[CR]djot\f[R]. For elements that accept attributes, a \f[CR]data\-pos\f[R] attribute is added; other elements are placed in a surrounding Div or Span element with a \f[CR]data\-pos\f[R] attribute. @@ -6504,7 +6686,7 @@ where \f[CR]FORMAT\f[R] is replaced with the name of the format. .PP Note that the list of extensions for \f[CR]commonmark\f[R], -\f[CR]gfm\f[R], and \f[CR]commonmark_x\f[R] are defined relative to +\f[CR]gfm\f[R], and \f[CR]commonmark_x\f[R] is defined relative to default commonmark. So, for example, \f[CR]backtick_code_blocks\f[R] does not appear as an extension, since it is enabled by default and cannot be disabled. @@ -6531,8 +6713,8 @@ \f[CR]bibliography\f[R] metadata field in a YAML metadata section or the \f[CR]\-\-bibliography\f[R] command line argument. If you want to use multiple bibliography files, you can supply multiple -\f[CR]\-\-bibliography\f[R] arguments or set \f[CR]bibliography\f[R] -metadata field to YAML array. +\f[CR]\-\-bibliography\f[R] arguments or set the \f[CR]bibliography\f[R] +metadata field to a YAML array. A bibliography may have any of these formats: .RS -14n .IP @@ -6693,7 +6875,7 @@ Spin wave dispersion on the <span class=\(dqnocase\(dq>nm</span> scale .EE .RE -.SS Conference Papers, Published vs.\ Unpublished +.SS Conference papers, published vs.\ unpublished For a formally published conference paper, use the biblatex entry type \f[CR]inproceedings\f[R] (which will be mapped to CSL \f[CR]paper\-conference\f[R]). @@ -6846,8 +7028,8 @@ For LaTeX output, you can also use \f[CR]natbib\f[R] or \f[CR]biblatex\f[R] to render the bibliography. In order to do so, specify bibliography files as outlined above, and add -\f[CR]\-\-natbib\f[R] or \f[CR]\-\-biblatex\f[R] argument to pandoc -invocation. +the \f[CR]\-\-natbib\f[R] or \f[CR]\-\-biblatex\f[R] argument to the +pandoc invocation. Bear in mind that bibliography files have to be in either BibTeX (for \f[CR]\-\-natbib\f[R]) or BibLaTeX (for \f[CR]\-\-biblatex\f[R]) format. .SS Other relevant metadata fields @@ -6859,8 +7041,8 @@ Defaults to false. .TP \f[CR]link\-bibliography\f[R] -If true, DOIs, PMCIDs, PMID, and URLs in bibliographies will be rendered -as hyperlinks. +If true, DOIs, PMCIDs, PMIDs, 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.) @@ -7414,7 +7596,9 @@ text: Sarah Jones identifier: \- scheme: DOI - text: doi:10.234234.234/33 + text: \(aqurn:doi:10.234234.234/33\(aq +\- scheme: ISBN\-13 + text: \(aqurn:isbn:9780000000000\(aq publisher: My Press rights: © 2007 John Smith, CC BY\-NC ibooks: @@ -7425,8 +7609,8 @@ The following fields are recognized: .TP \f[CR]identifier\f[R] -Either a string value or an object with fields \f[CR]text\f[R] and -\f[CR]scheme\f[R]. +Either a string value, or an object with fields \f[CR]text\f[R] and +\f[CR]scheme\f[R] (optional), or a list of such objects. Valid values for \f[CR]scheme\f[R] are \f[CR]ISBN\-10\f[R], \f[CR]GTIN\-13\f[R], \f[CR]UPC\f[R], \f[CR]ISMN\-10\f[R], \f[CR]DOI\f[R], \f[CR]LCCN\f[R], \f[CR]GTIN\-14\f[R], @@ -7436,17 +7620,22 @@ \f[CR]OLCC number\f[R], \f[CR]JP Magazine ID\f[R], \f[CR]UPC\-12+5\f[R], \f[CR]BNF Control number\f[R], \f[CR]ISSN\-13\f[R], \f[CR]ARK\f[R], \f[CR]Digital file internal version number\f[R]. +In the \f[CR]text\f[R] field, it is advisable to specify a URN as in the +examples above. +Note that quotes are needed around a YAML field containing a colon. .TP \f[CR]title\f[R] -Either a string value, or an object with fields \f[CR]file\-as\f[R] and -\f[CR]type\f[R], or a list of such objects. +Either a string value, or an object with fields \f[CR]text\f[R], +\f[CR]file\-as\f[R] (optional) and \f[CR]type\f[R] (optional), or a list +of such objects. Valid values for \f[CR]type\f[R] are \f[CR]main\f[R], \f[CR]subtitle\f[R], \f[CR]short\f[R], \f[CR]collection\f[R], \f[CR]edition\f[R], \f[CR]extended\f[R]. .TP \f[CR]creator\f[R] -Either a string value, or an object with fields \f[CR]role\f[R], -\f[CR]file\-as\f[R], and \f[CR]text\f[R], or a list of such objects. +Either a string value, or an object with fields \f[CR]text\f[R], +\f[CR]role\f[R] (optional), and \f[CR]file\-as\f[R] (optional), or a +list of such objects. Valid values for \f[CR]role\f[R] are MARC relators, but pandoc will attempt to translate the human\-readable versions (like \(lqauthor\(rq and \(lqeditor\(rq) to the appropriate marc relators. @@ -7465,7 +7654,8 @@ .TP \f[CR]subject\f[R] Either a string value, or an object with fields \f[CR]text\f[R], -\f[CR]authority\f[R], and \f[CR]term\f[R], or a list of such objects. +\f[CR]authority\f[R] (optional), and \f[CR]term\f[R] (optional), or a +list of such objects. Valid values for \f[CR]authority\f[R] are either a reserved authority value (currently \f[CR]AAT\f[R], \f[CR]BIC\f[R], \f[CR]BISAC\f[R], \f[CR]CLC\f[R], \f[CR]DDC\f[R], \f[CR]CLIL\f[R], \f[CR]EuroVoc\f[R], @@ -7794,8 +7984,8 @@ Setext\-style headings to be used; and \f[CR]\-\-preserve\-tabs\f[R] will prevent tabs from being turned to spaces. .SH VIMDOC -Vimdoc writer generates Vim help files and makes use of the following -metadata variables: +The Vimdoc writer generates Vim help files and makes use of the +following metadata variables: .IP .EX abstract\f[B]:\f[R] \(dqA short description\(dq @@ -7807,9 +7997,9 @@ vimdoc\-prefix\f[B]:\f[R] pandoc .EE .PP -Complete header requires \f[CR]abstract\f[R], \f[CR]author\f[R], +A complete header requires \f[CR]abstract\f[R], \f[CR]author\f[R], \f[CR]title\f[R] and \f[CR]filename\f[R] to be set. -Compiling file with such metadata produces the following file (assumes +Compiling a file with such metadata produces the following file (assumes \f[CR]\-\-standalone\f[R], see Templates): .IP .EX @@ -7826,8 +8016,8 @@ .EE .PP If \f[CR]vimdoc\-prefix\f[R] is set, all non\-command tags are prefixed -with its value, it is used to prevent tag collision: all headers have a -tag (either inferred or explicit) and multiple help pages can have the +with its value; this is used to prevent tag collision: all headers have +a tag (either inferred or explicit) and multiple help pages can have the same header names, therefore collision is to be expected. Let our input be the following markdown file: .IP @@ -7864,7 +8054,7 @@ inherently represent anything. .EE .PP -Convert it to vimdoc with metadata variable set (e.g.\ with +Convert it to vimdoc with the metadata variable set (e.g.\ with \f[CR]\-M vimdoc\-prefix=pandoc\f[R]) .IP .EX @@ -7963,11 +8153,11 @@ 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. +Custom styles can be used in the docx, odt, fodt and ICML formats. .SS Output -By default, pandoc\(cqs odt, docx and ICML output applies a predefined -set of styles for blocks such as paragraphs and block quotes, and uses -largely default formatting (italics, bold) for inlines. +By default, pandoc\(cqs odt, fodt, docx and ICML output applies a +predefined set of styles for blocks such as paragraphs and block quotes, +and uses largely default formatting (italics, bold) for inlines. This will work for most purposes, especially alongside a reference doc file. However, if you need to apply your own styles to blocks, or match a @@ -8200,11 +8390,11 @@ .EE .PP A recent \f[CR]context\f[R] version should be used, as older versions -contained a bug that lead to invalid PDF metadata. +contained a bug that led to invalid PDF metadata. .SS WeasyPrint The HTML\-based engine WeasyPrint includes experimental support for PDF/A and PDF/UA since version 57. -Tagged PDFs can created with +Tagged PDFs can be created with .IP .EX pandoc \-\-pdf\-engine=weasyprint \(rs @@ -8267,45 +8457,87 @@ .SH A NOTE ON SECURITY .IP "1." 3 Although pandoc itself will not create or modify any files other than -those you explicitly ask it create (with the exception of temporary +those you explicitly ask it to create (with the exception of temporary files used in producing PDFs), a filter or custom writer could in principle do anything on your file system. Please audit filters and custom writers very carefully before using them. .IP "2." 3 +If you want to use pandoc in a web application that accepts untrusted +user input, you should be aware that running pandoc in this context +requires special precautions, or you risk exfiltration of the contents +of local files, or worse. +In particular: +.RS 4 +.IP \(bu 2 Several input formats (including LaTeX, Org, RST, and Typst) support \f[CR]include\f[R] directives that allow the contents of a file to be included in the output. An untrusted attacker could use these to view the contents of files on the file system. -(Using the \f[CR]\-\-sandbox\f[R] option can protect against this -threat.) -.IP "3." 3 +Using the \f[CR]\-\-sandbox\f[R] option will protect against this +threat. +.IP \(bu 2 Several output formats (including RTF, FB2, HTML with \f[CR]\-\-self\-contained\f[R], EPUB, Docx, and ODT) will embed encoded or raw images into the output file. An untrusted attacker could exploit this to view the contents of non\-image files on the file system. -(Using the \f[CR]\-\-sandbox\f[R] option can protect against this -threat, but will also prevent including images in these formats.) -.IP "4." 3 +Using the \f[CR]\-\-sandbox\f[R] option will protect against this +threat, but will also prevent including images in these formats. +.IP \(bu 2 In reading HTML files, pandoc will attempt to include the contents of \f[CR]iframe\f[R] elements by fetching content from the local file or URL specified by \f[CR]src\f[R]. If untrusted HTML is processed on a server, this has the potential to -reveal anything readable by the process running the server. -Using the \f[CR]\-f html+raw_html\f[R] will mitigate this threat by -causing the whole \f[CR]iframe\f[R] to be parsed as a raw HTML block. -Using \f[CR]\-\-sandbox\f[R] will also protect against the threat. -.IP "5." 3 -If your application uses pandoc as a Haskell library (rather than -shelling out to the executable), it is possible to use it in a mode that -fully isolates pandoc from your file system, by running the pandoc -operations in the \f[CR]PandocPure\f[R] monad. -See the document Using the pandoc API for more details. -(This corresponds to the use of the \f[CR]\-\-sandbox\f[R] option on the -command line.) -.IP "6." 3 +reveal anything readable by the process running the server or to enable +server\-side request forgery (SSRF) attacks (CVE\-2025\-51591). +To mitigate such attacks, use \f[CR]\-\-sandbox\f[R] or +\f[CR]\-f html+raw_html\f[R] (which causes the whole \f[CR]iframe\f[R] +to be parsed as a raw HTML block). +.IP \(bu 2 +Using pandoc with \f[CR]\-\-pdf\-engine\f[R] introduces additional +risks, which cannot be mitigated by using \f[CR]\-\-sandbox\f[R]. +For example, in \f[CR]wkhtmltopdf\f[R] the \f[CR]footer\-html\f[R] and +\f[CR]header\-html\f[R] metadata fields will be passed directly to +\f[CR]wkhtmltopdf\f[R] as \f[CR]\-\-footer\-html\f[R] and +\f[CR]\-\-header\-html\f[R] arguments, and by using a \f[CR]file:\f[R] +URI with these, one could exfiltrate local files. +In addition, using \f[CR]\-\-pdf\-engine=wkhtmltopdf\f[R] with +\f[CR]\-f html+raw_html\f[R] enables an SSRF vulnerability in +wkhtmltopdf (CVE\-2022\-35583). +Note that \f[CR]wkhtmltopdf\f[R] is deprecated and its authors recommend +not to use it with any untrusted input. +However, there may be similar issues with other pdf\-engines. +Anyone including a pdf\-engine in a pandoc command run on untrusted +input should audit the engine carefully and carefully control the use of +\f[CR]\-\-pdf\-engine\-opt\f[R]. +.PP +Here are some alternatives for safe use of pandoc in a web application: +.IP \(bu 2 +Use \f[CR]pandoc server\f[R] to spin up a local web server, and have +your application make requests to it. +The server runs in sandboxed mode and will not be able to read files or +use filters. +.IP \(bu 2 +Use the WASM version of pandoc. +This allows the use of Lua filters, but everything runs in an isolated +WASM sandbox. +.IP \(bu 2 +Use \f[CR]pandoc \-\-sandbox\f[R]. +However, be aware that the sandbox function only affects readers and +writers, and security issues can arise if you use it together with +\f[CR]\-\-filter\f[R] or \f[CR]\-\-pdf\-engine\f[R]. +.RE +.IP "3." 3 +The HTML generated by pandoc is not guaranteed to be safe. +If \f[CR]raw_html\f[R] is enabled for the Markdown input, users can +inject arbitrary HTML. +Even if \f[CR]raw_html\f[R] is disabled, users can include dangerous +content in URLs and attributes. +To be safe, you should run all HTML generated from untrusted user input +through an HTML sanitizer. +.IP "4." 3 Pandoc\(cqs parsers can exhibit pathological performance on some corner cases. It is wise to put any pandoc operations under a timeout, to avoid DOS @@ -8317,14 +8549,14 @@ \f[CR]commonmark_x\f[R] and \f[CR]gfm\f[R]) is much less vulnerable to pathological performance than the \f[CR]markdown\f[R] parser, so it is a better choice when processing untrusted input. -.IP "7." 3 -The HTML generated by pandoc is not guaranteed to be safe. -If \f[CR]raw_html\f[R] is enabled for the Markdown input, users can -inject arbitrary HTML. -Even if \f[CR]raw_html\f[R] is disabled, users can include dangerous -content in URLs and attributes. -To be safe, you should run all HTML generated from untrusted user input -through an HTML sanitizer. +.IP "5." 3 +If your application uses pandoc as a Haskell library (rather than +shelling out to the executable), it is possible to use it in a mode that +fully isolates pandoc from your file system, by running the pandoc +operations in the \f[CR]PandocPure\f[R] monad. +See the document Using the pandoc API for more details. +(This corresponds to the use of the \f[CR]\-\-sandbox\f[R] option on the +command line.) .SH AUTHORS Copyright 2006\(en2024 John MacFarlane (jgm\(atberkeley.edu). Released under the GPL, version 2 or greater. diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/pandoc-cli-3.10/pandoc-cli.cabal new/pandoc-cli-3.13/pandoc-cli.cabal --- old/pandoc-cli-3.10/pandoc-cli.cabal 2001-09-09 03:46:40.000000000 +0200 +++ new/pandoc-cli-3.13/pandoc-cli.cabal 2001-09-09 03:46:40.000000000 +0200 @@ -1,6 +1,6 @@ cabal-version: 2.4 name: pandoc-cli -version: 3.10 +version: 3.13 build-type: Simple license: GPL-2.0-or-later license-file: COPYING.md @@ -69,7 +69,7 @@ buildable: True -- Note: we always link to an exact version of pandoc, with the -- same version as this package: - build-depends: pandoc == 3.10, text + build-depends: pandoc == 3.13, text other-modules: PandocCLI.Lua , PandocCLI.Server
