diff --git a/.circleci/config.yml b/.circleci/config.yml deleted file mode 100644 index a6019a6d9c3a..000000000000 --- a/.circleci/config.yml +++ /dev/null @@ -1,74 +0,0 @@ -version: "2.1" -jobs: - build: - macos: - xcode: 11.1.0 - environment: - HOMEBREW_NO_AUTO_UPDATE: 1 - steps: - - checkout - - restore_cache: - # See https://circleci.com/docs/2.0/caching/ - name: Restore Cached Dependencies - keys: - - stack-dependencies-{{ checksum "stack.yaml" }} - - run: - name: Install stack - command: | - brew install ghc - brew install haskell-stack - - run: - name: Resolve/Update Dependencies - command: stack --no-terminal setup - - run: - name: Run tests - command: stack --no-terminal test - - run: - name: Install executable - command: stack --no-terminal install - - run: - name: Create artifacts - command: | - export VERSION=$(grep '^[Vv]ersion:' pandoc.cabal | awk '{print $$2;}') - export ARTIFACTS=macos-release-candidate - export RESOURCES=${ARTIFACTS}/Resources - export ROOT=${ARTIFACTS}/pandoc - export DEST=${ROOT}/usr/local - export ME=$(whoami) - export BASE=pandoc-$VERSION - mkdir -p ${ARTIFACTS} - mkdir -p ${RESOURCES} - mkdir -p ${DEST}/bin - mkdir -p ${DEST}/share/man/man1 - cp ~/.local/bin/pandoc ${DEST}/bin/ - strip ${DEST}/bin/pandoc - cp man/pandoc.1 ${DEST}/share/man/man1/pandoc.1 - ~/.local/bin/pandoc -s COPYING.md -Vpagetitle=License -o ${RESOURCES}/license.html - chown -R $ME:staff ${ROOT} - sed -e "s/PANDOCVERSION/${VERSION}/" macos/distribution.xml.in > ${ARTIFACTS}/distribution.xml - cp macos/Makefile ${ARTIFACTS}/ - echo ${VERSION} > ${ARTIFACTS}/version.txt - zip -r macos-release-candidate.zip ${ARTIFACTS} - - - save_cache: - name: Cache Dependencies - key: stack-dependencies-{{ checksum "stack.yaml" }} - paths: - - "/root/.stack" - - ".stack-work" - - "/usr/local/bin/stack" - - - store_artifacts: - # https://circleci.com/docs/2.0/artifacts/ - path: macos-release-candidate.zip - destination: macos-release-candidate.zip - -workflows: - version: 2 - release: - jobs: - - build: - filters: - branches: - only: - - /rc\/.*/ diff --git a/.cirrus.yml b/.cirrus.yml index 20b28d7ba9da..7fd27a4cc584 100644 --- a/.cirrus.yml +++ b/.cirrus.yml @@ -7,9 +7,9 @@ task: image: ghcr.io/cirruslabs/macos-monterey-base:latest brew_script: - brew update - - brew install ghc@9.6 cabal-install + - brew install ghc@9.8 cabal-install env: - PATH: /opt/homebrew/opt/ghc@9.6/bin:${PATH} + PATH: /opt/homebrew/opt/ghc@9.8/bin:${PATH} cabal_store_cache: folder: ~/.cabal/store fingerprint_key: macos_2023_03_12 @@ -29,7 +29,7 @@ task: trigger_type: manual timeout_in: 90m arm_container: - image: quay.io/benz0li/ghc-musl:9.6 + image: quay.io/benz0li/ghc-musl:9.8 cpu: 4 memory: 12G env: @@ -55,7 +55,7 @@ task: trigger_type: manual timeout_in: 90m container: - image: quay.io/benz0li/ghc-musl:9.6 + image: quay.io/benz0li/ghc-musl:9.8 cpu: 4 memory: 12G env: diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index f4ef3ba4b97f..05149b100540 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1 +1 @@ -github: [jgm,tarleb] +github: [jgm,tarleb,silby] diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index f53a163aa9ed..14bb9da22de5 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -7,20 +7,29 @@ assignees: '' --- **Explain the problem.** Include the **exact command line** you used and **all inputs necessary to reproduce the issue**. Please create as minimal an example as possible, to help the maintainers isolate the problem. Explain the output you received and how it differs from what you expected. **Pandoc version?** -What version of pandoc are you using, on what OS? (If it's not the latest release, please try with the latest release before reporting the issue.) +What version of pandoc are you using, on what OS? (If it's not the latest release, please try with the latest release before reporting the issue. Note that many linux distributions have old versions of pandoc in their repositories.) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 79b0a08905f5..e08f166422dc 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -2,7 +2,6 @@ blank_issues_enabled: false contact_links: - name: Ask a question url: https://github.com/jgm/pandoc/discussions - # https://groups.google.com/forum/#!forum/pandoc-discuss about: "Discussion forum for pandoc" - name: Contributing Guidelines url: https://pandoc.org/CONTRIBUTING.html diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index cff52c1d4213..5bf1c95280a1 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -12,7 +12,7 @@ Thank you for suggesting a feature! Before you continue, please make sure that y - read the contributing guidelines: https://pandoc.org/CONTRIBUTING.html - searched the issue tracker for similar issues (including closed issues): https://github.com/jgm/pandoc/issues -- searched the pandoc-discuss mailing list for relevant discussions: https://groups.google.com/forum/#!forum/pandoc-discuss +- searched the discussion list for relevant discussions: https://github.com/jgm/pandoc/discussions --> **Describe your proposed improvement and the problem it solves.** diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 36b19895f636..35e5f5ecacb8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -51,18 +51,35 @@ jobs: - ghc: '8.10' cabal: 'latest' cabalopts: '' + ghcopts: '-Werror' - ghc: '9.0' cabal: 'latest' cabalopts: '' + ghcopts: '-Werror' - ghc: '9.2' cabal: 'latest' cabalopts: '' + ghcopts: '-Werror' - ghc: '9.4' cabal: 'latest' cabalopts: '' + ghcopts: '-Werror' - ghc: '9.6' cabal: 'latest' cabalopts: '' + ghcopts: '-Werror' + - ghc: '9.8' + cabal: 'latest' + cabalopts: '' + ghcopts: '-Werror' + - ghc: '9.10' + cabal: 'latest' + cabalopts: '' + ghcopts: '' + - ghc: '9.12' + cabal: 'latest' + cabalopts: '--allow-newer' + ghcopts: '' steps: - uses: actions/checkout@v4 @@ -103,7 +120,7 @@ jobs: - name: Build and test run: | - cabal test ${{ matrix.versions.cabalopts }} --enable-tests --disable-optimization --ghc-options=-Werror all + cabal test ${{ matrix.versions.cabalopts }} --enable-tests --disable-optimization --ghc-options="${{ matrix.verisons.ghcopts }}" all linux-stack: @@ -138,32 +155,32 @@ jobs: run: | stack test --fast - linux-nix-cabal: +# linux-nix-cabal: - runs-on: ubuntu-latest - strategy: - fail-fast: true - steps: - - uses: actions/checkout@v4 - - uses: cachix/install-nix-action@V27 - with: - nix_path: nixpkgs=channel:nixos-unstable - - name: Cache cabal global package db - id: cabal-global - uses: actions/cache@v4 - with: - path: | - ~/.local/state/cabal - key: ${{ runner.os }}-nix-cabal-global-${{ secrets.CACHE_VERSION }} - - name: Cache cabal work - id: cabal-local - uses: actions/cache@v4 - with: - path: | - dist-newstyle - key: ${{ runner.os }}-nix-cabal-local-${{ secrets.CACHE_VERSION }} - - run: | - nix-shell --run "cabal update && cabal test --enable-tests --disable-optimization --ghc-options=-Werror all" +# runs-on: ubuntu-latest +# strategy: +# fail-fast: true +# steps: +# - uses: actions/checkout@v4 +# - uses: cachix/install-nix-action@v30 +# with: +# nix_path: nixpkgs=channel:nixos-24.05 +# - name: Cache cabal global package db +# id: cabal-global +# uses: actions/cache@v4 +# with: +# path: | +# ~/.local/state/cabal +# key: ${{ runner.os }}-nix-cabal-global-${{ secrets.CACHE_VERSION }} +# - name: Cache cabal work +# id: cabal-local +# uses: actions/cache@v4 +# with: +# path: | +# dist-newstyle +# key: ${{ runner.os }}-nix-cabal-local-${{ secrets.CACHE_VERSION }} +# - run: | +# nix-shell --run "cabal update && cabal test --enable-tests --disable-optimization --ghc-options=-Werror all" windows: @@ -175,6 +192,7 @@ jobs: - name: Install ghc run: | ghcup install ghc --set 9.4.4 + ghcup install cabal --set 3.10 # declare/restore cached things @@ -194,7 +212,7 @@ jobs: dist-newstyle key: ${{ runner.os }}-stack-work-${{ hashFiles('cabal.project') }}-${{ secrets.CACHE_VERSION }} - - name: Install dependencies + - name: Build and test run: | cabal update cabal test ${{ matrix.versions.cabalopts }} --enable-tests --disable-optimization --ghc-options=-Werror all diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index cb625448fcb9..41ff88abf36a 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -17,7 +17,8 @@ jobs: - name: Install ghc run: | - ghcup install ghc --set 9.4.4 + ghcup install ghc --set 9.8 + ghcup install cabal --set 3.14 - name: Install dependencies run: | @@ -46,7 +47,8 @@ jobs: - uses: actions/checkout@v4 - name: Install ghc run: | - ghcup install ghc --set 9.4.4 + ghcup install ghc --set 9.8 + ghcup install cabal --set 3.14 - name: Install dependencies run: | cabal update @@ -69,13 +71,18 @@ jobs: macos: - runs-on: macos-12 + runs-on: macos-13 steps: - uses: actions/checkout@v4 + - name: Install ghcup + run: | + brew install ghcup - name: Install ghc run: | - ghcup install ghc --set 9.4.4 + ghcup install ghc --set 9.8 + ghcup install cabal --set 3.14 + echo "$HOME/.ghcup/bin" >> "${GITHUB_PATH}" - name: Install dependencies run: | cabal update diff --git a/.github/workflows/release-candidate.yml b/.github/workflows/release-candidate.yml index 1205ab27f045..584346f85095 100644 --- a/.github/workflows/release-candidate.yml +++ b/.github/workflows/release-candidate.yml @@ -21,8 +21,8 @@ jobs: - uses: actions/checkout@v4 - name: Install ghc run: | - ghcup install ghc --set 9.6 - ghcup install cabal --set 3.10 + ghcup install ghc --set 9.8 + ghcup install cabal --set 3.12 - name: Install dependencies run: | @@ -77,15 +77,20 @@ jobs: macos: - runs-on: macos-12 + runs-on: macos-13 steps: - uses: actions/checkout@v4 + - name: Install ghcup + run: | + brew install ghcup + - name: Install ghc and cabal run: | - ghcup install ghc --set 9.6 - ghcup install cabal --set 3.10 + ghcup install ghc --set 9.8 + ghcup install cabal --set 3.12 + echo "$HOME/.ghcup/bin" >> "${GITHUB_PATH}" - name: Create release run: | diff --git a/.gitignore b/.gitignore index 2540f73002fa..6034d7c36ccc 100644 --- a/.gitignore +++ b/.gitignore @@ -27,7 +27,7 @@ !Makefile !README.md !README.template -!RELEASE-CHECKLIST +!RELEASE-CHECKLIST-TEMPLATE.org !SECURITY.md !Setup.hs !cabal.project diff --git a/AUTHORS.md b/AUTHORS.md index 455fcfd00baf..51ebac7cc95f 100644 --- a/AUTHORS.md +++ b/AUTHORS.md @@ -3,6 +3,7 @@ - Aaron Wolen - Adelar da Silva Queiróz - Agustín Martín Barbero +- Akash Patel - Akos Marton - Albert Krewinkel - Alex Ivkin @@ -22,6 +23,7 @@ - Amy de Buitléir - Anabra - Anders Waldenborg +- Andreas Deininger - Andreas Lööw - Andreas Scherer - Andres Freund @@ -67,6 +69,7 @@ - Cezary Drożak - Chandrahas77 - Charanjit Singh +- Charles Tapley Hoyt - Charlotte Koch - Chris Black - Christian Conkle @@ -137,6 +140,7 @@ - Gavin Beatty - George Stagg - Georgi Lyubenov +- GHyman83 - Gokul Rajiv - Gordon Woodhull - Gottfried Haider @@ -147,6 +151,7 @@ - Gwern Branwen - Hamish Mackenzie - Hans-Peter Deifel +- Hendrik Erz - Heiko Schlittermann - Henrik Tramberend - Henry de Valence @@ -195,6 +200,7 @@ - Jeroen de Haas - Jerry Sky - Jesse Rosenthal +- Jez Cope - Joe Hermaszewski - Joe Hillenbrand - John KetzerX @@ -239,14 +245,18 @@ - Lucas Escot - Lucas Viana - Lucas V. R +- Luis Rivera - Luke Plant +- Manolis Stamatogiannakis - Marc Schreiber - Marcin Serwin - Mario Lang +- Mark Gardner - Mark Szepieniec - Mark Wright - Martin Joerg - Martin Linn +- Martin Michlmayr - Martín Pozo - Masataka Ogawa - Masayoshi Takahashi @@ -279,6 +289,7 @@ - Mikołaj Machowski - Milan Bracke - MinRK +- Mohamed Akram - Morgan Willcock - Morton Fox - Nathan Gass @@ -288,6 +299,7 @@ - Nick Berendsen - Nick Fleisher - Nicolas Kaiser +- Niklas Eicker - Nikolai Korobeinikov - Nikolay Yakimov - Nils Carlson @@ -301,6 +313,7 @@ - Oliver Fabel - Oliver Matthews - Olivier Benz +- Olivier Dossmann - Ophir Lifshitz - Or Neeman - OvidiusCicero @@ -340,10 +353,12 @@ - Sam May - Samuel Tardieu - Saumel Lemmenmeier +- Santiago Zarate - Sascha Wilde - Scott Morrison - Sebastian Talmon - Sebbones +- Sen-wen Deng - Sergei Trofimovich - Sergey Astanin - Seth Speaks @@ -361,9 +376,12 @@ - Stephan Meijer - Stephen Altamirano - Stephen Huan +- Stephen Reindl +- Stéphane Guillou - Sukil Etxenike - Sukka - Sumit Sahrawat +- Suraj Patil - Sven Wick - TEC - Tarik Graba @@ -373,6 +391,7 @@ - Thomas Hodgson - Thomas Soeiro - Thomas Weißschuh +- Tiago-Manzato - Tim Lin - Tim Stewart - Tim Wisotzki @@ -410,6 +429,7 @@ - Wout Gevaert - Xavier Olive - Yan Pashkovsky +- Yehuda Katz - YI - Yoan Blanc - Yuchen Pei @@ -431,12 +451,14 @@ - dbecher-ito - ebiim - ech0 +- etclub - favonia - guqicun - harabat - hseg - infinity0x - jeongminkim-islab +- josch - kaizshang91 - lawcho - lifeunleaded diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2a150736e76f..d1291db79c13 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -118,7 +118,7 @@ to `odt`. (You can, however, customize margin size using `--reference-doc`.) So before submitting a bug report, consider whether it might be "out of scope." If it concerns a feature of documents that isn't representable in pandoc's Markdown, then it very likely is. -(If in doubt, you can always ask on the [discussion-forum].) +(If in doubt, you can always ask on the [discussion forum].) Fixing bugs from the issue tracker ---------------------------------- diff --git a/COPYRIGHT b/COPYRIGHT index 1304a153e321..a7f889381f26 100644 --- a/COPYRIGHT +++ b/COPYRIGHT @@ -24,9 +24,9 @@ GPL can be found in `/usr/share/common-licenses/GPL`. [GPL]: https://www.gnu.org/copyleft/gpl.html -Pandoc's complete source code is available from the [Pandoc home page]. - -[Pandoc home page]: https://pandoc.org +The complete source code for pandoc version X.Y.Z is available at + +and at . Pandoc includes some code with different copyrights, or subject to different licenses. The copyright and license statements for these sources are included diff --git a/INSTALL.md b/INSTALL.md index 344c718fb0f2..ffb91ca22283 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -8,13 +8,13 @@ The simplest way to get the latest pandoc release is to use the installer. For alternative ways to install pandoc, see below under the heading for -your operating system. +your operating system. **Note**: the statically linked Pandoc binaries provided by us (or those available on Conda Forge) have a limitation. They are unable to utilise Lua filters that rely on Lua modules written in C. If you require the functionality offered by these filters, please consider an alternative -method of installation. +method of installation. ## Windows @@ -78,6 +78,10 @@ Note: On unsupported versions of macOS (more than three releases old), Homebrew installs from source, which takes additional time and disk space for the `ghc` compiler and dependent Haskell libraries. +You can also install pandoc using [MacPorts]: + + port install pandoc + Or, you can install Pandoc using [Conda forge]. We also provide a zip file containing the binaries and man @@ -399,7 +403,7 @@ To run just the markdown benchmarks: [GHC]: https://www.haskell.org/ghc/ [GitLab CI/CD]: https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/ [Haskell platform]: https://hackage.haskell.org/platform/ -[MacPorts]: https://trac.macports.org/browser/trunk/dports/textproc/pandoc/Portfile +[MacPorts]: https://ports.macports.org/port/pandoc/ [MacTeX]: https://tug.org/mactex/ [OpenBSD ports]: https://cvsweb.openbsd.org/ports/textproc/pandoc/ [BasicTeX]: https://www.tug.org/mactex/morepackages.html diff --git a/MANUAL.txt b/MANUAL.txt index 6d90f7c409a8..39355c4242bd 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -1,7 +1,7 @@ --- title: Pandoc User's Guide author: John MacFarlane -date: September 9, 2024 +date: 2025-05-28 --- # Synopsis @@ -263,11 +263,13 @@ header when requesting a document from a URL: - `markdown_strict` (original unextended [Markdown]) - `mediawiki` ([MediaWiki markup]) - `man` ([roff man]) + - `mdoc` ([mdoc] manual page markup) - `muse` ([Muse]) - `native` (native Haskell) - - `odt` ([OpenOffice text document][ODT]) + - `odt` ([OpenDocument text document][ODT]) - `opml` ([OPML]) - `org` ([Emacs Org mode]) + - `pod` (Perl's [Plain Old Documentation]) - `ris` ([RIS] bibliography) - `rtf` ([Rich Text Format]) - `rst` ([reStructuredText]) @@ -337,9 +339,9 @@ header when requesting a document from a URL: - `ms` ([roff ms]) - `muse` ([Muse]) - `native` (native Haskell) - - `odt` ([OpenOffice text document][ODT]) + - `odt` ([OpenDocument text document][ODT]) - `opml` ([OPML]) - - `opendocument` ([OpenDocument]) + - `opendocument` ([OpenDocument XML]) - `org` ([Emacs Org mode]) - `pdf` ([PDF]) - `plain` (plain text) @@ -496,8 +498,9 @@ header when requesting a document from a URL: [txt2tags]: https://txt2tags.org [EPUB]: http://idpf.org/epub [OPML]: http://dev.opml.org/spec2.html -[OpenDocument]: http://opendocument.xml.org +[OpenDocument XML]: https://www.oasis-open.org/2021/06/16/opendocument-v1-3-oasis-standard-published/ [ODT]: https://en.wikipedia.org/wiki/OpenDocument +[Plain Old Documentation]: https://perldoc.perl.org/perlpod [Textile]: https://textile-lang.com [MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting [DokuWiki markup]: https://www.dokuwiki.org/dokuwiki @@ -535,6 +538,7 @@ header when requesting a document from a URL: [Markua]: https://leanpub.com/markua/read [EndNote XML bibliography]: https://support.clarivate.com/Endnote/s/article/EndNote-XML-Document-Type-Definition [typst]: https://typst.app +[mdoc]: https://mandoc.bsd.lv/man/mdoc.7.html ## Reader options {.options} @@ -759,20 +763,42 @@ header when requesting a document from a URL: `--template=`*FILE*|*URL* : Use the specified file as a custom template for the generated document. - Implies `--standalone`. See [Templates], below, for a description - of template syntax. If no extension is specified, an extension - corresponding to the writer will be added, so that `--template=special` - looks for `special.html` for HTML output. If the template is not - found, pandoc will search for it in the `templates` subdirectory of - the user data directory (see `--data-dir`). If this option is not used, - a default template appropriate for the output format will be used (see - `-D/--print-default-template`). - -`-V` *KEY*[`=`*VAL*], `--variable=`*KEY*[`:`*VAL*] - -: Set the template variable *KEY* to the value *VAL* when rendering the - document in standalone mode. If no *VAL* is specified, the - key will be given the value `true`. + Implies `--standalone`. See [Templates], below, for a + description of template syntax. If the template is not found, + pandoc will search for it in the `templates` subdirectory of + the user data directory (see `--data-dir`). If no extension + is specified and an extensionless template is not found, + pandoc will look for a template with an extension + corresponding to the writer, so that `--template=special` + looks for `special.html` for HTML output. If this option is + not used, a default template appropriate for the output + format will be used (see `-D/--print-default-template`). + +`-V` *KEY*[`=`*VAL*], `--variable=`*KEY*[`=`*VAL*] + +: Set the template variable *KEY* to the string value *VAL* when rendering + the document in standalone mode. Either `:` or `=` may be used + to separate *KEY* from *VAL*. If no *VAL* is specified, the + key will be given the value `true`. Structured values (lists, maps) + cannot be assigned using this option, but they can be assigned in + the `variables` section of a [defaults file][Defaults files] or + using the `--variable-json` option. If the variable already has + a *list* value, the value will be added to the list. If it already + has another kind of value, it will be made into a list containing + the previous and the new value. For example, + `-V keyword=Joe -V author=Sue` makes `author` contain a list + of strings: `Joe` and `Sue`. + +`--variable-json=`*KEY*[`=`:*JSON*] + +: Set the template variable *KEY* to the value specified by a JSON + string (this may be a boolean, a string, a list, or a mapping; + a number will be treated as a string). For example, + `--variable-json foo=false` will give `foo` the boolean false + value, while `--variable-json foo='"false"'` will give it the + string value `"false"`. Either `:` or `=` may be used to + separate *KEY* from *VAL*. If the variable already has a + value, this value will be replaced. `--sandbox[=true|false]` @@ -857,11 +883,14 @@ header when requesting a document from a URL: unless `-s/--standalone` is used, and it has no effect on `man`, `docbook4`, `docbook5`, or `jats` output. - Note that if you are producing a PDF via `ms`, the table + Note that if you are producing a PDF via `ms` and using + (the default) `pdfroff` as a `--pdf-engine`, the table of contents will appear at the beginning of the document, before the title. If you would prefer it to be at the end of the document, use the option - `--pdf-engine-opt=--no-toc-relocation`. + `--pdf-engine-opt=--no-toc-relocation`. If `groff` is + used as the `--pdf-engine`, the table of contents will + always appear at the end of the document. `--toc-depth=`*NUMBER* @@ -869,6 +898,22 @@ header when requesting a document from a URL: of contents. The default is 3 (which means that level-1, 2, and 3 headings will be listed in the contents). +`--lof[=true|false]`, `--list-of-figures[=true|false]` + +: Include an automatically generated list of figures (or, in + some formats, an instruction to create one) in the output + document. This option has no effect unless `-s/--standalone` + is used, and it only has an effect on `latex`, `context`, and + `docx` output. + +`--lot[=true|false]`, `--list-of-tables[=true|false]` + +: Include an automatically generated list of tables (or, in + some formats, an instruction to create one) in the output + document. This option has no effect unless `-s/--standalone` + is used, and it only has an effect on `latex`, `context`, and + `docx` output. + `--strip-comments[=true|false]` : Strip out HTML comments in the Markdown or Textile source, @@ -1085,7 +1130,7 @@ header when requesting a document from a URL: `--top-level-division=default`|`section`|`chapter`|`part` : Treat top-level headings as the given division type in - LaTeX, ConTeXt, DocBook, and TEI output. The hierarchy + LaTeX, ConTeXt, DocBook, and TEI output. The hierarchy order is part, chapter, then section; all headings are shifted such that the top-level heading becomes the specified type. The default behavior is to determine the @@ -1098,6 +1143,11 @@ header when requesting a document from a URL: headings to become `\part{..}`, while second-level headings remain as their default type. + In Docx output, this option adds section breaks before first-level + headings if `chapter` is selected, and before first- and second-level + headings if `part` is selected. Footnote numbers will restart + with each section break unless the reference doc modifies this. + `-N`, `--number-sections=[true|false]` : Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB @@ -1252,7 +1302,6 @@ header when requesting a document from a URL: Character styles: - Default Paragraph Font - - Body Text Char - Verbatim Char - Footnote Reference - Hyperlink @@ -1427,11 +1476,11 @@ header when requesting a document from a URL: : Use the specified engine when producing PDF output. Valid values are `pdflatex`, `lualatex`, `xelatex`, `latexmk`, `tectonic`, `wkhtmltopdf`, `weasyprint`, `pagedjs-cli`, - `prince`, `context`, `pdfroff`, and `typst`. If the engine is not in - your PATH, the full path of the engine may be specified here. - If this option is not specified, pandoc uses the following - defaults depending on the output format specified using - `-t/--to`: + `prince`, `context`, `groff`, `pdfroff`, and `typst`. + If the engine is not in your PATH, the full path of the engine + may be specified here. If this option is not specified, + pandoc uses the following defaults depending on the output + format specified using `-t/--to`: - `-t latex` or none: `pdflatex` (other options: `xelatex`, `lualatex`, `tectonic`, `latexmk`) @@ -1443,6 +1492,14 @@ header when requesting a document from a URL: - `-t ms`: `pdfroff` - `-t typst`: `typst` + This option is normally intended to be used when a PDF + file is specified as `-o/--output`. However, it may still + have an effect when other output formats are requested. + For example, `ms` output will include `.pdfhref` macros + only if a `--pdf-engine` is selected, and the macros will + be differently encoded depending on whether `groff` or + `pdfroff` is specified. + `--pdf-engine-opt=`*STRING* : Use the given string as a command-line argument to the `pdf-engine`. @@ -1476,11 +1533,10 @@ header when requesting a document from a URL: order they appear on the command line. For more information, see the section on [Citations]. - Note: if your target format is `markdown`, `org`, or `typst`, - you will need to disable the `citations` extension (e.g., `-t - markdown-citations`) to see the rendered citations and - bibliography. Otherwise the format's own citation syntax will - be used. + Note: if this option is specified, the `citations` extension + will be disabled automatically in the writer, to ensure that + the citeproc-generated citations will be rendered instead of + the format's own citation syntax. `--bibliography=`*FILE* @@ -2026,6 +2082,22 @@ To include the built-in citeproc filter, use either `citeproc` or | ``` | ``` | +----------------------------------+-----------------------------------+ | ``` | ``` yaml | +| --list-of-figures | list-of-figures: true | +| ``` | ``` | ++----------------------------------+-----------------------------------+ +| ``` | ``` yaml | +| --lof | lof: true | +| ``` | ``` | ++----------------------------------+-----------------------------------+ +| ``` | ``` yaml | +| --list-of-tables | list-of-tables: true | +| ``` | ``` | ++----------------------------------+-----------------------------------+ +| ``` | ``` yaml | +| --lot | lot: true | +| ``` | ``` | ++----------------------------------+-----------------------------------+ +| ``` | ``` yaml | | --incremental | incremental: true | | ``` | ``` | +----------------------------------+-----------------------------------+ @@ -2209,14 +2281,19 @@ the system default templates for a given output format *FORMAT* by putting a file `templates/default.*FORMAT*` in the user data directory (see `--data-dir`, above). *Exceptions:* -- For `odt` output, customize the `default.opendocument` - template. +- For `odt` output, customize the `default.opendocument` template. +- For `docx` output, customize the `default.openxml` template. - For `pdf` output, customize the `default.latex` template (or the `default.context` template, if you use `-t context`, or the `default.ms` template, if you use `-t ms`, or the `default.html` template, if you use `-t html`). -- `docx` and `pptx` have no template (however, you can use - `--reference-doc` to customize the output). +- `pptx` has no template. + +Note that `docx`, `odt`, and `pptx` output can also be customized +using `--reference-doc`. Use a reference doc to adjust the styles +in your document; use a template to handle variable interpolation and +customize the presentation of metadata, the position of the table +of contents, boilerplate text, etc. Templates contain *variables*, which allow for the inclusion of arbitrary information at any point in the file. They may be set at the @@ -2457,9 +2534,9 @@ in square brackets, immediately after the variable name or partial: ``` -${months[, ]}$ +${months[, ]} -${articles:bibentry()[; ]$ +${articles:bibentry()[; ]} ``` The separator in this case is literal and (unlike with `sep` @@ -2770,7 +2847,7 @@ ODT or pptx. which is preferred to be unitless. `maxwidth` -: sets the CSS `max-width` property (default is 32em). +: sets the CSS `max-width` property (default is 36em). `backgroundcolor` : sets the CSS `background-color` property on the `html` element. @@ -2817,7 +2894,7 @@ pandoc](#slide-shows). `revealjs-url` : base URL for reveal.js documents (defaults to - `https://unpkg.com/reveal.js@^4/`) + `https://unpkg.com/reveal.js@^5`) `s5-url` : base URL for S5 documents (defaults to `s5/default`) @@ -2866,15 +2943,19 @@ These variables change the appearance of PDF slides using [`beamer`]. `theme`, `colortheme`, `fonttheme`, `innertheme`, `outertheme` : beamer themes -`themeoptions` -: options for LaTeX beamer themes (a list). +`themeoptions`, `colorthemeoptions`, `fontthemeoptions`, `innerthemeoptions`, `outerthemeoptions` +: options for LaTeX beamer themes (lists) `titlegraphic` -: image for title slide +: image for title slide: can be a list `titlegraphicoptions` : options for title slide image +`shorttitle`, `shortsubtitle`, `shortauthor`, `shortinstitute`, `shortdate` +: some beamer themes use short versions of the title, subtitle, author, + institute, date + ### Variables for PowerPoint These variables control the visual aspects of a slide show that @@ -2974,12 +3055,28 @@ Pandoc uses these variables when [creating a PDF] with a LaTeX engine. or `numbersections` variable) `beamerarticle` -: produce an article from Beamer slides +: produce an article from Beamer slides. Note: if you set + this variable, you must specify the beamer writer but use the + default *LaTeX* template: for example, + `pandoc -Vbeamerarticle -t beamer --template default.latex`. `handout` : produce a handout version of Beamer slides (with overlays condensed into single slides) +`csquotes` +: load `csquotes` package and use `\enquote` or `\enquote*` for quoted text. + +`csquotesoptions` +: options to use for `csquotes` package (repeat for multiple options). + +`babeloptions` +: options to pass to the babel package (may be repeated for + multiple options). This defaults to `provide=*` if the main + language isn't a European language written with Latin or + Cyrillic script or Vietnamese. Most users will not need to + adjust the default setting. + #### Fonts `fontenc` @@ -3078,7 +3175,8 @@ Pandoc uses these variables when [creating a PDF] with a LaTeX engine. #### Front matter `lof`, `lot` -: include list of figures, list of tables +: include list of figures, list of tables (can also be set using + `--lof/--list-of-figures`, `--lot/--list-of-tables`) `thanks` : contents of acknowledgments footnote after document title @@ -3267,6 +3365,9 @@ The `--css` option also affects the output. ### Variables for Typst +`template` +: Typst template to use. + `margin` : A dictionary with the fields defined in the Typst documentation: `x`, `y`, `top`, `bottom`, `left`, `right`. @@ -3283,6 +3384,10 @@ The `--css` option also affects the output. `section-numbering` : Schema to use for numbering sections, e.g. `1.A.1`. +`page-numbering` +: Schema to use for numbering pages, e.g. `1` or `i`, or + an empty string to omit page numbering. + `columns` : Number of columns for body text. @@ -3366,6 +3471,10 @@ on the output format, and include the following: If you need absolute paths, use e.g. `$curdir$/$sourcefile$`. +`pdf-engine` +: name of PDF engine if provided using `--pdf-engine`, or the + default engine for the format if PDF output is requested. + `curdir` : working directory from which pandoc is run. @@ -3696,11 +3805,14 @@ output formats ### Extension: `styles` ### {#ext-styles} -When converting from docx, read all docx styles as divs (for -paragraph styles) and spans (for character styles) regardless -of whether pandoc understands the meaning of these styles. -This can be used with [docx custom styles](#custom-styles). -Disabled by default. +When converting from docx, add `custom-styles` attributes +for all docx styles, regardless of whether pandoc understands +the meanings of these styles. Because attributes cannot be +added directly to paragraphs or text in the pandoc AST, +paragraph styles will cause Divs to be created and character +styles will cause Spans to be created to hold the attributes. +(Table styles will be added to the Table elements directly.) +This extension can be used with [docx custom styles](#custom-styles). input formats : `docx` @@ -3774,7 +3886,6 @@ additional markers for paragraphs and alternative markup for emphasized text. The `emphasis-command` template variable is set if the extension is enabled. - # Pandoc's Markdown Pandoc understands an extended and slightly revised version of @@ -4391,9 +4502,6 @@ definition: ~ Definition 2b Note that space between items in a definition list is required. -(A variant that loosens this requirement, but disallows "lazy" -hard wrapping, can be activated with the [`compact_definition_lists` -extension][Extension: `compact_definition_lists`].) [^3]: I have been influenced by the suggestions of [David Wheeler](https://justatheory.com/2009/02/modest-markdown-proposal/). @@ -4750,7 +4858,7 @@ If the file begins with a title block it will be parsed as bibliographic information, not regular text. (It will be used, for example, in the title of standalone LaTeX or HTML -output.) The block may contain just a title, a title and an author, +output.) The block may contain just a title, a date and an author, or all three elements. If you want to include an author but no title, or a title and a date but no author, you need a blank line: @@ -5974,6 +6082,9 @@ Supports [GitHub-style Markdown alerts], like [GitHub-style Markdown alerts]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts +Note: This extension currently only works with commonmark: +`commonmark`, `gfm`, `commonmark_x`. + ### Extension: `autolink_bare_uris` ### Makes all absolute URIs into links, even when not surrounded by @@ -5995,33 +6106,6 @@ and image references. This extension should not be confused with the Parses MultiMarkdown-style heading identifiers (in square brackets, after the heading but before any trailing `#`s in an ATX heading). -### Extension: `compact_definition_lists` ### - -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: - - - No blank line is required between consecutive items of the - definition list. - - To get a "tight" or "compact" list, omit space between consecutive - items; the space between a term and its definition does not affect - anything. - - Lazy wrapping of paragraphs is not allowed: the entire definition must - be indented four spaces.[^6] - -[^6]: To see why laziness is incompatible with relaxing the requirement - of a blank line between items, consider the following example: - - bar - : definition - foo - : definition - - Is this a single list item with two definitions of "bar," the first of - which is lazily wrapped, or two list items? To remove the ambiguity - we must either disallow lazy wrapping or require a blank line between - list items. - ### Extension: `gutenberg` ### Use [Project Gutenberg] conventions for `plain` output: @@ -6876,9 +6960,14 @@ Slide 2 has a special image for its background, even though the heading has no c ## EPUB Metadata -EPUB metadata may be specified using the `--epub-metadata` option, but -if the source document is Markdown, it is better to use a [YAML metadata -block][Extension: `yaml_metadata_block`]. Here is an example: +There are two ways to specify metadata for an EPUB. The first is to use +the `--epub-metadata` option, which takes as its argument an XML file +with [Dublin Core elements]. + +The second way is to use YAML, either in a +[YAML metadata block][Extension: `yaml_metadata_block`] in a Markdown +document, or in a separate YAML file specified with `--metadata-file`. +Here is an example of a YAML metadata block with EPUB metadata: --- title: @@ -7262,7 +7351,7 @@ use `--print-highlight-style` to generate a JSON `.theme` file which can be modified and used as the argument to `--highlight-style`. To get a JSON version of the `pygments` style, for example: - pandoc --print-highlight-style pygments > my.theme + pandoc -o my.theme --print-highlight-style pygments Then edit `my.theme` and use it like this: @@ -7275,6 +7364,9 @@ file](https://docs.kde.org/stable5/en/kate/katepart/highlight.html). Before writing your own, have a look at KDE's [repository of syntax definitions](https://github.com/KDE/syntax-highlighting/tree/master/data/syntax). +If you receive an error that pandoc "Could not read highlighting theme", +check that the JSON file is encoded with UTF-8 and has no Byte-Order Mark (BOM). + To disable highlighting, use the `--no-highlight` option. [skylighting]: https://github.com/jgm/skylighting @@ -7293,11 +7385,11 @@ However, if you need to apply your own styles to blocks, or match a preexisting set of styles, pandoc allows you to define custom styles for blocks and text using `div`s and `span`s, respectively. -If you define a `div` or `span` with the attribute `custom-style`, -pandoc will apply your specified style to the contained elements (with -the exception of elements whose function depends on a style, like -headings, code blocks, block quotes, or links). So, for example, using -the `bracketed_spans` syntax, +If you define a Div, Span, or Table with the attribute +`custom-style`, pandoc will apply your specified style to the +contained elements (with the exception of elements whose function +depends on a style, like headings, code blocks, block quotes, or +links). So, for example, using the `bracketed_spans` syntax, [Get out]{custom-style="Emphatically"}, he said. @@ -7339,9 +7431,10 @@ interpreting the derivation of the input document's styles. By enabling the [`styles` extension](#ext-styles) in the docx reader (`-f docx+styles`), you can produce output that maintains the styles -of the input document, using the `custom-style` class. Paragraph -styles are interpreted as divs, while character styles are interpreted -as spans. +of the input document, using the `custom-style` class. A `custom-style` +attribute will be added for each style. Divs will be created to +hold the paragraph styles, and Spans to hold the character styles. +Table styles will be applied directly to the Table. For example, using the `custom-style-reference.docx` file in the test directory, we have the following different outputs: @@ -7467,10 +7560,9 @@ ConTeXt always produces tagged PDFs, but the quality depends on the input. The default ConTeXt markup generated by pandoc is optimized for readability and reuse, not tagging. Enable the [`tagging`](#extension--tagging) format extension to force markup -that is optimized for tagging. This can be combined with the -`pdfa` variable to generate standard-compliant PDFs. E.g.: +that is optimized for tagging. For example: - pandoc --to=context+tagging -V pdfa=3a + pandoc -t context+tagging doc.md -o doc.pdf A recent `context` version should be used, as older versions contained a bug that lead to invalid PDF metadata. @@ -7496,6 +7588,12 @@ for various PDF standards as well as tagging. E.g.: See the prince documentation for more info. +## Typst + +Typst 0.12 can produce PDF/A-2b: + + pandoc --pdf-engine=typst --pdf-engine-opt=--pdf-standard=a-2b ... + ## Word Processors Word processors like LibreOffice and MS Word can also be used to @@ -7507,7 +7605,7 @@ See the documentation for [Word][word-accessible-pdfs] and [LibreOffice][lo-pdf-export]. [word-accessible-pdfs]: https://support.microsoft.com/en-us/office/create-accessible-pdfs-064625e0-56ea-4e16-ad71-3aa33bb4b7ed -[lo-pdf-export]: https://help.libreoffice.org/7.1/en-US/text/shared/01/ref_pdf_export_general.html +[lo-pdf-export]: https://help.libreoffice.org/latest/en-US/text/shared/01/ref_pdf_export_general.html # Running pandoc as a web server @@ -7534,7 +7632,10 @@ Calling the pandoc executable under the name `pandoc-lua` or with `lua` as the first argument will make it function as a standalone Lua interpreter. The behavior is mostly identical to that of the [standalone `lua` executable][lua standalone], version 5.4. -For full documentation, see the [pandoc-lua] man page. +All `pandoc.*` packages, as well as the packages `re` and `lpeg`, +are available via global variables. Furthermore, the globals +`PANDOC_VERSION`, `PANDOC_STATE`, and `PANDOC_API_VERSION` are +set at startup. For full documentation, see the [pandoc-lua] man page. [lua standalone]: https://www.lua.org/manual/5.4/manual.html#7 [pandoc-lua]: https://github.com/jgm/pandoc/blob/master/doc/pandoc-lua.md @@ -7547,11 +7648,11 @@ For full documentation, see the [pandoc-lua] man page. writer could in principle do anything on your file system. Please audit filters and custom writers very carefully before using them. -2. Several input formats (including HTML, Org, and RST) support `include` - 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 `--sandbox` option can - protect against this threat.) +2. Several input formats (including LaTeX, Org, RST, and Typst) + support `include` 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 + `--sandbox` option can protect against this threat.) 3. Several output formats (including RTF, FB2, HTML with `--self-contained`, EPUB, Docx, and ODT) will embed encoded @@ -7561,7 +7662,16 @@ For full documentation, see the [pandoc-lua] man page. against this threat, but will also prevent including images in these formats.) -4. If your application uses pandoc as a Haskell library (rather than +4. In reading HTML files, pandoc will attempt to include the + contents of `iframe` elements by fetching content from the + local file or URL specified by `src`. 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 html+raw_html` + will mitigate this threat by causing the whole `iframe` + to be parsed as a raw HTML block. Using `--sandbox will also + protect against the threat. + +5. 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 `PandocPure` monad. See the document @@ -7569,7 +7679,7 @@ For full documentation, see the [pandoc-lua] man page. for more details. (This corresponds to the use of the `--sandbox` option on the command line.) -5. Pandoc's parsers can exhibit pathological performance on some +6. Pandoc's parsers can exhibit pathological performance on some corner cases. It is wise to put any pandoc operations under a timeout, to avoid DOS attacks that exploit these issues. If you are using the pandoc executable, you can add the @@ -7579,7 +7689,7 @@ For full documentation, see the [pandoc-lua] man page. to pathological performance than the `markdown` parser, so it is a better choice when processing untrusted input. -6. The HTML generated by pandoc is not guaranteed to be safe. +7. The HTML generated by pandoc is not guaranteed to be safe. If `raw_html` is enabled for the Markdown input, users can inject arbitrary HTML. Even if `raw_html` is disabled, users can include dangerous content in URLs and attributes. diff --git a/Makefile b/Makefile index e8742a0f10a4..7c6b2bc17937 100644 --- a/Makefile +++ b/Makefile @@ -1,8 +1,8 @@ -version?=$(shell grep '^[Vv]ersion:' pandoc.cabal | awk '{print $$2;}') -pandoc-cli-version?=$(shell grep '^[Vv]ersion:' pandoc-cli/pandoc-cli.cabal | awk '{print $$2;}') +VERSION?=$(shell grep '^[Vv]ersion:' pandoc.cabal | awk '{print $$2;}') +PANDOC_CLI_VERSION?=$(shell grep '^[Vv]ersion:' pandoc-cli/pandoc-cli.cabal | awk '{print $$2;}') SOURCEFILES?=$(shell git ls-tree -r main --name-only src pandoc-cli pandoc-server pandoc-lua-engine | grep "\.hs$$") PANDOCSOURCEFILES?=$(shell git ls-tree -r main --name-only src | grep "\.hs$$") -DOCKERIMAGE=quay.io/benz0li/ghc-musl:9.6 +DOCKERIMAGE=quay.io/benz0li/ghc-musl:9.8 TIMESTAMP=$(shell date "+%Y%m%d_%H%M") LATESTBENCH=$(word 1,$(shell ls -t bench_*.csv 2>/dev/null)) BASELINE?=$(LATESTBENCH) @@ -28,8 +28,12 @@ build: ## build executable $(CABALOPTS) pandoc-cli .PHONY: build +prof: ## build with profiling and optimizations + cabal build --enable-profiling all +.PHONY: prof + binpath: ## print path of built pandoc executable - @cabal list-bin $(CABALOPTS) --ghc-options='$(GHCOPTS)' pandoc-cli + @cabal list-bin -v0 $(CABALOPTS) --ghc-options='$(GHCOPTS)' pandoc-cli .PHONY: binpath ghcid: ## run ghcid @@ -69,12 +73,11 @@ uncommitted_changes: ! git diff | grep '.' .PHONY: uncommitted_changes -authors: ## prints unique authors since LASTRELEASE (version) - git log --pretty=format:"%an" $(LASTRELEASE)..HEAD | sort | uniq - +authors: ## prints unique authors since last released version + git log --pretty=format:"%an" $$(git tag -l | grep '[^0-9]' | sort | tail -1)..HEAD | sort | uniq | while read -r; do grep -i -q "^- $$REPLY" AUTHORS.md || echo $$REPLY ; done check-stack: - stack-lint-extra-deps # check that stack.yaml dependencies are up to date + $$HOME/.local/bin/stack-lint-extra-deps # check that stack.yaml dependencies are up to date ! grep 'git:' stack.yaml # use only released versions .PHONY: check-stack @@ -84,7 +87,7 @@ check-cabal: git-files.txt sdist-files.txt @for pkg in . pandoc-lua-engine pandoc-server pandoc-cli; \ do \ pushd $$pkg ; \ - cabal check ; \ + cabal check --ignore=missing-upper-bounds ; \ cabal outdated ; \ popd ; \ done @@ -94,26 +97,26 @@ check-cabal: git-files.txt sdist-files.txt check-version-sync: @echo "Checking for match between pandoc and pandoc-cli versions" - [ $(version) == $(pandoc-cli-version) ] + [ $(VERSION) == $(PANDOC_CLI_VERSION) ] @echo "Checking that pandoc-cli depends on this version of pandoc" - grep 'pandoc == $(version)' pandoc-cli/pandoc-cli.cabal + grep 'pandoc == $(VERSION)' pandoc-cli/pandoc-cli.cabal .PHONY: check-version-sync check-changelog: @echo "Checking for changelog entry for this version" - grep '## pandoc $(version) (\d\d\d\d-\d\d-\d\d)' changelog.md + rg '## pandoc $(VERSION) \(\d\d\d\d-\d\d-\d\d\)' changelog.md .PHONY: check-changelog check-manversion: @echo "Checking version number in man pages" - grep '"pandoc $(version)"' "pandoc-cli/man/pandoc.1" - grep '"pandoc $(version)"' "pandoc-cli/man/pandoc-server.1" - grep '"pandoc $(version)"' "pandoc-cli/man/pandoc-lua.1" + grep '"pandoc $(VERSION)"' "pandoc-cli/man/pandoc.1" + grep '"pandoc $(VERSION)"' "pandoc-cli/man/pandoc-server.1" + grep '"pandoc $(VERSION)"' "pandoc-cli/man/pandoc-lua.1" .PHONY: check-manversion checkdocs: @echo "Checking for tabs in manual." - ! grep -q -n -e "\t" \ + ! rg -n -e '\t' \ MANUAL.txt changelog.md doc/pandoc-server.md doc/pandoc-lua.md .PHONY: checkdocs @@ -134,14 +137,14 @@ fix_spacing: ## fix trailing newlines and spaces .PHONY: fix_spacing changes_github: ## copy this release's changes in gfm - $(pandoc) --lua-filter tools/extract-changes.lua changelog.md -t gfm --wrap=none --template tools/changes_template.html | sed -e 's/\\#/#/g' | pbcopy + @$(pandoc) --lua-filter tools/extract-changes.lua changelog.md -t gfm --wrap=none --template tools/changes_template.html | sed -e 's/\\#/#/g' .PHONY: changes_github man: pandoc-cli/man/pandoc.1 pandoc-cli/man/pandoc-server.1 pandoc-cli/man/pandoc-lua.1 ## build man pages .PHONY: man latex-package-dependencies: ## print packages used by default latex template - $(pandoc) lua tools=latex-package-dependencies.lua + $(pandoc) lua tools/latex-package-dependencies.lua .PHONY: latex-package-dependencies coverage: ## code coverage information @@ -185,7 +188,7 @@ pandoc-cli/man/pandoc.1: MANUAL.txt man/pandoc.1.before man/pandoc.1.after pando --variable section="1" \ --variable title="pandoc" \ --variable header='Pandoc User\[cq]s Guide' \ - --variable footer="pandoc $(version)" \ + --variable footer="pandoc $(VERSION)" \ -o $@ pandoc-cli/man/%.1: doc/%.md pandoc.cabal @@ -195,7 +198,7 @@ pandoc-cli/man/%.1: doc/%.md pandoc.cabal --variable section="1" \ --variable title="$(basename $(notdir $@))" \ --variable header='Pandoc User\[cq]s Guide' \ - --variable footer="pandoc $(version)" \ + --variable footer="pandoc $(VERSION)" \ --include-after-body man/pandoc.1.after \ -o $@ @@ -224,7 +227,7 @@ pandoc-templates: ## update pandoc-templates repo cp data/templates/* ../pandoc-templates/ ; \ pushd ../pandoc-templates/ && \ git add * && \ - git commit -m "Updated templates for pandoc $(version)" && \ + git commit -m "Updated templates for pandoc $(VERSION)" && \ popd .PHONY: pandoc-templates @@ -248,16 +251,18 @@ validate-docx-golden-tests: ## validate docx golden tests against schema validate-docx-golden-tests2: ## validate docx golden tests using OOXMLValidator which dotnet || ("dotnet is required" && exit 1) - which json_reformat || ("json_reformat is required" && exit 1) + which jq || ("jq is required" && exit 1) test -d ./OOXML-Validator || \ (git clone https://github.com/mikeebowen/OOXML-Validator.git \ && cd OOXML-Validator && dotnet build --configuration=Release) sh ./tools/validate-docx2.sh test/docx/golden/ .PHONY: validate-docx-golden-tests2 -validate-epub: ## generate an epub and validate it with epubcheck and ace +node_modules/.bin/ace: + npm install @daisy/ace + +validate-epub: node_modules/.bin/ace ## generate an epub and validate it with epubcheck and ace which epubcheck || exit 1 - which ace || exit 1 tmp=$$(mktemp -d) && \ for epubver in 2 3; do \ file=$$tmp/ver$$epubver.epub ; \ @@ -265,7 +270,7 @@ validate-epub: ## generate an epub and validate it with epubcheck and ace echo $$file && \ epubcheck $$file || exit 1 ; \ done && \ - ace $$tmp/ver3.epub -o ace-report-v2 --force + ./node_modules/.bin/ace $$tmp/ver3.epub -o ace-report-v2 --force modules.csv: $(PANDOCSOURCEFILES) @rg '^import.*Text\.Pandoc\.' --with-filename $^ \ @@ -291,7 +296,7 @@ modules.pdf: modules.dot # make moduledeps ROOT=Text.Pandoc.Parsing moduledeps: modules.csv ## Print transitive dependencies of a module ROOT @echo "$(ROOT)" - @lua tools/moduledeps.lua transitive $(ROOT) | sort + @$(pandoc) lua tools/moduledeps.lua transitive $(ROOT) | sort .PHONY: moduledeps clean: ## clean up @@ -301,10 +306,10 @@ clean: ## clean up .PHONY: .FORCE sdist-files.txt: .FORCE - cabal sdist --list-only | sed 's/\.\///' | grep '^\(test\|data\)\/' | sort > $@ + cabal sdist --list-only | sed 's/\.\///' | grep '^\(test\|data\)/' | sort > $@ git-files.txt: .FORCE - git ls-tree -r --name-only HEAD | grep '^\(test\|data\)\/' | sort > $@ + git ls-tree -r --name-only HEAD | grep '^\(test\|data\)/' | sort > $@ help: ## display this help @echo "Targets:" @@ -318,6 +323,12 @@ help: ## display this help @printf "%-16s%s\n" "REVISION" "$(REVISION)" .PHONY: help +release-checklist: release-checklist-$(VERSION).org +.PHONY: release-checklist + +release-checklist-$(VERSION).org: RELEASE-CHECKLIST-TEMPLATE.org + sed -e 's/RELEASE_VERSION/$(VERSION)/g' $< > $@ + hie.yaml: ## regenerate hie.yaml gen-hie > $@ .PHONY: hie.yaml diff --git a/README.md b/README.md index ab560ce0e98a..20e97e8acc31 100644 --- a/README.md +++ b/README.md @@ -81,12 +81,16 @@ It can convert *from* - `mediawiki` ([MediaWiki markup](https://www.mediawiki.org/wiki/Help:Formatting)) - `man` ([roff man](https://man.cx/groff_man(7))) +- `mdoc` ([mdoc](https://mandoc.bsd.lv/man/mdoc.7.html) manual page + markup) - `muse` ([Muse](https://amusewiki.org/library/manual)) - `native` (native Haskell) -- `odt` ([OpenOffice text +- `odt` ([OpenDocument text document](https://en.wikipedia.org/wiki/OpenDocument)) - `opml` ([OPML](http://dev.opml.org/spec2.html)) - `org` ([Emacs Org mode](https://orgmode.org)) +- `pod` (Perl’s [Plain Old + Documentation](https://perldoc.perl.org/perlpod)) - `ris` ([RIS](https://en.wikipedia.org/wiki/RIS_(file_format)) bibliography) - `rtf` ([Rich Text @@ -183,10 +187,11 @@ It can convert *to* - `ms` ([roff ms](https://man.cx/groff_ms(7))) - `muse` ([Muse](https://amusewiki.org/library/manual)) - `native` (native Haskell) -- `odt` ([OpenOffice text +- `odt` ([OpenDocument text document](https://en.wikipedia.org/wiki/OpenDocument)) - `opml` ([OPML](http://dev.opml.org/spec2.html)) -- `opendocument` ([OpenDocument](http://opendocument.xml.org)) +- `opendocument` ([OpenDocument + XML](https://www.oasis-open.org/2021/06/16/opendocument-v1-3-oasis-standard-published/)) - `org` ([Emacs Org mode](https://orgmode.org)) - `pdf` ([PDF](https://www.adobe.com/pdf/)) - `plain` (plain text) diff --git a/RELEASE-CHECKLIST b/RELEASE-CHECKLIST deleted file mode 100644 index ed737720f828..000000000000 --- a/RELEASE-CHECKLIST +++ /dev/null @@ -1,34 +0,0 @@ -[ ] Bump version number for pandoc and pandoc-cli -[ ] Sync pandoc version in pandoc-cli -[ ] Update MANUAL.txt date -[ ] Finalize changelog -[ ] make prerelease -[ ] Update AUTHORS (make authors LASTRELEASE=x.y.z) -[ ] Run release candidate workflow manually on GitHub -[ ] Run release candidate workflows manually on cirrus-ci.com -[ ] If it builds successfully, download artifacts from GitHub, cirrus-ci.com - (Windows and intel mac from GitHub, linux amd64 and arm64 and m1 mac - from cirrus) -[ ] Use 'make' in macos and windows artifacts to sign code -[ ] make update-website -[ ] Tag release in git: - - use X.Y for pandoc - - pandoc-cli-X.Y - - if needed: pandoc-server-X.Y - - if needed: pandoc-lua-engine-X.Y -[ ] Upload packages to Hackage: - - pandoc - - pandoc-cli - and if changed: - - pandoc-server - - pandoc-lua-engine -[ ] make pandoc-templates - cd ../pandoc-templates - git tag REL - git push - git push --tags -[ ] Add release on github (use 'make changes_github' and upload files) -[ ] Copy deb to server, install it -[ ] If needed, sh tools/build-and-upload-api-docs.sh -[ ] Announce on pandoc-announce, pandoc-discuss - diff --git a/RELEASE-CHECKLIST-TEMPLATE.org b/RELEASE-CHECKLIST-TEMPLATE.org new file mode 100644 index 000000000000..6c61f129bac4 --- /dev/null +++ b/RELEASE-CHECKLIST-TEMPLATE.org @@ -0,0 +1,122 @@ +#+STARTUP: content +** pandoc RELEASE_VERSION release checklist +*** TODO Check [[https://github.com/jgm/pandoc/issues?q=state%3Aopen%20label%3A%22priority%3Ahigh%22%20][priority-high]] tag +*** TODO Release any prerelease packages in [[./cabal.project]] +*** TODO [[./pandoc.cabal]] - bump version number +*** TODO [[./pandoc-cli/pandoc-cli.cabal]] - bump version, sync pandoc version +#+begin_src sh +git log $(git describe --tags --abbrev=0)..HEAD --oneline pandoc-cli +#+end_src +*** TODO [[./pandoc-lua-engine/pandoc-lua-engine.cabal]] - bump version? +#+begin_src sh +git log $(git describe --tags --abbrev=0)..HEAD --oneline pandoc-lua-engine +#+end_src +*** TODO [[./pandoc-server/pandoc-server.cabal]] - bump version? +#+begin_src sh +git log $(git describe --tags --abbrev=0)..HEAD --oneline pandoc-server +#+end_src +*** TODO Update [[./MANUAL.txt]] date and rebuild man pages +#+begin_src sh :results silent +NEWDATE=$(date -I) +sed -i '' -e "/^---$/,/^---$/s/^date:.*$/date: $NEWDATE/" MANUAL.txt +make man +#+end_src +*** TODO Finalize [[./changelog.md]] +#+begin_src sh :results output file :file LOG.md +git log $(git describe --tags --abbrev=0)..HEAD --mailmap --reverse --format=format:' * %s%n %aN%n%w(78,4,4)%b' | sed -e '/^ *John MacFarlane$/d' | sed -e 's/ *$//' +#+end_src +*** TODO prerelease checks +#+begin_src sh :results output verbatim +make prerelease +#+end_src +*** TODO Update [[./AUTHORS.md]] +#+begin_src sh :results output list org +make authors +#+end_src +*** TODO Run [[https://github.com/jgm/pandoc/actions/workflows/release-candidate.yml][release candidate workflow]] on GitHub + #+begin_src sh :var ghtoken=(jgm-authinfo-get "api.github.com" "jgm_pandoc_release") +curl -L \ + -X POST \ + -H "Accept: application/vnd.github+json" \ + -H "Authorization: Bearer $ghtoken"\ + -H "X-GitHub-Api-Version: 2022-11-28" \ +https://api.github.com/repos/jgm/pandoc/actions/workflows/release-candidate.yml/dispatches \ + -d '{"ref":"main"}' + #+end_src +*** TODO Run [[https://cirrus-ci.com][release candidate workflows]] manually on cirrus-ci.com +*** TODO If it builds successfully, download artifacts from GitHub, cirrus-ci.com + (Windows and intel mac from GitHub, linux amd64 and arm64 and m1 mac + from cirrus) +*** TODO Use 'make' in macos and windows artifacts to sign code +*** TODO Update website +#+begin_src sh +make update-website +#+end_src +*** TODO Tag release in git: + - use X.Y for pandoc + - pandoc-cli-X.Y + - if needed: pandoc-server-X.Y + - if needed: pandoc-lua-engine-X.Y +*** TODO Upload packages to Hackage: +#+NAME: changed-packages +#+begin_src sh :results silent +echo pandoc +echo pandoc-cli +for package in pandoc-lua-engine pandoc-server; do + lines=$(git log $(git describe --tags --abbrev=0)..HEAD --oneline $package | wc -l) + if ! [ $lines -eq 0 ]; then + echo $package; + fi +done +#+end_src + + - pandoc + - pandoc-cli + and if changed: + - pandoc-server + - pandoc-lua-engine +*** TODO make pandoc-templates +#+begin_src sh +make pandoc-templates +pushd ~/src/pandoc-templates +git tag RELEASE_VERSION +git push +git push --tags +popd +#+end_src +*** TODO Copy binary to server, install it +#+begin_src +# example: +cd 3.7 +tar xvzf pandoc-3.7-linux-amd64.tar.gz +scp pandoc-3.7/bin/pandoc website:cgi-bin/pandoc-server.cgi +#+end_src + +*** TODO create release announcement and add to GH release announcement +#+NAME: relann +#+begin_src elisp :results value file :file relann-RELEASE_VERSION +"I'm pleased to announce the release of pandoc RELEASE_VERSION, +available in the usual places: + +Binary packages & changelog: +https://github.com/jgm/pandoc/releases/tag/RELEASE_VERSION + +Source & API documentation: +http://hackage.haskell.org/package/pandoc-RELEASE_VERSION + +Description of release. + +Any API changes. + +Thanks to all who contributed, especially new contributors ... +" +#+end_src +*** TODO Add [[https://github.com/jgm/pandoc/releases/][release on GitHub]] +#+begin_src sh :var announcement=relann :results output literal +echo '```' +cat $announcement +echo '```' +echo '' +make changes_github +#+end_src +*** TODO Announce on [[mailto:pandoc-announce@googlegroups.com][pandoc-announce]] diff --git a/cabal.project b/cabal.project index d810241ed92e..708f2a847328 100644 --- a/cabal.project +++ b/cabal.project @@ -4,6 +4,14 @@ packages: . pandoc-cli tests: True flags: +embed_data_files -constraints: skylighting-format-blaze-html >= 0.1.1.2, - skylighting-format-context >= 0.1.0.2 +constraints: skylighting-format-blaze-html >= 0.1.1.3, + skylighting-format-context >= 0.1.0.2, + -- for now (commercialhaskell/stackage#7545): + data-default-class <= 0.2, data-default <= 0.8 +source-repository-package + type: git + location: https://github.com/jgm/citeproc.git + tag: 157c7815f06e4e6771740a4eb8df97568626a8fe + +-- TODO: release new skylighting-core, skylighting diff --git a/changelog.md b/changelog.md index c974e15bcc00..005d4da4d9c9 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,1309 @@ # Revision history for pandoc +## pandoc 3.7.0.2 (2025-05-28) + + * RST writer: + + + Don't emit alignment markers in grid tables (#10857). + + * Asciidoc writer: + + + Add support for sidebars (GHyman83). + + * LaTeX writer: + + + Include alt option in `\includegraphics` (#6095). + + * Markdown writer: + + + Preserve figure attributes (Nikolay Yakimov, #10867). + Fixes a regression introduced by 0d2114e, which caused the + Markdown writer to ignore attributes on the figure if it + has class or key-value attributes set. + + * HTML writer: + + + Use the ID prefix in the ID for the footnotes section (Benjamin Esham). + + * Text.Pandoc.Writers.Shared: + + + `gridTable`: fix (3.7) regression with missing cell alignments (#10853). + + `gridTable`: fix headings with colspans (#10855). If the heading + contains a colspan, we still need to include information in the header + line about the colspecs. + + `gridTable`: fix headerless tables. The top line should encode + colspan information. + + * Text.Pandoc.SelfContained: + + + Fix handling of empty script element (#10862). Previously in this + case the closing tag was dropped. + + Do not drop `data-` attributes in script tags (#10861). + + * Lua subsystem (Albert Krewinkel): + + + Add function `pandoc.mediabag.make_data_uri` (#10876). + The function takes a MIME type and raw data from which it creates an + RFC 2397 data URI. + + * `tools/update-lua-module-docs`: fix handling of wikilinks + (Albert Krewinkel). + + * `doc/lua-filters.md`: add missing docs for `pandoc.Caption` + (Albert Krewinkel). + + * Require texmath 0.12.10.3, typst 0.8.0.1 + +## pandoc 3.7.0.1 (2025-05-17) + + * Text.Pandoc.Shared.Writer: Fix numerous problems with `gridTable` and add + tests (#10848). These fixes affect the Markdown, RST, and Muse writers. + + * Fix context writer/template to produce tagged PDFs (#10846). + As before, the `tagging` extension must be enabled. + We now add the command that tells ConTeXt to start tagging. + +## pandoc 3.7 (2025-05-14) + + * Add new command-line option `--variable-json` (#10341). + This allows non-string values (booleans, lists, maps) to be given to + template variables on the command line. + + * The `--pdf-engine` option can now take `groff` as a value. + + * Markdown writer: + + + Avoid spaces after/before open/close delimiters (#10696). + E.g. instead of rendering `x space y` as `x* space *y` we render + it as `x *space* y`. + + Handle row/colspans in grid tables, and expand cells when it isn't + possible to lay them out without breaking string of non-whitespace. + + Render a figure with Para caption as implicit figure (#10755). + + When falling back to a Div with class `figure` for a figure that + can't be represented any other way, include a Div with class + `caption` containing the caption. + + Improve use of implicit figures when possible (#10758). + When the alt differs from the caption, but only as regards formatting, we + still use an implicit figure. + + Omit initial newlines in gfm `math` blocks to avoid an ugly blank line. + * Support the `four_space_rule` extension for `plain` output (#10813, + Manolis Stamatogiannakis). + + * RST writer: + + + Handle row/colspans in grid tables, and expand cells when it isn't + possible to lay them out without breaking string of non-whitespace. + + * Muse writer: + + + Handle row/colspans in grid tables, and expand cells when it isn't + possible to lay them out without breaking string of non-whitespace. + + * JATS writer: + + + Fix escaping for writing-review-editing role (#10744). + + * HTML writer: + + + Remove trailing slash from default revealjs URL (#8749). This + avoids a double slash in the URL's path component. + + * LaTeX writer: + + + Make alignment work within `multirow` in tables (#10772). + + * Typst writer: + + + Support `mark` class on spans (#10747). + + Add equation label if math contains `\label{..}` (#10805). + + * Roff format writers (man, ms): + + + Use the most compatible form for roff escapes (#10716). + For example, `\(xy` instead of `\[xy]`. This was the original + AT&T troff form and is the most widely supported. The + bracketed form causes problem for some tools, e.g. + `makewhatis` on macOS. And emit `e` followed by an escape + for a unicode combining accent rather than the form `\[e aa]`, + which works for groff but not e.g. on macOS's man. + This change affects Text.Pandoc.RoffChar, + Text.Pandoc.Writers.Roff, and the Man and Ms writers. + + * Docx writer: + + + Ensure that figures and tables with custom styles are not dropped + (#10705). + + Preserve Relationships for images from reference docx (#10759). + This should allow one to include an image in a reference.docx and + reference it in an openxml template. + + Don't renumber rels (#10769). We used to renumber the + Relationships so they didn't conflict with the set of fixed + Relationships we imposed. We are now preserving the ids + from the reference doc's document.xml.refs, so we shouldn't + renumber them or references introduced by the user (e.g. in + a template) will fail. + + * Ms writer: + + + Improve PDF TOC labels. We now use the plain writer to render these, + so that Greek characters etc. will show up properly. + + When no `pdf-engine` variable is specified, do not use the + `.pdfhref` macros at all (#10738). This gives better results for links + in formats other than PDF, since the link text would simply + disappear if it exists only in a `.pdfhref` macro. When a PDF + engine is specified, escape the argument of `.pdfhref O` in a way + that is appropriate. + + * OpenDocument writer: + + + Fix character styles in footnotes (#10791). Character + styles governing the position of the footnote reference + should not be imposed on the footnote text. + + * Powerpoint writer: + + + Use reference-doc font for captions (#9896, R. N. West). + + * DocBook writer: + + + Use literallayout element for LineBlock (#10825). + + * MediaWiki reader/writer: + + + Allow definition on same line as term (#10708). + + * LaTeX reader: + + + Skip at most one argument to LaTeX tabular newline (#7512, + Evan Silberman). + + Disable ligatures inside `\texttt` (#10781). + + Support more symbol commands (#10782). + + * Commonmark Reader: + + + Handle GFM math irregularity with braces (#10631). In GFM, you need + to use `\\{` rather than `\{` for a literal brace. + + * DocBook reader: + + + Improve handling of literallayout (#10825). This is now only made + a CodeBlock when there is a `monospaced` class. Otherwise it is made + a LineBlock. + + * Org reader: + + + Add AVIF to Org Reader image extensions (#10736, Christian Christiansen). + + Don't include newlines in inine code/verbatim (#10730). + Convert newlines to spaces as we do in other formats. + + Change handling of inline TeX (#10836). Previously inline + TeX was handled in a way that was different from org's own export, + and that could lead to information loss. This was particularly noticeable + for inline math environments such as `equation`. Previously, an + `equation` environment starting at the beginning of a line would create + a raw block, splitting up the paragraph containing it (see + #10836). On the other hand, an `equation` environment not + at the beginning of a line would be turned into regular + inline elements representing the math. (This would cause + the equation number to go missing and in some cases degrade + the math formatting.) Now, we parse all of these as raw + "latex" inlines, which will be omitted when converting to + formats other than LaTeX (and other formats like pandoc's + Markdown that allow raw LaTex). + + * Beamer template: fix regression in 3.6.4, reverting the omission of + `\date` when the document does not have a date. By default, beamer + will display a date when no `\date` is present in the title block, + so this was an unintended behavior change. The reverted + change was motivated by the desire to include a custom + `\date` in the frontmatter via header-includes. This can be + achieved more simply by simply setting the `date` variable. + In markdown you can even use `date` in metadata and put some + raw LaTeX there. + + * Ms template: + + + Use T rather than P as default font family (#10738). + + Put PDF-specific things under a conditional. + Don't include them if `pdf-engine` isn't set. + + * Upgrade reveal.js URL to v5 (#10740, Kolen Cheung). + v4 is no longer available on unpkg.com. + + * Text.Pandoc.PDF: Allow `groff` to be used as `--pdf-engine` with `ms` + (#10738). When `groff` is used as a PDF engine, the `groff` + extension to `ms` is automatically enabled. Limitations: + + - `groff` currently produces larger PDFs than `pdfroff`. + - With `groff`, a table of contents produced with + `--table-of-contents/--toc` will always be placed at the end of + the document. + - Certain characters (e.g. Greek characters) may be dropped in + the PDF outline. + + * Text.Pandoc.Writers.Shared: + + + Export `delimited` [API change]. + + New version of `gridTable` (#6344) [API change]. This + handles row and colspans. It also ensures that cells won't + wrap text in places where it wouldn't normally wrap, even + if this means making the cells wider than requested by the + colspec (#9001, #7641). Because the parameters are + different, this is a breaking API change. + + * Text.Pandoc.App: set `pdf-engine` variable. + If `--pdf-engine` is specified or if a PDF is being produced, we set the + `pdf-engine` variable. This allows writers and templates to behave + differently depending on the PDF engine. + + * Text.Pandoc.Class and Text.Pandoc.URI: + + + Fix parsing of base64 data URIs to allow URI escapes and + whitespace (which will be ignored) (#10704). + + Handle percent encoding in `pBase64URI` instead of + unescaping later, for efficiency (#10704). + + * Text.Pandoc.Citeproc.BibTeX: + + + Recognize `en` as a `langid` in biblatex bibliographies (#10764). + + * Text.Pandoc.MIME: + + + Add mime type and extension for `avif` (#10704). + + Handle `apng`, `avif`, `jxl` (#10704). + + * Text.Pandoc.Readers.LaTeX.Math: export `inlineEnvironmentNames`. + Internal module, not a change to the public API. + + * `reference.docx` (Andrew Dunning): + + + Remove extra spaces around text placeholders. + + Add footnote block text sample. + + * Text.Pandoc.Class.Sandbox: + + + Add `sandboxWithFileTree` function [API change] (Albert Krewinkel). + + * Lua subsystem (Albert Krewinkel): + + + pandoc-lua-engine: add all test files to the cabal file. + + Allow `pandoc.read` to be called in "sandbox" mode for added + security (#10831). Readers running in a sandbox will not be + able to access the network or file system. The sandbox is + enabled if the fourth parameter is a list of files or + filename/content pairs. The files are read and then made + available in the sandbox via en ersatz file system. + + * Makefile: + + + Add target `release-checkist`. + + Install @daisy/ace from npm if not present. + + Use pandoc lua instead of lua. + + Fix typo in `latex-package-dependencies` target. + + Use `jq` instead of `json_reformat` in `validate-docx-golden-tests2`. + + * NiX infrastructure: new working `flake.nix` and simpler `shell.nix`. + Removed old `default.nix`. + + * Require random >= 1.3 and use `splitGen`. `split` has been deprecated. + + * Use citeproc-0.9. Bump citeproc bounds for pandoc, pandoc-lua-engine. + + * Use texmath-0.12.10.1. + + * Use released typst 0.8 (partially supporting typst 0.13). + + * Use citeproc 0.9.0.1. + + * MANUAL.txt: + + + Fix default URL for revealjs. + + Add note that `alerts` extension only works with commonmark (#9716). + + Remove "Body Text Char" from list of Word styles that can be customized + using a reference.docx (#10646). This doesn't seem to be present in + pandoc-generated docx files, nor is it a Word default. + + For pandoc lua, add note about the environment. + + Improve documentation of `--variable` option. + + * `doc/typst-property-output.md`: Mention that `typst:no-figure` is a + class, not an attribute (#10826, Niklas Eicker). + + * Change RELEASE-CHECKLIST to RELEASE-CHECKLIST-TEMPLATE.org. Use org-babel + to automate many of the steps of the release. + + * INSTALL.md: update MacPorts information (#10719, Mohamed Akram). + + * COPYRIGHT: fix link to source code. + + * CONTRIBUTING.md: Fix link to discussion forum. (#10834, R. N. West). + +## pandoc 3.6.4 (2025-03-16) + + * Disable `citations` extension in writers if `--citeproc` is used (#10662). + Otherwise we get undesirable results, as the format's native + citation mechanism is used instead of (or in addition to) the + citeproc-generated citations. + + * Markdown reader: + + + Allow line break between URL and title of link (#10621). + + Give better position information when YAML metadata parsing fails + with a YAML exception (#10231). + + Fixed `escapedChar'` parser (#10672). It should not accept + escaped newlines. + + Remove some misguided list fanciness (#9865, #7778, cf. #5628). + Previously we tried to handle things like commented out list items: + ``` + - one + + - three + ``` + and also things like: + ``` + - one `and + - two` and + ``` + But the code we added to handle these cases caused problems with + other, more straightforward things, like: + ```` + - one + - ``` + code + ``` + - three + ```` + So we are rolling back all the fanciness, so that the markdown + parser now behaves more like the commonmark parser, in which + indicators of block-level structure always take priority over + indicators of inline structure. + + * HTML reader: + + + Skip MathJaX-introduced cruft (#10673). + + Ignore style tags in the body (#10643). + + * LaTeX reader: + + + Better handle comments/whitespace in option lists and includes (#10659). + + Support `\newline`, `\linebreak`. + + * Docx reader/writer: + + + Revert commit adding row heads + (cbe67b9602a736976ef6921aefbbc60d51c6755a) (#10627). + Word sets `w:firstColumn="1"` by default for tables. You have to find + the Table Design tab and explicitly uncheck "First Column" to make this + go away. In most cases, I don't think writers intend to designate + the first column as a row head, so this commit is going to produce + unexpected results. In addition, because of the table normalization + done by pandoc-type's `tableWith`, any table containing a colspanned + cell in the left-hand column will get broken if the first column is + designated a row head. For these reasons it seems best to revert this + change, which was made in response to #9495. + + * LaTeX writer and template: + + + Remove `selnolig-langs` (#9863). We now specify the language as + a global option again, so we no longer need to specify it when + invoking selnolig. + + Use babel options `shorthands=off` (#6817). + + Use `*` for multirow width when no colwidth specified (#10685). + Otherwise the multirow will be excessively wide. + + Protect `\phantomsection` (#10688, etclub). + + * Markdown writer: + + + Omit extra space after bullets (#7172). Those who want the old + behavior can obtain it by using `-t markdown+four_space_rule`. + + Treat `Emph [Emph ils]]` as `ils` (#10642). Otherwise we get + `**content**` which means strong emphasis. + + * EPUB writer: + + + Use a nonbreaking space after section number in nav.xhtml. + This seems to be required for iOS books app to display the space. + + * Typst writer: + + + Better heuristics for escaping potential list markers (#10650). + + Ensure that `citation-style` works as well as `csl` (#10661). + + * Powerpoint writer: + + + Avoid extra blank lines before author when there is no + subtitle (#10619). + + * JATS template: + + + Fix typo in author prefix in article.jats_publishing template + (#10622, Tiago-Manzato). + + * Text.Pandoc.Parsing: + + + Smart quote parsing: ignore curly quotes (#10610). Previously we + tried to match curly quotes as well as straight quotes, + producing Quoted inlines. But it seems better just to assume + that those who use curly quotes want them passed through + verbatim. This also fixes an (unintended) bug whereby curly + single left quotes would sometimes be changed to single right quotes. + + * Text.Pandoc.Shared: + + + `makeSections`: put some attributes on section element only. + Certain `role` and `epub:type` attributes should only be on the section + (and indeed, many `role`s give a validation error if left on the + heading element). + + * Text.Pandoc.Logging: + + + Change NoTitleElement from WARNING to INFO (#10671). Users + commonly complain about the warning when producing HTML + documents without an explicit title. It seems that an info + message is more appropriate, since pandoc's default here (using + the input's base name) ensures compliance with the standard and + many users are happy with that default. Those who want to make + sure the message is seen can use `--verbose`. + + * Beamer template: only emit `\date` if set (#10687, josch). + + * Fix invalid OOXML in definition_list.docx test (#10394). + + * MANUAL.txt: + + + Correct typo: 'date' for doubled 'title' (#10654, Olivier Dossmann). + + Add note about `template` variable for typst. + + Change maxwidth default in MANUAL.txt (#10683). + + Improve EPUB metadata documentation. + + In Security section, alert readers to a threat relating to iframe in + HTML, and add LaTeX, Typst to the list of formats that have an + `include` (#10682). + + * `doc/lua-filters.md`: Add missing html_math_method 'katex' (R. N. West). + + * Use texmath 0.12.9. + + * Use typst 0.7. Fixes an issue with package loading, a regression + in pandoc 3.6.3. + +## pandoc 3.6.3 (2025-02-09) + + * Track wikilinks with a class instead of a title (Evan Silberman). + Previously wikilinks were distinguished by giving them the `title` + `wikilink`. Now that we have link attributes, it makes more sense + to give them the `class` `wikilink`. This change affects all readers + and writers that support wikilinks. + + * DocBook reader: + + + Handle title inside `orderedlist` (#10594). Also some other + elements that allow title: `blockquote`, `calloutlist`, etc. + + Better handle `informalequation` (#10592, tombolano). Include `id` + attribute. + + Better handle `formalpara`, `example`, and `sidebar` (#8666, tombolano). + Include identifiers and titles in each case. + + * Markdown reader: + + + Simplify and fix normal citation parsing (#10584). + This fixes a bug that causes some normal citations to be + parsed as bracketed regular citations. + + * ODT reader: + + + Create Figure elements for images that are figures (#10567). + + Avoid producing spurious blockquotes in list items (#9505). + + Fix unwanted block quotes (#10575). Previously the reader created + block quotes whenever a paragraph was marked indented (even though + this just affects the first line). With this change we still + generate block quotes for content that has an altered left margin, + but not for indented paragraphs. + + * Docx reader: + + + Do not issue warning for comments with `+styles` (#10571, Stephen Reindl). + + * LaTeX reader: + + + Test \{,re}newcommand arguments (#4470, Evan Silberman). + + * Pod reader: + + + Consume blanks after =encoding in pod reader (#10537, Evan Silberman). + + * JATS writer: + + + Add CRediT roles to JATS (Charles Tapley Hoyt and Jez Cope, #10152). + Enable annotating author roles using the Contribution Role Taxonomy + (CRediT) and export this information in conformant JATS. + + * LaTeX writer/templates: + + + Improve babel support (#8283). Previously we used the `.ini` + files for every language, but for European languages these tend to + provide inferior results to the `.ldf` files used by classic + Babel. Currently Babel documentation recommends using the classic + system for European languages written in Latin and Cyrillic + scripts and Vietnamese. So the LaTeX writer and template now + follow this guidance. + + Main languages in the list of languages with good "classic" support + are added to global documentclass options and will be automatically + handled by Babel using the `.ldf` files. + + If the main language is not in this list, the `babeloptions` variable + will be set to `provide=*`, which will cause support to be loaded from + the `.ini` file rather than an `.ldf`. So, for example, setting + `-V babeloptions=''` with a polytonic Greek document will cause the + `.ldf` support to be used instead of the `.ini`. + + The default setting of this variable can be overwritten, but in most + cases the default should give good results. + + + Allow `csquotesoptions` to be specified. + + Fix indentation bugs in `font-settings.latex`. + + * Docx writer: + + + Repeat reference doc's `sectPr` for each new section (#10577). + Previously we were only carrying over the reference doc's `sectPr` + at the end of the document, so it wouldn't affect the intermediate + sections that are now added if `--top-level-division` is `chapter` + or `part`. This could lead to bad results (e.g. page numbering + starting only on the last chapter). + + Create section divisions with `--top-level-division=part` (#10576). + + Improve title style in reference.docx; base Author and Date + on Title; remove condensed spacing (Andrew Dunning, #10581). + + * Typst writer: + + + Brace tables with `typst:no-figure` and `typst:text` attributes (#10563, + Gordon Woodhull). + + * Ms writer: + + + Fix escaping of `-` (#10536). `-` should now be escaped in man + output but not in ms output (where `\-` is a unicode minus sign). + + * HTML styles: fix style of `hr` so it works when printed (#10535, Hendrik Erz). + Previously `background-color` was used to style the hr, but this gets ignored + when printing. This commit uses `border-top` instead. + + * Text.Pandoc.Shared: + + + Handle `` as a span-like inline in `htmlSpanLikeElements` + (#5793, Evan Silberman). + + * Text.Pandoc.MediaBag: + + + Prefer MIME type when determining extensions for MediaBag items (#10557, + Max Heller). This should give different results for remote images + that are served at URLs that do not contain misleading extensions + (e.g. `shields.io`). + + * Text.Pandoc.Citeproc: + + + Fix moving punctuation before citation notes. This previously worked with + regular citations, but not author-in-text citations. Now it works with both. + + * `doc/lua-filters.md`: + + + Correct luacheck URL (#10589, R. N. West). + + Add static analysis paragraph to debugging section (#10568, R. N. West). + + Add note about extensions handling in `read` and `write` (Albert Krewinkel). + + * `doc/extras.md`: + + + Add entry for pandoc-subfigs (R. N. West). + + Update diagram Lua filter URL and description (R. N. West). + + * MANUAL.txt: + + + Add note on using typst to produce pdf/a-2b. + + Document top-level-division functionality with Docx (#10579, Andrew Dunning). + + * Raise xml-conduit upper bound. + + * Depend on latest commonmark-pandoc, commonmark-extensions, + citeproc, typst. + + * Makefile: make `make binpath` quiet. + +## pandoc 3.6.2 (2025-01-12) + + * New input format: `pod` (Evan Silberman). Pod ("Plain old documentation") + is a markup languaged used principally to document Perl modules and + programs. + + * New reader module Text.Pandoc.Readers.Pod, exporting `readPod` + [API change]. + + * Docx reader: + + + Support row heads in tables (#9495). Reader: When `w:tblLook` has + `w:firstColumn` set (or an equivalent bit mask), we set row heads = 1 + in the AST. + + Read table styles as custom styles when `styles` extension + is enabled (#9603). + + * HTML reader: + + + Add size information for font awesome SVG icons (#10134). + If the icon has class `fa-fw` or `fa-w16` or `fa-w14`, we add a width + attribute to prevent the icon from appearing full-width in PDF or + docx output. + + * Djot reader: + + + Use a Span with class "mark" rather than "highlighted" for + highlighted text, for consistency with the other pandoc readers and + writers. + + * mandoc reader: + + + Add mdoc St for C23 (Evan Silberman). + + * RST reader: + + + Fix handling of underscores (#10497). Fixes a a regression + introduced in 3.6. + + * Docx writer: + + + Support row heads in tables (#9495). Writer: set `w:firstColumn` in + `w:tblLook` when there are row heads. (Word only allows one, so this + is triggered by any number of row heads > 0.) + + * Djot writer: + + + Render a Span with sole class "mark" as highlighted text. + + * Asciidoc writer: + + + Don't emit the class in a span if it's just "mark" (#10511). + The "mark" class is used for highlighting, and Asciidoc treats + bare `#...#` with no attributes as highlighted text. + + Improve escaping (#10385, #2337, #6424). + + * EPUB v2 writer: + + + Fix cover image (#10505). This is a regression introduced in 3.6. + + * Typst writer: + + + Fix handling of pixel image dimensions (#9945). + These are now converted to inches as in the LaTeX writer. + + * Improve error message given when users specify `asciidoc` as input + format (#8416, Santiago Zarate). + + * Allow random 1.3. + + * Use texmath 0.12.8.13 (typst improvements). + + * `lua-filters.md`: document `system.os` return values (#10523). + + * `MANUAL.txt`: + + + Improve manual's coverage of custom styles. + + Replace LibreOffice PDF documentation link to latest so it links + to the latest major release rather than a specific major release + (which there are two of every year) (Stéphane Guillou). + + Improve links and descriptions for `odt`, `opendocument` (#10518). + +## pandoc 3.6.1 (2024-12-23) + + * Allow YAML bibliographies to be arrays of references (#10452). + Previously, they had to be YAML objects with a `references` key. + + * Change `--template` to allow use of extensionless templates (#5270). + The intent is to allow bash process substitution: e.g., + `--template <(echo "foo")`. Previously pandoc *always* added an + extension based on the output format, which caused problems + with the absolute filenames used by bash process substitution + (e.g. `/dev/fd/11`). Now, if the template has no extension, + pandoc will first try to find it without the extension, and + then add the extension if it can't be found. So, in general, + extensionless templates can now be used. But this has been + implemented in a way that should not cause problems for + existing uses, unless you are using a template `NAME.FORMAT` + but happen to have an extensionless file `NAME` in the template + search path. + + * Allow `--shift-heading-level-by=-1` to work in djot in the same way + it works for other formats (with the top-level heading being + promoted to metadata title) (#10459). This needed special + treatment because of the way djot surrounds sections with Divs. + + * RST reader: + + + Handle explicit reference links (#10484, Evan Silberman). + This case was missed when changing the reference link strategy for + RST to allow a single pass. (It is a regression in pandoc 3.6.) + + * Markdown reader: + + + Use T.P.URI's `pBase64DataURI` in parsing data URIs (#10075, + Evan Silberman and John MacFarlane). + + More efficient base64 data URI parsing (#10075, Evan + Silberman and John MacFarlane). This should yield dramatic + performance improvements for markdown documents containing + large data URIs in images. + + * HTML reader: + + + Don't canonicalize data: URIs (#10075). It can be very expensive + to call network-uri's URI parser on these. + + * LaTeX reader: + + + Handle `figure*` environment as a figure (#10472). + + * MediaWiki reader: + + + Allow empty quoted attributes (#10490). + + Allow cells starting with `+` (#10491). + + * Textile reader: + + + Improve parsing of spans (#9878). The span needs to be separated + from its surroundings by spaces. Also, a span can have attributes, + which we now attach. + + Inline constructors shouldn't trigger if closer is preceded by + whitespace (#10414). + + * Docx writer: + + + Put chapters in separate sections, and restart footnotes + by section by default (#2773). The main effect of this change is that + when `--top-level-division=chapter` is used, chapters will start on + a new page and footnote numbering will restart for each chapter. + Both of these defaults can be overridden in the reference.docx. + + Use styleIds not styleNames for Title, Subtitle, etc. + (#10282). This fixes a regression introduced in pandoc 3.5. + This change affects the default openxml template as well as the + OpenXML writer. + + * Markdown writer: + + + Avoid collapsing of initial/final newline in markdown raw blocks. + This makes it easy to write a filter that adds extra blank lines + before certain elements (#10477). + + * Mediawiki writer: + + + Escape line-initial characters that would otherwise be interpreted + as list starts (#9700). + + * LaTeX writer: + + + Properly handle boolean value for `csquotes` variable (#10403). + + Use displayquote for block quotes with `csquotes` (#10456). + + * HTML writer: + + + Avoid calling parseURIString for data URIs (#10075). + This was done to determine the "media category," but we can + get that directly from the mime component of data: URIs. + + * Typst writer: + + + Properly handle data URIs in images (#10460). + + * LaTeX/Beamer templates: + + + Fix default.beamer `nocite` location (Thomas Hodgson). + It must be inside a frame or it is ignored (#10465). + + Move nocites from LaTeX preamble to body (#10461, Thomas + Hodgson). Putting `\nocite` in the preamble works only with biblatex. + + * Text.Pandoc.Parsing: + + + Correct example in comment on `charsInBalanced` (Evan Silberman). + + * Text.Pandoc.Error: + + + Mention typst in rendering `PandocUnknownWriterError` for `pdf` + (Evan Silberman). + + * Text.Pandoc.MediaBag: + + + `insertMedia`: fast path for data URIs. Avoid the slow URI + parser from network-uri on large data URIs (#10075). + + * Text.Pandoc.Class: + + + Add shortcut for base64 data URIs in `downloadOrRead` (#10075). + This avoids calling the slow URI parser from network-uri on + data URIs, instead calling our own parser. + + * Text.Pandoc.MIME: + + + Fix `extensionFromMimeType`. We had a few special cases encoded, + but as previously written they wouldn't work properly with + modifiers like `;charset=utf-8`. + + * Text.Pandoc.URI: + + + Export `pBase64DataURI`. Modify `isURI` to use this and avoid + calling network-uri's inefficient `parseURI` for data URIs. + + * Text.Pandoc.PDF: + + + Fix temp file extension in `toPdfViaTempFile` (#10468). + This fixes a regression in pandoc 3.6, which changed + the extension from `html` to `source`. Apparently + `wkhtmltopdf` needs it to be `.html`. So now we have added + a parameter to `toPdfViaTempFile` that allows the extension + to be specified in a way that is appropriate to the PDF engine + used. + + * Lua (Albert Krewinkel): + + + Support more elements as input to `pandoc.utils.stringify` + (#10450). Elements of type Caption, Cell, TableHead, and TableFoot + can now be stringified. + + Add `Caption` constructor to `pandoc` module. + + * Miscellaneous code quality improvements (Joseph C. Sible). + + * Depend on citeproc 0.8.1.2, skylighting and skylighting-core + 0.14.5. + + * `doc/lua-filters.md: Fix links to constructors (Albert Krewinkel). + + +## pandoc 3.6 (2024-12-07) + + * Add `mdoc` as input format (Evan Silberman). This change + introduces a reader for mdoc, a roff-derived semantic markup + language for manual pages. This reader has been developed almost + exclusively against mandoc's documentation and implementation of + mdoc as a reference, and the real-world manual pages tested + against are those from the OpenBSD base system. Of ~3500 manuals + in mdoc format shipped with a fresh OpenBSD install, 17 cause the + mdoc reader to exit with a parse error. Any further chasing of + edge cases is deferred to future work. + + * New module: Text.Pandoc.Readers.Mdoc, exporting `readMdoc` [API change]. + + * Issue warnings for duplicate YAML metadata keys (#10312). + + * Ensure that `--sandbox` affects `--embed-resources`. Previously it + did not (contrary to what was implied by the manual), which means + that an image with URL `/etc/passwd` would leak an encoded version + of that file to HTML output with `--self-contained` or + `--embed-resources`, even if `--sandbox` was used. Thanks to + Samuel Mortenson for pointing out the issue. + + * Text.Pandoc.App.OutputSettings: add `sandbox'` function. + This computes the sandboxed files from Opt and avoids code repetition. + + * Docx reader: + + + Parse index references as empty spans with attributes (#10171). + Attributes included are `entry`, and optionally `bold`, `italic`, + `yomi`, `see`. + + Don't create multiple paragraphs for title or subtitle (#10359). + If there are multiple paragraphs with Title or Subtitle style, + use only the first for metadata. + + Handle case where Zotero `itemData` has different id from the + `citationItem` id. In this case we use the `citationItemId` + in the bibliography as well, overriding the `referenceId` + in the itemData (#10366). + + * LaTeX reader: + + + Put parsed minipage in specially marked Div (#10266). + + * HTML reader: + + + Parse footnotes defined by dpub-aria roles (#5294). + + * MediaWiki reader: + + + Fix indented tables with caption (#10390). + + Fix parsing of col/rowspan (#6992). + + * Typst reader: + + + Avoid generating empty paragraphs. + + Support `underparen`, `overparen`. + + Fix `#quote` attribution. If attribution is not present, don't print + the `--` (#10320). + + Fix typo in unicode code point for em dash (see #10320). + + * Commonmark reader: + + + `implicit_figures` should check for empty caption + and not produce an implicit figure in this case (#10429). + + * RST reader: + + + Use a new one-pass parsing strategy. Instead of having an initial pass + where we collect reference definitions, we create links with target + `##SUBST##something` or `##REF##something` or `##NOTE##something`, + and resolve these in a pass over the parsed AST. This allows us to handle + link references that are not at the top level (#10281). + + Ignore newlines in URL in explicit link (#10279). + + Handle block level substitutions. + + Support `:file:` on raw directive (#8584). + + Implement option lists (#10318). + + Avoid putting metadata in Para (#7766). Create MetaInlines when possible, + just as with markdown input. MetaBlocks is still used when there are + multiple paragraphs or non-paragraph content. + This change also affects field lists. + + Fix linked substitutions (#6588). E.g. `|Python|_`. + + Support inline anchors (#9196). + + Explicit links define references (#5081). For example, + ``Go to `g`_ `g `_.`` should produce two links to + www.example.com. + + * EPUB writer: + + + Use standardized filename for cover image instead of the original name + (#10404). This avoids problems with e.g. filenames containing spaces. + + * Markdown writer: + + + Issue INFO warning when not rendering table, e.g., when `raw_html` is + disabled and the table can't be fit into a supported markdown table + format (#10407). + + Respect empty LineBlock lines in `plain` output (Evan Silberman). + The plain writer behaved as a markdown variant with `Ext_line_blocks` + turned off, and so empty lines in a line block would get eliminated. + + * LaTeX writer: + + Ensure that beamer footnotes go on frame, not column (#5769). + + * HTML writer: + + + Unwrap empty incremental divs (#10328, Albert Krewinkel). + Divs are unwrapped if the only purpose of the div seems to be to control + whether lists are presented incrementally on slides. + + * Typst writer: + + + Make template sensitive to a `page-numbering` variable (#10370). + This can be set to an empty string (or, in metadata, to false) for + no page numbers. + + Make `smart` extension work (#10271). If `smart` is not enabled, a command + in the default template will disable smartquote substitutions. + When `smart` is enabled, render curly apostrophes as straight + and escape straight apostrophes. When `smart` is disabled, + render curly apostrophes as curly and don't escape straight + apostrophes. Similarly for quotes, em and en dashes. This should + give more idiomatic typst output, with fewer unnecessary + escapes. + + * ANSI writer: + + + Respect empty LineBlock lines (Evan Silberman). + + * JATS writer: + + + Correct spelling of suppress attribute (#10350, Andreas Deininger). + + * Typst template: + + + Remove `definitions.typst` partial. + + Remove unnecessary definition of `endnote`. + + Incorporate the one remaining definition into `default.typst`. + + Use typst 0.12 code for two column layout (#10294, Luis Rivera). + + Note: the new templates presuppose typst 0.12; if you try to use an + earlier version of typst, an error will be raised. + + * LaTeX/Beamer template: + + + Split `fonts.latex` partial into two parts: `fonts.latex` and + `font-settings.latex`. + + In beamer template, load beamer theme between `fonts.latex` and + `font-settings.latex`. This allows a theme (such as metropolis) + to set its own default font, while still allowing the user to + override it. This fixes a regression in pandoc 3.5 (#10297). + + Note: Users who have custom templates based on pandoc 3.5 templates will + need to add `font-settings.latex()` after `fonts.latex()` in the + latex template. In a beamer template, the beamer theme-setting + code needs to be moved between these two partials. + + * ConTeXt template: Ensure that font names don't wrap (#10305). + + * `epub.css`: remove background-color (#10264, Suraj Patil). + With this greyish background color, epubs look bad on a Kindle (#10263). + + * Text.Pandoc.ImageSize: add WebP support (Evan Silberman, #10397). + Add `Webp` constructor on ImageType [API change]. + + * Text.Pandoc.Readers.Roff and a new unexported module + Text.Pandoc.Readers.Roff.Escape: parameterize Roff + escaping (Evan Silberman) [API change]. This allows code to + be reused between the mdoc and man readers, despite the + differing Token types. + + * Text.Pandoc.PDF: + + + PDF via LaTeX: always do max runs if `toc` is present (#10308). + The old method (checking to see if toc hash had changed) is not + completely reliable. + + Use `.source` extension, not `.html`, in `toPdfViaTempFile` (#10314). + + * Text.Pandoc.Logging: add `YamlWarning` constructor to `LogMessage` + [API change] (#10312). + + * Text.Pandoc.Format: remove duplicate typst entry (#10388, Caleb Mclennan). + + * Fix a typo in the `ua.yaml` localization for 'See' (Jens). + + * Lua subsystem (Albert Krewinkel): + + + Remove prefixes from Lua type names (#8574). Lua type names were + inconsistent with regard to the use of prefixes; all prefixes + are removed now, and Lua types now have the same name as the + Haskell types. The use of app-specific prefixes is suggested by + the Lua manual to avoid collisions. However, this shouldn't be a + problem with pandoc, as it cannot be used as a Lua package. + + * doc/libraries.md: Add newly developed Haskell packages. + Sort list alphabetically (Albert Krewinkel). + + * doc/lua-filters.md: document `pandoc.List:iter` method (Albert Krewinkel). + List objects have a new function `iter` that returns an iterator + function that returns the next list item on each call. + + * MANUAL.txt: + + + Clarify what the example of YAML EPUB metadata shows (#10405). + + Fix typo in template syntax (#10265, Pascal Wagler). + + Update manual with information on openxml template (#10273). + + Clarify that `--variable` can only assign string values (#10298). + + * Fix comments in TEI writer referring to DocBook (#10430, Evan Silberman). + + * Fix several typos in documentation (#10349, Andreas Deininger). + + * Allow Diff 1.0. + + * Add font-settings.latex partial to pandoc.cabal (#10379). + + * Bump upper bound for data-default. + + * Use latest typst, texmath, pandoc-lua-marshal, commonmark-pandoc, + commonmark-extensions, skylighting, skylighting-format-blaze-html. + + +## pandoc 3.5 (2024-10-04) + + * Add command-line options `--list-of-figures/--lof` and + `--list-of-tables/--lot` (#10029, Akash Patel). + Only docx, latex, and context are affected by these options currently. + Setting the `lof` and `lot` variables will also work for the formats + that are currently supported. + + * Defaults files: interpolation of environment variables now + works for `to` and `from` fields (#8024). This is needed because + these files can contain paths of custom readers/writers. + + * Docx reader: + + + Reset lists after headers in same list `numId` (#10258). + To accomplish this, we add a Heading constructor to BodyPart and + include on it all the information list items have. + + * DocBook reader: + + + Parse id, class, and tabstyle on tables (#10181, Erik Rask). + Add parsing of id (xml:id), class, and tabstyle XML attributes + for table and informaltable in the DocBook reader. + The tabstyle value is put in the 'custom-style' attribute. + + * Dokuwiki reader: + + + Be more forgiving about misaligned lists, like dokuwiki itself (#8863). + + Improve blockquote parsing in dokuwiki. Allow for quoted code blocks. + + Enable smart extension. + + Properly parse `--` and `---` as dashes. + + Fix block quote behavior (#6461). Blockquotes are not really block + containers in DokuWiki; the lines are interpreted literally (so, + e.g., you can't start a list), and line breaks are added at the ends. + + * EPUB reader: + + + Fix links to other files in the EPUB, making them internal links + to a fragment derived from the filename (#10207). There was + already code to handle links like `#foo`, but not to handle links + like `ch0001.html#foo`. + + * LaTeX reader: + + + Add em, ex, px, mu to list of units for dimension args (#10212). + + * ANSI writer: + + + Fix subscripts (Evan Silberman). + + * DokuWiki writer: + + + Don't emit `` tags (#7413). The use of these tags is now + strongly discouraged for security reasons, and will be removed. + We previously used them as a fallback for lists that could not + be represented using DokuWiki syntax, e.g. ordered lists with + fancy numbers or lists with multiple blocks in their items. + We also used them for block quotes with multiple blocks as + their contents. We now use the `` syntax (from the optional + WRAP plugin) to handle lists with multiple blocks as their contents. + A new method of handling block quotes with complex contents + has the side benefit of also handling nested block quotes, + which weren't supported before. + `` and `` tags are only for raw HTML blocks and + inlines, and only if the `raw_html` extension is enabled. (It is + now a valid extension for `dokuwiki`, though off by default.) + + * Docx writer: + + + Support `--list-of-figures` and `--list-of-tables` (or `lof` and + `lot` variables) (Akash Patel). + + * HTML writer: + + + Don't emit missing title/lang warnings if templates does not + contain the `pagetitle` or `lang` variables respectively (#9370). + + * LaTeX writer: + + + Better fix for lists in definition lists (#10241). + In commit a26ec96d89ccf532f7bca7591c96ba30d8544e4a we added an + empty `\item[]` to the beginning of a list that occurs first + in a definition list, to avoid having one item on the line with + the label. This gave bad results in some cases (#10241) and there + is a more idiomatic solution anyway: using `\hfill`. + + Avoid error on `refs` div with empty citations (#10185). + If there are no citations, don't emit an empty CSLReferences environment. + + * RST writer: + + + Change bullet list hang from 3 to 2. This accords with the style in + the RST reference docs. + + Handle cases where indented context starts with block quote (#10236). + In these cases we emit an empty comment to fix the point from + which indentation is measured; otherwise the block quote is not + parsed as a block quote. This affects list items and admonitions. + + Don't enclose the list table in a `.. table::`; this leads to + doubled captions (#10226). + + Fix alignment of list table items corresponding to cells (#10227). + + * JATS template: + + + Support `floats-group` (Albert Krewinkel, see #10196). + The content of the `floats-group` variable is now rendered in a + `` element when using the *publishing* or *archiving* tag + sets. + + * LaTeX and Beamer templates: + + + Split old default.latex into two templates, `default.latex` and + `default.beamer`, factoring common parts into partials: + `fonts.latex`, `common.latex`, `passoptions.latex`, + `hypersetup.latex`, `after-header-includes.latex`. + + Make `default.beamer` the default template for beamer. + + Add `shorttitle`, `shortsubtitle`, `shortauthor`, `shortinstitute`, + `shortdate` variables to beamer template (#10248, Thomas Hodgson). + + Make `--number-sections` work with beamer (#12045, Thomas Hodgson). + + Support a list of images for `titlegraphic` in beamer template + (#10246, Thomas Hodgson). Title graphic options will be + applied to each title graphic. Images will be separated by `\enspace`. + + Beamer theme options (#10243) + + Add theme options to beamer template: `colorthemeoptions`, + `fontthemeoptions`, `innerthemeoptions`, `outerthemeoptions` (#10243, + Thomas Hodgson). + + Don't load amsmath, amssym in beamer template. These are loaded by + beamer automatically. + + * Text.Pandoc.SelfContained: + + + Improve handling of links to remote CSS (#10261). + + * Text.Pandoc.Class: + + + Allow extracting `data:` URIs even in PandocPure (`--sandbox`) + (#10249). + + Export `extractURIData` [API change]. + + * Text.Pandoc.PDF: + + + Read `.toc` and `.log` files from output directory (#10186). + When this is different from the input directory, this is + where `.toc` and `.log` files are written. + + * Text.Pandoc.Shared: + + + Modify `addPandocAttributes` for changes in commonmark-pandoc. + The new commonmark-pandoc version automatically adds the + attribute `wrapper="1"` on all Divs and Spans that + are introduced just as containers for attributes that belong + properly to their contents. So we don't need to add the + attribute here. This gives much better results in some cases. + Previously the wrapper attribute was being added even for + explicit Divs and Spans in djot, but it is not needed in these cases. + + * Text.Pandoc.Options: + + + Add `writerListOfFigures` and `writerListOfTables` fields + to `WriterOptions` (#8245, Akash Patel). [API change] + + * Text.Pandoc.App: + + + Add `optListOfFigures` and `optListOfTables` to `Opt` (#8245) + [API change]. + + * Lua subsystem (Albert Krewinkel): + + + Update List module (#9835). The module now comes with a method + `:at(index[, def])` that allows to access indices, accepts + negative indices to count from the end, and will return the + `def` value as a default if the list has no item at the given position. + Furthermore, the list constructor `pandoc.List` now accepts iterators. + E.g., `pandoc.List(text:gmatch '%S+')` returns the list of words + in `text`. + + Support character styling via `pandoc.layout`. The `Doc` values + produced and handled by the `pandoc.layout` module can now + be styled using `bold`, `italic`, `underlined`, or `strikeout`. The + style is ignored in normal rendering, but becomes visible when + rendering to ANSI output. The `pandoc.layout.render` function + now takes a third parameter that defines the output style, + either *plain* or *ansi*. + + It is now possible to return a single filter from a filter file, e.g. + ``` lua + -- Switch single- and double quotes + return { + Quoted = function (q) + elem.quotetype = elem.quotetype == 'SingleQuote' + and 'DoubleQuote' or 'SingleQuote' + return elem + end + } + ``` + The filter must not contain numerical indexes, or it might be treated + as a list of filters. + + Add `list_of_figures` and `list_of_tables` to writer options + (Akash Patel). + + * Use latest releases of commonmark, commonmark-pandoc, texmath, djot. + + * Stop depending on package SHA (Albert Krewinkel). Use `crypton` instead. + + * `linux/make_artifacts.sh`: add riscv64 support (Olivier Benz). + + * Fix invalid XML in `test/docx/normalize.docx` (#10242). + + * `doc/lua-filters.md`: list functions in `pandoc.utils` alphabetically + (Albert Krewinkel). + + * MANUAL.txt: + + + Clarify use of `beamerarticle` variable (#10250). + + Add clarification to address user issues like #6704 (Yehuda Katz). + ## pandoc 3.4 (2024-09-09) * New output format: `ansi` (for formatted console output) (Evan Silberman). @@ -31,11 +1335,11 @@ * RST reader: - + Improve simple table support (#10093). Multiline rows occur - only when the *first* cell is empty; we were previously treating - lines with *any* empty cell as row continuations. In addition, we - no longer wrap multiline cells in Para if they can be represented - as Plain. This is consistent with docutils behavior. + + Improve simple table support (#10093). Multiline rows occur + only when the *first* cell is empty; we were previously treating + lines with *any* empty cell as row continuations. In addition, we + no longer wrap multiline cells in Para if they can be represented + as Plain. This is consistent with docutils behavior. * LaTeX reader: @@ -61,12 +1365,15 @@ converting both. We now ignore the HTML fallback span, marked with class `katex-html`. + * Docx reader: + + + Add "SuppressAuthor" and "AuthorOnly" to citationMode + when `+citations` is used (thomjur). + * New module: Text.Pandoc.Writers.ANSI [API change] (Evan Silberman). * Docx writer: - + Add "SuppressAuthor" and "AuthorOnly" to citationMode - when `+citations` is used (thomjur). + Support `custom-style` attribute for docx table (Sebbones). + Support `--number-offsets`. + Make table/figure rendering sensitive to caption position settings. @@ -3096,7 +4403,7 @@ * HTML, Markdown writers: filter out empty class attributes (#8251). These should not be generated by any pandoc readers, but they - might be produced programatically. + might be produced programmatically. * Markdown writer: diff --git a/data/docx/word/document.xml b/data/docx/word/document.xml index 475ae1894cb4..e4953d2d7acf 100644 --- a/data/docx/word/document.xml +++ b/data/docx/word/document.xml @@ -15,9 +15,7 @@ xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing - -Title - + Title @@ -25,9 +23,7 @@ Title - -Subtitle - + Subtitle @@ -35,9 +31,7 @@ Subtitle - -Author - + Author @@ -45,9 +39,7 @@ Author - -Date - + Date @@ -55,9 +47,7 @@ Date - -Abstract - + Abstract @@ -66,9 +56,7 @@ Abstract - -Heading 1 - + Heading 1 @@ -78,9 +66,7 @@ Heading 1 - -Heading 2 - + Heading 2 @@ -90,9 +76,7 @@ Heading 2 - -Heading 3 - + Heading 3 @@ -102,9 +86,7 @@ Heading 3 - -Heading 4 - + Heading 4 @@ -114,9 +96,7 @@ Heading 4 - -Heading 5 - + Heading 5 @@ -126,9 +106,7 @@ Heading 5 - -Heading 6 - + Heading 6 @@ -138,9 +116,7 @@ Heading 6 - -Heading 7 - + Heading 7 @@ -150,9 +126,7 @@ Heading 7 - -Heading 8 - + Heading 8 @@ -162,9 +136,7 @@ Heading 8 - -Heading 9 - + Heading 9 @@ -173,9 +145,7 @@ Heading 9 - -First Paragraph. - + First Paragraph. @@ -183,57 +153,39 @@ First Paragraph. - -Body Text. Body Text Char. - + Body Text. Body Text Char. - - - + - -Verbatim Char - + Verbatim Char - -. - + . - - - + - -Hyperlink - + Hyperlink - -. - + . - - - + - -Footnote. - + Footnote. @@ -247,9 +199,7 @@ Footnote. - -Block Text. - + Block Text. @@ -257,9 +207,7 @@ Block Text. - -Table caption. - + Table caption. @@ -286,9 +234,7 @@ Table caption. - -Table - + Table @@ -305,9 +251,7 @@ Table - -Table - + Table @@ -320,9 +264,7 @@ Table - -1 - + 1 @@ -333,9 +275,7 @@ Table - -2 - + 2 @@ -346,9 +286,7 @@ Table - -Image Caption - + Image Caption @@ -356,9 +294,7 @@ Image Caption - -DefinitionTerm - + DefinitionTerm @@ -366,9 +302,7 @@ DefinitionTerm - -Definition - + Definition @@ -376,9 +310,7 @@ Definition - -DefinitionTerm - + DefinitionTerm @@ -386,11 +318,13 @@ DefinitionTerm - -Definition - + Definition - + + + + + diff --git a/data/docx/word/footnotes.xml b/data/docx/word/footnotes.xml index 2a150e026067..4703b22a3083 100644 --- a/data/docx/word/footnotes.xml +++ b/data/docx/word/footnotes.xml @@ -1,7 +1,21 @@ - - - - - - Footnote Text. \ No newline at end of file + + + + + + + + + + + + + Footnote Text. + + + + Footnote Block Text + + + \ No newline at end of file diff --git a/data/docx/word/styles.xml b/data/docx/word/styles.xml index a7babfc6bfca..4569bb1c37af 100644 --- a/data/docx/word/styles.xml +++ b/data/docx/word/styles.xml @@ -3,10 +3,10 @@ - + - + @@ -60,8 +60,6 @@ - - @@ -77,8 +75,6 @@ - - @@ -123,23 +119,31 @@ + - + + + + + - + + + + diff --git a/data/epub.css b/data/epub.css index 8b2a3844fce6..5746daedd2bb 100644 --- a/data/epub.css +++ b/data/epub.css @@ -19,7 +19,6 @@ html { line-height: 1.2; font-family: Georgia, serif; color: #1a1a1a; - background-color: #fdfdfd; } p { text-indent: 0; diff --git a/data/templates/after-header-includes.latex b/data/templates/after-header-includes.latex new file mode 100644 index 000000000000..2c59e8718a3f --- /dev/null +++ b/data/templates/after-header-includes.latex @@ -0,0 +1,10 @@ +\usepackage{bookmark} +\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available +\urlstyle{$if(urlstyle)$$urlstyle$$else$same$endif$} +$if(links-as-notes)$ +% Make links footnotes instead of hotlinks: +\DeclareRobustCommand{\href}[2]{#2\footnote{\url{#1}}} +$endif$ +$if(verbatim-in-note)$ +\VerbatimFootnotes % allow verbatim text in footnotes +$endif$ diff --git a/data/templates/article.jats_publishing b/data/templates/article.jats_publishing index ebd14e9d707b..b33263cfd33a 100644 --- a/data/templates/article.jats_publishing +++ b/data/templates/article.jats_publishing @@ -98,7 +98,7 @@ $if(author.surname)$ $if(author.non-dropping-particle)$${author.non-dropping-particle} $endif$$author.surname$ $author.given-names$$if(author.dropping-particle)$ ${author.dropping-particle}$endif$ $if(author.prefix)$ -${author.suffix} +${author.prefix} $endif$ $if(author.suffix)$ ${author.suffix} @@ -109,6 +109,17 @@ $elseif(author.name)$ $else$ $author$ $endif$ +$for(author.roles)$ +$if(it.credit)$ +$if(it.name)$$it.name$$else$$it.credit-name$$endif$ +$elseif(it.name)$ +$it.name$ +$endif$ +$endfor$ $if(author.email)$ $author.email$ $endif$ @@ -232,5 +243,10 @@ $if(back)$ $back$ $endif$ +$if(floats-group)$ + +$floats-group$ + +$endif$ diff --git a/data/templates/common.latex b/data/templates/common.latex new file mode 100644 index 000000000000..cb745941de6b --- /dev/null +++ b/data/templates/common.latex @@ -0,0 +1,256 @@ +$if(linestretch)$ +\usepackage{setspace} +$endif$ +$-- +$-- paragraph formatting +$-- +$if(indent)$ +$else$ +\makeatletter +\@ifundefined{KOMAClassName}{% if non-KOMA class + \IfFileExists{parskip.sty}{% + \usepackage{parskip} + }{% else + \setlength{\parindent}{0pt} + \setlength{\parskip}{6pt plus 2pt minus 1pt}} +}{% if KOMA class + \KOMAoptions{parskip=half}} +\makeatother +$endif$ +$if(beamer)$ +$else$ +$if(block-headings)$ +% Make \paragraph and \subparagraph free-standing +\makeatletter +\ifx\paragraph\undefined\else + \let\oldparagraph\paragraph + \renewcommand{\paragraph}{ + \@ifstar + \xxxParagraphStar + \xxxParagraphNoStar + } + \newcommand{\xxxParagraphStar}[1]{\oldparagraph*{#1}\mbox{}} + \newcommand{\xxxParagraphNoStar}[1]{\oldparagraph{#1}\mbox{}} +\fi +\ifx\subparagraph\undefined\else + \let\oldsubparagraph\subparagraph + \renewcommand{\subparagraph}{ + \@ifstar + \xxxSubParagraphStar + \xxxSubParagraphNoStar + } + \newcommand{\xxxSubParagraphStar}[1]{\oldsubparagraph*{#1}\mbox{}} + \newcommand{\xxxSubParagraphNoStar}[1]{\oldsubparagraph{#1}\mbox{}} +\fi +\makeatother +$endif$ +$endif$ +$-- +$-- verbatim in notes +$-- +$if(verbatim-in-note)$ +\usepackage{fancyvrb} +$endif$ +$-- highlighting +$if(listings)$ +\usepackage{listings} +\newcommand{\passthrough}[1]{#1} +\lstset{defaultdialect=[5.3]Lua} +\lstset{defaultdialect=[x86masm]Assembler} +$endif$ +$if(lhs)$ +\lstnewenvironment{code}{\lstset{language=Haskell,basicstyle=\small\ttfamily}}{} +$endif$ +$if(highlighting-macros)$ +$highlighting-macros$ +$endif$ +$-- +$-- tables +$-- +$if(tables)$ +\usepackage{longtable,booktabs,array} +$if(multirow)$ +\usepackage{multirow} +$endif$ +\usepackage{calc} % for calculating minipage widths +$if(beamer)$ +\usepackage{caption} +% Make caption package work with longtable +\makeatletter +\def\fnum@table{\tablename~\thetable} +\makeatother +$else$ +% Correct order of tables after \paragraph or \subparagraph +\usepackage{etoolbox} +\makeatletter +\patchcmd\longtable{\par}{\if@noskipsec\mbox{}\fi\par}{}{} +\makeatother +% Allow footnotes in longtable head/foot +\IfFileExists{footnotehyper.sty}{\usepackage{footnotehyper}}{\usepackage{footnote}} +\makesavenoteenv{longtable} +$endif$ +$endif$ +$-- +$-- graphics +$-- +$if(graphics)$ +\usepackage{graphicx} +\makeatletter +\newsavebox\pandoc@box +\newcommand*\pandocbounded[1]{% scales image to fit in text height/width + \sbox\pandoc@box{#1}% + \Gscale@div\@tempa{\textheight}{\dimexpr\ht\pandoc@box+\dp\pandoc@box\relax}% + \Gscale@div\@tempb{\linewidth}{\wd\pandoc@box}% + \ifdim\@tempb\p@<\@tempa\p@\let\@tempa\@tempb\fi% select the smaller of both + \ifdim\@tempa\p@<\p@\scalebox{\@tempa}{\usebox\pandoc@box}% + \else\usebox{\pandoc@box}% + \fi% +} +% Set default figure placement to htbp +\def\fps@figure{htbp} +\makeatother +$endif$ +$if(svg)$ +\usepackage{svg} +$endif$ +$-- +$-- strikeout/underline +$-- +$if(strikeout)$ +\ifLuaTeX + \usepackage{luacolor} + \usepackage[soul]{lua-ul} +\else + \usepackage{soul} +$if(beamer)$ + \makeatletter + \let\HL\hl + \renewcommand\hl{% fix for beamer highlighting + \let\set@color\beamerorig@set@color + \let\reset@color\beamerorig@reset@color + \HL} + \makeatother +$endif$ +$if(CJKmainfont)$ + \ifXeTeX + % soul's \st doesn't work for CJK: + \usepackage{xeCJKfntef} + \renewcommand{\st}[1]{\sout{#1}} + \fi +$endif$ +\fi +$endif$ +$-- +$-- CSL citations +$-- +$if(csl-refs)$ +% definitions for citeproc citations +\NewDocumentCommand\citeproctext{}{} +\NewDocumentCommand\citeproc{mm}{% + \begingroup\def\citeproctext{#2}\cite{#1}\endgroup} +\makeatletter + % allow citations to break across lines + \let\@cite@ofmt\@firstofone + % avoid brackets around text for \cite: + \def\@biblabel#1{} + \def\@cite#1#2{{#1\if@tempswa , #2\fi}} +\makeatother +\newlength{\cslhangindent} +\setlength{\cslhangindent}{1.5em} +\newlength{\csllabelwidth} +\setlength{\csllabelwidth}{3em} +\newenvironment{CSLReferences}[2] % #1 hanging-indent, #2 entry-spacing + {\begin{list}{}{% + \setlength{\itemindent}{0pt} + \setlength{\leftmargin}{0pt} + \setlength{\parsep}{0pt} + % turn on hanging indent if param 1 is 1 + \ifodd #1 + \setlength{\leftmargin}{\cslhangindent} + \setlength{\itemindent}{-1\cslhangindent} + \fi + % set entry spacing + \setlength{\itemsep}{#2\baselineskip}}} + {\end{list}} +\usepackage{calc} +\newcommand{\CSLBlock}[1]{\hfill\break\parbox[t]{\linewidth}{\strut\ignorespaces#1\strut}} +\newcommand{\CSLLeftMargin}[1]{\parbox[t]{\csllabelwidth}{\strut#1\strut}} +\newcommand{\CSLRightInline}[1]{\parbox[t]{\linewidth - \csllabelwidth}{\strut#1\strut}} +\newcommand{\CSLIndent}[1]{\hspace{\cslhangindent}#1} +$endif$ +$-- +$-- Babel language support +$-- +$if(lang)$ +\ifLuaTeX +\usepackage[bidi=basic,shorthands=off,$for(babeloptions)$,$babeloptions$$endfor$]{babel} +\else +\usepackage[bidi=default,shorthands=off,$for(babeloptions)$,$babeloptions$$endfor$]{babel} +\fi +$if(babel-lang)$ +$if(mainfont)$ +\ifPDFTeX +\else +\babelfont{rm}[$for(mainfontoptions)$$mainfontoptions$$sep$,$endfor$$if(mainfontfallback)$,RawFeature={fallback=mainfontfallback}$endif$]{$mainfont$} +\fi +$endif$ +$endif$ +$for(babelfonts/pairs)$ +\babelfont[$babelfonts.key$]{rm}{$babelfonts.value$} +$endfor$ +\ifLuaTeX + \usepackage{selnolig} % disable illegal ligatures +\fi +$endif$ +$-- +$-- pagestyle +$-- +$if(pagestyle)$ +\pagestyle{$pagestyle$} +$endif$ +$-- +$-- prevent overfull lines +$-- +\setlength{\emergencystretch}{3em} % prevent overfull lines +$-- +$-- tight lists +$-- +\providecommand{\tightlist}{% + \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} +$-- +$-- subfigure support +$-- +$if(subfigure)$ +\usepackage{subcaption} +$endif$ +$-- +$-- text direction support for pdftex +$-- +$if(dir)$ +\ifPDFTeX + \TeXXeTstate=1 + \newcommand{\RL}[1]{\beginR #1\endR} + \newcommand{\LR}[1]{\beginL #1\endL} + \newenvironment{RTL}{\beginR}{\endR} + \newenvironment{LTR}{\beginL}{\endL} +\fi +$endif$ +$-- +$-- bibliography support support for natbib and biblatex +$-- +$if(natbib)$ +\usepackage[$natbiboptions$]{natbib} +\bibliographystyle{$if(biblio-style)$$biblio-style$$else$plainnat$endif$} +$endif$ +$if(biblatex)$ +\usepackage[$if(biblio-style)$style=$biblio-style$,$endif$$for(biblatexoptions)$$biblatexoptions$$sep$,$endfor$]{biblatex} +$for(bibliography)$ +\addbibresource{$bibliography$} +$endfor$ +$endif$ +$-- +$-- csquotes +$-- +$if(csquotes)$ +\usepackage[$for(csquotesoptions)$$csquotesoptions$$sep$,$endfor$]{csquotes} +$endif$ diff --git a/data/templates/default.beamer b/data/templates/default.beamer new file mode 100644 index 000000000000..b2eafaadf9f7 --- /dev/null +++ b/data/templates/default.beamer @@ -0,0 +1,204 @@ +$passoptions.latex()$ +\documentclass[ +$if(fontsize)$ + $fontsize$, +$endif$ + ignorenonframetext, +$if(handout)$ + handout, +$endif$ +$if(aspectratio)$ + aspectratio=$aspectratio$, +$endif$ +$if(babel-lang)$ + $babel-lang$, +$endif$ +$for(classoption)$ + $classoption$$sep$, +$endfor$ +]{$documentclass$} +$if(geometry)$ +\geometry{$for(geometry)$$geometry$$sep$,$endfor$} +$endif$ +\newif\ifbibliography +$if(background-image)$ +\usebackgroundtemplate{% + \includegraphics[width=\paperwidth]{$background-image$}% +} +% In beamer background-image does not work well when other images are used, so this is the workaround +\pgfdeclareimage[width=\paperwidth,height=\paperheight]{background}{$background-image$} +\usebackgroundtemplate{\pgfuseimage{background}} +$endif$ +\usepackage{pgfpages} +\setbeamertemplate{caption}[numbered] +\setbeamertemplate{caption label separator}{: } +\setbeamercolor{caption name}{fg=normal text.fg} +\beamertemplatenavigationsymbols$if(navigation)$$navigation$$else$empty$endif$ +$-- +$-- section numbering +$-- +$if(numbersections)$ +$else$ +% remove section numbering +\setbeamertemplate{part page}{ + \centering + \begin{beamercolorbox}[sep=16pt,center]{part title} + \usebeamerfont{part title}\insertpart\par + \end{beamercolorbox} +} +\setbeamertemplate{section page}{ + \centering + \begin{beamercolorbox}[sep=12pt,center]{section title} + \usebeamerfont{section title}\insertsection\par + \end{beamercolorbox} +} +\setbeamertemplate{subsection page}{ + \centering + \begin{beamercolorbox}[sep=8pt,center]{subsection title} + \usebeamerfont{subsection title}\insertsubsection\par + \end{beamercolorbox} +} +$endif$ +$for(beameroption)$ +\setbeameroption{$beameroption$} +$endfor$ +% Prevent slide breaks in the middle of a paragraph +\widowpenalties 1 10000 +\raggedbottom +$if(section-titles)$ +\AtBeginPart{ + \frame{\partpage} +} +\AtBeginSection{ + \ifbibliography + \else + \frame{\sectionpage} + \fi +} +\AtBeginSubsection{ + \frame{\subsectionpage} +} +$endif$ +$fonts.latex()$ +$-- Set Beamer theme before user font settings so they can override theme +$if(theme)$ +\usetheme[$for(themeoptions)$$themeoptions$$sep$,$endfor$]{$theme$} +$endif$ +$if(colortheme)$ +\usecolortheme[$for(colorthemeoptions)$$colorthemeoptions$$sep$,$endfor$]{$colortheme$} +$endif$ +$if(fonttheme)$ +\usefonttheme[$for(fontthemeoptions)$$fontthemeoptions$$sep$,$endfor$]{$fonttheme$} +$endif$ +$if(mainfont)$ +\usefonttheme{serif} % use mainfont rather than sansfont for slide text +$endif$ +$if(innertheme)$ +\useinnertheme[$for(innerthemeoptions)$$innerthemeoptions$$sep$,$endfor$]{$innertheme$} +$endif$ +$if(outertheme)$ +\useoutertheme[$for(outerthemeoptions)$$outerthemeoptions$$sep$,$endfor$]{$outertheme$} +$endif$ +$font-settings.latex()$ +$common.latex()$ +$for(header-includes)$ +$header-includes$ +$endfor$ +$after-header-includes.latex()$ +$hypersetup.latex()$ + +$if(title)$ +\title$if(shorttitle)$[$shorttitle$]$endif${$title$$if(thanks)$\thanks{$thanks$}$endif$} +$endif$ +$if(subtitle)$ +\subtitle$if(shortsubtitle)$[$shortsubtitle$]$endif${$subtitle$} +$endif$ +\author$if(shortauthor)$[$shortauthor$]$endif${$for(author)$$author$$sep$ \and $endfor$} +\date$if(shortdate)$[$shortdate$]$endif${$date$} +$if(institute)$ +\institute$if(shortinstitute)$[$shortinstitute$]$endif${$for(institute)$$institute$$sep$ \and $endfor$} +$endif$ +$if(titlegraphic)$ +\titlegraphic{ +$for(titlegraphic)$ + \includegraphics$if(titlegraphicoptions)$[$for(titlegraphicoptions)$$titlegraphicoptions$$sep$, $endfor$]$endif${$titlegraphic$}$sep$\enspace +$endfor$} +$endif$ +$if(logo)$ +\logo{\includegraphics{$logo$}} +$endif$ + +\begin{document} +$if(title)$ +\frame{\titlepage} +$if(abstract)$ +\begin{abstract} +$abstract$ +\end{abstract} +$endif$ +$endif$ + +$for(include-before)$ +$include-before$ + +$endfor$ +$if(toc)$ +$if(toc-title)$ +\renewcommand*\contentsname{$toc-title$} +$endif$ +\begin{frame}[allowframebreaks] +$if(toc-title)$ + \frametitle{$toc-title$} +$endif$ + \setcounter{tocdepth}{$toc-depth$} + \tableofcontents +\end{frame} +\setcounter{tocdepth}{$toc-depth$} +\tableofcontents +} +$endif$ +$if(lof)$ +\listoffigures +$endif$ +$if(lot)$ +\listoftables +$endif$ +$if(linestretch)$ +\setstretch{$linestretch$} +$endif$ +$body$ + +$if(natbib)$ +$if(bibliography)$ +$if(biblio-title)$ +$if(has-chapters)$ +\renewcommand\bibname{$biblio-title$} +$else$ +\renewcommand\refname{$biblio-title$} +$endif$ +$endif$ +\begin{frame}[allowframebreaks]{$biblio-title$} +$if(nocite-ids)$ + \nocite{$for(nocite-ids)$$it$$sep$, $endfor$} +$endif$ + \bibliographytrue + \bibliography{$for(bibliography)$$bibliography$$sep$,$endfor$} +\end{frame} + +$endif$ +$endif$ +$if(biblatex)$ +\begin{frame}[allowframebreaks]{$biblio-title$} +$if(nocite-ids)$ + \nocite{$for(nocite-ids)$$it$$sep$, $endfor$} +$endif$ + \bibliographytrue + \printbibliography[heading=none] +\end{frame} + +$endif$ +$for(include-after)$ +$include-after$ + +$endfor$ +\end{document} diff --git a/data/templates/default.context b/data/templates/default.context index 91e730c1b536..21d0c1e51d0b 100644 --- a/data/templates/default.context +++ b/data/templates/default.context @@ -1,3 +1,8 @@ +$if(tagging)$ +\setupbackend[format=pdf/ua-2] +\enabledirectives[backend.usetags=mkiv] +\setuptagging[state=start] +$endif$ $if(context-lang)$ \mainlanguage[$context-lang$] $endif$ @@ -60,19 +65,19 @@ $endif$ $-- set up font fallbacks $for(mainfontfallback)$ -\definefallbackfamily[mainface][rm][$mainfontfallback$][range=0x0000-0xFFFF, check=yes, force=no] +\definefallbackfamily[mainface][rm][$mainfontfallback/nowrap$][range=0x0000-0xFFFF, check=yes, force=no] $endfor$ $for(sansfontfallback)$ -\definefallbackfamily[mainface][ss][$sansfontfallback$][range=0x0000-0xFFFF, check=yes, force=no] +\definefallbackfamily[mainface][ss][$sansfontfallback/nowrap$][range=0x0000-0xFFFF, check=yes, force=no] $endfor$ $for(monofontfallback)$ -\definefallbackfamily[mainface][tt][$monofontfallback$][range=0x0000-0xFFFF, check=yes, force=no] +\definefallbackfamily[mainface][tt][$monofontfallback/nowrap$][range=0x0000-0xFFFF, check=yes, force=no] $endfor$ \definefallbackfamily[mainface][rm][CMU Serif][preset=range:greek, force=yes] -\definefontfamily[mainface][rm][$if(mainfont)$$mainfont$$else$Latin Modern Roman$endif$] -\definefontfamily[mainface][mm][$if(mathfont)$$mathfont$$else$Latin Modern Math$endif$] -\definefontfamily[mainface][ss][$if(sansfont)$$sansfont$$else$Latin Modern Sans$endif$] -\definefontfamily[mainface][tt][$if(monofont)$$monofont$$else$Latin Modern Typewriter$endif$][features=none] +\definefontfamily[mainface][rm][$if(mainfont)$$mainfont/nowrap$$else$Latin Modern Roman$endif$] +\definefontfamily[mainface][mm][$if(mathfont)$$mathfont/nowrap$$else$Latin Modern Math$endif$] +\definefontfamily[mainface][ss][$if(sansfont)$$sansfont/nowrap$$else$Latin Modern Sans$endif$] +\definefontfamily[mainface][tt][$if(monofont)$$monofont/nowrap$$else$Latin Modern Typewriter$endif$][features=none] \setupbodyfont[mainface$if(fontsize)$,$fontsize$$endif$] \setupwhitespace[$if(whitespace)$$whitespace$$else$medium$endif$] diff --git a/data/templates/default.latex b/data/templates/default.latex index 678583f999ad..781133776cda 100644 --- a/data/templates/default.latex +++ b/data/templates/default.latex @@ -1,563 +1,67 @@ -% Options for packages loaded elsewhere -\PassOptionsToPackage{unicode$for(hyperrefoptions)$,$hyperrefoptions$$endfor$}{hyperref} -\PassOptionsToPackage{hyphens}{url} -$if(colorlinks)$ -\PassOptionsToPackage{dvipsnames,svgnames,x11names}{xcolor} -$endif$ -$if(CJKmainfont)$ -\PassOptionsToPackage{space}{xeCJK} -$endif$ -% +$passoptions.latex()$ \documentclass[ +$for(babel-otherlangs)$ + $babel-otherlangs$, +$endfor$ +$if(babel-lang)$ + $babel-lang$, +$endif$ $if(fontsize)$ $fontsize$, $endif$ $if(papersize)$ $papersize$paper, $endif$ -$if(beamer)$ - ignorenonframetext, -$if(handout)$ - handout, -$endif$ -$if(aspectratio)$ - aspectratio=$aspectratio$, -$endif$ -$if(babel-lang)$ - $babel-lang$, -$endif$ -$endif$ $for(classoption)$ $classoption$$sep$, $endfor$ ]{$documentclass$} -$if(beamer)$ -$if(background-image)$ -\usebackgroundtemplate{% - \includegraphics[width=\paperwidth]{$background-image$}% -} -% In beamer background-image does not work well when other images are used, so this is the workaround -\pgfdeclareimage[width=\paperwidth,height=\paperheight]{background}{$background-image$} -\usebackgroundtemplate{\pgfuseimage{background}} -$endif$ -\usepackage{pgfpages} -\setbeamertemplate{caption}[numbered] -\setbeamertemplate{caption label separator}{: } -\setbeamercolor{caption name}{fg=normal text.fg} -\beamertemplatenavigationsymbols$if(navigation)$$navigation$$else$empty$endif$ -$for(beameroption)$ -\setbeameroption{$beameroption$} -$endfor$ -% Prevent slide breaks in the middle of a paragraph -\widowpenalties 1 10000 -\raggedbottom -$if(section-titles)$ -\setbeamertemplate{part page}{ - \centering - \begin{beamercolorbox}[sep=16pt,center]{part title} - \usebeamerfont{part title}\insertpart\par - \end{beamercolorbox} -} -\setbeamertemplate{section page}{ - \centering - \begin{beamercolorbox}[sep=12pt,center]{section title} - \usebeamerfont{section title}\insertsection\par - \end{beamercolorbox} -} -\setbeamertemplate{subsection page}{ - \centering - \begin{beamercolorbox}[sep=8pt,center]{subsection title} - \usebeamerfont{subsection title}\insertsubsection\par - \end{beamercolorbox} -} -\AtBeginPart{ - \frame{\partpage} -} -\AtBeginSection{ - \ifbibliography - \else - \frame{\sectionpage} - \fi -} -\AtBeginSubsection{ - \frame{\subsectionpage} -} -$endif$ -$endif$ $if(beamerarticle)$ \usepackage{beamerarticle} % needs to be loaded first $endif$ -\usepackage{amsmath,amssymb} -$if(linestretch)$ -\usepackage{setspace} -$endif$ -\usepackage{iftex} -\ifPDFTeX - \usepackage[$if(fontenc)$$fontenc$$else$T1$endif$]{fontenc} - \usepackage[utf8]{inputenc} - \usepackage{textcomp} % provide euro and other symbols -\else % if luatex or xetex -$if(mathspec)$ - \ifXeTeX - \usepackage{mathspec} % this also loads fontspec - \else - \usepackage{unicode-math} % this also loads fontspec - \fi -$else$ - \usepackage{unicode-math} % this also loads fontspec -$endif$ - \defaultfontfeatures{Scale=MatchLowercase}$-- must come before Beamer theme - \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1} -\fi -$if(fontfamily)$ -$else$ -$-- Set default font before Beamer theme so the theme can override it -\usepackage{lmodern} -$endif$ -$-- Set Beamer theme before user font settings so they can override theme -$if(beamer)$ -$if(theme)$ -\usetheme[$for(themeoptions)$$themeoptions$$sep$,$endfor$]{$theme$} -$endif$ -$if(colortheme)$ -\usecolortheme{$colortheme$} -$endif$ -$if(fonttheme)$ -\usefonttheme{$fonttheme$} -$endif$ -$if(mainfont)$ -\usefonttheme{serif} % use mainfont rather than sansfont for slide text -$endif$ -$if(innertheme)$ -\useinnertheme{$innertheme$} -$endif$ -$if(outertheme)$ -\useoutertheme{$outertheme$} -$endif$ -$endif$ -$-- User font settings (must come after default font and Beamer theme) -$if(fontfamily)$ -\usepackage[$for(fontfamilyoptions)$$fontfamilyoptions$$sep$,$endfor$]{$fontfamily$} -$endif$ -\ifPDFTeX\else - % xetex/luatex font selection -$if(mainfont)$ - $if(mainfontfallback)$ - \ifLuaTeX - \usepackage{luaotfload} - \directlua{luaotfload.add_fallback("mainfontfallback",{ - $for(mainfontfallback)$"$mainfontfallback$"$sep$,$endfor$ - })} - \fi - $endif$ - \setmainfont[$for(mainfontoptions)$$mainfontoptions$$sep$,$endfor$$if(mainfontfallback)$,RawFeature={fallback=mainfontfallback}$endif$]{$mainfont$} -$endif$ -$if(sansfont)$ - $if(sansfontfallback)$ - \ifLuaTeX - \usepackage{luaotfload} - \directlua{luaotfload.add_fallback("sansfontfallback",{ - $for(sansfontfallback)$"$sansfontfallback$"$sep$,$endfor$ - })} - \fi - $endif$ - \setsansfont[$for(sansfontoptions)$$sansfontoptions$$sep$,$endfor$$if(sansfontfallback)$,RawFeature={fallback=sansfontfallback}$endif$]{$sansfont$} -$endif$ -$if(monofont)$ - $if(monofontfallback)$ - \ifLuaTeX - \usepackage{luaotfload} - \directlua{luaotfload.add_fallback("monofontfallback",{ - $for(monofontfallback)$"$monofontfallback$"$sep$,$endfor$ - })} - \fi - $endif$ - \setmonofont[$for(monofontoptions)$$monofontoptions$$sep$,$endfor$$if(monofontfallback)$,RawFeature={fallback=monofontfallback}$endif$]{$monofont$} -$endif$ -$for(fontfamilies)$ - \newfontfamily{$fontfamilies.name$}[$for(fontfamilies.options)$$fontfamilies.options$$sep$,$endfor$]{$fontfamilies.font$} -$endfor$ -$if(mathfont)$ -$if(mathspec)$ - \ifXeTeX - \setmathfont(Digits,Latin,Greek)[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} - \else - \setmathfont[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} - \fi -$else$ - \setmathfont[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} -$endif$ -$endif$ -$if(CJKmainfont)$ - \ifXeTeX - \usepackage{xeCJK} - \setCJKmainfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmainfont$} - $if(CJKsansfont)$ - \setCJKsansfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKsansfont$} - $endif$ - $if(CJKmonofont)$ - \setCJKmonofont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmonofont$} - $endif$ - \fi -$endif$ -$if(luatexjapresetoptions)$ - \ifLuaTeX - \usepackage[$for(luatexjapresetoptions)$$luatexjapresetoptions$$sep$,$endfor$]{luatexja-preset} - \fi -$endif$ -$if(CJKmainfont)$ - \ifLuaTeX - \usepackage[$for(luatexjafontspecoptions)$$luatexjafontspecoptions$$sep$,$endfor$]{luatexja-fontspec} - \setmainjfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmainfont$} - \fi -$endif$ -\fi -$if(zero-width-non-joiner)$ -%% Support for zero-width non-joiner characters. -\makeatletter -\def\zerowidthnonjoiner{% - % Prevent ligatures and adjust kerning, but still support hyphenating. - \texorpdfstring{% - \TextOrMath{\nobreak\discretionary{-}{}{\kern.03em}% - \ifvmode\else\nobreak\hskip\z@skip\fi}{}% - }{}% -} -\makeatother -\ifPDFTeX - \DeclareUnicodeCharacter{200C}{\zerowidthnonjoiner} -\else - \catcode`^^^^200c=\active - \protected\def ^^^^200c{\zerowidthnonjoiner} -\fi -%% End of ZWNJ support -$endif$ -% Use upquote if available, for straight quotes in verbatim environments -\IfFileExists{upquote.sty}{\usepackage{upquote}}{} -\IfFileExists{microtype.sty}{% use microtype if available - \usepackage[$for(microtypeoptions)$$microtypeoptions$$sep$,$endfor$]{microtype} - \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts -}{} -$if(indent)$ -$else$ -\makeatletter -\@ifundefined{KOMAClassName}{% if non-KOMA class - \IfFileExists{parskip.sty}{% - \usepackage{parskip} - }{% else - \setlength{\parindent}{0pt} - \setlength{\parskip}{6pt plus 2pt minus 1pt}} -}{% if KOMA class - \KOMAoptions{parskip=half}} -\makeatother -$endif$ -$if(verbatim-in-note)$ -\usepackage{fancyvrb} -$endif$ \usepackage{xcolor} $if(geometry)$ -$if(beamer)$ -\geometry{$for(geometry)$$geometry$$sep$,$endfor$} -$else$ \usepackage[$for(geometry)$$geometry$$sep$,$endfor$]{geometry} $endif$ -$endif$ -$if(beamer)$ -\newif\ifbibliography -$endif$ -$if(listings)$ -\usepackage{listings} -\newcommand{\passthrough}[1]{#1} -\lstset{defaultdialect=[5.3]Lua} -\lstset{defaultdialect=[x86masm]Assembler} -$endif$ -$if(lhs)$ -\lstnewenvironment{code}{\lstset{language=Haskell,basicstyle=\small\ttfamily}}{} -$endif$ -$if(highlighting-macros)$ -$highlighting-macros$ -$endif$ -$if(tables)$ -\usepackage{longtable,booktabs,array} -$if(multirow)$ -\usepackage{multirow} -$endif$ -\usepackage{calc} % for calculating minipage widths -$if(beamer)$ -\usepackage{caption} -% Make caption package work with longtable -\makeatletter -\def\fnum@table{\tablename~\thetable} -\makeatother -$else$ -% Correct order of tables after \paragraph or \subparagraph -\usepackage{etoolbox} -\makeatletter -\patchcmd\longtable{\par}{\if@noskipsec\mbox{}\fi\par}{}{} -\makeatother -% Allow footnotes in longtable head/foot -\IfFileExists{footnotehyper.sty}{\usepackage{footnotehyper}}{\usepackage{footnote}} -\makesavenoteenv{longtable} -$endif$ -$endif$ -$if(graphics)$ -\usepackage{graphicx} -\makeatletter -\newsavebox\pandoc@box -\newcommand*\pandocbounded[1]{% scales image to fit in text height/width - \sbox\pandoc@box{#1}% - \Gscale@div\@tempa{\textheight}{\dimexpr\ht\pandoc@box+\dp\pandoc@box\relax}% - \Gscale@div\@tempb{\linewidth}{\wd\pandoc@box}% - \ifdim\@tempb\p@<\@tempa\p@\let\@tempa\@tempb\fi% select the smaller of both - \ifdim\@tempa\p@<\p@\scalebox{\@tempa}{\usebox\pandoc@box}% - \else\usebox{\pandoc@box}% - \fi% -} -% Set default figure placement to htbp -\def\fps@figure{htbp} -\makeatother -$endif$ -$if(svg)$ -\usepackage{svg} -$endif$ -$if(strikeout)$ -$-- also used for underline -\ifLuaTeX - \usepackage{luacolor} - \usepackage[soul]{lua-ul} -\else - \usepackage{soul} -$if(beamer)$ - \makeatletter - \let\HL\hl - \renewcommand\hl{% fix for beamer highlighting - \let\set@color\beamerorig@set@color - \let\reset@color\beamerorig@reset@color - \HL} - \makeatother -$endif$ -$if(CJKmainfont)$ - \ifXeTeX - % soul's \st doesn't work for CJK: - \usepackage{xeCJKfntef} - \renewcommand{\st}[1]{\sout{#1}} - \fi -$endif$ -\fi -$endif$ -\setlength{\emergencystretch}{3em} % prevent overfull lines -\providecommand{\tightlist}{% - \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} +\usepackage{amsmath,amssymb} +$-- +$-- section numbering +$-- $if(numbersections)$ \setcounter{secnumdepth}{$if(secnumdepth)$$secnumdepth$$else$5$endif$} $else$ \setcounter{secnumdepth}{-\maxdimen} % remove section numbering $endif$ -$if(subfigure)$ -\usepackage{subcaption} -$endif$ -$if(beamer)$ -$else$ -$if(block-headings)$ -% Make \paragraph and \subparagraph free-standing -\makeatletter -\ifx\paragraph\undefined\else - \let\oldparagraph\paragraph - \renewcommand{\paragraph}{ - \@ifstar - \xxxParagraphStar - \xxxParagraphNoStar - } - \newcommand{\xxxParagraphStar}[1]{\oldparagraph*{#1}\mbox{}} - \newcommand{\xxxParagraphNoStar}[1]{\oldparagraph{#1}\mbox{}} -\fi -\ifx\subparagraph\undefined\else - \let\oldsubparagraph\subparagraph - \renewcommand{\subparagraph}{ - \@ifstar - \xxxSubParagraphStar - \xxxSubParagraphNoStar - } - \newcommand{\xxxSubParagraphStar}[1]{\oldsubparagraph*{#1}\mbox{}} - \newcommand{\xxxSubParagraphNoStar}[1]{\oldsubparagraph{#1}\mbox{}} -\fi -\makeatother -$endif$ -$endif$ -$if(pagestyle)$ -\pagestyle{$pagestyle$} -$endif$ -$if(csl-refs)$ -% definitions for citeproc citations -\NewDocumentCommand\citeproctext{}{} -\NewDocumentCommand\citeproc{mm}{% - \begingroup\def\citeproctext{#2}\cite{#1}\endgroup} -\makeatletter - % allow citations to break across lines - \let\@cite@ofmt\@firstofone - % avoid brackets around text for \cite: - \def\@biblabel#1{} - \def\@cite#1#2{{#1\if@tempswa , #2\fi}} -\makeatother -\newlength{\cslhangindent} -\setlength{\cslhangindent}{1.5em} -\newlength{\csllabelwidth} -\setlength{\csllabelwidth}{3em} -\newenvironment{CSLReferences}[2] % #1 hanging-indent, #2 entry-spacing - {\begin{list}{}{% - \setlength{\itemindent}{0pt} - \setlength{\leftmargin}{0pt} - \setlength{\parsep}{0pt} - % turn on hanging indent if param 1 is 1 - \ifodd #1 - \setlength{\leftmargin}{\cslhangindent} - \setlength{\itemindent}{-1\cslhangindent} - \fi - % set entry spacing - \setlength{\itemsep}{#2\baselineskip}}} - {\end{list}} -\usepackage{calc} -\newcommand{\CSLBlock}[1]{\hfill\break\parbox[t]{\linewidth}{\strut\ignorespaces#1\strut}} -\newcommand{\CSLLeftMargin}[1]{\parbox[t]{\csllabelwidth}{\strut#1\strut}} -\newcommand{\CSLRightInline}[1]{\parbox[t]{\linewidth - \csllabelwidth}{\strut#1\strut}} -\newcommand{\CSLIndent}[1]{\hspace{\cslhangindent}#1} -$endif$ -$if(lang)$ -\ifLuaTeX -\usepackage[bidi=basic]{babel} -\else -\usepackage[bidi=default]{babel} -\fi -$if(babel-lang)$ -\babelprovide[main,import]{$babel-lang$} -$if(mainfont)$ -\ifPDFTeX -\else -\babelfont{rm}[$for(mainfontoptions)$$mainfontoptions$$sep$,$endfor$$if(mainfontfallback)$,RawFeature={fallback=mainfontfallback}$endif$]{$mainfont$} -\fi -$endif$ -$endif$ -$for(babel-otherlangs)$ -\babelprovide[import]{$babel-otherlangs$} -$endfor$ -$for(babelfonts/pairs)$ -\babelfont[$babelfonts.key$]{rm}{$babelfonts.value$} -$endfor$ -% get rid of language-specific shorthands (see #6817): -\let\LanguageShortHands\languageshorthands -\def\languageshorthands#1{} -$if(selnolig-langs)$ -\ifLuaTeX - \usepackage[$for(selnolig-langs)$$it$$sep$,$endfor$]{selnolig} % disable illegal ligatures -\fi -$endif$ -$endif$ +$fonts.latex()$ +$font-settings.latex()$ +$common.latex()$ $for(header-includes)$ $header-includes$ $endfor$ -$if(dir)$ -\ifPDFTeX - \TeXXeTstate=1 - \newcommand{\RL}[1]{\beginR #1\endR} - \newcommand{\LR}[1]{\beginL #1\endL} - \newenvironment{RTL}{\beginR}{\endR} - \newenvironment{LTR}{\beginL}{\endL} -\fi -$endif$ -$if(natbib)$ -\usepackage[$natbiboptions$]{natbib} -\bibliographystyle{$if(biblio-style)$$biblio-style$$else$plainnat$endif$} -$endif$ -$if(biblatex)$ -\usepackage[$if(biblio-style)$style=$biblio-style$,$endif$$for(biblatexoptions)$$biblatexoptions$$sep$,$endfor$]{biblatex} -$for(bibliography)$ -\addbibresource{$bibliography$} -$endfor$ -$endif$ -$if(nocite-ids)$ -\nocite{$for(nocite-ids)$$it$$sep$, $endfor$} -$endif$ -$if(csquotes)$ -\usepackage{csquotes} -$endif$ -\usepackage{bookmark} -\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available -\urlstyle{$if(urlstyle)$$urlstyle$$else$same$endif$} -$if(links-as-notes)$ -% Make links footnotes instead of hotlinks: -\DeclareRobustCommand{\href}[2]{#2\footnote{\url{#1}}} -$endif$ -$if(verbatim-in-note)$ -\VerbatimFootnotes % allow verbatim text in footnotes -$endif$ -\hypersetup{ -$if(title-meta)$ - pdftitle={$title-meta$}, -$endif$ -$if(author-meta)$ - pdfauthor={$author-meta$}, -$endif$ -$if(lang)$ - pdflang={$lang$}, -$endif$ -$if(subject)$ - pdfsubject={$subject$}, -$endif$ -$if(keywords)$ - pdfkeywords={$for(keywords)$$keywords$$sep$, $endfor$}, -$endif$ -$if(colorlinks)$ - colorlinks=true, - linkcolor={$if(linkcolor)$$linkcolor$$else$Maroon$endif$}, - filecolor={$if(filecolor)$$filecolor$$else$Maroon$endif$}, - citecolor={$if(citecolor)$$citecolor$$else$Blue$endif$}, - urlcolor={$if(urlcolor)$$urlcolor$$else$Blue$endif$}, -$else$ -$if(boxlinks)$ -$else$ - hidelinks, -$endif$ -$endif$ - pdfcreator={LaTeX via pandoc}} +$after-header-includes.latex()$ +$hypersetup.latex()$ $if(title)$ \title{$title$$if(thanks)$\thanks{$thanks$}$endif$} $endif$ $if(subtitle)$ -$if(beamer)$ -$else$ \usepackage{etoolbox} \makeatletter \providecommand{\subtitle}[1]{% add subtitle to \maketitle \apptocmd{\@title}{\par {\large #1 \par}}{}{} } \makeatother -$endif$ \subtitle{$subtitle$} $endif$ \author{$for(author)$$author$$sep$ \and $endfor$} \date{$date$} -$if(beamer)$ -$if(institute)$ -\institute{$for(institute)$$institute$$sep$ \and $endfor$} -$endif$ -$if(titlegraphic)$ -\titlegraphic{\includegraphics$if(titlegraphicoptions)$[$for(titlegraphicoptions)$$titlegraphicoptions$$sep$, $endfor$]$endif${$titlegraphic$}} -$endif$ -$if(logo)$ -\logo{\includegraphics{$logo$}} -$endif$ -$endif$ \begin{document} $if(has-frontmatter)$ \frontmatter $endif$ $if(title)$ -$if(beamer)$ -\frame{\titlepage} -$else$ \maketitle -$endif$ $if(abstract)$ \begin{abstract} $abstract$ @@ -573,15 +77,6 @@ $if(toc)$ $if(toc-title)$ \renewcommand*\contentsname{$toc-title$} $endif$ -$if(beamer)$ -\begin{frame}[allowframebreaks] -$if(toc-title)$ - \frametitle{$toc-title$} -$endif$ - \setcounter{tocdepth}{$toc-depth$} - \tableofcontents -\end{frame} -$else$ { $if(colorlinks)$ \hypersetup{linkcolor=$if(toccolor)$$toccolor$$else$$endif$} @@ -590,7 +85,6 @@ $endif$ \tableofcontents } $endif$ -$endif$ $if(lof)$ \listoffigures $endif$ @@ -608,6 +102,9 @@ $body$ $if(has-frontmatter)$ \backmatter $endif$ +$if(nocite-ids)$ +\nocite{$for(nocite-ids)$$it$$sep$, $endfor$} +$endif$ $if(natbib)$ $if(bibliography)$ $if(biblio-title)$ @@ -617,26 +114,12 @@ $else$ \renewcommand\refname{$biblio-title$} $endif$ $endif$ -$if(beamer)$ -\begin{frame}[allowframebreaks]{$biblio-title$} - \bibliographytrue -$endif$ - \bibliography{$for(bibliography)$$bibliography$$sep$,$endfor$} -$if(beamer)$ -\end{frame} -$endif$ +\bibliography{$for(bibliography)$$bibliography$$sep$,$endfor$} $endif$ $endif$ $if(biblatex)$ -$if(beamer)$ -\begin{frame}[allowframebreaks]{$biblio-title$} - \bibliographytrue - \printbibliography[heading=none] -\end{frame} -$else$ \printbibliography$if(biblio-title)$[title=$biblio-title$]$endif$ -$endif$ $endif$ $for(include-after)$ diff --git a/data/templates/default.ms b/data/templates/default.ms index 27c4f9b7f568..b7d918d76a9c 100644 --- a/data/templates/default.ms +++ b/data/templates/default.ms @@ -35,7 +35,7 @@ $endif$ .\" line height .nr VS $if(lineheight)$$lineheight$$else$12p$endif$ .\" font family: A, BM, H, HN, N, P, T, ZCM -.fam $if(fontfamily)$$fontfamily$$else$P$endif$ +.fam $if(fontfamily)$$fontfamily$$else$T$endif$ .\" paragraph indent .nr PI $if(indent)$$indent$$else$0m$endif$ .\" interparagraph space @@ -50,10 +50,6 @@ $if(papersize)$ $endif$ .\" color used for strikeout .defcolor strikecolor rgb 0.7 0.7 0.7 -.\" color for links (rgb) -.ds PDFHREF.COLOUR 0.35 0.00 0.60 -.\" border for links (default none) -.ds PDFHREF.BORDER 0 0 0 .\" point size difference between heading levels .nr PSINCR 1p .\" heading level above which point size no longer changes @@ -64,14 +60,6 @@ $endif$ .\" page numbers in footer, centered .ds CH .ds CF % -.\" pdf outline fold level -.nr PDFOUTLINE.FOLDLEVEL 3 -.\" start out in outline view -.pdfview /PageMode /UseOutlines -.\" *************************************************************** -.\" PDF metadata -.pdfinfo /Title "$title-meta$" -.pdfinfo /Author "$author-meta$" $if(adjusting)$ .ad $adjusting$ $endif$ @@ -85,6 +73,20 @@ $if(has-inline-math)$ delim @@ .EN $endif$ +$if(pdf-engine)$ +.\" color for links (rgb) +.ds PDFHREF.COLOUR 0.35 0.00 0.60 +.\" border for links (default none) +.ds PDFHREF.BORDER 0 0 0 +.\" pdf outline fold level +.nr PDFOUTLINE.FOLDLEVEL 3 +.\" start out in outline view +.pdfview /PageMode /UseOutlines +.\" *************************************************************** +.\" PDF metadata +.pdfinfo /Title "$title-meta$" +.pdfinfo /Author "$author-meta$" +$endif$ $for(header-includes)$ $header-includes$ $endfor$ diff --git a/data/templates/default.openxml b/data/templates/default.openxml index bfbf102d7ab7..1344857fe990 100644 --- a/data/templates/default.openxml +++ b/data/templates/default.openxml @@ -4,7 +4,7 @@ $if(title)$ - + $title$ @@ -12,7 +12,7 @@ $endif$ $if(subtitle)$ - + $subtitle$ @@ -20,7 +20,7 @@ $endif$ $for(author)$ - + $author$ @@ -28,7 +28,7 @@ $endfor$ $if(date)$ - + $date$ @@ -37,7 +37,7 @@ $if(abstract)$ $if(abstract-title)$ - + $abstract-title$ @@ -49,16 +49,17 @@ $for(include-before)$ $endfor$ $if(toc)$ $toc$ +$endif$ +$if(lof)$ + $lof$ +$endif$ +$if(lot)$ + $lot$ $endif$ $body$ $for(include-after)$ $include-after$ $endfor$ -$-- sectpr will be set to the last sectpr in a reference.docx, if present -$if(sectpr)$ $sectpr$ -$else$ - -$endif$ diff --git a/data/templates/default.typst b/data/templates/default.typst index 1e7b5efd422e..79b2c33f5833 100644 --- a/data/templates/default.typst +++ b/data/templates/default.typst @@ -1,4 +1,4 @@ -$definitions.typst()$ +#let horizontalrule = line(start: (25%,0%), end: (75%,0%)) #show terms: it => { it.children @@ -28,6 +28,11 @@ $else$ $template.typst()$ $endif$ +$if(smart)$ +$else$ +#set smartquote(enabled: false) + +$endif$ $for(header-includes)$ $header-includes$ @@ -84,6 +89,7 @@ $endif$ $if(section-numbering)$ sectionnumbering: "$section-numbering$", $endif$ + pagenumbering: $if(page-numbering)$"$page-numbering$"$else$none$endif$, cols: $if(columns)$$columns$$else$1$endif$, doc, ) diff --git a/data/templates/definitions.typst b/data/templates/definitions.typst deleted file mode 100644 index a6deba053e74..000000000000 --- a/data/templates/definitions.typst +++ /dev/null @@ -1,8 +0,0 @@ -// Some definitions presupposed by pandoc's typst output. -#let horizontalrule = [ - #line(start: (25%,0%), end: (75%,0%)) -] - -#let endnote(num, contents) = [ - #stack(dir: ltr, spacing: 3pt, super[#num], contents) -] diff --git a/data/templates/font-settings.latex b/data/templates/font-settings.latex new file mode 100644 index 000000000000..d1224b77967a --- /dev/null +++ b/data/templates/font-settings.latex @@ -0,0 +1,103 @@ +$-- User font settings (must come after default font and Beamer theme) +$if(fontfamily)$ +\usepackage[$for(fontfamilyoptions)$$fontfamilyoptions$$sep$,$endfor$]{$fontfamily$} +$endif$ +\ifPDFTeX\else + % xetex/luatex font selection +$if(mainfont)$ +$if(mainfontfallback)$ + \ifLuaTeX + \usepackage{luaotfload} + \directlua{luaotfload.add_fallback("mainfontfallback",{ + $for(mainfontfallback)$"$mainfontfallback$"$sep$,$endfor$ + })} + \fi +$endif$ + \setmainfont[$for(mainfontoptions)$$mainfontoptions$$sep$,$endfor$$if(mainfontfallback)$,RawFeature={fallback=mainfontfallback}$endif$]{$mainfont$} +$endif$ +$if(sansfont)$ +$if(sansfontfallback)$ + \ifLuaTeX + \usepackage{luaotfload} + \directlua{luaotfload.add_fallback("sansfontfallback",{ + $for(sansfontfallback)$"$sansfontfallback$"$sep$,$endfor$ + })} + \fi +$endif$ + \setsansfont[$for(sansfontoptions)$$sansfontoptions$$sep$,$endfor$$if(sansfontfallback)$,RawFeature={fallback=sansfontfallback}$endif$]{$sansfont$} +$endif$ +$if(monofont)$ +$if(monofontfallback)$ + \ifLuaTeX + \usepackage{luaotfload} + \directlua{luaotfload.add_fallback("monofontfallback",{ + $for(monofontfallback)$"$monofontfallback$"$sep$,$endfor$ + })} + \fi +$endif$ + \setmonofont[$for(monofontoptions)$$monofontoptions$$sep$,$endfor$$if(monofontfallback)$,RawFeature={fallback=monofontfallback}$endif$]{$monofont$} +$endif$ +$for(fontfamilies)$ + \newfontfamily{$fontfamilies.name$}[$for(fontfamilies.options)$$fontfamilies.options$$sep$,$endfor$]{$fontfamilies.font$} +$endfor$ +$if(mathfont)$ +$if(mathspec)$ + \ifXeTeX + \setmathfont(Digits,Latin,Greek)[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} + \else + \setmathfont[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} + \fi +$else$ + \setmathfont[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} +$endif$ +$endif$ +$if(CJKmainfont)$ + \ifXeTeX + \usepackage{xeCJK} + \setCJKmainfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmainfont$} +$if(CJKsansfont)$ + \setCJKsansfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKsansfont$} +$endif$ +$if(CJKmonofont)$ + \setCJKmonofont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmonofont$} +$endif$ + \fi +$endif$ +$if(luatexjapresetoptions)$ + \ifLuaTeX + \usepackage[$for(luatexjapresetoptions)$$luatexjapresetoptions$$sep$,$endfor$]{luatexja-preset} + \fi +$endif$ +$if(CJKmainfont)$ + \ifLuaTeX + \usepackage[$for(luatexjafontspecoptions)$$luatexjafontspecoptions$$sep$,$endfor$]{luatexja-fontspec} + \setmainjfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmainfont$} + \fi +$endif$ +\fi +$if(zero-width-non-joiner)$ +%% Support for zero-width non-joiner characters. +\makeatletter +\def\zerowidthnonjoiner{% + % Prevent ligatures and adjust kerning, but still support hyphenating. + \texorpdfstring{% + \TextOrMath{\nobreak\discretionary{-}{}{\kern.03em}% + \ifvmode\else\nobreak\hskip\z@skip\fi}{}% + }{}% +} +\makeatother +\ifPDFTeX + \DeclareUnicodeCharacter{200C}{\zerowidthnonjoiner} +\else + \catcode`^^^^200c=\active + \protected\def ^^^^200c{\zerowidthnonjoiner} +\fi +%% End of ZWNJ support +$endif$ +% Use upquote if available, for straight quotes in verbatim environments +\IfFileExists{upquote.sty}{\usepackage{upquote}}{} +\IfFileExists{microtype.sty}{% use microtype if available + \usepackage[$for(microtypeoptions)$$microtypeoptions$$sep$,$endfor$]{microtype} + \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts +}{} + diff --git a/data/templates/fonts.latex b/data/templates/fonts.latex new file mode 100644 index 000000000000..53a8e3c84390 --- /dev/null +++ b/data/templates/fonts.latex @@ -0,0 +1,23 @@ +\usepackage{iftex} +\ifPDFTeX + \usepackage[$if(fontenc)$$fontenc$$else$T1$endif$]{fontenc} + \usepackage[utf8]{inputenc} + \usepackage{textcomp} % provide euro and other symbols +\else % if luatex or xetex +$if(mathspec)$ + \ifXeTeX + \usepackage{mathspec} % this also loads fontspec + \else + \usepackage{unicode-math} % this also loads fontspec + \fi +$else$ + \usepackage{unicode-math} % this also loads fontspec +$endif$ + \defaultfontfeatures{Scale=MatchLowercase}$-- must come before Beamer theme + \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1} +\fi +$if(fontfamily)$ +$else$ +$-- Set default font before Beamer theme so the theme can override it +\usepackage{lmodern} +$endif$ diff --git a/data/templates/hypersetup.latex b/data/templates/hypersetup.latex new file mode 100644 index 000000000000..ff67655576e7 --- /dev/null +++ b/data/templates/hypersetup.latex @@ -0,0 +1,30 @@ +\hypersetup{ +$if(title-meta)$ + pdftitle={$title-meta$}, +$endif$ +$if(author-meta)$ + pdfauthor={$author-meta$}, +$endif$ +$if(lang)$ + pdflang={$lang$}, +$endif$ +$if(subject)$ + pdfsubject={$subject$}, +$endif$ +$if(keywords)$ + pdfkeywords={$for(keywords)$$keywords$$sep$, $endfor$}, +$endif$ +$if(colorlinks)$ + colorlinks=true, + linkcolor={$if(linkcolor)$$linkcolor$$else$Maroon$endif$}, + filecolor={$if(filecolor)$$filecolor$$else$Maroon$endif$}, + citecolor={$if(citecolor)$$citecolor$$else$Blue$endif$}, + urlcolor={$if(urlcolor)$$urlcolor$$else$Blue$endif$}, +$else$ +$if(boxlinks)$ +$else$ + hidelinks, +$endif$ +$endif$ + pdfcreator={LaTeX via pandoc}} + diff --git a/data/templates/passoptions.latex b/data/templates/passoptions.latex new file mode 100644 index 000000000000..c218b0d20152 --- /dev/null +++ b/data/templates/passoptions.latex @@ -0,0 +1,9 @@ +% Options for packages loaded elsewhere +\PassOptionsToPackage{unicode$for(hyperrefoptions)$,$hyperrefoptions$$endfor$}{hyperref} +\PassOptionsToPackage{hyphens}{url} +$if(colorlinks)$ +\PassOptionsToPackage{dvipsnames,svgnames,x11names}{xcolor} +$endif$ +$if(CJKmainfont)$ +\PassOptionsToPackage{space}{xeCJK} +$endif$ diff --git a/data/templates/styles.html b/data/templates/styles.html index cd3b95958f1c..9e253e3e141d 100644 --- a/data/templates/styles.html +++ b/data/templates/styles.html @@ -130,8 +130,8 @@ overflow: visible; } hr { - background-color: #1a1a1a; border: none; + border-top: 1px solid #1a1a1a; height: 1px; margin: 1em 0; } diff --git a/data/templates/template.typst b/data/templates/template.typst index 42532e1b24f0..1889bef6fa53 100644 --- a/data/templates/template.typst +++ b/data/templates/template.typst @@ -24,6 +24,7 @@ font: (), fontsize: 11pt, sectionnumbering: none, + pagenumbering: "1", doc, ) = { set document( @@ -34,8 +35,9 @@ set page( paper: paper, margin: margin, - numbering: "1", - ) + numbering: pagenumbering, + columns: cols, + ) set par(justify: true) set text(lang: lang, region: region, @@ -43,7 +45,8 @@ size: fontsize) set heading(numbering: sectionnumbering) - if title != none { + place(top, float: true, scope: "parent", clearance: 4mm)[ + #if title != none { align(center)[#block(inset: 2em)[ #text(weight: "bold", size: 1.5em)[#title] #(if subtitle != none { @@ -53,7 +56,7 @@ ]] } - if authors != none and authors != [] { + #if authors != none and authors != [] { let count = authors.len() let ncols = calc.min(count, 3) grid( @@ -69,21 +72,18 @@ ) } - if date != none { + #if date != none { align(center)[#block(inset: 1em)[ #date ]] } - if abstract != none { + #if abstract != none { block(inset: 2em)[ #text(weight: "semibold")[Abstract] #h(1em) #abstract ] } + ] - if cols == 1 { - doc - } else { - columns(cols, doc) - } + doc } diff --git a/data/translations/ua.yaml b/data/translations/ua.yaml index a17ba2de00af..51085d02b76d 100644 --- a/data/translations/ua.yaml +++ b/data/translations/ua.yaml @@ -16,7 +16,7 @@ Part: Частина Preface: Передмова Proof: Докази References: Література -See.: див. +See: див. SeeAlso: див. також Table: Таблиця To: До diff --git a/default.nix b/default.nix deleted file mode 100644 index 0aa98f0228ed..000000000000 --- a/default.nix +++ /dev/null @@ -1,13 +0,0 @@ -# default.nix -let - pkgs = import { }; -in - pkgs.haskellPackages.developPackage { - root = ./.; - modifier = drv: - pkgs.haskell.lib.addBuildTools drv (with pkgs.haskellPackages; - [ cabal-install - ghcid - ]); - } - diff --git a/doc/extras.md b/doc/extras.md index 3a4e86688339..18d505607583 100644 --- a/doc/extras.md +++ b/doc/extras.md @@ -20,7 +20,7 @@ complete list, see the [Pandoc Extras wiki page](https://github.com/jgm/pandoc/w ### Editor support - - [pandoc-mode](http://joostkremers.github.com/pandoc-mode/) for Emacs + - [pandoc-mode](http://joostkremers.github.io/pandoc-mode) for Emacs - [vim-pandoc](https://github.com/vim-pandoc) for Vim ### CLI wrappers @@ -47,7 +47,7 @@ complete list, see the [Pandoc Extras wiki page](https://github.com/jgm/pandoc/w process Markdown documents with integrated data and charts (integrates pandoc). - [pandoc-plot](https://github.com/LaurentRDC/pandoc-plot) - allows you to integrate programatically generated plots + allows you to integrate programmatically generated plots generated by various tools. ### Citations @@ -95,10 +95,12 @@ complete list, see the [Pandoc Extras wiki page](https://github.com/jgm/pandoc/w repository](https://github.com/pandoc/lua-filters).) - [Spell - checking](https://github.com/pandoc/lua-filters/tree/master/spellcheck) + checking](https://github.com/pandoc/lua-filters/tree/master/spellcheck). - [Word count](https://github.com/pandoc/lua-filters/tree/master/wordcount). - [Embed textually-specified - diagrams](https://github.com/pandoc/lua-filters/tree/master/diagram-generator) in PlantUML, Graphviz, TikZ, and Python. + diagrams](https://github.com/pandoc-ext/diagram) in Mermaid, Dot/GraphViz, + PlantUML, Asymptote, CeTZ, and TikZ. + - [Create subfigures in pandoc's Markdown](https://github.com/rnwst/pandoc-subfigs). - [Handle scholarly metadata](https://github.com/pandoc/lua-filters/tree/master/scholarly-metadata). - [Panda](http://christophe.delord.free.fr/panda/) provides diff --git a/doc/jats.md b/doc/jats.md index bbcfb724bbed..a723ccce506d 100644 --- a/doc/jats.md +++ b/doc/jats.md @@ -61,6 +61,85 @@ Metadata Values set it used, as affiliation links are not allowed in that schema. + `roles` + : a list of dictionaries describing the author's role(s). + Each role is added as an [``] element to + the author's [``] element. The following examples + illustrate: + + An ad-hoc role: + + ```yaml + roles: + - name: Dolphin Catcher + ``` + + A role specified with CRediT. + + ```yaml + roles: + - credit: writing-review-editing + ``` + + The `credit-name` is automatically looked up from + the CRediT taxonomy, but you can also specify it + yourself: + + ```yaml + roles: + - credit: writing-review-editing + credit-name: Writing – review & editing + ``` + + A role specified with CRediT, including an + optional degree of contribution. Note that + specifying the degree only is allowed when + using CRediT roles and not ad-hoc roles. + + ```yaml + roles: + - credit: writing-review-editing + degree: Lead + ``` + + A role specified with CRediT with a label override, + useful for internationalization: + + ```yaml + roles: + - credit: writing-review-editing + name: Escrita – revisão e edição + ``` + + The value for `credit` and `credit-name` + must be from one of the 14 terms from the + Contribution Role Taxonomy (CRediT): + + | `credit` | `credit-name` | + |--------------------------|----------------------------| + | `conceptualization` | Conceptualization | + | `data-curation` | Data curation | + | `formal-analysis` | Formal analysis | + | `funding-acquisition` | Funding acquisition | + | `investigation` | Investigation | + | `methodology` | Methodology | + | `project-administration` | Project administration | + | `resources` | Resources | + | `software` | Software | + | `supervision` | Supervision | + | `validation` | Validation | + | `visualization` | Visualization | + | `writing-original-draft` | Writing – original draft | + | `writing-review-editing` | Writing – review & editing | + + JATS suggests in [``] to use one of + the following three values when specifying the degree of + contribution: + + 1. `Lead` + 2. `Equal` + 3. `Supporting` + `equal-contrib` : boolean attribute used to mark authors who contributed equally to the work. The @@ -399,6 +478,13 @@ Metadata Values via the [``][elem:supplementary-material] element. Only available with `jats_articlepublishing`. +`floats-group` +: List of floating objects, such as figures, tables, text boxes, + etc., that are not part of the main text. The value is + rendered by nesting it below a + [``][elem:floats-group] element. Only available + with `jats_publishing` and `jats_archiving`. + Required Metadata ----------------- @@ -445,6 +531,7 @@ Required metadata values: [elem:copyright-year]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/copyright-year.html [elem:corresp]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/corresp.html [elem:email]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/email.html +[elem:floats-group]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/floats-group.html [elem:fn]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/fn.html [elem:funding-statement]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/funding-statement.html [elem:given-names]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/given-names.html @@ -475,3 +562,5 @@ Required metadata values: [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution-wrap.html [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution.html [``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/pub-date.html +[``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/role.html +[``]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/degree-contribution.html diff --git a/doc/libraries.md b/doc/libraries.md index 2fbcf94b7f17..6e0abdd8a7b9 100644 --- a/doc/libraries.md +++ b/doc/libraries.md @@ -7,17 +7,14 @@ The following Haskell libraries have been developed to support pandoc: -[skylighting-core] and [skylighting] -: Syntax highlighting engine supporting over 140 languages. - [citeproc] : Citation processing using CSL stylesheets. -[texmath] -: Conversion of math between tex, Word equation, MathML, and GNU eqn. +[commonmark], [commonmark-extensions], and [commonmark-pandoc] +: Efficient, standards-compliant parser for commonmark and extensions. -[unicode-collation] -: Proper Unicode collation (sorting). +[djot] +: Parser and renderer for djot light markup syntax. [doclayout] : Combinators for laying out a textual document, with support @@ -26,64 +23,83 @@ pandoc: [doctemplates] : Supports pandoc's templates. -[commonmark], [commonmark-extensions], and [commonmark-pandoc] -: Efficient, standards-compliant parser for commonmark and extensions. +[emojis] +: Conversion between emoji characters and aliases. + +[gridtables] +: Support for parsing grid style textual tables. + +[hslua-aeson] +: Converter from aeson data types to Lua objects. + +[hslua-cli] +: Command-line interface mimicking the default `lua` executable. + +[hslua-module-doclayout] +: Lua bindings to the doclayout library mentioned above. + +[hslua-module-path], [-system], [-text], and [-version] +: Lua modules that expose functionality of basic Haskell + libraries to Lua. + +[hslua-objectorientation], [hslua-packaging] +: Bindings, wrappers, and helper functions to access Haskell data + types from Lua via an object-oriented interface. [ipynb] : Representation of Jupyter notebooks and conversion to and from JSON. -[zip-archive] -: A pure zip file creator and extractor, used by pandoc for - docx, ODT, and EPUB. +[jira-wiki-markup] +: Support for parsing Jira wiki syntax. [rfc5051] : Simple unicode collation (used for citation sorting). -[emojis] -: Conversion between emoji characters and aliases. - -[jira-wiki-markup] -: Support for parsing Jira wiki syntax. +[skylighting-core] and [skylighting] +: Syntax highlighting engine supporting over 140 languages. -[gridtables] -: Support for parsing grid style textual tables. +[texmath] +: Conversion of math between tex, Word equation, MathML, and GNU eqn. -[hslua-objectorientation], [hslua-packaging] -: Bindings, wrappers, and helper functions to access Haskell data - types from Lua via an object-oriented interface. +[typst] +: Parsing and evaluating typst syntax. -[hslua-module-path], [-system], [-text], and [-version] -: Lua modules that expose functionality of basic Haskell - libraries to Lua. +[typst-symbol] +: Symbol and emoji lookup for typst language. -[hslua-aeson] -: Converter from aeson data types to Lua objects. +[unicode-collation] +: Proper Unicode collation (sorting). -[hslua-cli] -: Command-line interface mimicking the default `lua` executable. +[zip-archive] +: A pure zip file creator and extractor, used by pandoc for + docx, ODT, and EPUB. -[skylighting]: https://hackage.haskell.org/package/skylighting -[skylighting-core]: https://hackage.haskell.org/package/skylighting-core [citeproc]: https://hackage.haskell.org/package/citeproc -[texmath]: https://hackage.haskell.org/package/texmath -[doclayout]: https://hackage.haskell.org/package/doclayout -[doctemplates]: https://hackage.haskell.org/package/doctemplates -[commonmark]: https://hackage.haskell.org/package/commonmark [commonmark-extensions]: https://hackage.haskell.org/package/commonmark-extensions [commonmark-pandoc]: https://hackage.haskell.org/package/commonmark-pandoc -[ipynb]: https://hackage.haskell.org/package/ipynb -[zip-archive]: https://hackage.haskell.org/package/zip-archive -[rfc5051]: https://hackage.haskell.org/package/rfc5051 +[commonmark]: https://hackage.haskell.org/package/commonmark +[djot]: https://hackage.haskell.org/package/djot +[doclayout]: https://hackage.haskell.org/package/doclayout +[doctemplates]: https://hackage.haskell.org/package/doctemplates [emojis]: https://hackage.haskell.org/package/emojis -[jira-wiki-markup]: https://hackage.haskell.org/package/jira-wiki-markup -[unicode-collation]: https://hackage.haskell.org/package/unicode-collation [gridtables]: https://hackage.haskell.org/package/gridtables -[hslua-objectorientation]: https://hackage.haskell.org/package/hslua-objectorientation -[hslua-packaging]: https://hackage.haskell.org/package/hslua-packaging [hslua-aeson]: https://hackage.haskell.org/package/hslua-aeson [hslua-cli]: https://hackage.haskell.org/package/hslua-cli +[hslua-module-doclayout]: https://hackage.haskell.org/package/hslua-module-doclayout [hslua-module-path]: https://hackage.haskell.org/package/hslua-module-path [-system]: https://hackage.haskell.org/package/hslua-module-system [-text]: https://hackage.haskell.org/package/hslua-module-text [-version]: https://hackage.haskell.org/package/hslua-module-version +[hslua-objectorientation]: https://hackage.haskell.org/package/hslua-objectorientation +[hslua-packaging]: https://hackage.haskell.org/package/hslua-packaging +[ipynb]: https://hackage.haskell.org/package/ipynb +[jira-wiki-markup]: https://hackage.haskell.org/package/jira-wiki-markup +[rfc5051]: https://hackage.haskell.org/package/rfc5051 +[skylighting-core]: https://hackage.haskell.org/package/skylighting-core +[skylighting]: https://hackage.haskell.org/package/skylighting +[texmath]: https://hackage.haskell.org/package/texmath +[typst-symbol]: https://hackage.haskell.org/package/typst-symbol +[typst]: https://hackage.haskell.org/package/typst +[unicode-collation]: https://hackage.haskell.org/package/unicode-collation +[zip-archive]: https://hackage.haskell.org/package/zip-archive diff --git a/doc/lua-filters.md b/doc/lua-filters.md index 9de10cfbf9cc..f728e5bdbec2 100644 --- a/doc/lua-filters.md +++ b/doc/lua-filters.md @@ -40,11 +40,9 @@ to small caps: ``` lua return { - { - Strong = function (elem) - return pandoc.SmallCaps(elem.content) - end, - } + Strong = function (elem) + return pandoc.SmallCaps(elem.content) + end, } ``` @@ -187,7 +185,7 @@ local filter = { traverse = 'topdown', -- ... filter functions ... } -return {filter} +return filter ``` Support for this was added in pandoc 2.17; previous versions @@ -400,6 +398,11 @@ colon syntax (`mystring:uc_upper()`). # Debugging Lua filters +Many errors can be avoided by performing static analysis. +[`luacheck`](https://github.com/lunarmodules/luacheck) may be used +for this purpose. A Luacheck configuration file for pandoc filters +is available at . + William Lupton has written a Lua module with some handy functions for debugging Lua filters, including functions that can pretty-print the Pandoc AST elements manipulated @@ -424,7 +427,7 @@ its dependency install by adding `path.lua = "/path/to/your/lua"` in your ZeroBrane settings file. Next, open your Lua filter in ZeroBrane, and add `require('mobdebug').start()` at the line where you want your -breakpoint. Then make sure the Project > Lua Intepreter is set to the +breakpoint. Then make sure the Project > Lua Interpreter is set to the "Lua" you added in settings and enable "Start Debugger Server" [see detailed instructions here](https://studio.zerobrane.com/doc-remote-debugging). Run Pandoc @@ -1029,7 +1032,7 @@ Usage: A block quote element. Values of this type can be created with the -[`pandoc.BlockQuote`](#pandoc.blockquote) constructor. +[`pandoc.BlockQuote`](#pandoc.BlockQuote) constructor. Fields: @@ -1044,7 +1047,7 @@ Fields: A bullet list. Values of this type can be created with the -[`pandoc.BulletList`](#pandoc.bulletlist) constructor. +[`pandoc.BulletList`](#pandoc.BulletList) constructor. Fields: @@ -1059,7 +1062,7 @@ Fields: Block of code. Values of this type can be created with the -[`pandoc.CodeBlock`](#pandoc.codeblock) constructor. +[`pandoc.CodeBlock`](#pandoc.CodeBlock) constructor. Fields: @@ -1086,7 +1089,7 @@ Fields: Definition list, containing terms and their explanation. Values of this type can be created with the -[`pandoc.DefinitionList`](#pandoc.definitionlist) constructor. +[`pandoc.DefinitionList`](#pandoc.DefinitionList) constructor. Fields: @@ -1101,7 +1104,7 @@ Fields: Generic block container with attributes. Values of this type can be created with the -[`pandoc.Div`](#pandoc.div) constructor. +[`pandoc.Div`](#pandoc.Div) constructor. Fields: @@ -1129,7 +1132,7 @@ Fields: Figure with caption and arbitrary block contents. Values of this type can be created with the -[`pandoc.Figure`](#pandoc.figure) constructor. +[`pandoc.Figure`](#pandoc.Figure) constructor. Fields: @@ -1159,7 +1162,7 @@ Fields: Creates a header element. Values of this type can be created with the -[`pandoc.Header`](#pandoc.header) constructor. +[`pandoc.Header`](#pandoc.Header) constructor. Fields: @@ -1190,7 +1193,7 @@ Fields: A horizontal rule. Values of this type can be created with the -[`pandoc.HorizontalRule`](#pandoc.horizontalrule) constructor. +[`pandoc.HorizontalRule`](#pandoc.HorizontalRule) constructor. Fields: @@ -1203,7 +1206,7 @@ A line block, i.e. a list of lines, each separated from the next by a newline. Values of this type can be created with the -[`pandoc.LineBlock`](#pandoc.lineblock) constructor. +[`pandoc.LineBlock`](#pandoc.LineBlock) constructor. Fields: @@ -1218,7 +1221,7 @@ Fields: An ordered list. Values of this type can be created with the -[`pandoc.OrderedList`](#pandoc.orderedlist) constructor. +[`pandoc.OrderedList`](#pandoc.OrderedList) constructor. Fields: @@ -1245,7 +1248,7 @@ Fields: A paragraph. Values of this type can be created with the -[`pandoc.Para`](#pandoc.para) constructor. +[`pandoc.Para`](#pandoc.Para) constructor. Fields: @@ -1260,7 +1263,7 @@ Fields: Plain text, not a paragraph. Values of this type can be created with the -[`pandoc.Plain`](#pandoc.plain) constructor. +[`pandoc.Plain`](#pandoc.Plain) constructor. Fields: @@ -1275,7 +1278,7 @@ Fields: Raw content of a specified format. Values of this type can be created with the -[`pandoc.RawBlock`](#pandoc.rawblock) constructor. +[`pandoc.RawBlock`](#pandoc.RawBlock) constructor. Fields: @@ -1293,7 +1296,7 @@ Fields: A table. Values of this type can be created with the -[`pandoc.Table`](#pandoc.table) constructor. +[`pandoc.Table`](#pandoc.Table) constructor. Fields: @@ -1435,7 +1438,7 @@ Usage: Citation. Values of this type can be created with the -[`pandoc.Cite`](#pandoc.cite) constructor. +[`pandoc.Cite`](#pandoc.Cite) constructor. Fields: @@ -1453,7 +1456,7 @@ Fields: Inline code Values of this type can be created with the -[`pandoc.Code`](#pandoc.code) constructor. +[`pandoc.Code`](#pandoc.Code) constructor. Fields: @@ -1480,7 +1483,7 @@ Fields: Emphasized text Values of this type can be created with the -[`pandoc.Emph`](#pandoc.emph) constructor. +[`pandoc.Emph`](#pandoc.Emph) constructor. Fields: @@ -1495,7 +1498,7 @@ Fields: Image: alt text (list of inlines), target Values of this type can be created with the -[`pandoc.Image`](#pandoc.image) constructor. +[`pandoc.Image`](#pandoc.Image) constructor. Fields: @@ -1528,7 +1531,7 @@ Fields: Hard line break Values of this type can be created with the -[`pandoc.LineBreak`](#pandoc.linebreak) constructor. +[`pandoc.LineBreak`](#pandoc.LineBreak) constructor. Fields: @@ -1540,7 +1543,7 @@ Fields: Hyperlink: alt text (list of inlines), target Values of this type can be created with the -[`pandoc.Link`](#pandoc.link) constructor. +[`pandoc.Link`](#pandoc.Link) constructor. Fields: @@ -1573,7 +1576,7 @@ Fields: TeX math (literal) Values of this type can be created with the -[`pandoc.Math`](#pandoc.math) constructor. +[`pandoc.Math`](#pandoc.Math) constructor. Fields: @@ -1593,7 +1596,7 @@ Fields: Footnote or endnote Values of this type can be created with the -[`pandoc.Note`](#pandoc.note) constructor. +[`pandoc.Note`](#pandoc.Note) constructor. Fields: @@ -1608,7 +1611,7 @@ Fields: Quoted text Values of this type can be created with the -[`pandoc.Quoted`](#pandoc.quoted) constructor. +[`pandoc.Quoted`](#pandoc.Quoted) constructor. Fields: @@ -1627,7 +1630,7 @@ Fields: Raw inline Values of this type can be created with the -[`pandoc.RawInline`](#pandoc.rawinline) constructor. +[`pandoc.RawInline`](#pandoc.RawInline) constructor. Fields: @@ -1645,7 +1648,7 @@ Fields: Small caps text Values of this type can be created with the -[`pandoc.SmallCaps`](#pandoc.smallcaps) constructor. +[`pandoc.SmallCaps`](#pandoc.Smallcaps) constructor. Fields: @@ -1660,7 +1663,7 @@ Fields: Soft line break Values of this type can be created with the -[`pandoc.SoftBreak`](#pandoc.softbreak) constructor. +[`pandoc.SoftBreak`](#pandoc.Softbreak) constructor. Fields: @@ -1672,7 +1675,7 @@ Fields: Inter-word space Values of this type can be created with the -[`pandoc.Space`](#pandoc.space) constructor. +[`pandoc.Space`](#pandoc.Space) constructor. Fields: @@ -1684,7 +1687,7 @@ Fields: Generic inline container with attributes Values of this type can be created with the -[`pandoc.Span`](#pandoc.span) constructor. +[`pandoc.Span`](#pandoc.Span) constructor. Fields: @@ -1711,7 +1714,7 @@ Fields: Text Values of this type can be created with the -[`pandoc.Str`](#pandoc.str) constructor. +[`pandoc.Str`](#pandoc.Str) constructor. Fields: @@ -1726,7 +1729,7 @@ Fields: Strikeout text Values of this type can be created with the -[`pandoc.Strikeout`](#pandoc.strikeout) constructor. +[`pandoc.Strikeout`](#pandoc.Strikeout) constructor. Fields: @@ -1741,7 +1744,7 @@ Fields: Strongly emphasized text Values of this type can be created with the -[`pandoc.Strong`](#pandoc.strong) constructor. +[`pandoc.Strong`](#pandoc.Strong) constructor. Fields: @@ -1756,7 +1759,7 @@ Fields: Subscripted text Values of this type can be created with the -[`pandoc.Subscript`](#pandoc.subscript) constructor. +[`pandoc.Subscript`](#pandoc.Subscript) constructor. Fields: @@ -1771,7 +1774,7 @@ Fields: Superscripted text Values of this type can be created with the -[`pandoc.Superscript`](#pandoc.superscript) constructor. +[`pandoc.Superscript`](#pandoc.Superscript) constructor. Fields: @@ -1786,7 +1789,7 @@ Fields: Underlined text Values of this type can be created with the -[`pandoc.Underline`](#pandoc.underline) constructor. +[`pandoc.Underline`](#pandoc.Underline) constructor. Fields: @@ -1855,7 +1858,7 @@ Usage: ### Attr {#type-attr} A set of element attributes. Values of this type can be created -with the [`pandoc.Attr`](#pandoc.attr) constructor. For +with the [`pandoc.Attr`](#pandoc.Attr) constructor. For convenience, it is usually not necessary to construct the value directly if it is part of an element, and it is sufficient to pass an HTML-like table. E.g., to create a span with identifier @@ -1981,7 +1984,7 @@ components: List attributes Values of this type can be created with the -[`pandoc.ListAttributes`](#pandoc.listattributes) constructor. +[`pandoc.ListAttributes`](#pandoc.ListAttributes) constructor. Fields: @@ -2154,9 +2157,9 @@ Fields: value `nil` means that no highlighting is used. (table|nil) `html_math_method` -: How to print math in HTML; one 'plain', 'gladtex', 'webtex', - 'mathml', 'mathjax', or a table with keys `method` and - `url`. (string|table) +: How to print math in HTML; one of 'plain', 'mathjax', + 'mathml', 'webtex', 'katex', 'gladtex', or a table with keys + `method` and `url`. (string|table) `html_q_tags` : Use `` tags for quotes in HTML (boolean) @@ -2378,7 +2381,7 @@ Comparisons are performed element-wise, i.e. Version '1.12' > Version '1.9' Values of this type can be created with the -[`pandoc.types.Version`](#pandoc.types.version) constructor. +[`pandoc.types.Version`](#pandoc.types.Version) constructor. ### `must_be_at_least` @@ -2531,7 +2534,7 @@ Parameters: Returns: -- new Pandoc document ([Pandoc]) +- new Pandoc document ([Pandoc]) ### Meta {#pandoc.Meta} @@ -2544,7 +2547,7 @@ Parameters: Returns: -- new Meta table (table) +- new Meta table (table) ### MetaBlocks {#pandoc.MetaBlocks} @@ -2561,7 +2564,7 @@ Parameters: Returns: -- list of Block elements ([Blocks]) +- list of Block elements ([Blocks]) ### MetaBool {#pandoc.MetaBool} @@ -2574,7 +2577,7 @@ Parameters: Returns: -- input, unchanged (boolean) +- input, unchanged (boolean) ### MetaInlines {#pandoc.MetaInlines} @@ -2591,7 +2594,7 @@ Parameters: Returns: -- list of Inline elements ([Inlines]) +- list of Inline elements ([Inlines]) ### MetaList {#pandoc.MetaList} @@ -2608,7 +2611,7 @@ Parameters: Returns: -- list of meta values ([List]{unknown-type="List"}) +- list of meta values ([List]{unknown-type="List"}) ### MetaMap {#pandoc.MetaMap} @@ -2625,7 +2628,7 @@ Parameters: Returns: -- map of meta values (table) +- map of meta values (table) ### MetaString {#pandoc.MetaString} @@ -2642,7 +2645,7 @@ Parameters: Returns: -- unchanged input (string) +- unchanged input (string) ### BlockQuote {#pandoc.BlockQuote} @@ -2657,7 +2660,7 @@ Parameters: Returns: -- BlockQuote element ([Block]) +- BlockQuote element ([Block]) ### BulletList {#pandoc.BulletList} @@ -2672,7 +2675,7 @@ Parameters: Returns: -- BulletList element ([Block]) +- BulletList element ([Block]) ### CodeBlock {#pandoc.CodeBlock} @@ -2690,7 +2693,7 @@ Parameters: Returns: -- CodeBlock element ([Block]) +- CodeBlock element ([Block]) ### DefinitionList {#pandoc.DefinitionList} @@ -2706,7 +2709,7 @@ Parameters: Returns: -- DefinitionList element ([Block]) +- DefinitionList element ([Block]) ### Div {#pandoc.Div} @@ -2724,7 +2727,7 @@ Parameters: Returns: -- Div element ([Block]) +- Div element ([Block]) ### Figure {#pandoc.Figure} @@ -2745,7 +2748,7 @@ Parameters: Returns: -- Figure object ([Block]) +- Figure object ([Block]) ### Header {#pandoc.Header} @@ -2766,7 +2769,7 @@ Parameters: Returns: -- Header element ([Block]) +- Header element ([Block]) ### HorizontalRule {#pandoc.HorizontalRule} @@ -2776,7 +2779,7 @@ Creates a horizontal rule. Returns: -- HorizontalRule element ([Block]) +- HorizontalRule element ([Block]) ### LineBlock {#pandoc.LineBlock} @@ -2791,7 +2794,7 @@ Parameters: Returns: -- LineBlock element ([Block]) +- LineBlock element ([Block]) ### OrderedList {#pandoc.OrderedList} @@ -2809,7 +2812,7 @@ Parameters: Returns: -- OrderedList element ([Block]) +- OrderedList element ([Block]) ### Para {#pandoc.Para} @@ -2824,7 +2827,7 @@ Parameters: Returns: -- Para element ([Block]) +- Para element ([Block]) ### Plain {#pandoc.Plain} @@ -2839,7 +2842,7 @@ Parameters: Returns: -- Plain element ([Block]) +- Plain element ([Block]) ### RawBlock {#pandoc.RawBlock} @@ -2857,7 +2860,7 @@ Parameters: Returns: -- RawBlock element ([Block]) +- RawBlock element ([Block]) ### Table {#pandoc.Table} @@ -2887,7 +2890,7 @@ Parameters: Returns: -- Table element ([Block]) +- Table element ([Block]) ### Blocks {#pandoc.Blocks} @@ -2903,25 +2906,25 @@ Parameters: Returns: -- list of block elements ([Blocks]) +- list of block elements ([Blocks]) ### Cite {#pandoc.Cite} -`Cite (Inlines, citations)` +`Cite (content, citations)` Creates a Cite inline element Parameters: -`Inlines` -: placeholder content ([content]{unknown-type="content"}) +`content` +: placeholder content ([Inlines]) `citations` : List of Citations ({[Citation]{unknown-type="Citation"},\...}) Returns: -- cite element ([Inline]) +- cite element ([Inline]) ### Code {#pandoc.Code} @@ -2939,7 +2942,7 @@ Parameters: Returns: -- code element ([Inline]) +- code element ([Inline]) ### Emph {#pandoc.Emph} @@ -2954,7 +2957,7 @@ Parameters: Returns: -- new object ([Inline]) +- new object ([Inline]) ### Image {#pandoc.Image} @@ -2978,7 +2981,7 @@ Parameters: Returns: -- Image element ([Inline]) +- Image element ([Inline]) ### LineBreak {#pandoc.LineBreak} @@ -2988,7 +2991,7 @@ Create a LineBreak inline element Returns: -- line break ([Inline]) +- line break ([Inline]) ### Link {#pandoc.Link} @@ -3012,7 +3015,7 @@ Parameters: Returns: -- link element ([Inline]) +- link element ([Inline]) ### Math {#pandoc.Math} @@ -3030,7 +3033,7 @@ Parameters: Returns: -- math element ([Inline]) +- math element ([Inline]) ### Note {#pandoc.Note} @@ -3045,7 +3048,7 @@ Parameters: Returns: -- note ([Inline]) +- note ([Inline]) ### Quoted {#pandoc.Quoted} @@ -3064,7 +3067,7 @@ Parameters: Returns: -- quoted element ([Inline]) +- quoted element ([Inline]) ### RawInline {#pandoc.RawInline} @@ -3082,7 +3085,7 @@ Parameters: Returns: -- raw inline element ([Inline]) +- raw inline element ([Inline]) ### SmallCaps {#pandoc.SmallCaps} @@ -3097,7 +3100,7 @@ Parameters: Returns: -- new object ([Inline]) +- new object ([Inline]) ### SoftBreak {#pandoc.SoftBreak} @@ -3107,7 +3110,7 @@ Creates a SoftBreak inline element. Returns: -- soft break ([Inline]) +- soft break ([Inline]) ### Space {#pandoc.Space} @@ -3117,7 +3120,7 @@ Create a Space inline element Returns: -- new space ([Inline]) +- new space ([Inline]) ### Span {#pandoc.Span} @@ -3135,7 +3138,7 @@ Parameters: Returns: -- [Span] object ([Inline]) +- [Span] object ([Inline]) ### Str {#pandoc.Str} @@ -3150,7 +3153,7 @@ Parameters: Returns: -- [Str] object ([Inline]) +- [Str] object ([Inline]) ### Strikeout {#pandoc.Strikeout} @@ -3165,7 +3168,7 @@ Parameters: Returns: -- new object ([Inline]) +- new object ([Inline]) ### Strong {#pandoc.Strong} @@ -3181,7 +3184,7 @@ Parameters: Returns: -- new object ([Inline]) +- new object ([Inline]) ### Subscript {#pandoc.Subscript} @@ -3196,7 +3199,7 @@ Parameters: Returns: -- new object ([Inline]) +- new object ([Inline]) ### Superscript {#pandoc.Superscript} @@ -3211,7 +3214,7 @@ Parameters: Returns: -- new object ([Inline]) +- new object ([Inline]) ### Underline {#pandoc.Underline} @@ -3226,7 +3229,7 @@ Parameters: Returns: -- new object ([Inline]) +- new object ([Inline]) ### Inlines {#pandoc.Inlines} @@ -3234,11 +3237,11 @@ Returns: Converts its argument into an [Inlines] list: -- copies a list of [Inline] elements into a fresh list; any - string `s` within the list is treated as `pandoc.Str(s)`; -- turns a single [Inline] into a singleton list; -- splits a string into `Str`-wrapped words, treating interword - spaces as `Space`s or `SoftBreak`s. +- copies a list of [Inline] elements into a fresh list; any string + `s` within the list is treated as `pandoc.Str(s)`; +- turns a single [Inline] into a singleton list; +- splits a string into `Str`-wrapped words, treating interword + spaces as `Space`s or `SoftBreak`s. Parameters: @@ -3248,7 +3251,7 @@ Parameters: Returns: -- list of inline elements ([Inlines]) +- list of inline elements ([Inlines]) ### Attr {#pandoc.Attr} @@ -3270,7 +3273,27 @@ Parameters: Returns: -- new Attr object ([Attr]) +- new Attr object ([Attr]) + +### Caption {#pandoc.Caption} + +`Caption ([long[, short]])` + +Creates a new Caption object. + +Parameters: + +`long` +: full caption ([Blocks]) + +`short` +: short summary caption ([Inlines]) + +Returns: + +- new Caption object ([Caption]) + +*Since: 3.6.1* ### Cell {#pandoc.Cell} @@ -3299,7 +3322,7 @@ Parameters: Returns: -- new Cell object ([Cell]) +- new Cell object ([Cell]) ### AttributeList {#pandoc.AttributeList} @@ -3312,7 +3335,7 @@ Parameters: Returns: -- new AttributeList object ([AttributeList]) +- new AttributeList object ([AttributeList]) ### Citation {#pandoc.Citation} @@ -3343,7 +3366,7 @@ Parameters: Returns: -- new citation object ([Citation]{unknown-type="Citation"}) +- new citation object ([Citation]{unknown-type="Citation"}) ### ListAttributes {#pandoc.ListAttributes} @@ -3365,7 +3388,7 @@ Parameters: Returns: -- new ListAttributes object ([ListAttributes]) +- new ListAttributes object ([ListAttributes]) ### Row {#pandoc.Row} @@ -3383,7 +3406,7 @@ Parameters: Returns: -- new Row object ([Row]) +- new Row object ([Row]) ### TableFoot {#pandoc.TableFoot} @@ -3401,7 +3424,7 @@ Parameters: Returns: -- new TableFoot object ([TableFoot]) +- new TableFoot object ([TableFoot]) ### TableHead {#pandoc.TableHead} @@ -3419,7 +3442,7 @@ Parameters: Returns: -- new TableHead object ([TableHead]) +- new TableHead object ([TableHead]) ### SimpleTable {#pandoc.SimpleTable} @@ -3463,7 +3486,7 @@ Parameters: Returns: -- new SimpleTable object ([SimpleTable]) +- new SimpleTable object ([SimpleTable]) @@ -3727,7 +3750,7 @@ Parameters: Returns: the transformed inline element -### `read (markup[, format[, reader_options]])` {#pandoc.read} +### `read (markup[, format[, reader_options[, read_env]]])` {#pandoc.read} Parse the given string into a Pandoc document. @@ -3737,7 +3760,8 @@ the mediabag. This means that if the document specifies files to be included, as is possible in formats like LaTeX, reStructuredText, and Org, then these will be included in the resulting document. Any media elements are added to those -retrieved from the other parsed input files. +retrieved from the other parsed input files. Use the `read_env` +parameter to modify this behavior. The `format` parameter defines the format flavor that will be parsed. This can be either a string, using `+` and `-` to enable @@ -3747,6 +3771,10 @@ all enabled extensions, or a table with extensions as keys and their activation status as values (`true` or `'enable'` to enable an extension, `false` or `'disable'` to disable it). +Note: The extensions field in `reader_options` is ignored, as the +function will always use the format extensions specified via the +`format` parameter. + Parameters: `markup` @@ -3763,6 +3791,15 @@ Parameters: ReaderOptions object; defaults to the default values documented in the manual. ([ReaderOptions]|table) +`read_env` +: If the value is not given or `nil`, then the global + environment is used. Passing a list of filenames causes the + reader to be run in a sandbox. The given files are read from + the file system and provided to the sandbox via an ersatz file + system. The table can also contain mappings from filenames to + contents, which will be used to populate the ersatz file + system. + Returns: pandoc document ([Pandoc](#type-pandoc)) Usage: @@ -3780,6 +3817,10 @@ Usage: Converts a document to the given target format. +Note: The extensions field in `writer_options` is ignored, as the +function will always use the format extensions specified via the +`format` parameter. + Parameters: `doc` @@ -3868,7 +3909,7 @@ Parameters: Returns: -- parsed options, using their JSON-like representation. (table) +- parsed options, using their JSON-like representation. (table) *Since: 3.0* @@ -3955,7 +3996,7 @@ Parameters: Returns: -- ([Inlines]) +- ([Inlines]) *Since: 2.2.3* @@ -3981,7 +4022,7 @@ Parameters: Returns: -- processed document ([Pandoc]) +- processed document ([Pandoc]) *Since: 2.19.1* @@ -4006,7 +4047,7 @@ Parameters: Returns: -- Whether the two objects represent the same element (boolean) +- Whether the two objects represent the same element (boolean) *Since: 2.5* @@ -4033,7 +4074,7 @@ Parameters: Returns: -- table block element ([Block]) +- table block element ([Block]) *Since: 2.11* @@ -4064,10 +4105,31 @@ Parameters: Returns: -- blocks with sections ([Blocks]) +- blocks with sections ([Blocks]) *Since: 2.8* +### normalize_date {#pandoc.utils.normalize_date} + +`normalize_date (date)` + +Parse a date and convert (if possible) to "YYYY-MM-DD" format. We +limit years to the range 1601-9999 (ISO 8601 accepts greater than +or equal to 1583, but MS Word only accepts dates starting 1601). +Returns nil instead of a string if the conversion failed. + +Parameters: + +`date` +: the date string (string) + +Returns: + +- normalized date, or nil if normalization failed. ([string or + nil]{unknown-type="string or nil"}) + +*Since: 2.0.6* + ### references {#pandoc.utils.references} `references (doc)` @@ -4098,35 +4160,10 @@ Parameters: Returns: -- lift of references. (table) +- lift of references. (table) *Since: 2.17* -### run_lua_filter {#pandoc.utils.run_lua_filter} - -`run_lua_filter (doc, filter[, env])` - -Filter the given doc by passing it through a Lua filter. - -The filter will be run in the current Lua process. - -Parameters: - -`doc` -: the Pandoc document to filter ([Pandoc]) - -`filter` -: filepath of the filter to run (string) - -`env` -: environment to load and run the filter in (table) - -Returns: - -- filtered document ([Pandoc]) - -*Since: 3.2.1* - ### run_json_filter {#pandoc.utils.run_json_filter} `run_json_filter (doc, filter[, args])` @@ -4147,30 +4184,34 @@ Parameters: Returns: -- filtered document ([Pandoc]) +- filtered document ([Pandoc]) *Since: 2.1.1* -### normalize_date {#pandoc.utils.normalize_date} +### run_lua_filter {#pandoc.utils.run_lua_filter} -`normalize_date (date)` +`run_lua_filter (doc, filter[, env])` -Parse a date and convert (if possible) to "YYYY-MM-DD" format. We -limit years to the range 1601-9999 (ISO 8601 accepts greater than -or equal to 1583, but MS Word only accepts dates starting 1601). -Returns nil instead of a string if the conversion failed. +Filter the given doc by passing it through a Lua filter. + +The filter will be run in the current Lua process. Parameters: -`date` -: the date string (string) +`doc` +: the Pandoc document to filter ([Pandoc]) + +`filter` +: filepath of the filter to run (string) + +`env` +: environment to load and run the filter in (table) Returns: -- normalized date, or nil if normalization failed. ([string or - nil]{unknown-type="string or nil"}) +- filtered document ([Pandoc]) -*Since: 2.0.6* +*Since: 3.2.1* ### sha1 {#pandoc.utils.sha1} @@ -4185,7 +4226,7 @@ Parameters: Returns: -- hexadecimal hash value (string) +- hexadecimal hash value (string) *Since: 2.0.6* @@ -4204,7 +4245,7 @@ Parameters: Returns: -- A plain string representation of the given element. (string) +- A plain string representation of the given element. (string) *Since: 2.0.6* @@ -4228,7 +4269,7 @@ Parameters: Returns: -- A roman numeral. (string) +- A roman numeral. (string) *Since: 2.0.6* @@ -4253,7 +4294,7 @@ Parameters: Returns: -- SimpleTable object ([SimpleTable]) +- SimpleTable object ([SimpleTable]) *Since: 2.11* @@ -4288,7 +4329,7 @@ Parameters: Returns: -- type of the given value (string) +- type of the given value (string) *Since: 2.17* @@ -4306,7 +4347,7 @@ Parameters: Returns: -- new Version object ([Version]) +- new Version object ([Version]) @@ -4373,10 +4414,10 @@ Parameters: Returns: -- The entry's MIME type, or `nil` if the file was not found. - (string) -- Contents of the file, or `nil` if the file was not found. - (string) +- The entry's MIME type, or `nil` if the file was not found. + (string) +- Contents of the file, or `nil` if the file was not found. + (string) *Since: 2.0* @@ -4398,7 +4439,7 @@ Parameters: Returns: -- modified document ([Pandoc]) +- modified document ([Pandoc]) *Since: 2.19* @@ -4452,11 +4493,11 @@ Returns: Iterator triple: -- The iterator function; must be called with the iterator state - and the current iterator value. -- Iterator state -- an opaque value to be passed to the iterator - function. -- Initial iterator value. +- The iterator function; must be called with the iterator state + and the current iterator value. +- Iterator state -- an opaque value to be passed to the iterator + function. +- Initial iterator value. *Since: 2.7.3* @@ -4478,10 +4519,10 @@ Usage: Returns: -- A list of elements summarizing each entry in the media bag. - The summary item contains the keys `path`, `type`, and - `length`, giving the filepath, MIME type, and length of - contents in bytes, respectively. (table) +- A list of elements summarizing each entry in the media bag. The + summary item contains the keys `path`, `type`, and `length`, + giving the filepath, MIME type, and length of contents in bytes, + respectively. (table) *Since: 2.0* @@ -4504,13 +4545,44 @@ Parameters: Returns: -- The entry's MIME type, or nil if the file was not found. - (string) -- Contents of the file, or nil if the file was not found. - (string) +- The entry's MIME type, or nil if the file was not found. + (string) +- Contents of the file, or nil if the file was not found. (string) *Since: 2.0* +### make_data_uri {#pandoc.mediabag.make_data_uri} + +`make_data_uri (mime_type, raw_data)` + +Convert the input data into a data URI as defined by RFC 2397. + +Example: + + -- Embed an unofficial pandoc logo + local pandoc_logo_url = 'https://raw.githubusercontent.com/' + .. 'tarleb/pandoc-logo/main/pandoc.svg' + + local datauri = pandoc.mediabag.make_data_uri( + pandoc.mediabag.fetch(pandoc_logo_url) + ) + + local image = pandoc.Image('Logo', datauri) + +Parameters: + +`mime_type` +: MIME type of the data (string) + +`raw_data` +: data to encode (string) + +Returns: + +- data uri (string) + +*Since: 3.7.1* + ### write {#pandoc.mediabag.write} `write (dir[, fp])` @@ -4578,6 +4650,28 @@ Returns: ## Methods +### `pandoc.List:at` {#pandoc.list:at} + +`:at (index[, default])` + +Returns the element at the given index, or `default` if the list +contains no item at the given position. + +Negative integers count back from the last item in the list. + +Parameters: + +`index` +: element position (integer) + +`default` +: the default value that is returned if the index is out of + range (any) + +Returns: + +- the list item at `index`, or `default`. + ### `pandoc.List:clone ()` {#pandoc.list:clone} Returns a (shallow) copy of the list. (To get a deep copy @@ -4668,6 +4762,28 @@ Parameters: `value` : value to insert into the list +### `pandoc.List:iter ([step])` {#pandoc.list:iter} + +Create an iterator over the list. The resulting function returns the +next value each time it is called. + +Usage: + + for item in List{1, 1, 2, 3, 5, 8}:iter() do + -- process item + end + +Parameters: + +`step` +: step width with which to step through the list. Negative step sizes + will cause the iterator to start from the end of the list. Defaults + to 1. (integer) + +Returns: + +- iterator (function) + ### `pandoc.List:map (fn)` {#pandoc.list:map} Returns a copy of the current list by applying the given @@ -4683,6 +4799,9 @@ Parameters: Create a new List. If the optional argument `table` is given, set the metatable of that value to `pandoc.List`. +The function also accepts an iterator, in which case it creates a +new list from the return values of the iterator function. + Parameters: `table` @@ -4758,8 +4877,8 @@ Parameters: Returns: -- all extensions supported for `format` - ([FormatExtensions]{unknown-type="FormatExtensions"}) +- all extensions supported for `format` + ([FormatExtensions]{unknown-type="FormatExtensions"}) *Since: 3.0* @@ -4778,8 +4897,8 @@ Parameters: Returns: -- default extensions enabled for `format` - ([FormatExtensions]{unknown-type="FormatExtensions"}) +- default extensions enabled for `format` + ([FormatExtensions]{unknown-type="FormatExtensions"}) *Since: 3.0* @@ -4803,7 +4922,7 @@ Parameters: Returns: -- extensions config (table) +- extensions config (table) *Since: 3.0* @@ -4818,7 +4937,7 @@ Parameters: Returns: -- format determined by heuristic (string\|nil) +- format determined by heuristic (string\|nil) *Since: 3.1.2* @@ -4840,7 +4959,7 @@ Returns a table containing the size and resolution of an image; throws an error if the given string is not an image, or if the size of the image cannot be determined. -The resulting table has four entires: *width*, *height*, +The resulting table has four entries: *width*, *height*, *dpi_horz*, and *dpi_vert*. The `opts` parameter, when given, should be either a WriterOptions @@ -4858,7 +4977,7 @@ Parameters: Returns: -- image size information or error message (table) +- image size information or error message (table) *Since: 3.1.13* @@ -4878,8 +4997,8 @@ Parameters: Returns: -- image format, or nil if the format cannot be determined - (string\|nil) +- image format, or nil if the format cannot be determined + (string\|nil) *Since: 3.1.13* @@ -4925,7 +5044,7 @@ Parameters: Returns: -- decoded object (any) +- decoded object (any) *Since: 3.1.1* @@ -4947,7 +5066,7 @@ Parameters: Returns: -- JSON encoding of the given `object` (string) +- JSON encoding of the given `object` (string) *Since: 3.1.1* @@ -5046,7 +5165,7 @@ Parameters: Returns: -- The filepath up to the last directory separator. (string) +- The filepath up to the last directory separator. (string) *Since: 2.12* @@ -5063,7 +5182,7 @@ Parameters: Returns: -- File name part of the input path. (string) +- File name part of the input path. (string) *Since: 2.12* @@ -5080,8 +5199,8 @@ Parameters: Returns: -- `true` iff `filepath` is an absolute path, `false` otherwise. - (boolean) +- `true` iff `filepath` is an absolute path, `false` otherwise. + (boolean) *Since: 2.12* @@ -5098,8 +5217,8 @@ Parameters: Returns: -- `true` iff `filepath` is a relative path, `false` otherwise. - (boolean) +- `true` iff `filepath` is a relative path, `false` otherwise. + (boolean) *Since: 2.12* @@ -5116,7 +5235,7 @@ Parameters: Returns: -- The joined path. (string) +- The joined path. (string) *Since: 2.12* @@ -5142,7 +5261,7 @@ Parameters: Returns: -- contracted filename (string) +- contracted filename (string) *Since: 2.12* @@ -5152,12 +5271,12 @@ Returns: Normalizes a path. -- `//` makes sense only as part of a (Windows) network drive; - elsewhere, multiple slashes are reduced to a single - `path.separator` (platform dependent). -- `/` becomes `path.separator` (platform dependent). -- `./` is removed. -- an empty path becomes `.` +- `//` makes sense only as part of a (Windows) network drive; + elsewhere, multiple slashes are reduced to a single + `path.separator` (platform dependent). +- `/` becomes `path.separator` (platform dependent). +- `./` is removed. +- an empty path becomes `.` Parameters: @@ -5166,7 +5285,7 @@ Parameters: Returns: -- The normalized path. (string) +- The normalized path. (string) *Since: 2.12* @@ -5183,7 +5302,7 @@ Parameters: Returns: -- List of all path components. ({string,\...}) +- List of all path components. ({string,\...}) *Since: 2.12* @@ -5203,8 +5322,8 @@ Parameters: Returns: -- filepath without extension (string) -- extension or empty string (string) +- filepath without extension (string) +- extension or empty string (string) *Since: 2.12* @@ -5223,7 +5342,7 @@ Parameters: Returns: -- list of directories in search path ({string,\...}) +- list of directories in search path ({string,\...}) *Since: 2.12* @@ -5285,7 +5404,7 @@ Parameters: Returns: -- processed blocks ([Blocks]) +- processed blocks ([Blocks]) *Since: 3.0* @@ -5304,7 +5423,7 @@ Parameters: Returns: -- slide level ([integer]{unknown-type="integer"}) +- slide level ([integer]{unknown-type="integer"}) *Since: 3.0* @@ -5353,7 +5472,7 @@ Parameters: Returns: -- ([ChunkedDoc]) +- ([ChunkedDoc]) *Since: 3.0* @@ -5374,7 +5493,7 @@ Parameters: Returns: -- Table of contents as a BulletList object ([Block]) +- Table of contents as a BulletList object ([Block]) *Since: 3.0* @@ -5394,7 +5513,10 @@ The machine architecture on which the program is running. (string) ### os {#pandoc.system.os} -The operating system on which the program is running. (string) +The operating system on which the program is running. The most +common values are `darwin` (macOS), `freebsd`, `linux`, +`linux-android`, `mingw32` (Windows), `netbsd`, `openbsd`. +(string) ## Functions {#pandoc.system-functions} @@ -5408,7 +5530,7 @@ versions and on different platforms. Returns: -- CPU time in picoseconds ([integer]{unknown-type="integer"}) +- CPU time in picoseconds ([integer]{unknown-type="integer"}) *Since: 3.1.1* @@ -5420,8 +5542,8 @@ Retrieves the entire environment as a string-indexed table. Returns: -- A table mapping environment variable names to their value. - (table) +- A table mapping environment variable names to their value. + (table) *Since: 2.7.3* @@ -5433,7 +5555,7 @@ Obtain the current working directory as an absolute path. Returns: -- The current working directory. (string) +- The current working directory. (string) *Since: 2.8* @@ -5451,8 +5573,8 @@ Parameters: Returns: -- A table of all entries in `directory`, except for the special - entries (`.` and `..`). (table) +- A table of all entries in `directory`, except for the special + entries (`.` and `..`). (table) *Since: 2.19* @@ -5620,7 +5742,7 @@ Parameters: Returns: -- new doc ([Doc]) +- new doc ([Doc]) *Since: 2.18* @@ -5638,7 +5760,7 @@ Parameters: Returns: -- conditional doc ([Doc]) +- conditional doc ([Doc]) *Since: 2.18* @@ -5655,7 +5777,7 @@ Parameters: Returns: -- conditional blank lines ([Doc]) +- conditional blank lines ([Doc]) *Since: 2.18* @@ -5672,7 +5794,7 @@ Parameters: Returns: -- `doc` enclosed by {}. ([Doc]) +- `doc` enclosed by {}. ([Doc]) *Since: 2.18* @@ -5689,7 +5811,7 @@ Parameters: Returns: -- doc enclosed by \[\]. ([Doc]) +- doc enclosed by \[\]. ([Doc]) *Since: 2.18* @@ -5710,8 +5832,8 @@ Parameters: Returns: -- doc, aligned centered in a block with max `width` chars per - line. ([Doc]) +- doc, aligned centered in a block with max `width` chars per + line. ([Doc]) *Since: 2.18* @@ -5728,7 +5850,7 @@ Parameters: Returns: -- `doc` without trailing blanks ([Doc]) +- `doc` without trailing blanks ([Doc]) *Since: 2.18* @@ -5748,7 +5870,7 @@ Parameters: Returns: -- concatenated doc ([Doc]) +- concatenated doc ([Doc]) *Since: 2.18* @@ -5765,7 +5887,7 @@ Parameters: Returns: -- `doc` enclosed by `"` chars ([Doc]) +- `doc` enclosed by `"` chars ([Doc]) *Since: 2.18* @@ -5782,7 +5904,7 @@ Parameters: Returns: -- flushed `doc` ([Doc]) +- flushed `doc` ([Doc]) *Since: 2.18* @@ -5805,8 +5927,8 @@ Parameters: Returns: -- `doc` prefixed by `start` on the first line, subsequent lines - indented by `ind` spaces. ([Doc]) +- `doc` prefixed by `start` on the first line, subsequent lines + indented by `ind` spaces. ([Doc]) *Since: 2.18* @@ -5829,7 +5951,7 @@ Parameters: Returns: -- enclosed contents ([Doc]) +- enclosed contents ([Doc]) *Since: 2.18* @@ -5850,7 +5972,7 @@ Parameters: Returns: -- doc put into block with max `width` chars per line. ([Doc]) +- doc put into block with max `width` chars per line. ([Doc]) *Since: 2.18* @@ -5867,7 +5989,7 @@ Parameters: Returns: -- doc contatining just the literal string ([Doc]) +- doc contatining just the literal string ([Doc]) *Since: 2.18* @@ -5887,7 +6009,7 @@ Parameters: Returns: -- `doc` indented by `ind` spaces ([Doc]) +- `doc` indented by `ind` spaces ([Doc]) *Since: 2.18* @@ -5904,7 +6026,7 @@ Parameters: Returns: -- `doc` with leading blanks removed ([Doc]) +- `doc` with leading blanks removed ([Doc]) *Since: 2.18* @@ -5921,7 +6043,7 @@ Parameters: Returns: -- same as input, but non-reflowable ([Doc]) +- same as input, but non-reflowable ([Doc]) *Since: 2.18* @@ -5938,7 +6060,7 @@ Parameters: Returns: -- doc enclosed by (). ([Doc]) +- doc enclosed by (). ([Doc]) *Since: 2.18* @@ -5959,7 +6081,7 @@ Parameters: Returns: -- prefixed `doc` ([Doc]) +- prefixed `doc` ([Doc]) *Since: 2.18* @@ -5976,7 +6098,7 @@ Parameters: Returns: -- doc enclosed in `'`. ([Doc]) +- doc enclosed in `'`. ([Doc]) *Since: 2.18* @@ -5997,8 +6119,8 @@ Parameters: Returns: -- doc, right aligned in a block with max `width` chars per line. - ([Doc]) +- doc, right aligned in a block with max `width` chars per line. + ([Doc]) *Since: 2.18* @@ -6016,13 +6138,13 @@ Parameters: Returns: -- automatically expanding border Doc ([Doc]) +- automatically expanding border Doc ([Doc]) *Since: 2.18* ### render {#pandoc.layout.render} -`render (doc[, colwidth])` +`render (doc[, colwidth[, style]])` Render a [Doc]. The text is reflowed on breakable spaces to match the given line length. Text is not reflowed if the line line @@ -6034,12 +6156,18 @@ Parameters: : document ([Doc]) `colwidth` -: planned maximum line length +: Maximum number of characters per line. A value of `nil`, the + default, means that the text is not reflown. ([integer]{unknown-type="integer"}) +`style` +: Whether to generate plain text or ANSI terminal output. Must + be either `'plain'` or `'ansi'`. Defaults to `'plain'`. + (string) + Returns: -- rendered doc (string) +- rendered doc (string) *Since: 2.18* @@ -6056,8 +6184,8 @@ Parameters: Returns: -- `true` iff `doc` is the empty document, `false` otherwise. - (boolean) +- `true` iff `doc` is the empty document, `false` otherwise. + (boolean) *Since: 2.18* @@ -6074,7 +6202,7 @@ Parameters: Returns: -- doc height ([integer]{unknown-type="integer"}\|string) +- doc height ([integer]{unknown-type="integer"}\|string) *Since: 2.18* @@ -6092,8 +6220,8 @@ Parameters: Returns: -- minimal possible width - ([integer]{unknown-type="integer"}\|string) +- minimal possible width + ([integer]{unknown-type="integer"}\|string) *Since: 2.18* @@ -6110,7 +6238,7 @@ Parameters: Returns: -- doc width ([integer]{unknown-type="integer"}\|string) +- doc width ([integer]{unknown-type="integer"}\|string) *Since: 2.18* @@ -6129,7 +6257,7 @@ Parameters: Returns: -- text length ([integer]{unknown-type="integer"}\|string) +- text length ([integer]{unknown-type="integer"}\|string) *Since: 2.18* @@ -6150,10 +6278,120 @@ Parameters: Returns: -- column number ([integer]{unknown-type="integer"}\|string) +- column number ([integer]{unknown-type="integer"}\|string) *Since: 2.18* +### bold {#pandoc.layout.bold} + +`bold (doc)` + +Puts a [Doc] in boldface. + +Parameters: + +`doc` +: document ([Doc]) + +Returns: + +- bolded Doc ([Doc]) + +*Since: 3.4.1* + +### italic {#pandoc.layout.italic} + +`italic (doc)` + +Puts a [Doc] in italics. + +Parameters: + +`doc` +: document ([Doc]) + +Returns: + +- styled Doc ([Doc]) + +*Since: 3.4.1* + +### underlined {#pandoc.layout.underlined} + +`underlined (doc)` + +Underlines a [Doc]. + +Parameters: + +`doc` +: document ([Doc]) + +Returns: + +- styled Doc ([Doc]) + +*Since: 3.4.1* + +### strikeout {#pandoc.layout.strikeout} + +`strikeout (doc)` + +Puts a line through the [Doc]. + +Parameters: + +`doc` +: document ([Doc]) + +Returns: + +- styled Doc ([Doc]) + +*Since: 3.4.1* + +### fg {#pandoc.layout.fg} + +`fg (doc, color)` + +Set the foreground color. + +Parameters: + +`doc` +: document ([Doc]) + +`color` +: One of 'black', 'red', 'green', 'yellow', 'blue', 'magenta' + 'cyan', or 'white'. (string) + +Returns: + +- styled Doc ([Doc]) + +*Since: 3.4.1* + +### bg {#pandoc.layout.bg} + +`bg (doc, color)` + +Set the background color. + +Parameters: + +`doc` +: document ([Doc]) + +`color` +: One of 'black', 'red', 'green', 'yellow', 'blue', 'magenta' + 'cyan', or 'white'. (string) + +Returns: + +- styled Doc ([Doc]) + +*Since: 3.4.1* + ## Types {#pandoc.layout-types} ### Doc {#type-pandoc.Doc} @@ -6221,7 +6459,7 @@ Parameters: Returns: -- UTF-8 string (string) +- UTF-8 string (string) *Since: 3.0* @@ -6239,7 +6477,7 @@ Parameters: Returns: -- length ([integer]{unknown-type="integer"}\|string) +- length ([integer]{unknown-type="integer"}\|string) *Since: 2.0.3* @@ -6256,7 +6494,7 @@ Parameters: Returns: -- Lowercase copy of `s` (string) +- Lowercase copy of `s` (string) *Since: 2.0.3* @@ -6273,7 +6511,7 @@ Parameters: Returns: -- Reversed `s` (string) +- Reversed `s` (string) *Since: 2.0.3* @@ -6297,7 +6535,7 @@ Parameters: Returns: -- text substring (string) +- text substring (string) *Since: 2.0.3* @@ -6324,7 +6562,7 @@ Parameters: Returns: -- re-encoded string (string) +- re-encoded string (string) *Since: 3.0* @@ -6341,7 +6579,7 @@ Parameters: Returns: -- Uppercase copy of `s` (string) +- Uppercase copy of `s` (string) *Since: 2.0.3* @@ -6375,7 +6613,7 @@ Parameters: Returns: -- rendered template ([Doc]) +- rendered template ([Doc]) *Since: 3.0* @@ -6405,7 +6643,7 @@ Parameters: Returns: -- compiled template ([Template]) +- compiled template ([Template]) *Since: 2.17* @@ -6424,7 +6662,7 @@ Parameters: Returns: -- raw template (string) +- raw template (string) *Since: 2.17* @@ -6446,7 +6684,7 @@ Parameters: Returns: -- content of template file (string) +- content of template file (string) *Since: 3.2.1* @@ -6471,10 +6709,14 @@ Parameters: Returns: -- template context (table) +- template context (table) *Since: 3.0* +## Types {#pandoc.template-types} + +### Template {#type-pandoc.Template} + @@ -6498,7 +6740,7 @@ Parameters: Returns: -- New Version object. ([Version]) +- New Version object. ([Version]) *Since: 2.7.3* @@ -6516,15 +6758,14 @@ like the `zip` function described below. Zip options are optional; when defined, they must be a table with any of the following keys: -- `recursive`: recurse directories when set to `true`; -- `verbose`: print info messages to stdout; -- `destination`: the value specifies the directory in which to - extract; -- `location`: value is used as path name, defining where files - are placed. -- `preserve_symlinks`: Boolean value, controlling whether - symbolic links are preserved as such. This option is ignored - on Windows. +- `recursive`: recurse directories when set to `true`; +- `verbose`: print info messages to stdout; +- `destination`: the value specifies the directory in which to + extract; +- `location`: value is used as path name, defining where files are + placed. +- `preserve_symlinks`: Boolean value, controlling whether symbolic + links are preserved as such. This option is ignored on Windows. ## Functions {#pandoc.zip-functions} @@ -6544,7 +6785,7 @@ Parameters: Returns: -- new Archive ([zip.Archive]) +- new Archive ([zip.Archive]) *Since: 3.0* @@ -6568,7 +6809,7 @@ Parameters: Returns: -- a new zip archive entry ([zip.Entry]) +- a new zip archive entry ([zip.Entry]) *Since: 3.0* @@ -6588,7 +6829,7 @@ Parameters: Returns: -- a new zip archive entry ([zip.Entry]) +- a new zip archive entry ([zip.Entry]) *Since: 3.0* @@ -6609,7 +6850,7 @@ Parameters: Returns: -- a new archive ([zip.Archive]) +- a new archive ([zip.Archive]) *Since: 3.0* @@ -6638,7 +6879,7 @@ Parameters: Returns: -- bytes of the archive (string) +- bytes of the archive (string) ##### extract {#pandoc.zip.Archive.extract} @@ -6690,7 +6931,7 @@ Parameters: Returns: -- binary contents (string) +- binary contents (string) ##### symlink {#pandoc.zip.Entry.symlink} @@ -6706,7 +6947,7 @@ Parameters: Returns: -- link target if entry represents a symbolic link (string\|nil) +- link target if entry represents a symbolic link (string\|nil) diff --git a/doc/pandoc-server.md b/doc/pandoc-server.md index c5c4e36d9162..881e16f46ec7 100644 --- a/doc/pandoc-server.md +++ b/doc/pandoc-server.md @@ -190,6 +190,14 @@ the first one given is the default. : Depth of sections to include in the table of contents. +`list-of-figures` (boolean, default false) + +: Include a list of figures (in supported formats). + +`list-of-tables` (boolean, default false) + +: Include a list of tables (in supported formats). + `strip-comments` (boolean, default false) : Causes HTML comments to be stripped in Markdown or Textile diff --git a/doc/typst-property-output.md b/doc/typst-property-output.md index 112c82afc6a8..8a1907b29350 100644 --- a/doc/typst-property-output.md +++ b/doc/typst-property-output.md @@ -96,9 +96,9 @@ The following Pandoc AST elements are currently supported. More may be supported : The table is wrapped in a Typst [text element](https://typst.app/docs/reference/text/text/) with `prop` as one of its parameters. - `typst:no-figure` + `typst:no-figure` (class) - : By default, Pandoc will wrap the table in a Typst [figure element](https://typst.app/docs/reference/model/figure/). If this attribute is set, only the table element itself will be emitted. This avoids Typst's crossreference counter of kind `table` from being incremented. + : By default, Pandoc will wrap the table in a Typst [figure element](https://typst.app/docs/reference/model/figure/). If the table has this class, only the table element itself will be emitted. This avoids Typst's crossreference counter of kind `table` from being incremented. `typst:figure:kind` diff --git a/flake.lock b/flake.lock index cb4c63efadbe..b38a7be3d3a5 100644 --- a/flake.lock +++ b/flake.lock @@ -5,11 +5,11 @@ "systems": "systems" }, "locked": { - "lastModified": 1681202837, - "narHash": "sha256-H+Rh19JDwRtpVPAWp64F+rlEtxUWBAQW28eAi3SRSzg=", + "lastModified": 1731533236, + "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=", "owner": "numtide", "repo": "flake-utils", - "rev": "cfacdce06f30d2b68473a46042957675eebb3401", + "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b", "type": "github" }, "original": { @@ -20,16 +20,15 @@ }, "nixpkgs": { "locked": { - "lastModified": 1683594133, - "narHash": "sha256-iUhLhEAgOCnexSGDsYT2ouydis09uDoNzM7UC685XGE=", + "lastModified": 1747069600, + "narHash": "sha256-weeDl3e6oMgiPVOdfYIrHZUnPTjrXF9lM9cXz+kspUI=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "8d447c5626cfefb9b129d5b30103344377fe09bc", + "rev": "ff566ca9c981243696ed60531cfdf8b8d702a41c", "type": "github" }, "original": { "owner": "NixOS", - "ref": "nixpkgs-unstable", "repo": "nixpkgs", "type": "github" } diff --git a/flake.nix b/flake.nix index 9e7908765adc..55cc5fccfbb0 100644 --- a/flake.nix +++ b/flake.nix @@ -1,53 +1,68 @@ { - description = "Pandoc development"; + description = "pandoc"; - inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - inputs.flake-utils.url = "github:numtide/flake-utils"; + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs"; + flake-utils.url = "github:numtide/flake-utils"; + }; - outputs = inputs: - let - overlay = final: prev: { - haskell = prev.haskell // { - packageOverrides = hfinal: hprev: - prev.haskell.packageOverrides hfinal hprev // { - crypton-connection = final.fetchFromGitHub { - owner = "kazu-yamamoto"; - repo = "crypton-connection"; - rev = "5c064b911e7327a4d399fd9dd057663d0d0fb256"; - sha256 = "00j1nf9glbz0cnzd84vp08j9ybzjbm3b6gcamlqxxcjb31kllz4b"; - }; - pandoc = hfinal.callCabal2nix "pandoc" ./. { }; - }; - }; - pandoc = final.haskell.lib.compose.justStaticExecutables final.haskellPackages.pandoc; - }; - perSystem = system: - let - pkgs = import inputs.nixpkgs { inherit system; overlays = [ overlay ]; }; - hspkgs = pkgs.haskellPackages; - in - { - devShell = hspkgs.shellFor { - withHoogle = true; - packages = p : [ - p.pandoc - ]; - buildInputs = [ - hspkgs.cabal-install - hspkgs.haskell-language-server - hspkgs.hlint - hspkgs.ghcid - hspkgs.ormolu - hspkgs.stylish-haskell - hspkgs.weeder - hspkgs.servant-server - hspkgs.hslua - pkgs.bashInteractive - ]; + outputs = { self, nixpkgs, flake-utils }: + flake-utils.lib.eachDefaultSystem (system: + let + pkgs = nixpkgs.legacyPackages.${system}; + + haskellPackages = pkgs.haskellPackages; + # Or, override some dependencies as follows: + # haskellPackages = (pkgs.haskellPackages.override { + # all-cabal-hashes = pkgs.fetchurl { + # # The hash in the URL is just a git commit hash + # url = "https://github.com/commercialhaskell/all-cabal-hashes/archive/2e3f153549871ada6ecbf36719339a5da051bc76.tar.gz"; + # sha256 = "ymHZb6wCZlrtKb+T+iOL17jyN8IzA7s52uiamUIkWNI="; + # }; + # }).extend(self: super: { + # citeproc = pkgs.haskell.lib.dontCheck (self.callHackage "citeproc" "0.9.0.1" {}); + # commonmark-pandoc = self.callHackage "commonmark-pandoc" "0.2.3" {}; + # typst-symbols = self.callHackage "typst-symbols" "0.1.8.1" {}; + # typst = self.callHackage "typst" "0.8" {}; + # texmath = self.callHackage "texmath" "0.12.10.2" {}; + # toml-parser = self.callHackage "toml-parser" "2.0.1.2" {}; + # }); + + jailbreakUnbreak = pkg: + pkgs.haskell.lib.doJailbreak (pkg.overrideAttrs (_: { meta = { }; })); + + # DON'T FORGET TO PUT YOUR PACKAGE NAME HERE, REMOVING `throw` + packageName = "pandoc"; + in { + packages.${packageName} = + haskellPackages.callCabal2nix packageName self rec { + # Dependency overrides go here }; - defaultPackage = pkgs.pandoc; + + packages.default = self.packages.${system}.${packageName}; + defaultPackage = self.packages.${system}.default; + + devShells.default = pkgs.mkShell { + buildInputs = with pkgs; [ + haskellPackages.haskell-language-server # you must build it with your ghc to work + haskellPackages.hlint + haskellPackages.cabal-install + haskellPackages.cabal-plan + haskellPackages.weeder + haskellPackages.hpc + haskellPackages.ghcid + haskellPackages.stylish-haskell + zlib.dev + git + bashInteractive + epubcheck # for validate-epub + nodejs # for validate-epub + ripgrep + libxml2 # for xmllint + jq + ]; + inputsFrom = map (__getAttr "env") (__attrValues self.packages.${system}); }; - in - { inherit overlay; } // - inputs.flake-utils.lib.eachDefaultSystem perSystem; + devShell = self.devShells.${system}.default; + }); } diff --git a/linux/make_artifacts.sh b/linux/make_artifacts.sh index 27f866adf17a..dff3cc24eac6 100644 --- a/linux/make_artifacts.sh +++ b/linux/make_artifacts.sh @@ -16,6 +16,7 @@ case "$MACHINE" in i386) ARCHITECTURE=i386;; aarch64) ARCHITECTURE=arm64;; armv6l | armv7l) ARCHITECTURE=armhf;; + riscv64) ARCHITECTURE=riscv64;; *) ARCHITECTURE=unknown;; esac diff --git a/pandoc-cli/man/pandoc-lua.1 b/pandoc-cli/man/pandoc-lua.1 index d0c4a68d5cd4..4b9210401960 100644 --- a/pandoc-cli/man/pandoc-lua.1 +++ b/pandoc-cli/man/pandoc-lua.1 @@ -1,13 +1,13 @@ -.\" Automatically generated by Pandoc 3.4 +.\" Automatically generated by Pandoc 3.7.0.2 .\" -.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.4" "Pandoc User\[cq]s Guide" +.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.7.0.2" "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]]] .SH DESCRIPTION \f[CR]pandoc\-lua\f[R] is a standalone Lua interpreter with behavior similar to that of the standard \f[CR]lua\f[R] executable, but exposing -all of pandoc\[cq]s Lua libraries. +all of pandoc\(cqs Lua libraries. All \f[CR]pandoc.*\f[R] packages, as well as the packages \f[CR]re\f[R] and \f[CR]lpeg\f[R], are available via global variables. Furthermore, the globals \f[CR]PANDOC_VERSION\f[R], @@ -27,7 +27,7 @@ When called without the option \f[CR]\-E\f[R], the interpreter checks for an environment variable \f[CR]LUA_INIT\f[R] before running any argument. If the variable content has the format -\f[I]\f[CI]\[at]filename\f[I]\f[R], then \f[CR]pandoc\-lua\f[R] executes +\f[I]\f[CI]\(atfilename\f[I]\f[R], then \f[CR]pandoc\-lua\f[R] executes the file. Otherwise, \f[CR]pandoc\-lua\f[R] executes the string itself. .SH OPTIONS @@ -69,9 +69,9 @@ Exit the interactive mode by pressing \f[CR]Ctrl\-D\f[R] or \f[CR]Ctrl\-C\f[R], or by typing \f[CR]os.exit()\f[R]. The \f[I]Isocline\f[R] library is used for line editing. Press \f[CR]F1\f[R] to get a list of available keybindings; the -\f[CR]ctrl\f[R] key is abbreviated as \f[CR]\[ha]\f[R] in that list. +\f[CR]ctrl\f[R] key is abbreviated as \f[CR]\(ha\f[R] in that list. .SH AUTHORS -Copyright 2023 John MacFarlane (jgm\[at]berkeley.edu) and contributors. +Copyright 2023 John MacFarlane (jgm\(atberkeley.edu) and contributors. Released under the GPL, version 2 or later. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.) diff --git a/pandoc-cli/man/pandoc-server.1 b/pandoc-cli/man/pandoc-server.1 index f4aba4ee551b..50e3e644301f 100644 --- a/pandoc-cli/man/pandoc-server.1 +++ b/pandoc-cli/man/pandoc-server.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.4 +.\" Automatically generated by Pandoc 3.7.0.2 .\" -.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.4" "Pandoc User\[cq]s Guide" +.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.7.0.2" "Pandoc User\[cq]s Guide" .SH SYNOPSIS \f[CR]pandoc\-server\f[R] [\f[I]options\f[R]] .SH DESCRIPTION @@ -10,7 +10,7 @@ It can be used either as a running server or as a CGI program. .PP To use \f[CR]pandoc\-server\f[R] as a CGI program, rename it (or symlink it) as \f[CR]pandoc\-server.cgi\f[R]. -(Note: if you symlink it, you may need to adjust your webserver\[cq]s +(Note: if you symlink it, you may need to adjust your webserver\(cqs configuration in order to allow it to follow symlinks for the CGI script.) .PP @@ -18,13 +18,13 @@ All pandoc functions are run in the PandocPure monad, which ensures that they can do no I/O operations on the server. This should provide a high degree of security. This security does, however, impose certain limitations: -.IP \[bu] 2 +.IP \(bu 2 PDFs cannot be produced. -.IP \[bu] 2 +.IP \(bu 2 Filters are not supported. -.IP \[bu] 2 +.IP \(bu 2 Resources cannot be fetched via HTTP. -.IP \[bu] 2 +.IP \(bu 2 Any images, include files, or other resources needed for the document conversion must be explicitly included in the request, via the \f[CR]files\f[R] field (see below under API). @@ -54,11 +54,11 @@ The root (\f[CR]/\f[R]) endpoint accepts only POST requests. .SS Response It returns a converted document in one of the following formats (in order of preference), depending on the \f[CR]Accept\f[R] header: -.IP \[bu] 2 +.IP \(bu 2 \f[CR]application/octet\-stream\f[R] -.IP \[bu] 2 +.IP \(bu 2 \f[CR]text/plain\f[R] -.IP \[bu] 2 +.IP \(bu 2 \f[CR]application/json\f[R] .PP If the result is a binary format (e.g., \f[CR]epub\f[R] or @@ -69,22 +69,22 @@ If a JSON response is given, it will have one of the following formats. If the conversion is not successful: .IP .EX -{ \[dq]error\[dq]: string with the error message } +{ \(dqerror\(dq: string with the error message } .EE .PP If the conversion is successful: .IP .EX -{ \[dq]output\[dq]: string with textual or base64\-encoded binary output, - \[dq]base64\[dq]: boolean (true means the \[dq]output\[dq] is base64\-encoded), - \[dq]messages\[dq]: array of message objects (see below) } +{ \(dqoutput\(dq: string with textual or base64\-encoded binary output, + \(dqbase64\(dq: boolean (true means the \(dqoutput\(dq is base64\-encoded), + \(dqmessages\(dq: array of message objects (see below) } .EE .PP -Each element of the \[lq]messages\[rq] array will have the format +Each element of the \(lqmessages\(rq array will have the format .IP .EX -{ \[dq]message\[dq]: string, - \[dq]verbosity\[dq]: string (either \[dq]WARNING\[dq] or \[dq]INFO\[dq]) } +{ \(dqmessage\(dq: string, + \(dqverbosity\(dq: string (either \(dqWARNING\(dq or \(dqINFO\(dq) } .EE .SS Request The body of the POST request should be a JSON object, with the following @@ -100,11 +100,11 @@ Note: if the \f[CR]from\f[R] format is binary (e.g., \f[CR]epub\f[R] or \f[CR]docx\f[R]), then \f[CR]text\f[R] should be a base64 encoding of the document. .TP -\f[CR]from\f[R] (string, default \f[CR]\[dq]markdown\[dq]\f[R]) +\f[CR]from\f[R] (string, default \f[CR]\(dqmarkdown\(dq\f[R]) The input format, possibly with extensions, just as it is specified on the pandoc command line. .TP -\f[CR]to\f[R] (string, default \f[CR]\[dq]html\[dq]\f[R]) +\f[CR]to\f[R] (string, default \f[CR]\(dqhtml\(dq\f[R]) The output format, possibly with extensions, just as it is specified on the pandoc command line. .TP @@ -116,7 +116,7 @@ List of classes to be applied to indented Markdown code blocks. .TP \f[CR]default\-image\-extension\f[R] (string) Extension to be applied to image sources that lack extensions -(e.g.\ \f[CR]\[dq].jpg\[dq]\f[R]). +(e.g.\ \f[CR]\(dq.jpg\(dq\f[R]). .TP \f[CR]metadata\f[R] (JSON map) String\-valued metadata. @@ -124,9 +124,9 @@ String\-valued metadata. \f[CR]tab\-stop\f[R] (integer, default 4) Tab stop (spaces per tab). .TP -\f[CR]track\-changes\f[R] (\f[CR]\[dq]accept\[dq]|\[dq]reject\[dq]|\[dq]all\[dq]\f[R]) +\f[CR]track\-changes\f[R] (\f[CR]\(dqaccept\(dq|\(dqreject\(dq|\(dqall\(dq\f[R]) Specifies what to do with insertions, deletions, and comments produced -by the MS Word \[lq]Track Changes\[rq] feature. +by the MS Word \(lqTrack Changes\(rq feature. Only affects docx input. .TP \f[CR]abbreviations\f[R] (file path) @@ -150,12 +150,12 @@ Variables to be interpolated in the template. Dots\-per\-inch to use for conversions between pixels and other measurements (for image sizes). .TP -\f[CR]wrap\f[R] (\f[CR]\[dq]auto\[dq]|\[dq]preserve\[dq]|\[dq]none\[dq]\f[R]) -Text wrapping option: either \f[CR]\[dq]auto\[dq]\f[R] (automatic +\f[CR]wrap\f[R] (\f[CR]\(dqauto\(dq|\(dqpreserve\(dq|\(dqnone\(dq\f[R]) +Text wrapping option: either \f[CR]\(dqauto\(dq\f[R] (automatic hard\-wrapping to fit within a column width), -\f[CR]\[dq]preserve\[dq]\f[R] (insert newlines where they are present in -the source), or \f[CR]\[dq]none\[dq]\f[R] (don\[cq]t insert any -unnecessary newlines at all). +\f[CR]\(dqpreserve\(dq\f[R] (insert newlines where they are present in +the source), or \f[CR]\(dqnone\(dq\f[R] (don\(cqt insert any unnecessary +newlines at all). .TP \f[CR]columns\f[R] (integer, default 72) Column width (affects text wrapping and calculation of table column @@ -167,17 +167,23 @@ Include a table of contents (in supported formats). \f[CR]toc\-depth\f[R] (integer, default 3) Depth of sections to include in the table of contents. .TP +\f[CR]list\-of\-figures\f[R] (boolean, default false) +Include a list of figures (in supported formats). +.TP +\f[CR]list\-of\-tables\f[R] (boolean, default false) +Include a list of tables (in supported formats). +.TP \f[CR]strip\-comments\f[R] (boolean, default false) Causes HTML comments to be stripped in Markdown or Textile source, instead of being passed through to the output format. .TP \f[CR]highlight\-style\f[R] (string, leave unset for no highlighting) Specify the style to use for syntax highlighting of code. -Standard styles are \f[CR]\[dq]pygments\[dq]\f[R] (the default), -\f[CR]\[dq]kate\[dq]\f[R], \f[CR]\[dq]monochrome\[dq]\f[R], -\f[CR]\[dq]breezeDark\[dq]\f[R], \f[CR]\[dq]espresso\[dq]\f[R], -\f[CR]\[dq]zenburn\[dq]\f[R], \f[CR]\[dq]haddock\[dq]\f[R], and -\f[CR]\[dq]tango\[dq]\f[R]. +Standard styles are \f[CR]\(dqpygments\(dq\f[R] (the default), +\f[CR]\(dqkate\(dq\f[R], \f[CR]\(dqmonochrome\(dq\f[R], +\f[CR]\(dqbreezeDark\(dq\f[R], \f[CR]\(dqespresso\(dq\f[R], +\f[CR]\(dqzenburn\(dq\f[R], \f[CR]\(dqhaddock\(dq\f[R], and +\f[CR]\(dqtango\(dq\f[R]. Alternatively, the path of a \f[CR].theme\f[R] with a KDE syntax theme may be used (in this case, the relevant file contents must also be included in \f[CR]files\f[R], see below). @@ -198,7 +204,7 @@ the output. \f[CR]reference\-links\f[R] (boolean, default false) Create reference links rather than inline links in Markdown output. .TP -\f[CR]reference\-location\f[R] (\f[CR]\[dq]document\[dq]|\[dq]section\[dq]|\[dq]block\[dq]\f[R]) +\f[CR]reference\-location\f[R] (\f[CR]\(dqdocument\(dq|\(dqsection\(dq|\(dqblock\(dq\f[R]) Determines whether link references and footnotes are placed at the end of the document, the end of the section, or the end of the block (e.g.\ paragraph), in certain formats. @@ -208,10 +214,10 @@ of the document, the end of the section, or the end of the block Use Setext (underlined) headings instead of ATX (\f[CR]#\f[R]\-prefixed) in Markdown output. .TP -\f[CR]top\-level\-division\f[R] (\f[CR]\[dq]default\[dq]|\[dq]part\[dq]|\[dq]chapter\[dq]|\[dq]section\[dq]\f[R]) +\f[CR]top\-level\-division\f[R] (\f[CR]\(dqdefault\(dq|\(dqpart\(dq|\(dqchapter\(dq|\(dqsection\(dq\f[R]) Determines how top\-level headings are interpreted in LaTeX, ConTeXt, DocBook, and TEI. -The \f[CR]\[dq]default\[dq]\f[R] value tries to choose the best +The \f[CR]\(dqdefault\(dq\f[R] value tries to choose the best interpretation based on heuristics. .TP \f[CR]number\-sections\f[R] (boolean, default false) @@ -220,11 +226,11 @@ Automatically number sections (in supported formats). \f[CR]number\-offset\f[R] (array of integers) Offsets to be added to each component of the section number. For example, \f[CR][1]\f[R] will cause the first section to be numbered -\[lq]2\[rq] and the first subsection \[lq]2.1\[rq]; \f[CR][0,1]\f[R] -will cause the first section to be numbered \[lq]1\[rq] and the first -subsection \[lq]1.2.\[rq] +\(lq2\(rq and the first subsection \(lq2.1\(rq; \f[CR][0,1]\f[R] will +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]\[dq]plain\[dq]|\[dq]webtex\[dq]|\[dq]gladtex\[dq]|\[dq]mathml\[dq]|\[dq]mathjax\[dq]|\[dq]katex\[dq]\f[R]) +\f[CR]html\-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) @@ -242,7 +248,7 @@ body text. Arrange the document into a hierarchy of nested sections based on the headings. .TP -\f[CR]email\-obfuscation\f[R] (\f[CR]\[dq]none\[dq]|\[dq]references\[dq]|\[dq]javascript\[dq]\f[R]) +\f[CR]email\-obfuscation\f[R] (\f[CR]\(dqnone\(dq|\(dqreferences\(dq|\(dqjavascript\(dq\f[R]) Determines how email addresses are obfuscated in HTML. .TP \f[CR]identifier\-prefix\f[R] (string) @@ -270,14 +276,14 @@ Path of file containing Dublin core XML elements to be used for EPUB metadata. The contents of the file must be included under \f[CR]files\f[R]. .TP -\f[CR]epub\-subdirectory\f[R] (string, default \[lq]EPUB\[rq]) +\f[CR]epub\-subdirectory\f[R] (string, default \(lqEPUB\(rq) Name of content subdirectory in the EPUB container. .TP \f[CR]epub\-fonts\f[R] (array of file paths) Fonts to include in the EPUB. The fonts themselves must be included in \f[CR]files\f[R] (see below). .TP -\f[CR]ipynb\-output\f[R] (\f[CR]\[dq]best\[dq]|\[dq]all\[dq]|\[dq]none\[dq]\f[R]) +\f[CR]ipynb\-output\f[R] (\f[CR]\(dqbest\(dq|\(dqall\(dq|\(dqnone\(dq\f[R]) Determines how ipynb output cells are treated. \f[CR]all\f[R] means that all of the data formats included in the original are preserved. @@ -297,7 +303,7 @@ The contents of the files must be included in \f[CR]files\f[R]. CSL style file. The contents of the file must be included in \f[CR]files\f[R]. .TP -\f[CR]cite\-method\f[R] (\f[CR]\[dq]citeproc\[dq]|\[dq]natbib\[dq]|\[dq]biblatex\[dq]\f[R]) +\f[CR]cite\-method\f[R] (\f[CR]\(dqciteproc\(dq|\(dqnatbib\(dq|\(dqbiblatex\(dq\f[R]) Determines how citations are formatted in LaTeX output. .TP \f[CR]files\f[R] (JSON mapping of file paths to base64\-encoded strings) @@ -309,10 +315,10 @@ base 64 data, in which case it will be interpreted that way. .SS \f[CR]/batch\f[R] endpoint The \f[CR]/batch\f[R] endpoint behaves like the root endpoint, except for these two points: -.IP \[bu] 2 +.IP \(bu 2 It accepts a JSON array, each element of which is a JSON object like the one expected by the root endpoint. -.IP \[bu] 2 +.IP \(bu 2 It returns a JSON array of JSON results. .PP This endpoint can be used to convert a sequence of small snippets in one @@ -324,21 +330,21 @@ headers. .SS \f[CR]/babelmark\f[R] endpoint The \f[CR]/babelmark\f[R] endpoint accepts a GET request with the following query parameters: -.IP \[bu] 2 +.IP \(bu 2 \f[CR]text\f[R] (required string) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]from\f[R] (optional string, default is -\f[CR]\[dq]markdown\[dq]\f[R]) -.IP \[bu] 2 -\f[CR]to\f[R] (optional string, default is \f[CR]\[dq]html\[dq]\f[R]) -.IP \[bu] 2 +\f[CR]\(dqmarkdown\(dq\f[R]) +.IP \(bu 2 +\f[CR]to\f[R] (optional string, default is \f[CR]\(dqhtml\(dq\f[R]) +.IP \(bu 2 \f[CR]standalone\f[R] (optional boolean, default is \f[CR]false\f[R]) .PP It returns a JSON object with fields \f[CR]html\f[R] and \f[CR]version\f[R]. This endpoint is designed to support the Babelmark website. .SH AUTHORS -Copyright 2022 John MacFarlane (jgm\[at]berkeley.edu). +Copyright 2022 John MacFarlane (jgm\(atberkeley.edu). Released under the GPL, version 2 or greater. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.) diff --git a/pandoc-cli/man/pandoc.1 b/pandoc-cli/man/pandoc.1 index 755b23fb774c..7a2dd7f7c9e9 100644 --- a/pandoc-cli/man/pandoc.1 +++ b/pandoc-cli/man/pandoc.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.4 +.\" Automatically generated by Pandoc 3.7.0.2 .\" -.TH "pandoc" "1" "September 9, 2024" "pandoc 3.4" "Pandoc User\[cq]s Guide" +.TH "pandoc" "1" "2025\-05\-28" "pandoc 3.7.0.2" "Pandoc User\[cq]s Guide" .SH NAME pandoc - general markup converter .SH SYNOPSIS @@ -16,10 +16,10 @@ For the full lists of input and output formats, see the \f[CR]\-\-from\f[R] and \f[CR]\-\-to\f[R] options below. Pandoc can also produce PDF output: see creating a PDF, below. .PP -Pandoc\[cq]s enhanced version of Markdown includes syntax for tables, +Pandoc\(cqs enhanced version of Markdown includes syntax for tables, definition lists, metadata blocks, footnotes, citations, math, and much more. -See below under Pandoc\[cq]s Markdown. +See below under Pandoc\(cqs Markdown. .PP Pandoc has a modular design: it consists of a set of readers, which parse text in a given format and produce a native representation of the @@ -29,15 +29,15 @@ Thus, adding an input or output format requires only adding a reader or writer. Users can also run custom pandoc filters to modify the intermediate AST. .PP -Because pandoc\[cq]s intermediate representation of a document is less +Because pandoc\(cqs intermediate representation of a document is less expressive than many of the formats it converts between, one should not expect perfect conversions between every format and every other. Pandoc attempts to preserve the structural elements of a document, but not formatting details such as margin size. And some document elements, such as complex tables, may not fit into -pandoc\[cq]s simple document model. -While conversions from pandoc\[cq]s Markdown to all formats aspire to be -perfect, conversions from formats more expressive than pandoc\[cq]s +pandoc\(cqs simple document model. +While conversions from pandoc\(cqs Markdown to all formats aspire to be +perfect, conversions from formats more expressive than pandoc\(cqs Markdown can be expected to be lossy. .SS Using pandoc If no \f[I]input\-files\f[R] are specified, input is read from @@ -98,10 +98,10 @@ pandoc \-o hello.tex hello.txt .PP will convert \f[CR]hello.txt\f[R] from Markdown to LaTeX. If no output file is specified (so that output goes to -\f[I]stdout\f[R]), or if the output file\[cq]s extension is unknown, the +\f[I]stdout\f[R]), or if the output file\(cqs extension is unknown, the output format will default to HTML. If no input file is specified (so that input comes from -\f[I]stdin\f[R]), or if the input files\[cq] extensions are unknown, the +\f[I]stdin\f[R]), or if the input files\(cq extensions are unknown, the input format will be assumed to be Markdown. .SS Character encoding Pandoc uses the UTF\-8 character encoding for both input and output. @@ -193,7 +193,7 @@ It is possible to supply a custom User\-Agent string or other header when requesting a document from a URL: .IP .EX -pandoc \-f html \-t markdown \-\-request\-header User\-Agent:\[dq]Mozilla/5.0\[dq] \[rs] +pandoc \-f html \-t markdown \-\-request\-header User\-Agent:\(dqMozilla/5.0\(dq \(rs https://www.fsf.org .EE .SH OPTIONS @@ -203,97 +203,101 @@ pandoc \-f html \-t markdown \-\-request\-header User\-Agent:\[dq]Mozilla/5.0\[d Specify input format. \f[I]FORMAT\f[R] can be: .RS -.IP \[bu] 2 +.IP \(bu 2 \f[CR]bibtex\f[R] (BibTeX bibliography) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]biblatex\f[R] (BibLaTeX bibliography) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]bits\f[R] (BITS XML, alias for \f[CR]jats\f[R]) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]commonmark\f[R] (CommonMark Markdown) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]commonmark_x\f[R] (CommonMark Markdown with extensions) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]creole\f[R] (Creole 1.0) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]csljson\f[R] (CSL JSON bibliography) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]csv\f[R] (CSV table) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]tsv\f[R] (TSV table) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]djot\f[R] (Djot markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]docbook\f[R] (DocBook) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]docx\f[R] (Word docx) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]dokuwiki\f[R] (DokuWiki markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]endnotexml\f[R] (EndNote XML bibliography) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]epub\f[R] (EPUB) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]fb2\f[R] (FictionBook2 e\-book) -.IP \[bu] 2 +.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]. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]haddock\f[R] (Haddock markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]html\f[R] (HTML) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]ipynb\f[R] (Jupyter notebook) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]jats\f[R] (JATS XML) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]jira\f[R] (Jira/Confluence wiki markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]json\f[R] (JSON version of native AST) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]latex\f[R] (LaTeX) -.IP \[bu] 2 -\f[CR]markdown\f[R] (Pandoc\[cq]s Markdown) -.IP \[bu] 2 +.IP \(bu 2 +\f[CR]markdown\f[R] (Pandoc\(cqs Markdown) +.IP \(bu 2 \f[CR]markdown_mmd\f[R] (MultiMarkdown) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]markdown_phpextra\f[R] (PHP Markdown Extra) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]markdown_strict\f[R] (original unextended Markdown) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]mediawiki\f[R] (MediaWiki markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]man\f[R] (roff man) -.IP \[bu] 2 +.IP \(bu 2 +\f[CR]mdoc\f[R] (mdoc manual page markup) +.IP \(bu 2 \f[CR]muse\f[R] (Muse) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]native\f[R] (native Haskell) -.IP \[bu] 2 -\f[CR]odt\f[R] (OpenOffice text document) -.IP \[bu] 2 +.IP \(bu 2 +\f[CR]odt\f[R] (OpenDocument text document) +.IP \(bu 2 \f[CR]opml\f[R] (OPML) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]org\f[R] (Emacs Org mode) -.IP \[bu] 2 +.IP \(bu 2 +\f[CR]pod\f[R] (Perl\(cqs Plain Old Documentation) +.IP \(bu 2 \f[CR]ris\f[R] (RIS bibliography) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]rtf\f[R] (Rich Text Format) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]rst\f[R] (reStructuredText) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]t2t\f[R] (txt2tags) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]textile\f[R] (Textile) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]tikiwiki\f[R] (TikiWiki markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]twiki\f[R] (TWiki markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]typst\f[R] (typst) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]vimwiki\f[R] (Vimwiki) -.IP \[bu] 2 +.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 @@ -307,137 +311,137 @@ See \f[CR]\-\-list\-input\-formats\f[R] and Specify output format. \f[I]FORMAT\f[R] can be: .RS -.IP \[bu] 2 +.IP \(bu 2 \f[CR]ansi\f[R] (text with ANSI escape codes, for terminal viewing) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]asciidoc\f[R] (modern AsciiDoc as interpreted by AsciiDoctor) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]asciidoc_legacy\f[R] (AsciiDoc as interpreted by \f[CR]asciidoc\-py\f[R]). -.IP \[bu] 2 +.IP \(bu 2 \f[CR]asciidoctor\f[R] (deprecated synonym for \f[CR]asciidoc\f[R]) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]beamer\f[R] (LaTeX beamer slide show) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]bibtex\f[R] (BibTeX bibliography) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]biblatex\f[R] (BibLaTeX bibliography) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]chunkedhtml\f[R] (zip archive of multiple linked HTML files) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]commonmark\f[R] (CommonMark Markdown) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]commonmark_x\f[R] (CommonMark Markdown with extensions) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]context\f[R] (ConTeXt) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]csljson\f[R] (CSL JSON bibliography) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]djot\f[R] (Djot markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]docbook\f[R] or \f[CR]docbook4\f[R] (DocBook 4) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]docbook5\f[R] (DocBook 5) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]docx\f[R] (Word docx) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]dokuwiki\f[R] (DokuWiki markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]epub\f[R] or \f[CR]epub3\f[R] (EPUB v3 book) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]epub2\f[R] (EPUB v2) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]fb2\f[R] (FictionBook2 e\-book) -.IP \[bu] 2 +.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]. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]haddock\f[R] (Haddock markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]html\f[R] or \f[CR]html5\f[R] (HTML, i.e.\ HTML5/XHTML polyglot markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]html4\f[R] (XHTML 1.0 Transitional) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]icml\f[R] (InDesign ICML) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]ipynb\f[R] (Jupyter notebook) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]jats_archiving\f[R] (JATS XML, Archiving and Interchange Tag Set) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]jats_articleauthoring\f[R] (JATS XML, Article Authoring Tag Set) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]jats_publishing\f[R] (JATS XML, Journal Publishing Tag Set) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]jats\f[R] (alias for \f[CR]jats_archiving\f[R]) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]jira\f[R] (Jira/Confluence wiki markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]json\f[R] (JSON version of native AST) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]latex\f[R] (LaTeX) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]man\f[R] (roff man) -.IP \[bu] 2 -\f[CR]markdown\f[R] (Pandoc\[cq]s Markdown) -.IP \[bu] 2 +.IP \(bu 2 +\f[CR]markdown\f[R] (Pandoc\(cqs Markdown) +.IP \(bu 2 \f[CR]markdown_mmd\f[R] (MultiMarkdown) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]markdown_phpextra\f[R] (PHP Markdown Extra) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]markdown_strict\f[R] (original unextended Markdown) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]markua\f[R] (Markua) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]mediawiki\f[R] (MediaWiki markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]ms\f[R] (roff ms) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]muse\f[R] (Muse) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]native\f[R] (native Haskell) -.IP \[bu] 2 -\f[CR]odt\f[R] (OpenOffice text document) -.IP \[bu] 2 +.IP \(bu 2 +\f[CR]odt\f[R] (OpenDocument text document) +.IP \(bu 2 \f[CR]opml\f[R] (OPML) -.IP \[bu] 2 -\f[CR]opendocument\f[R] (OpenDocument) -.IP \[bu] 2 +.IP \(bu 2 +\f[CR]opendocument\f[R] (OpenDocument XML) +.IP \(bu 2 \f[CR]org\f[R] (Emacs Org mode) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]pdf\f[R] (PDF) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]plain\f[R] (plain text) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]pptx\f[R] (PowerPoint slide show) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]rst\f[R] (reStructuredText) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]rtf\f[R] (Rich Text Format) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]texinfo\f[R] (GNU Texinfo) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]textile\f[R] (Textile) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]slideous\f[R] (Slideous HTML and JavaScript slide show) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]slidy\f[R] (Slidy HTML and JavaScript slide show) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]dzslides\f[R] (DZSlides HTML5 + JavaScript slide show) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]revealjs\f[R] (reveal.js HTML5 + JavaScript slide show) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]s5\f[R] (S5 HTML and JavaScript slide show) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]tei\f[R] (TEI Simple) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]typst\f[R] (typst) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]xwiki\f[R] (XWiki markup) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]zimwiki\f[R] (ZimWiki markup) -.IP \[bu] 2 +.IP \(bu 2 the path of a custom Lua writer, see Custom readers and writers below .PP Note that \f[CR]odt\f[R], \f[CR]docx\f[R], \f[CR]epub\f[R], and @@ -473,12 +477,12 @@ subdirectory of the XDG data directory (by default, If that directory does not exist and \f[CR]$HOME/.pandoc\f[R] exists, it will be used (for backwards compatibility). On Windows the default user data directory is -\f[CR]%APPDATA%\[rs]pandoc\f[R]. +\f[CR]%APPDATA%\(rspandoc\f[R]. You can find the default user data directory on your system by looking at the output of \f[CR]pandoc \-\-version\f[R]. Data files placed in this directory (for example, \f[CR]reference.odt\f[R], \f[CR]reference.docx\f[R], -\f[CR]epub.css\f[R], \f[CR]templates\f[R]) will override pandoc\[cq]s +\f[CR]epub.css\f[R], \f[CR]templates\f[R]) will override pandoc\(cqs normal defaults. (Note that the user data directory is not created by pandoc, so you will need to create it yourself if you want to make use of it.) @@ -504,7 +508,7 @@ To enable bash completion with pandoc, add this to your .RS .IP .EX -eval \[dq]$(pandoc \-\-bash\-completion)\[dq] +eval \(dq$(pandoc \-\-bash\-completion)\(dq .EE .RE .TP @@ -532,7 +536,7 @@ List supported output formats, one per line. List supported extensions for \f[I]FORMAT\f[R], one per line, preceded by a \f[CR]+\f[R] or \f[CR]\-\f[R] indicating whether it is enabled by default in \f[I]FORMAT\f[R]. -If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[cq]s Markdown +If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\(cqs Markdown are given. .TP \f[CR]\-\-list\-highlight\-languages\f[R] @@ -571,7 +575,7 @@ Use \f[CI]\-\-shift\-heading\-level\-by\f[I]=X instead, where X = NUMBER \- 1.\f[R] Specify the base level for headings (defaults to 1). .TP \f[CR]\-\-indented\-code\-classes=\f[R]\f[I]CLASSES\f[R] -Specify classes to use for indented code blocks\[em]for example, +Specify classes to use for indented code blocks\(emfor example, \f[CR]perl,numberLines\f[R] or \f[CR]haskell\f[R]. Multiple classes may be separated by spaces or commas. .TP @@ -603,7 +607,7 @@ For example, a header with identifier \f[CR]foo\f[R] in Specify an executable to be used as a filter transforming the pandoc AST after the input is parsed and before the output is written. The executable should read JSON from stdin and write JSON to stdout. -The JSON must be formatted like pandoc\[cq]s own JSON input and output. +The JSON must be formatted like pandoc\(cqs own JSON input and output. The name of the output format will be passed to the filter as the first argument. Hence, @@ -645,7 +649,7 @@ specified on the command line. .TP \f[CR]\-L\f[R] \f[I]SCRIPT\f[R], \f[CR]\-\-lua\-filter=\f[R]\f[I]SCRIPT\f[R] Transform the document in a similar fashion as JSON filters (see -\f[CR]\-\-filter\f[R]), but use pandoc\[cq]s built\-in Lua filtering +\f[CR]\-\-filter\f[R]), but use pandoc\(cqs built\-in Lua filtering system. The given Lua script is expected to return a list of Lua filters which will be applied in order. @@ -656,7 +660,7 @@ applied. .PP The \f[CR]pandoc\f[R] Lua module provides helper functions for element creation. -It is always loaded into the script\[cq]s Lua environment. +It is always loaded into the script\(cqs Lua environment. .PP See the Lua filters documentation for further details. .PP @@ -690,7 +694,7 @@ This option can be used with every input format, but string scalars in the metadata file will always be parsed as Markdown. (If the input format is Markdown or a Markdown variant, then the same variant will be used to parse the metadata file; if it is a -non\-Markdown format, pandoc\[cq]s default Markdown extensions will be +non\-Markdown format, pandoc\(cqs default Markdown extensions will be used.) This option can be used repeatedly to include multiple metadata files; values in files specified later on the command line will be preferred @@ -713,7 +717,7 @@ Specify the number of spaces per tab (default is 4). .TP \f[CR]\-\-track\-changes=accept\f[R]|\f[CR]reject\f[R]|\f[CR]all\f[R] Specifies what to do with insertions, deletions, and comments produced -by the MS Word \[lq]Track Changes\[rq] feature. +by the MS Word \(lqTrack Changes\(rq feature. \f[CR]accept\f[R] (the default) processes all the insertions and deletions. \f[CR]reject\f[R] ignores them. @@ -774,21 +778,46 @@ included; otherwise, metadata is suppressed. Use the specified file as a custom template for the generated document. Implies \f[CR]\-\-standalone\f[R]. See Templates, below, for a description of template syntax. -If no extension is specified, an extension corresponding to the writer -will be added, so that \f[CR]\-\-template=special\f[R] looks for -\f[CR]special.html\f[R] for HTML output. If the template is not found, pandoc will search for it in the \f[CR]templates\f[R] subdirectory of the user data directory (see \f[CR]\-\-data\-dir\f[R]). +If no extension is specified and an extensionless template is not found, +pandoc will look for a template with an extension corresponding to the +writer, so that \f[CR]\-\-template=special\f[R] looks for +\f[CR]special.html\f[R] for HTML output. If this option is not used, a default template appropriate for the output format will be used (see \f[CR]\-D/\-\-print\-default\-template\f[R]). .TP -\f[CR]\-V\f[R] \f[I]KEY\f[R][\f[CR]=\f[R]\f[I]VAL\f[R]], \f[CR]\-\-variable=\f[R]\f[I]KEY\f[R][\f[CR]:\f[R]\f[I]VAL\f[R]] -Set the template variable \f[I]KEY\f[R] to the value \f[I]VAL\f[R] when -rendering the document in standalone mode. +\f[CR]\-V\f[R] \f[I]KEY\f[R][\f[CR]=\f[R]\f[I]VAL\f[R]], \f[CR]\-\-variable=\f[R]\f[I]KEY\f[R][\f[CR]=\f[R]\f[I]VAL\f[R]] +Set the template variable \f[I]KEY\f[R] to the string value +\f[I]VAL\f[R] when rendering the document in standalone mode. +Either \f[CR]:\f[R] or \f[CR]=\f[R] may be used to separate +\f[I]KEY\f[R] from \f[I]VAL\f[R]. If no \f[I]VAL\f[R] is specified, the key will be given the value \f[CR]true\f[R]. +Structured values (lists, maps) cannot be assigned using this option, +but they can be assigned in the \f[CR]variables\f[R] section of a +defaults file or using the \f[CR]\-\-variable\-json\f[R] option. +If the variable already has a \f[I]list\f[R] value, the value will be +added to the list. +If it already has another kind of value, it will be made into a list +containing the previous and the new value. +For example, \f[CR]\-V keyword=Joe \-V author=Sue\f[R] makes +\f[CR]author\f[R] contain a list of strings: \f[CR]Joe\f[R] and +\f[CR]Sue\f[R]. +.TP +\f[CR]\-\-variable\-json=\f[R]\f[I]KEY\f[R][\f[CR]=\f[R]:\f[I]JSON\f[R]] +Set the template variable \f[I]KEY\f[R] to the value specified by a JSON +string (this may be a boolean, a string, a list, or a mapping; a number +will be treated as a string). +For example, \f[CR]\-\-variable\-json foo=false\f[R] will give +\f[CR]foo\f[R] the boolean false value, while +\f[CR]\-\-variable\-json foo=\(aq\(dqfalse\(dq\(aq\f[R] will give it the +string value \f[CR]\(dqfalse\(dq\f[R]. +Either \f[CR]:\f[R] or \f[CR]=\f[R] may be used to separate +\f[I]KEY\f[R] from \f[I]VAL\f[R]. +If the variable already has a value, this value will be replaced. .TP \f[CR]\-\-sandbox[=true|false]\f[R] Run pandoc in a sandbox, limiting IO operations in readers and writers @@ -878,10 +907,14 @@ and it has no effect on \f[CR]man\f[R], \f[CR]docbook4\f[R], \f[CR]docbook5\f[R], or \f[CR]jats\f[R] output. .RS .PP -Note that if you are producing a PDF via \f[CR]ms\f[R], the table of -contents will appear at the beginning of the document, before the title. +Note that if you are producing a PDF via \f[CR]ms\f[R] and using (the +default) \f[CR]pdfroff\f[R] as a \f[CR]\-\-pdf\-engine\f[R], the table +of contents will appear at the beginning of the document, before the +title. If you would prefer it to be at the end of the document, use the option \f[CR]\-\-pdf\-engine\-opt=\-\-no\-toc\-relocation\f[R]. +If \f[CR]groff\f[R] is used as the \f[CR]\-\-pdf\-engine\f[R], the table +of contents will always appear at the end of the document. .RE .TP \f[CR]\-\-toc\-depth=\f[R]\f[I]NUMBER\f[R] @@ -890,6 +923,20 @@ contents. The default is 3 (which means that level\-1, 2, and 3 headings will be listed in the contents). .TP +\f[CR]\-\-lof[=true|false]\f[R], \f[CR]\-\-list\-of\-figures[=true|false]\f[R] +Include an automatically generated list of figures (or, in some formats, +an instruction to create one) in the output document. +This option has no effect unless \f[CR]\-s/\-\-standalone\f[R] is used, +and it only has an effect on \f[CR]latex\f[R], \f[CR]context\f[R], and +\f[CR]docx\f[R] output. +.TP +\f[CR]\-\-lot[=true|false]\f[R], \f[CR]\-\-list\-of\-tables[=true|false]\f[R] +Include an automatically generated list of tables (or, in some formats, +an instruction to create one) in the output document. +This option has no effect unless \f[CR]\-s/\-\-standalone\f[R] is used, +and it only has an effect on \f[CR]latex\f[R], \f[CR]context\f[R], and +\f[CR]docx\f[R] output. +.TP \f[CR]\-\-strip\-comments[=true|false]\f[R] Strip out HTML comments in the Markdown or Textile source, rather than passing them on to Markdown, Textile or HTML output as raw HTML. @@ -946,7 +993,7 @@ Implies \f[CR]\-\-standalone\f[R]. \f[CR]\-B\f[R] \f[I]FILE\f[R], \f[CR]\-\-include\-before\-body=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R] Include contents of \f[I]FILE\f[R], verbatim, at the beginning of the document body (e.g.\ after the \f[CR]\f[R] tag in HTML, or the -\f[CR]\[rs]begin{document}\f[R] command in LaTeX). +\f[CR]\(rsbegin{document}\f[R] command in LaTeX). This can be used to include navigation bars or banners in HTML documents. This option can be used repeatedly to include multiple files. @@ -960,7 +1007,7 @@ appropriate OpenXML format. \f[CR]\-A\f[R] \f[I]FILE\f[R], \f[CR]\-\-include\-after\-body=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R] Include contents of \f[I]FILE\f[R], verbatim, at the end of the document body (before the \f[CR]\f[R] tag in HTML, or the -\f[CR]\[rs]end{document}\f[R] command in LaTeX). +\f[CR]\(rsend{document}\f[R] command in LaTeX). This option can be used repeatedly to include multiple files. They will be included in the order specified. Implies \f[CR]\-\-standalone\f[R]. @@ -994,7 +1041,7 @@ pandoc is generating LaTeX or HTML). Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when making HTTP requests (for example, when a URL is given on the command line, or when resources used in a document must be downloaded). -If you\[cq]re behind a proxy, you also need to set the environment +If you\(cqre behind a proxy, you also need to set the environment variable \f[CR]http_proxy\f[R] to \f[CR]http://...\f[R]. .TP \f[CR]\-\-no\-check\-certificate[=true|false]\f[R] @@ -1011,9 +1058,9 @@ signed). Produce a standalone HTML file with no external dependencies, using \f[CR]data:\f[R] URIs to incorporate the contents of linked scripts, stylesheets, images, and videos. -The resulting file should be \[lq]self\-contained,\[rq] in the sense -that it needs no external files and no net access to be displayed -properly by a browser. +The resulting file should be \(lqself\-contained,\(rq in the sense that +it needs no external files and no net access to be displayed properly by +a browser. This option works only with HTML output formats, including \f[CR]html4\f[R], \f[CR]html5\f[R], \f[CR]html+lhs\f[R], \f[CR]html5+lhs\f[R], \f[CR]s5\f[R], \f[CR]slidy\f[R], @@ -1022,13 +1069,13 @@ Scripts, images, and stylesheets at absolute URLs will be downloaded; those at relative URLs will be sought relative to the working directory (if the first source file is local) or relative to the base URL (if the first source file is remote). -Elements with the attribute \f[CR]data\-external=\[dq]1\[dq]\f[R] will -be left alone; the documents they link to will not be incorporated in -the document. +Elements with the attribute \f[CR]data\-external=\(dq1\(dq\f[R] will be +left alone; the documents they link to will not be incorporated in the +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 \[lq]self\-contained\[rq] +or speaker notes) may not work in an offline \(lqself\-contained\(rq \f[CR]reveal.js\f[R] slide show. .RS .PP @@ -1110,8 +1157,16 @@ option is specified), \f[CR]chapter\f[R] is implied as the setting for this option. If \f[CR]beamer\f[R] is the output format, specifying either \f[CR]chapter\f[R] or \f[CR]part\f[R] will cause top\-level headings to -become \f[CR]\[rs]part{..}\f[R], while second\-level headings remain as +become \f[CR]\(rspart{..}\f[R], while second\-level headings remain as their default type. +.RS +.PP +In Docx output, this option adds section breaks before first\-level +headings if \f[CR]chapter\f[R] is selected, and before first\- and +second\-level headings if \f[CR]part\f[R] is selected. +Footnote numbers will restart with each section break unless the +reference doc modifies this. +.RE .TP \f[CR]\-N\f[R], \f[CR]\-\-number\-sections=[true|false]\f[R] Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB @@ -1125,10 +1180,10 @@ Offsets for section heading numbers. The first number is added to the section number for level\-1 headings, the second for level\-2 headings, and so on. So, for example, if you want the first level\-1 heading in your document -to be numbered \[lq]6\[rq] instead of \[lq]1\[rq], specify +to be numbered \(lq6\(rq instead of \(lq1\(rq, specify \f[CR]\-\-number\-offset=5\f[R]. If your document starts with a level\-2 heading which you want to be -numbered \[lq]1.5\[rq], specify \f[CR]\-\-number\-offset=1,4\f[R]. +numbered \(lq1.5\(rq, specify \f[CR]\-\-number\-offset=1,4\f[R]. \f[CR]\-\-number\-offset\f[R] only directly affects the number of the first section heading in a document; subsequent numbers increment in the normal way. @@ -1235,87 +1290,85 @@ For best results, do not make changes to this file other than modifying the styles used by pandoc: .PP Paragraph styles: -.IP \[bu] 2 +.IP \(bu 2 Normal -.IP \[bu] 2 +.IP \(bu 2 Body Text -.IP \[bu] 2 +.IP \(bu 2 First Paragraph -.IP \[bu] 2 +.IP \(bu 2 Compact -.IP \[bu] 2 +.IP \(bu 2 Title -.IP \[bu] 2 +.IP \(bu 2 Subtitle -.IP \[bu] 2 +.IP \(bu 2 Author -.IP \[bu] 2 +.IP \(bu 2 Date -.IP \[bu] 2 +.IP \(bu 2 Abstract -.IP \[bu] 2 +.IP \(bu 2 AbstractTitle -.IP \[bu] 2 +.IP \(bu 2 Bibliography -.IP \[bu] 2 +.IP \(bu 2 Heading 1 -.IP \[bu] 2 +.IP \(bu 2 Heading 2 -.IP \[bu] 2 +.IP \(bu 2 Heading 3 -.IP \[bu] 2 +.IP \(bu 2 Heading 4 -.IP \[bu] 2 +.IP \(bu 2 Heading 5 -.IP \[bu] 2 +.IP \(bu 2 Heading 6 -.IP \[bu] 2 +.IP \(bu 2 Heading 7 -.IP \[bu] 2 +.IP \(bu 2 Heading 8 -.IP \[bu] 2 +.IP \(bu 2 Heading 9 -.IP \[bu] 2 +.IP \(bu 2 Block Text [for block quotes] -.IP \[bu] 2 +.IP \(bu 2 Footnote Block Text [for block quotes in footnotes] -.IP \[bu] 2 +.IP \(bu 2 Source Code -.IP \[bu] 2 +.IP \(bu 2 Footnote Text -.IP \[bu] 2 +.IP \(bu 2 Definition Term -.IP \[bu] 2 +.IP \(bu 2 Definition -.IP \[bu] 2 +.IP \(bu 2 Caption -.IP \[bu] 2 +.IP \(bu 2 Table Caption -.IP \[bu] 2 +.IP \(bu 2 Image Caption -.IP \[bu] 2 +.IP \(bu 2 Figure -.IP \[bu] 2 +.IP \(bu 2 Captioned Figure -.IP \[bu] 2 +.IP \(bu 2 TOC Heading .PP Character styles: -.IP \[bu] 2 +.IP \(bu 2 Default Paragraph Font -.IP \[bu] 2 -Body Text Char -.IP \[bu] 2 +.IP \(bu 2 Verbatim Char -.IP \[bu] 2 +.IP \(bu 2 Footnote Reference -.IP \[bu] 2 +.IP \(bu 2 Hyperlink -.IP \[bu] 2 +.IP \(bu 2 Section Number .PP Table style: -.IP \[bu] 2 +.IP \(bu 2 Table .RE .TP @@ -1345,19 +1398,19 @@ are most templates derived from these. .PP The specific requirement is that the template should contain layouts with the following names (as seen within PowerPoint): -.IP \[bu] 2 +.IP \(bu 2 Title Slide -.IP \[bu] 2 +.IP \(bu 2 Title and Content -.IP \[bu] 2 +.IP \(bu 2 Section Header -.IP \[bu] 2 +.IP \(bu 2 Two Content -.IP \[bu] 2 +.IP \(bu 2 Comparison -.IP \[bu] 2 +.IP \(bu 2 Content with Caption -.IP \[bu] 2 +.IP \(bu 2 Blank .PP For each name, the first layout found with that name will be used. @@ -1388,7 +1441,7 @@ Some readers may be slow if the chapter files are too large, so for large documents with few level\-1 headings, one might want to use a chapter level of 2 or 3. For chunked HTML, this option determines how much content goes in each -\[lq]chunk.\[rq] +\(lqchunk.\(rq .TP \f[CR]\-\-chunk\-template=\f[R]\f[I]PATHTEMPLATE\f[R] Specify a template for the filenames in a \f[CR]chunkedhtml\f[R] @@ -1399,8 +1452,8 @@ 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 \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. +The characters \f[CR]/\f[R] and \f[CR]\(rs\f[R] are not allowed in chunk +templates and will be ignored. The default is \f[CR]%s\-%i.html\f[R]. .TP \f[CR]\-\-epub\-chapter\-level=\f[R]\f[I]NUMBER\f[R] @@ -1434,7 +1487,7 @@ By default, pandoc will include the following metadata elements: (from the document authors), \f[CR]\f[R] (from the document date, which should be in ISO 8601 format), \f[CR]\f[R] (from the \f[CR]lang\f[R] variable, or, if is not set, the locale), and -\f[CR]\f[R] (a randomly generated +\f[CR]\f[R] (a randomly generated UUID). Any of these may be overridden by elements in the metadata file. .PP @@ -1455,31 +1508,31 @@ following to your CSS (see \f[CR]\-\-css\f[R]): .RS .IP .EX -\[at]font\-face { +\(atfont\-face { font\-family: DejaVuSans; font\-style: normal; font\-weight: normal; - src:url(\[dq]../fonts/DejaVuSans\-Regular.ttf\[dq]); + src:url(\(dq../fonts/DejaVuSans\-Regular.ttf\(dq); } -\[at]font\-face { +\(atfont\-face { font\-family: DejaVuSans; font\-style: normal; font\-weight: bold; - src:url(\[dq]../fonts/DejaVuSans\-Bold.ttf\[dq]); + src:url(\(dq../fonts/DejaVuSans\-Bold.ttf\(dq); } -\[at]font\-face { +\(atfont\-face { font\-family: DejaVuSans; font\-style: italic; font\-weight: normal; - src:url(\[dq]../fonts/DejaVuSans\-Oblique.ttf\[dq]); + src:url(\(dq../fonts/DejaVuSans\-Oblique.ttf\(dq); } -\[at]font\-face { +\(atfont\-face { font\-family: DejaVuSans; font\-style: italic; font\-weight: bold; - src:url(\[dq]../fonts/DejaVuSans\-BoldOblique.ttf\[dq]); + src:url(\(dq../fonts/DejaVuSans\-BoldOblique.ttf\(dq); } -body { font\-family: \[dq]DejaVuSans\[dq]; } +body { font\-family: \(dqDejaVuSans\(dq; } .EE .RE .TP @@ -1503,35 +1556,44 @@ Use the specified engine when producing PDF output. Valid values are \f[CR]pdflatex\f[R], \f[CR]lualatex\f[R], \f[CR]xelatex\f[R], \f[CR]latexmk\f[R], \f[CR]tectonic\f[R], \f[CR]wkhtmltopdf\f[R], \f[CR]weasyprint\f[R], \f[CR]pagedjs\-cli\f[R], -\f[CR]prince\f[R], \f[CR]context\f[R], \f[CR]pdfroff\f[R], and -\f[CR]typst\f[R]. +\f[CR]prince\f[R], \f[CR]context\f[R], \f[CR]groff\f[R], +\f[CR]pdfroff\f[R], and \f[CR]typst\f[R]. If the engine is not in your PATH, the full path of the engine may be specified here. If this option is not specified, pandoc uses the following defaults depending on the output format specified using \f[CR]\-t/\-\-to\f[R]: .RS -.IP \[bu] 2 +.IP \(bu 2 \f[CR]\-t latex\f[R] or none: \f[CR]pdflatex\f[R] (other options: \f[CR]xelatex\f[R], \f[CR]lualatex\f[R], \f[CR]tectonic\f[R], \f[CR]latexmk\f[R]) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]\-t context\f[R]: \f[CR]context\f[R] -.IP \[bu] 2 +.IP \(bu 2 \f[CR]\-t html\f[R]: \f[CR]weasyprint\f[R] (other options: \f[CR]prince\f[R], \f[CR]wkhtmltopdf\f[R], \f[CR]pagedjs\-cli\f[R]; see print\-css.rocks for a good introduction to PDF generation from HTML/CSS) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]\-t ms\f[R]: \f[CR]pdfroff\f[R] -.IP \[bu] 2 +.IP \(bu 2 \f[CR]\-t typst\f[R]: \f[CR]typst\f[R] +.PP +This option is normally intended to be used when a PDF file is specified +as \f[CR]\-o/\-\-output\f[R]. +However, it may still have an effect when other output formats are +requested. +For example, \f[CR]ms\f[R] output will include \f[CR].pdfhref\f[R] +macros only if a \f[CR]\-\-pdf\-engine\f[R] is selected, and the macros +will be differently encoded depending on whether \f[CR]groff\f[R] or +\f[CR]pdfroff\f[R] is specified. .RE .TP \f[CR]\-\-pdf\-engine\-opt=\f[R]\f[I]STRING\f[R] Use the given string as a command\-line argument to the \f[CR]pdf\-engine\f[R]. For example, to use a persistent directory \f[CR]foo\f[R] for -\f[CR]latexmk\f[R]\[cq]s auxiliary files, use +\f[CR]latexmk\f[R]\(cqs auxiliary files, use \f[CR]\-\-pdf\-engine\-opt=\-outdir=foo\f[R]. Note that no check for duplicate options is done. .SS Citation rendering @@ -1556,15 +1618,14 @@ order they appear on the command line. For more information, see the section on Citations. .RS .PP -Note: if your target format is \f[CR]markdown\f[R], \f[CR]org\f[R], or -\f[CR]typst\f[R], you will need to disable the \f[CR]citations\f[R] -extension (e.g., \f[CR]\-t markdown\-citations\f[R]) to see the rendered -citations and bibliography. -Otherwise the format\[cq]s own citation syntax will be used. +Note: if this option is specified, the \f[CR]citations\f[R] extension +will be disabled automatically in the writer, to ensure that the +citeproc\-generated citations will be rendered instead of the +format\(cqs own citation syntax. .RE .TP \f[CR]\-\-bibliography=\f[R]\f[I]FILE\f[R] -Set the \f[CR]bibliography\f[R] field in the document\[cq]s metadata to +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. @@ -1573,7 +1634,7 @@ 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]). .TP \f[CR]\-\-csl=\f[R]\f[I]FILE\f[R] -Set the \f[CR]csl\f[R] field in the document\[cq]s metadata to +Set the \f[CR]csl\f[R] field in the document\(cqs metadata to \f[I]FILE\f[R], overriding any value set in the metadata. (This is equivalent to \f[CR]\-\-metadata csl=FILE\f[R].) If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP. @@ -1583,7 +1644,7 @@ and finally in the \f[CR]csl\f[R] subdirectory of the pandoc user data directory. .TP \f[CR]\-\-citation\-abbreviations=\f[R]\f[I]FILE\f[R] -Set the \f[CR]citation\-abbreviations\f[R] field in the document\[cq]s +Set the \f[CR]citation\-abbreviations\f[R] field in the document\(cqs metadata to \f[I]FILE\f[R], overriding any value set in the metadata. (This is equivalent to \f[CR]\-\-metadata citation\-abbreviations=FILE\f[R].) @@ -1610,7 +1671,7 @@ with \f[CR]bibtex\f[R] or \f[CR]biber\f[R]. 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=\[dq]math\[dq]\f[R], so that they may be styled differently +\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 @@ -1618,8 +1679,8 @@ options. .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. -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 +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]\f[R] tags with class \f[CR]math\f[R]. Then the MathJax JavaScript will render it. The \f[I]URL\f[R] should point to the \f[CR]MathJax.js\f[R] load script. @@ -1643,7 +1704,7 @@ For SVG images you can for example use 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\[cq]re targeting a version of +well as HTML, 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]] @@ -1820,35 +1881,34 @@ from stdin, and it can be an empty sequence \f[CR][]\f[R] for no input. .IP .EX - command line defaults file - \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- - \-\-from markdown+emoji from: markdown+emoji - - reader: markdown+emoji + command line defaults file + \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + \-\-from markdown+emoji from: markdown+emoji + + reader: markdown+emoji - to: markdown+hard_line_breaks - \-\-to markdown+hard_line_breaks - - writer: markdown+hard_line_breaks + \-\-to markdown+hard_line_breaks to: markdown+hard_line_breaks + + writer: markdown+hard_line_breaks - \-\-output foo.pdf output\-file: foo.pdf + \-\-output foo.pdf output\-file: foo.pdf - \-\-output \- output\-file: + \-\-output \- output\-file: - \-\-data\-dir dir data\-dir: dir + \-\-data\-dir dir data\-dir: dir - \-\-defaults file defaults: - \- file + \-\-defaults file defaults: + \- file - \-\-verbose verbosity: INFO + \-\-verbose verbosity: INFO - \-\-quiet verbosity: ERROR + \-\-quiet verbosity: ERROR - \-\-fail\-if\-warnings fail\-if\-warnings: true + \-\-fail\-if\-warnings fail\-if\-warnings: true - \-\-sandbox sandbox: true + \-\-sandbox sandbox: true - \-\-log=FILE log\-file: FILE + \-\-log=FILE log\-file: FILE .EE .RE @@ -1863,44 +1923,43 @@ those in another file included with a \f[CR]defaults:\f[R] entry. .IP .EX - command line defaults file - \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- - \-\-shift\-heading\-level\-by \-1 shift\-heading\-level\-by: \-1 + command line defaults file + \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + \-\-shift\-heading\-level\-by \-1 shift\-heading\-level\-by: \-1 - indented\-code\-classes: - \-\-indented\-code\-classes python \- python + \-\-indented\-code\-classes python indented\-code\-classes: + \- python - - \-\-default\-image\-extension \[dq].jpg\[dq] default\-image\-extension: \[aq].jpg\[aq] + \-\-default\-image\-extension \(dq.jpg\(dq default\-image\-extension: \(aq.jpg\(aq - \-\-file\-scope file\-scope: true + \-\-file\-scope file\-scope: true - \-\-citeproc \[rs] filters: - \- citeproc - \-\-lua\-filter count\-words.lua \[rs] \- count\-words.lua - \-\-filter special.lua \- type: json - path: special.lua + \-\-citeproc \(rs filters: + \-\-lua\-filter count\-words.lua \(rs \- citeproc + \-\-filter special.lua \- count\-words.lua + \- type: json + path: special.lua - \-\-metadata key=value \[rs] metadata: - \-\-metadata key2 key: value - key2: true + \-\-metadata key=value \(rs metadata: + \-\-metadata key2 key: value + key2: true - \-\-metadata\-file meta.yaml metadata\-files: - \- meta.yaml - - metadata\-file: meta.yaml + \-\-metadata\-file meta.yaml metadata\-files: + \- meta.yaml + + metadata\-file: meta.yaml - \-\-preserve\-tabs preserve\-tabs: true + \-\-preserve\-tabs preserve\-tabs: true - \-\-tab\-stop 8 tab\-stop: 8 + \-\-tab\-stop 8 tab\-stop: 8 - \-\-track\-changes accept track\-changes: accept + \-\-track\-changes accept track\-changes: accept - \-\-extract\-media dir extract\-media: dir + \-\-extract\-media dir extract\-media: dir - \-\-abbreviations abbrevs.txt abbreviations: abbrevs.txt + \-\-abbreviations abbrevs.txt abbreviations: abbrevs.txt - \-\-trace trace: true + \-\-trace trace: true .EE .RE @@ -1919,57 +1978,56 @@ or \f[CR]{type: citeproc}\f[R]. .IP .EX - command line defaults file - \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- - \-\-standalone standalone: true + command line defaults file + \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + \-\-standalone standalone: true - \-\-template letter template: letter + \-\-template letter template: letter - \-\-variable key=val \[rs] variables: - \-\-variable key2 key: val - key2: true + \-\-variable key=val \(rs variables: + \-\-variable key2 key: val + key2: true - \-\-eol nl eol: nl + \-\-eol nl eol: nl - \-\-dpi 300 dpi: 300 + \-\-dpi 300 dpi: 300 - \-\-wrap 60 wrap: 60 + \-\-wrap 60 wrap: 60 - \-\-columns 72 columns: 72 + \-\-columns 72 columns: 72 - \-\-table\-of\-contents table\-of\-contents: true + \-\-table\-of\-contents table\-of\-contents: true - \-\-toc toc: true + \-\-toc toc: true - \-\-toc\-depth 3 toc\-depth: 3 + \-\-toc\-depth 3 toc\-depth: 3 - \-\-strip\-comments strip\-comments: true + \-\-strip\-comments strip\-comments: true - \-\-no\-highlight highlight\-style: null + \-\-no\-highlight highlight\-style: null - \-\-highlight\-style kate highlight\-style: kate + \-\-highlight\-style kate highlight\-style: kate - syntax\-definitions: - \-\-syntax\-definition mylang.xml \- mylang.xml - - syntax\-definition: mylang.xml + \-\-syntax\-definition mylang.xml syntax\-definitions: + \- mylang.xml + + syntax\-definition: mylang.xml - \-\-include\-in\-header inc.tex include\-in\-header: - \- inc.tex + \-\-include\-in\-header inc.tex include\-in\-header: + \- inc.tex - include\-before\-body: -\-\-include\-before\-body inc.tex \- inc.tex + \-\-include\-before\-body inc.tex include\-before\-body: + \- inc.tex - \-\-include\-after\-body inc.tex include\-after\-body: - \- inc.tex + \-\-include\-after\-body inc.tex include\-after\-body: + \- inc.tex - \-\-resource\-path .:foo resource\-path: [\[aq].\[aq],\[aq]foo\[aq]] + \-\-resource\-path .:foo resource\-path: [\(aq.\(aq,\(aqfoo\(aq] - \-\-request\-header foo:bar request\-headers: - - \- [\[dq]User\-Agent\[dq], \[dq]Mozilla/5.0\[dq]] + \-\-request\-header foo:bar request\-headers: + \- [\(dqUser\-Agent\(dq, \(dqMozilla/5.0\(dq] - \-\-no\-check\-certificate no\-check\-certificate: true + \-\-no\-check\-certificate no\-check\-certificate: true .EE .RE @@ -1978,83 +2036,86 @@ or \f[CR]{type: citeproc}\f[R]. .IP .EX - command line defaults file - \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- - \-\-self\-contained self\-contained: true + command line defaults file + \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + \-\-self\-contained self\-contained: true - \-\-link\-images link\-images: true + \-\-link\-images link\-images: true - \-\-html\-q\-tags html\-q\-tags: true + \-\-html\-q\-tags html\-q\-tags: true - \-\-ascii ascii: true + \-\-ascii ascii: true - \-\-reference\-links reference\-links: true + \-\-reference\-links reference\-links: true - \-\-reference\-location block reference\-location: block + \-\-reference\-location block reference\-location: block - - \-\-figure\-caption\-position=above figure\-caption\-position: above + \-\-figure\-caption\-position=above figure\-caption\-position: above - table\-caption\-position: below - \-\-table\-caption\-position=below + \-\-table\-caption\-position=below table\-caption\-position: below - \-\-markdown\-headings atx markdown\-headings: atx + \-\-markdown\-headings atx markdown\-headings: atx - \-\-list\-tables list\-tables: true + \-\-list\-tables list\-tables: true - \-\-top\-level\-division chapter top\-level\-division: chapter + \-\-top\-level\-division chapter top\-level\-division: chapter - \-\-number\-sections number\-sections: true + \-\-number\-sections number\-sections: true - \-\-number\-offset=1,4 number\-offset: \[rs][1,4\[rs]] + \-\-number\-offset=1,4 number\-offset: \(rs[1,4\(rs] - \-\-listings listings: true + \-\-listings listings: true - \-\-incremental incremental: true + \-\-list\-of\-figures list\-of\-figures: true - \-\-slide\-level 2 slide\-level: 2 + \-\-lof lof: true - \-\-section\-divs section\-divs: true + \-\-list\-of\-tables list\-of\-tables: true - email\-obfuscation: references - \-\-email\-obfuscation references + \-\-lot lot: true - \-\-id\-prefix ch1 identifier\-prefix: ch1 + \-\-incremental incremental: true - \-\-title\-prefix MySite title\-prefix: MySite + \-\-slide\-level 2 slide\-level: 2 - \-\-css styles/screen.css \[rs] css: - \-\-css styles/special.css \- styles/screen.css - \- styles/special.css + \-\-section\-divs section\-divs: true - \-\-reference\-doc my.docx reference\-doc: my.docx + \-\-email\-obfuscation references email\-obfuscation: references - \-\-epub\-cover\-image cover.jpg epub\-cover\-image: cover.jpg + \-\-id\-prefix ch1 identifier\-prefix: ch1 - \-\-epub\-title\-page=false epub\-title\-page: false + \-\-title\-prefix MySite title\-prefix: MySite - \-\-epub\-metadata meta.xml epub\-metadata: meta.xml + \-\-css styles/screen.css \(rs css: + \-\-css styles/special.css \- styles/screen.css + \- styles/special.css - epub\-fonts: - \-\-epub\-embed\-font special.otf \[rs] \- special.otf - \- headline.otf - \-\-epub\-embed\-font headline.otf + \-\-reference\-doc my.docx reference\-doc: my.docx - \-\-split\-level 2 split\-level: 2 + \-\-epub\-cover\-image cover.jpg epub\-cover\-image: cover.jpg - \-\-chunk\-template=\[dq]%i.html\[dq] chunk\-template: \[dq]%i.html\[dq] + \-\-epub\-title\-page=false epub\-title\-page: false - \-\-epub\-subdirectory=\[dq]\[dq] epub\-subdirectory: \[aq]\[aq] + \-\-epub\-metadata meta.xml epub\-metadata: meta.xml - \-\-ipynb\-output best ipynb\-output: best + \-\-epub\-embed\-font special.otf \(rs epub\-fonts: + \-\-epub\-embed\-font headline.otf \- special.otf + \- headline.otf - \-\-pdf\-engine xelatex pdf\-engine: xelatex + \-\-split\-level 2 split\-level: 2 - pdf\-engine\-opts: - \-\-pdf\-engine\-opt=\-\-shell\-escape \- \[aq]\-shell\-escape\[aq] - - - pdf\-engine\-opt: \[aq]\-shell\-escape\[aq] + \-\-chunk\-template=\(dq%i.html\(dq chunk\-template: \(dq%i.html\(dq + + \-\-epub\-subdirectory=\(dq\(dq epub\-subdirectory: \(aq\(aq + + \-\-ipynb\-output best ipynb\-output: best + + \-\-pdf\-engine xelatex pdf\-engine: xelatex + + \-\-pdf\-engine\-opt=\-\-shell\-escape pdf\-engine\-opts: + \- \(aq\-shell\-escape\(aq + + pdf\-engine\-opt: \(aq\-shell\-escape\(aq .EE .RE @@ -2063,20 +2124,19 @@ or \f[CR]{type: citeproc}\f[R]. .IP .EX - command line defaults file - \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- - \-\-citeproc citeproc: true + command line defaults file + \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + \-\-citeproc citeproc: true - \-\-bibliography logic.bib bibliography: logic.bib + \-\-bibliography logic.bib bibliography: logic.bib - \-\-csl ieee.csl csl: ieee.csl + \-\-csl ieee.csl csl: ieee.csl - - \-\-citation\-abbreviations ab.json citation\-abbreviations: ab.json + \-\-citation\-abbreviations ab.json citation\-abbreviations: ab.json - \-\-natbib cite\-method: natbib + \-\-natbib cite\-method: natbib - \-\-biblatex cite\-method: biblatex + \-\-biblatex cite\-method: biblatex .EE .RE @@ -2151,28 +2211,37 @@ format \f[I]FORMAT\f[R] by putting a file \f[CR]templates/default.*FORMAT*\f[R] in the user data directory (see \f[CR]\-\-data\-dir\f[R], above). \f[I]Exceptions:\f[R] -.IP \[bu] 2 +.IP \(bu 2 For \f[CR]odt\f[R] output, customize the \f[CR]default.opendocument\f[R] template. -.IP \[bu] 2 +.IP \(bu 2 +For \f[CR]docx\f[R] output, customize the \f[CR]default.openxml\f[R] +template. +.IP \(bu 2 For \f[CR]pdf\f[R] output, customize the \f[CR]default.latex\f[R] template (or the \f[CR]default.context\f[R] template, if you use \f[CR]\-t context\f[R], or the \f[CR]default.ms\f[R] template, if you use \f[CR]\-t ms\f[R], or the \f[CR]default.html\f[R] template, if you use \f[CR]\-t html\f[R]). -.IP \[bu] 2 -\f[CR]docx\f[R] and \f[CR]pptx\f[R] have no template (however, you can -use \f[CR]\-\-reference\-doc\f[R] to customize the output). +.IP \(bu 2 +\f[CR]pptx\f[R] has no template. +.PP +Note that \f[CR]docx\f[R], \f[CR]odt\f[R], and \f[CR]pptx\f[R] output +can also be customized using \f[CR]\-\-reference\-doc\f[R]. +Use a reference doc to adjust the styles in your document; use a +template to handle variable interpolation and customize the presentation +of metadata, the position of the table of contents, boilerplate text, +etc. .PP Templates contain \f[I]variables\f[R], which allow for the inclusion of arbitrary information at any point in the file. They may be set at the command line using the \f[CR]\-V/\-\-variable\f[R] option. If a variable is not set, pandoc will look for the key in the -document\[cq]s metadata, which can be set using either YAML metadata +document\(cqs metadata, which can be set using either YAML metadata blocks or with the \f[CR]\-M/\-\-metadata\f[R] option. In addition, some variables are given default values by pandoc. -See Variables below for a list of variables used in pandoc\[cq]s default +See Variables below for a list of variables used in pandoc\(cqs default templates. .PP If you use custom templates, you may need to revise them as pandoc @@ -2223,16 +2292,16 @@ values. So, for example, \f[CR]employee.salary\f[R] will return the value of the \f[CR]salary\f[R] field of the object that is the value of the \f[CR]employee\f[R] field. -.IP \[bu] 2 +.IP \(bu 2 If the value of the variable is a simple value, it will be rendered verbatim. (Note that no escaping is done; the assumption is that the calling program will escape the strings appropriately for the output format.) -.IP \[bu] 2 +.IP \(bu 2 If the value is a list, the values will be concatenated. -.IP \[bu] 2 +.IP \(bu 2 If the value is a map, the string \f[CR]true\f[R] will be rendered. -.IP \[bu] 2 +.IP \(bu 2 Every other value will be rendered as the empty string. .SS Conditionals A conditional begins with \f[CR]if(variable)\f[R] (enclosed in matched @@ -2243,13 +2312,13 @@ delimiters). The \f[CR]if\f[R] section is used if \f[CR]variable\f[R] has a true value, otherwise the \f[CR]else\f[R] section is used (if present). The following values count as true: -.IP \[bu] 2 +.IP \(bu 2 any map -.IP \[bu] 2 +.IP \(bu 2 any array containing at least one true value -.IP \[bu] 2 +.IP \(bu 2 any nonempty string -.IP \[bu] 2 +.IP \(bu 2 boolean True .PP Note that in YAML metadata (and metadata specified on the command line @@ -2304,14 +2373,14 @@ $endif$ A for loop begins with \f[CR]for(variable)\f[R] (enclosed in matched delimiters) and ends with \f[CR]endfor\f[R] (enclosed in matched delimiters). -.IP \[bu] 2 +.IP \(bu 2 If \f[CR]variable\f[R] is an array, the material inside the loop will be evaluated repeatedly, with \f[CR]variable\f[R] being set to each value of the array in turn, and concatenated. -.IP \[bu] 2 +.IP \(bu 2 If \f[CR]variable\f[R] is a map, the material inside will be set to the map. -.IP \[bu] 2 +.IP \(bu 2 If the value of the associated variable is not an array or a map, a single iteration will be performed on its value. .PP @@ -2403,20 +2472,20 @@ A separator between values of an array may be specified in square brackets, immediately after the variable name or partial: .IP .EX -${months[, ]}$ +${months[, ]} -${articles:bibentry()[; ]$ +${articles:bibentry()[; ]} .EE .PP The separator in this case is literal and (unlike with \f[CR]sep\f[R] in an explicit \f[CR]for\f[R] loop) cannot contain interpolated variables or other template directives. .SS Nesting -To ensure that content is \[lq]nested,\[rq] that is, subsequent lines -indented, use the \f[CR]\[ha]\f[R] directive: +To ensure that content is \(lqnested,\(rq that is, subsequent lines +indented, use the \f[CR]\(ha\f[R] directive: .IP .EX -$item.number$ $\[ha]$$item.description$ ($item.price$) +$item.number$ $\(ha$$item.description$ ($item.price$) .EE .PP In this example, if \f[CR]item.description\f[R] has multiple lines, they @@ -2428,11 +2497,11 @@ will all be indented to line up with the first line: .EE .PP To nest multiple lines to the same level, align them with the -\f[CR]\[ha]\f[R] directive in the template. +\f[CR]\(ha\f[R] directive in the template. For example: .IP .EX -$item.number$ $\[ha]$$item.description$ ($item.price$) +$item.number$ $\(ha$$item.description$ ($item.price$) (Available til $item.sellby$.) .EE .PP @@ -2446,17 +2515,17 @@ will produce .PP If a variable occurs by itself on a line, preceded by whitespace and not followed by further text or directives on the same line, and the -variable\[cq]s value contains multiple lines, it will be nested +variable\(cqs value contains multiple lines, it will be nested automatically. .SS Breakable spaces Normally, spaces in the template itself (as opposed to values of the interpolated variables) are not breakable, but they can be made -breakable in part of the template by using the \f[CR]\[ti]\f[R] keyword -(ended with another \f[CR]\[ti]\f[R]). +breakable in part of the template by using the \f[CR]\(ti\f[R] keyword +(ended with another \f[CR]\(ti\f[R]). .IP .EX -$\[ti]$This long line may break if the document is rendered -with a short line length.$\[ti]$ +$\(ti$This long line may break if the document is rendered +with a short line length.$\(ti$ .EE .SS Pipes A pipe transforms the value of a variable or partial. @@ -2489,69 +2558,69 @@ Some pipes take parameters: .EX |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-| $for(employee)$ -$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$ +$it.name.first/uppercase/left 20 \(dq| \(dq$$it.name.salary/right 10 \(dq | \(dq \(dq |\(dq$ $endfor$ |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-| .EE .PP Currently the following pipes are predefined: -.IP \[bu] 2 +.IP \(bu 2 \f[CR]pairs\f[R]: Converts a map or array to an array of maps, each with \f[CR]key\f[R] and \f[CR]value\f[R] fields. If the original value was an array, the \f[CR]key\f[R] will be the array index, starting with 1. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]uppercase\f[R]: Converts text to uppercase. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]lowercase\f[R]: Converts text to lowercase. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]length\f[R]: Returns the length of the value: number of characters for a textual value, number of elements for a map or array. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]reverse\f[R]: Reverses a textual value or array, and has no effect on other values. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]first\f[R]: Returns the first value of an array, if applied to a non\-empty array; otherwise returns the original value. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]last\f[R]: Returns the last value of an array, if applied to a non\-empty array; otherwise returns the original value. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]rest\f[R]: Returns all but the first value of an array, if applied to a non\-empty array; otherwise returns the original value. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]allbutlast\f[R]: Returns all but the last value of an array, if applied to a non\-empty array; otherwise returns the original value. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]chomp\f[R]: Removes trailing newlines (and breakable space). -.IP \[bu] 2 +.IP \(bu 2 \f[CR]nowrap\f[R]: Disables line wrapping on breakable spaces. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]alpha\f[R]: Converts textual values that can be read as an integer into lowercase alphabetic characters \f[CR]a..z\f[R] (mod 26). This can be used to get lettered enumeration from array indices. To get uppercase letters, chain with \f[CR]uppercase\f[R]. -.IP \[bu] 2 +.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. To get uppercase roman, chain with \f[CR]uppercase\f[R]. -.IP \[bu] 2 -\f[CR]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a +.IP \(bu 2 +\f[CR]left n \(dqleftborder\(dq \(dqrightborder\(dq\f[R]: Renders a textual value in a block of width \f[CR]n\f[R], aligned to the left, with an optional left and right border. Has no effect on other values. This can be used to align material in tables. Widths are positive integers indicating the number of characters. -Borders are strings inside double quotes; literal \f[CR]\[dq]\f[R] and -\f[CR]\[rs]\f[R] characters must be backslash\-escaped. -.IP \[bu] 2 -\f[CR]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a +Borders are strings inside double quotes; literal \f[CR]\(dq\f[R] and +\f[CR]\(rs\f[R] characters must be backslash\-escaped. +.IP \(bu 2 +\f[CR]right n \(dqleftborder\(dq \(dqrightborder\(dq\f[R]: Renders a textual value in a block of width \f[CR]n\f[R], aligned to the right, and has no effect on other values. -.IP \[bu] 2 -\f[CR]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders -a textual value in a block of width \f[CR]n\f[R], aligned to the center, +.IP \(bu 2 +\f[CR]center n \(dqleftborder\(dq \(dqrightborder\(dq\f[R]: Renders a +textual value in a block of width \f[CR]n\f[R], aligned to the center, and has no effect on other values. .SS Variables .SS Metadata variables @@ -2614,8 +2683,8 @@ The following YAML metadata block for instance: .IP .EX \-\-\- -title: \[aq]This is the title\[aq] -subtitle: \[dq]This is the subtitle\[dq] +title: \(aqThis is the title\(aq +subtitle: \(dqThis is the subtitle\(dq author: \- Author One \- Author Two @@ -2657,7 +2726,7 @@ Text in the main document language (British English). > Cette citation est écrite en français canadien. ::: -More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de} +More text in English. [\(aqZitat auf Deutsch.\(aq]{lang=de} .EE .RE .TP @@ -2693,7 +2762,7 @@ sets the CSS \f[CR]font\-family\f[R] property on the \f[CR]html\f[R] element. .TP \f[CR]fontsize\f[R] -sets the base CSS \f[CR]font\-size\f[R], which you\[cq]d usually set to +sets the base CSS \f[CR]font\-size\f[R], which you\(cqd usually set to e.g.\ \f[CR]20px\f[R], but it also accepts \f[CR]pt\f[R] (12pt = 16px in most browsers). .TP @@ -2716,7 +2785,7 @@ sets the CSS \f[CR]line\-height\f[R] property on the \f[CR]html\f[R] element, which is preferred to be unitless. .TP \f[CR]maxwidth\f[R] -sets the CSS \f[CR]max\-width\f[R] property (default is 32em). +sets the CSS \f[CR]max\-width\f[R] property (default is 36em). .TP \f[CR]backgroundcolor\f[R] sets the CSS \f[CR]background\-color\f[R] property on the @@ -2761,7 +2830,7 @@ author affiliations: can be a list when there are multiple authors .TP \f[CR]revealjs\-url\f[R] base URL for reveal.js documents (defaults to -\f[CR]https://unpkg.com/reveal.js\[at]\[ha]4/\f[R]) +\f[CR]https://unpkg.com/reveal.js\(at\(ha5\f[R]) .TP \f[CR]s5\-url\f[R] base URL for S5 documents (defaults to \f[CR]s5/default\f[R]) @@ -2790,7 +2859,7 @@ slide aspect ratio (\f[CR]43\f[R] for 4:3 [default], \f[CR]169\f[R] for for 1.41:1, \f[CR]54\f[R] for 5:4, \f[CR]32\f[R] for 3:2) .TP \f[CR]beameroption\f[R] -add extra beamer option with \f[CR]\[rs]setbeameroption{}\f[R] +add extra beamer option with \f[CR]\(rssetbeameroption{}\f[R] .TP \f[CR]institute\f[R] author affiliations: can be a list when there are multiple authors @@ -2804,19 +2873,23 @@ navigation symbols; other valid values are \f[CR]frame\f[R], \f[CR]vertical\f[R], and \f[CR]horizontal\f[R]) .TP \f[CR]section\-titles\f[R] -enables \[lq]title pages\[rq] for new sections (default is true) +enables \(lqtitle pages\(rq for new sections (default is true) .TP \f[CR]theme\f[R], \f[CR]colortheme\f[R], \f[CR]fonttheme\f[R], \f[CR]innertheme\f[R], \f[CR]outertheme\f[R] beamer themes .TP -\f[CR]themeoptions\f[R] -options for LaTeX beamer themes (a list). +\f[CR]themeoptions\f[R], \f[CR]colorthemeoptions\f[R], \f[CR]fontthemeoptions\f[R], \f[CR]innerthemeoptions\f[R], \f[CR]outerthemeoptions\f[R] +options for LaTeX beamer themes (lists) .TP \f[CR]titlegraphic\f[R] -image for title slide +image for title slide: can be a list .TP \f[CR]titlegraphicoptions\f[R] options for title slide image +.TP +\f[CR]shorttitle\f[R], \f[CR]shortsubtitle\f[R], \f[CR]shortauthor\f[R], \f[CR]shortinstitute\f[R], \f[CR]shortdate\f[R] +some beamer themes use short versions of the title, subtitle, author, +institute, date .SS Variables for PowerPoint These variables control the visual aspects of a slide show that are not easily controlled via templates. @@ -2828,10 +2901,10 @@ Pandoc uses these variables when creating a PDF with a LaTeX engine. .SS Layout .TP \f[CR]block\-headings\f[R] -make \f[CR]\[rs]paragraph\f[R] and \f[CR]\[rs]subparagraph\f[R] -(fourth\- and fifth\-level headings, or fifth\- and sixth\-level with -book classes) free\-standing rather than run\-in; requires further -formatting to distinguish from \f[CR]\[rs]subsubsection\f[R] (third\- or +make \f[CR]\(rsparagraph\f[R] and \f[CR]\(rssubparagraph\f[R] (fourth\- +and fifth\-level headings, or fifth\- and sixth\-level with book +classes) free\-standing rather than run\-in; requires further formatting +to distinguish from \f[CR]\(rssubsubsection\f[R] (third\- or fourth\-level headings). Instead of using this option, KOMA\-Script can adjust headings more extensively: @@ -2841,14 +2914,14 @@ extensively: \-\-\- documentclass: scrartcl header\-includes: | - \[rs]RedeclareSectionCommand[ + \(rsRedeclareSectionCommand[ beforeskip=\-10pt plus \-2pt minus \-1pt, afterskip=1sp plus \-1sp minus 1sp, - font=\[rs]normalfont\[rs]itshape]{paragraph} - \[rs]RedeclareSectionCommand[ + font=\(rsnormalfont\(rsitshape]{paragraph} + \(rsRedeclareSectionCommand[ beforeskip=\-10pt plus \-2pt minus \-1pt, afterskip=1sp plus \-1sp minus 1sp, - font=\[rs]normalfont\[rs]scshape, + font=\(rsnormalfont\(rsscshape, indent=0pt]{subparagraph} \&... .EE @@ -2918,7 +2991,7 @@ sets margins if \f[CR]geometry\f[R] is not used (otherwise \f[CR]geometry\f[R] overrides these) .TP \f[CR]pagestyle\f[R] -control \f[CR]\[rs]pagestyle{}\f[R]: the default article class supports +control \f[CR]\(rspagestyle{}\f[R]: the default article class supports \f[CR]plain\f[R] (default), \f[CR]empty\f[R] (no running heads or page numbers), and \f[CR]headings\f[R] (section titles in running heads) .TP @@ -2930,11 +3003,29 @@ numbering depth for sections (with \f[CR]\-\-number\-sections\f[R] option or \f[CR]numbersections\f[R] variable) .TP \f[CR]beamerarticle\f[R] -produce an article from Beamer slides +produce an article from Beamer slides. +Note: if you set this variable, you must specify the beamer writer but +use the default \f[I]LaTeX\f[R] template: for example, +\f[CR]pandoc \-Vbeamerarticle \-t beamer \-\-template default.latex\f[R]. .TP \f[CR]handout\f[R] produce a handout version of Beamer slides (with overlays condensed into single slides) +.TP +\f[CR]csquotes\f[R] +load \f[CR]csquotes\f[R] package and use \f[CR]\(rsenquote\f[R] or +\f[CR]\(rsenquote*\f[R] for quoted text. +.TP +\f[CR]csquotesoptions\f[R] +options to use for \f[CR]csquotes\f[R] package (repeat for multiple +options). +.TP +\f[CR]babeloptions\f[R] +options to pass to the babel package (may be repeated for multiple +options). +This defaults to \f[CR]provide=*\f[R] if the main language isn\(cqt a +European language written with Latin or Cyrillic script or Vietnamese. +Most users will not need to adjust the default setting. .SS Fonts .TP \f[CR]fontenc\f[R] @@ -2998,7 +3089,7 @@ mainfontoptions: .RE .TP \f[CR]mainfontfallback\f[R], \f[CR]sansfontfallback\f[R], \f[CR]monofontfallback\f[R] -fonts to try if a glyph isn\[cq]t found in \f[CR]mainfont\f[R], +fonts to try if a glyph isn\(cqt found in \f[CR]mainfont\f[R], \f[CR]sansfont\f[R], or \f[CR]monofont\f[R] respectively. These are lists. The font name must be followed by a colon and optionally a set of @@ -3008,8 +3099,8 @@ options, for example: .EX \-\-\- mainfontfallback: - \- \[dq]FreeSans:\[dq] - \- \[dq]NotoColorEmoji:mode=harf\[dq] + \- \(dqFreeSans:\(dq + \- \(dqNotoColorEmoji:mode=harf\(dq \&... .EE .PP @@ -3024,8 +3115,8 @@ be used with the language: .EX \-\-\- babelfonts: - chinese\-hant: \[dq]Noto Serif CJK TC\[dq] - russian: \[dq]Noto Serif\[dq] + chinese\-hant: \(dqNoto Serif CJK TC\(dq + russian: \(dqNoto Serif\(dq \&... .EE .RE @@ -3058,7 +3149,9 @@ the default, \f[CR]same\f[R]) .SS Front matter .TP \f[CR]lof\f[R], \f[CR]lot\f[R] -include list of figures, list of tables +include list of figures, list of tables (can also be set using +\f[CR]\-\-lof/\-\-list\-of\-figures\f[R], +\f[CR]\-\-lot/\-\-list\-of\-tables\f[R]) .TP \f[CR]thanks\f[R] contents of acknowledgments footnote after document title @@ -3129,7 +3222,7 @@ Switching) \f[CR]mainfontfallback\f[R], \f[CR]sansfontfallback\f[R], \f[CR]monofontfallback\f[R] list of fonts to try, in order, if a glyph is not found in the main font. -Use \f[CR]\[rs]definefallbackfamily\f[R]\-compatible font name syntax. +Use \f[CR]\(rsdefinefallbackfamily\f[R]\-compatible font name syntax. Emoji fonts are unsupported. .TP \f[CR]margin\-left\f[R], \f[CR]margin\-right\f[R], \f[CR]margin\-top\f[R], \f[CR]margin\-bottom\f[R] @@ -3171,7 +3264,7 @@ They can be obtained from ConTeXt ICC Profiles. \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\[rs]letterpercent\[rs]space (ECI)\f[R] If +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] @@ -3226,6 +3319,9 @@ name of info file to be generated (defaults to a name based on the texi filename) .SS Variables for Typst .TP +\f[CR]template\f[R] +Typst template to use. +.TP \f[CR]margin\f[R] A dictionary with the fields defined in the Typst documentation: \f[CR]x\f[R], \f[CR]y\f[R], \f[CR]top\f[R], \f[CR]bottom\f[R], @@ -3243,6 +3339,10 @@ Font size (e.g., \f[CR]12pt\f[R]). \f[CR]section\-numbering\f[R] Schema to use for numbering sections, e.g.\ \f[CR]1.A.1\f[R]. .TP +\f[CR]page\-numbering\f[R] +Schema to use for numbering pages, e.g.\ \f[CR]1\f[R] or \f[CR]i\f[R], +or an empty string to omit page numbering. +.TP \f[CR]columns\f[R] Number of columns for body text. .SS Variables for ms @@ -3299,7 +3399,7 @@ contents specified by \f[CR]\-A/\-\-include\-after\-body\f[R] (may have multiple values) .TP \f[CR]meta\-json\f[R] -JSON representation of all of the document\[cq]s metadata. +JSON representation of all of the document\(cqs metadata. Field values are transformed to the selected output format. .TP \f[CR]numbersections\f[R] @@ -3328,6 +3428,10 @@ the terminal. If you need absolute paths, use e.g.\ \f[CR]$curdir$/$sourcefile$\f[R]. .RE .TP +\f[CR]pdf\-engine\f[R] +name of PDF engine if provided using \f[CR]\-\-pdf\-engine\f[R], or the +default engine for the format if PDF output is requested. +.TP \f[CR]curdir\f[R] working directory from which pandoc is run. .TP @@ -3351,12 +3455,12 @@ An extension can be enabled by adding \f[CR]+EXTENSION\f[R] to the format name and disabled by adding \f[CR]\-EXTENSION\f[R]. For example, \f[CR]\-\-from markdown_strict+footnotes\f[R] is strict Markdown with footnotes enabled, while -\f[CR]\-\-from markdown\-footnotes\-pipe_tables\f[R] is pandoc\[cq]s +\f[CR]\-\-from markdown\-footnotes\-pipe_tables\f[R] is pandoc\(cqs Markdown without footnotes or pipe tables. .PP The Markdown reader and writer make by far the most use of extensions. Extensions only used by them are therefore covered in the section -Pandoc\[cq]s Markdown below (see Markdown variants for +Pandoc\(cqs Markdown below (see Markdown variants for \f[CR]commonmark\f[R] and \f[CR]gfm\f[R]). In the following, extensions that also work for other formats are covered. @@ -3370,7 +3474,7 @@ Interpret straight quotes as curly quotes, \f[CR]\-\-\-\f[R] as em\-dashes, \f[CR]\-\-\f[R] as en\-dashes, and \f[CR]...\f[R] as ellipses. Nonbreaking spaces are inserted after certain abbreviations, such as -\[lq]Mr.\[rq] +\(lqMr.\(rq .PP This extension can be enabled/disabled for the following formats: .TP @@ -3392,9 +3496,9 @@ extension has the reverse effect: what would have been curly quotes comes out straight. .PP In LaTeX, \f[CR]smart\f[R] means to use the standard TeX ligatures for -quotation marks (\f[CR]\[ga]\[ga]\f[R] and \f[CR]\[aq]\[aq]\f[R] for -double quotes, \f[CR]\[ga]\f[R] and \f[CR]\[aq]\f[R] for single quotes) -and dashes (\f[CR]\-\-\f[R] for en\-dash and \f[CR]\-\-\-\f[R] for +quotation marks (\f[CR]\(ga\(ga\f[R] and \f[CR]\(aq\(aq\f[R] for double +quotes, \f[CR]\(ga\f[R] and \f[CR]\(aq\f[R] for single quotes) and +dashes (\f[CR]\-\-\f[R] for en\-dash and \f[CR]\-\-\-\f[R] for em\-dash). If \f[CR]smart\f[R] is disabled, then in reading LaTeX pandoc will parse these characters literally. @@ -3420,21 +3524,21 @@ enabled by default in .PP The default algorithm used to derive the identifier from the heading text is: -.IP \[bu] 2 +.IP \(bu 2 Remove all formatting, links, etc. -.IP \[bu] 2 +.IP \(bu 2 Remove all footnotes. -.IP \[bu] 2 +.IP \(bu 2 Remove all non\-alphanumeric characters, except underscores, hyphens, and periods. -.IP \[bu] 2 +.IP \(bu 2 Replace all spaces and newlines with hyphens. -.IP \[bu] 2 +.IP \(bu 2 Convert all alphabetic characters to lowercase. -.IP \[bu] 2 +.IP \(bu 2 Remove everything up to the first letter (identifiers may not begin with a number or punctuation mark). -.IP \[bu] 2 +.IP \(bu 2 If nothing is left after this, use the identifier \f[CR]section\f[R]. .PP Thus, for example, @@ -3444,7 +3548,7 @@ Thus, for example, Heading Identifier \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- Heading identifiers in HTML heading\-identifiers\-in\-html - Maître d\[aq]hôtel maître\-dhôtel + Maître d\(aqhôtel maître\-dhôtel *Dogs*?\-\-in *my* house? dogs\-\-in\-my\-house [HTML], [S5], or [RTF]? html\-s5\-or\-rtf 3. Applications applications @@ -3491,7 +3595,7 @@ Accents are stripped off of accented Latin letters, and non\-Latin letters are omitted. .SS Extension: \f[CR]gfm_auto_identifiers\f[R] Changes the algorithm used by \f[CR]auto_identifiers\f[R] to conform to -GitHub\[cq]s method. +GitHub\(cqs method. Spaces are converted to dashes (\f[CR]\-\f[R]), uppercase characters to lowercase characters, and punctuation characters other than \f[CR]\-\f[R] and \f[CR]_\f[R] are removed. @@ -3500,19 +3604,19 @@ Emojis are replaced by their names. The extensions \f[CR]tex_math_dollars\f[R], \f[CR]tex_math_gfm\f[R], \f[CR]tex_math_single_backslash\f[R], and \f[CR]tex_math_double_backslash\f[R] are described in the section about -Pandoc\[cq]s Markdown. +Pandoc\(cqs Markdown. .PP However, they can also be used with HTML input. This is handy for reading web pages formatted using MathJax, for example. .SS Raw HTML/TeX The following extensions are described in more detail in their -respective sections of Pandoc\[cq]s Markdown: -.IP \[bu] 2 +respective sections of Pandoc\(cqs Markdown: +.IP \(bu 2 \f[CR]raw_html\f[R] allows HTML elements which are not representable in -pandoc\[cq]s AST to be parsed as raw HTML. +pandoc\(cqs AST to be parsed as raw HTML. By default, this is disabled for HTML input. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]raw_tex\f[R] allows raw LaTeX, TeX, and ConTeXt to be included in a document. This extension can be enabled/disabled for the following formats (in @@ -3521,7 +3625,7 @@ addition to \f[CR]markdown\f[R]): .TP input formats \f[CR]latex\f[R], \f[CR]textile\f[R], \f[CR]html\f[R] (environments, -\f[CR]\[rs]ref\f[R], and \f[CR]\[rs]eqref\f[R] only), \f[CR]ipynb\f[R] +\f[CR]\(rsref\f[R], and \f[CR]\(rseqref\f[R] only), \f[CR]ipynb\f[R] .TP output formats \f[CR]textile\f[R], \f[CR]commonmark\f[R] @@ -3532,15 +3636,15 @@ with mime type \f[CR]text/html\f[R] in output cells. Since the \f[CR]ipynb\f[R] reader attempts to preserve the richest possible outputs when several options are given, you will get best results if you disable \f[CR]raw_html\f[R] and \f[CR]raw_tex\f[R] when -converting to formats like \f[CR]docx\f[R] which don\[cq]t allow raw +converting to formats like \f[CR]docx\f[R] which don\(cqt allow raw \f[CR]html\f[R] or \f[CR]tex\f[R]. .RE -.IP \[bu] 2 +.IP \(bu 2 \f[CR]native_divs\f[R] causes HTML \f[CR]div\f[R] elements to be parsed as native pandoc Div blocks. If you want them to be parsed as raw HTML, use \f[CR]\-f html\-native_divs+raw_html\f[R]. -.IP \[bu] 2 +.IP \(bu 2 \f[CR]native_spans\f[R] causes HTML \f[CR]span\f[R] elements to be parsed as native pandoc Span inlines. If you want them to be parsed as raw HTML, use @@ -3564,13 +3668,13 @@ If you append \f[CR]+lhs\f[R] (or \f[CR]+literate_haskell\f[R]) to one of the formats above, pandoc will treat the document as literate Haskell source. This means that -.IP \[bu] 2 -In Markdown input, \[lq]bird track\[rq] sections will be parsed as -Haskell code rather than block quotations. -Text between \f[CR]\[rs]begin{code}\f[R] and \f[CR]\[rs]end{code}\f[R] +.IP \(bu 2 +In Markdown input, \(lqbird track\(rq sections will be parsed as Haskell +code rather than block quotations. +Text between \f[CR]\(rsbegin{code}\f[R] and \f[CR]\(rsend{code}\f[R] will also be treated as Haskell code. For ATX\-style headings the character `=' will be used instead of `#'. -.IP \[bu] 2 +.IP \(bu 2 In Markdown output, code blocks with classes \f[CR]haskell\f[R] and \f[CR]literate\f[R] will be rendered using bird tracks, and block quotations will be indented one space, so they will not be treated as @@ -3579,19 +3683,19 @@ In addition, headings will be rendered setext\-style (with underlines) rather than ATX\-style (with `#' characters). (This is because ghc treats `#' characters in column 1 as introducing line numbers.) -.IP \[bu] 2 -In restructured text input, \[lq]bird track\[rq] sections will be parsed +.IP \(bu 2 +In restructured text input, \(lqbird track\(rq sections will be parsed as Haskell code. -.IP \[bu] 2 +.IP \(bu 2 In restructured text output, code blocks with class \f[CR]haskell\f[R] will be rendered using bird tracks. -.IP \[bu] 2 +.IP \(bu 2 In LaTeX input, text in \f[CR]code\f[R] environments will be parsed as Haskell code. -.IP \[bu] 2 +.IP \(bu 2 In LaTeX output, code blocks with class \f[CR]haskell\f[R] will be rendered inside \f[CR]code\f[R] environments. -.IP \[bu] 2 +.IP \(bu 2 In HTML output, code blocks with class \f[CR]haskell\f[R] will be rendered with class \f[CR]literatehaskell\f[R] and bird tracks. .PP @@ -3671,11 +3775,14 @@ This extension can be enabled/disabled for the following formats: output formats \f[CR]odt\f[R], \f[CR]opendocument\f[R] .SS Extension: \f[CR]styles\f[R] -When converting from docx, read all docx styles as divs (for paragraph -styles) and spans (for character styles) regardless of whether pandoc -understands the meaning of these styles. -This can be used with docx custom styles. -Disabled by default. +When converting from docx, add \f[CR]custom\-styles\f[R] attributes for +all docx styles, regardless of whether pandoc understands the meanings +of these styles. +Because attributes cannot be added directly to paragraphs or text in the +pandoc AST, paragraph styles will cause Divs to be created and character +styles will cause Spans to be created to hold the attributes. +(Table styles will be added to the Table elements directly.) +This extension can be used with docx custom styles. .TP input formats \f[CR]docx\f[R] @@ -3705,7 +3812,7 @@ native pandoc citations. (Otherwise, the formatted citations generated by the bibliographic software will be parsed as regular text.) .SS Extension: \f[CR]fancy_lists\f[R] (org) -Some aspects of Pandoc\[cq]s Markdown fancy lists are also accepted in +Some aspects of Pandoc\(cqs Markdown fancy lists are also accepted in \f[CR]org\f[R] input, mimicking the option \f[CR]org\-list\-allow\-alphabetical\f[R] in Emacs. As in Org Mode, enabling this extension allows lowercase and uppercase @@ -3713,7 +3820,7 @@ alphabetical markers for ordered lists to be parsed in addition to arabic ones. Note that for Org, this does not include roman numerals or the \f[CR]#\f[R] placeholder that are enabled by the extension in -Pandoc\[cq]s Markdown. +Pandoc\(cqs Markdown. .SS Extension: \f[CR]element_citations\f[R] In the \f[CR]jats\f[R] output formats, this causes reference items to be replaced with \f[CR]\f[R] elements. @@ -3731,9 +3838,9 @@ This includes additional markers for paragraphs and alternative markup for emphasized text. The \f[CR]emphasis\-command\f[R] template variable is set if the extension is enabled. -.SH PANDOC\[cq]S MARKDOWN +.SH PANDOC\(cqS MARKDOWN Pandoc understands an extended and slightly revised version of John -Gruber\[cq]s Markdown syntax. +Gruber\(cqs Markdown syntax. This document explains the syntax, noting differences from original Markdown. Except where noted, these differences can be suppressed by using the @@ -3749,18 +3856,18 @@ easy to read: .RS .PP A Markdown\-formatted document should be publishable as\-is, as plain -text, without looking like it\[cq]s been marked up with tags or +text, without looking like it\(cqs been marked up with tags or formatting instructions. .PD 0 .P .PD -\[en] John Gruber +\(en John Gruber .RE .PP -This principle has guided pandoc\[cq]s decisions in finding syntax for +This principle has guided pandoc\(cqs decisions in finding syntax for tables, footnotes, and other extensions. .PP -There is, however, one respect in which pandoc\[cq]s aims are different +There is, however, one respect in which pandoc\(cqs aims are different from the original aims of Markdown. Whereas Markdown was originally designed with HTML generation in mind, pandoc is designed for multiple output formats. @@ -3781,9 +3888,9 @@ a hard line break, since trailing spaces in the cells are ignored. .SS Headings There are two kinds of headings: Setext and ATX. .SS Setext\-style headings -A setext\-style heading is a line of text \[lq]underlined\[rq] with a -row of \f[CR]=\f[R] signs (for a level\-one heading) or \f[CR]\-\f[R] -signs (for a level\-two heading): +A setext\-style heading is a line of text \(lqunderlined\(rq with a row +of \f[CR]=\f[R] signs (for a level\-one heading) or \f[CR]\-\f[R] signs +(for a level\-two heading): .IP .EX A level\-one heading @@ -3855,7 +3962,7 @@ My other heading {#foo} (This syntax is compatible with PHP Markdown Extra.) .PP Note that although this syntax allows assignment of classes and -key/value attributes, writers generally don\[cq]t use all of this +key/value attributes, writers generally don\(cqt use all of this information. Identifiers, classes, and key/value attributes are used in HTML and HTML\-based formats such as EPUB and slidy. @@ -3950,7 +4057,7 @@ be indented more than three spaces.) > 2. Second item. .EE .PP -A \[lq]lazy\[rq] form, which requires the \f[CR]>\f[R] character only on +A \(lqlazy\(rq form, which requires the \f[CR]>\f[R] character only on the first line of each block, is also allowed: .IP .EX @@ -3993,7 +4100,7 @@ does not produce a nested block quote in pandoc: .IP .EX > This is a block quote. ->> Not nested, since \[ga]blank_before_blockquote\[ga] is enabled by default +>> Not nested, since \(gablank_before_blockquote\(ga is enabled by default .EE .SS Verbatim (code) blocks .SS Indented code blocks @@ -4016,18 +4123,17 @@ Note: blank lines in the verbatim text need not begin with four spaces. .SS Extension: \f[CR]fenced_code_blocks\f[R] In addition to standard indented code blocks, pandoc supports \f[I]fenced\f[R] code blocks. -These begin with a row of three or more tildes (\f[CR]\[ti]\f[R]) and -end with a row of tildes that must be at least as long as the starting -row. +These begin with a row of three or more tildes (\f[CR]\(ti\f[R]) and end +with a row of tildes that must be at least as long as the starting row. Everything between these lines is treated as code. No indentation is necessary: .IP .EX -\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +\(ti\(ti\(ti\(ti\(ti\(ti\(ti if (a > 3) { moveShip(5 * gravity, DOWN); } -\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +\(ti\(ti\(ti\(ti\(ti\(ti\(ti .EE .PP Like regular code blocks, fenced code blocks must be separated from @@ -4037,25 +4143,25 @@ If the code itself contains a row of tildes or backticks, just use a longer row of tildes or backticks at the start and end: .IP .EX -\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] -\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti +\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti code including tildes -\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] -\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti +\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti .EE .SS Extension: \f[CR]backtick_code_blocks\f[R] 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]). +(\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 using this syntax: .IP .EX -\[ti]\[ti]\[ti]\[ti] {#mycode .haskell .numberLines startFrom=\[dq]100\[dq]} +\(ti\(ti\(ti\(ti {#mycode .haskell .numberLines startFrom=\(dq100\(dq} qsort [] = [] qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++ qsort (filter (>= x) xs) -\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti .EE .PP Here \f[CR]mycode\f[R] is an identifier, \f[CR]haskell\f[R] and @@ -4071,7 +4177,7 @@ the code block above will appear highlighted, with numbered lines. Otherwise, the code block above will appear as follows: .IP .EX -
+
   
   ...
   
@@ -4088,33 +4194,33 @@ A shortcut form can also be used for specifying the language of the code
 block:
 .IP
 .EX
-\[ga]\[ga]\[ga]haskell
+\(ga\(ga\(gahaskell
 qsort [] = []
-\[ga]\[ga]\[ga]
+\(ga\(ga\(ga
 .EE
 .PP
 This is equivalent to:
 .IP
 .EX
-\[ga]\[ga]\[ga] {.haskell}
+\(ga\(ga\(ga {.haskell}
 qsort [] = []
-\[ga]\[ga]\[ga]
+\(ga\(ga\(ga
 .EE
 .PP
 This shortcut form may be combined with attributes:
 .IP
 .EX
-\[ga]\[ga]\[ga]haskell {.numberLines}
+\(ga\(ga\(gahaskell {.numberLines}
 qsort [] = []
-\[ga]\[ga]\[ga]
+\(ga\(ga\(ga
 .EE
 .PP
 Which is equivalent to:
 .IP
 .EX
-\[ga]\[ga]\[ga] {.haskell .numberLines}
+\(ga\(ga\(ga {.haskell .numberLines}
 qsort [] = []
-\[ga]\[ga]\[ga]
+\(ga\(ga\(ga
 .EE
 .PP
 If the \f[CR]fenced_code_attributes\f[R] extension is disabled, but
@@ -4135,7 +4241,7 @@ This is useful for verse and addresses:
 .EX
 | The limerick packs laughs anatomical
 | In space that is quite economical.
-|    But the good ones I\[aq]ve seen
+|    But the good ones I\(aqve seen
 |    So seldom are clean
 | And the clean ones so seldom are comical
 
@@ -4154,7 +4260,7 @@ begin with a space.
 .EE
 .PP
 Inline formatting (such as emphasis) is allowed in the content (though
-it can\[cq]t cross line boundaries).
+it can\(cqt cross line boundaries).
 Block\-level formatting (such as block quotes or lists) is not
 recognized.
 .PP
@@ -4172,8 +4278,8 @@ Here is a simple example:
 * three
 .EE
 .PP
-This will produce a \[lq]compact\[rq] list.
-If you want a \[lq]loose\[rq] list, in which each item is formatted as a
+This will produce a \(lqcompact\(rq list.
+If you want a \(lqloose\(rq list, in which each item is formatted as a
 paragraph, put spaces between the items:
 .IP
 .EX
@@ -4197,7 +4303,7 @@ List items look best if subsequent lines are flush with the first line
 * and my second.
 .EE
 .PP
-But Markdown also allows a \[lq]lazy\[rq] format:
+But Markdown also allows a \(lqlazy\(rq format:
 .IP
 .EX
 * here is my first
@@ -4250,8 +4356,8 @@ character after the list marker of the containing list item.
   + chard
 .EE
 .PP
-As noted above, Markdown allows you to write list items
-\[lq]lazily,\[rq] instead of indenting continuation lines.
+As noted above, Markdown allows you to write list items \(lqlazily,\(rq
+instead of indenting continuation lines.
 However, if there are multiple paragraphs or other blocks in a list
 item, the first line of each must be indented.
 .IP
@@ -4305,7 +4411,7 @@ used as an ordered list marker in place of a numeral:
 #. two
 .EE
 .PP
-Note: the `\f[CR]#\f[R]' ordered list marker doesn\[cq]t work with
+Note: the `\f[CR]#\f[R]' ordered list marker doesn\(cqt work with
 \f[CR]commonmark\f[R].
 .SS Extension: \f[CR]startnum\f[R]
 Pandoc also pays attention to the type of list marker used, and to the
@@ -4379,7 +4485,7 @@ one or more block elements (paragraph, code block, list, etc.), each
 indented four spaces or one tab stop.
 The body of the definition (not including the first line) should be
 indented four spaces.
-However, as with other Markdown lists, you can \[lq]lazily\[rq] omit
+However, as with other Markdown lists, you can \(lqlazily\(rq omit
 indentation except at the beginning of a paragraph or other block
 element:
 .IP
@@ -4401,43 +4507,43 @@ definition:
 .IP
 .EX
 Term 1
-  \[ti] Definition 1
+  \(ti Definition 1
 
 Term 2
-  \[ti] Definition 2a
-  \[ti] Definition 2b
+  \(ti Definition 2a
+  \(ti Definition 2b
 .EE
 .PP
 Note that space between items in a definition list is required.
-(A variant that loosens this requirement, but disallows \[lq]lazy\[rq]
+(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
+The special list marker \f[CR]\(at\f[R] can be used for sequentially
 numbered examples.
-The first list item with a \f[CR]\[at]\f[R] marker will be numbered `1',
+The first list item with a \f[CR]\(at\f[R] marker will be numbered `1',
 the next `2', and so on, throughout the document.
 The numbered examples need not occur in a single list; each new list
-using \f[CR]\[at]\f[R] will take up where the last stopped.
+using \f[CR]\(at\f[R] will take up where the last stopped.
 So, for example:
 .IP
 .EX
-(\[at])  My first example will be numbered (1).
-(\[at])  My second example will be numbered (2).
+(\(at)  My first example will be numbered (1).
+(\(at)  My second example will be numbered (2).
 
 Explanation of examples.
 
-(\[at])  My third example will be numbered (3).
+(\(at)  My third example will be numbered (3).
 .EE
 .PP
 Numbered examples can be labeled and referred to elsewhere in the
 document:
 .IP
 .EX
-(\[at]good)  This is a good example.
+(\(atgood)  This is a good example.
 
-As (\[at]good) illustrates, ...
+As (\(atgood) illustrates, ...
 .EE
 .PP
 The label can be any string of alphanumeric characters, underscores, or
@@ -4453,13 +4559,13 @@ the first non\-space character after the label would be awkward.
 You can repeat an earlier numbered example by re\-using its label:
 .IP
 .EX
-(\[at]foo) Sample sentence.
+(\(atfoo) Sample sentence.
 
 Intervening text...
 
 This theory can explain the case we saw earlier (repeated):
 
-(\[at]foo) Sample sentence.
+(\(atfoo) Sample sentence.
 .EE
 .PP
 This only works reliably, though, if the repeated item is in a list by
@@ -4480,8 +4586,8 @@ Here pandoc (like other Markdown implementations) will treat
 \f[CR]{ my code block }\f[R] as the second paragraph of item two, and
 not as a code block.
 .PP
-To \[lq]cut off\[rq] the list after item two, you can insert some
-non\-indented content, like an HTML comment, which won\[cq]t produce
+To \(lqcut off\(rq the list after item two, you can insert some
+non\-indented content, like an HTML comment, which won\(cqt produce
 visible output in any format:
 .IP
 .EX
@@ -4550,16 +4656,16 @@ Table:  Demonstration of simple table syntax.
 The header and table rows must each fit on one line.
 Column alignments are determined by the position of the header text
 relative to the dashed line below it:
-.IP \[bu] 2
+.IP \(bu 2
 If the dashed line is flush with the header text on the right side but
 extends beyond it on the left, the column is right\-aligned.
-.IP \[bu] 2
+.IP \(bu 2
 If the dashed line is flush with the header text on the left side but
 extends beyond it on the right, the column is left\-aligned.
-.IP \[bu] 2
+.IP \(bu 2
 If the dashed line extends beyond the header text on both sides, the
 column is centered.
-.IP \[bu] 2
+.IP \(bu 2
 If the dashed line is flush with the header text on both sides, the
 default alignment is used (in most cases, this will be left).
 .PP
@@ -4596,22 +4702,22 @@ Here is an example:
    First    row                12.0 Example of a row that
                                     spans multiple lines.
 
-  Second    row                 5.0 Here\[aq]s another one. Note
+  Second    row                 5.0 Here\(aqs another one. Note
                                     the blank line between
                                     rows.
 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 
-Table: Here\[aq]s the caption. It, too, may span
+Table: Here\(aqs the caption. It, too, may span
 multiple lines.
 .EE
 .PP
 These work like simple tables, but with the following differences:
-.IP \[bu] 2
+.IP \(bu 2
 They must begin with a row of dashes, before the header text (unless the
 header row is omitted).
-.IP \[bu] 2
+.IP \(bu 2
 They must end with a row of dashes, then a blank line.
-.IP \[bu] 2
+.IP \(bu 2
 The rows must be separated by blank lines.
 .PP
 In multiline tables, the table parser pays attention to the widths of
@@ -4627,12 +4733,12 @@ The header may be omitted in multiline tables as well as simple tables:
    First    row                12.0 Example of a row that
                                     spans multiple lines.
 
-  Second    row                 5.0 Here\[aq]s another one. Note
+  Second    row                 5.0 Here\(aqs another one. Note
                                     the blank line between
                                     rows.
 \-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 
-: Here\[aq]s a multiline table without a header.
+: Here\(aqs a multiline table without a header.
 .EE
 .PP
 It is possible for a multiline table to have just one row, but the row
@@ -4725,7 +4831,7 @@ use \f[CR]=\f[R] instead of \f[CR]\-\f[R]:
 .PP
 The foot must always be placed at the very bottom of the table.
 .PP
-Grid tables can be created easily using Emacs\[cq] table\-mode
+Grid tables can be created easily using Emacs\(cq table\-mode
 (\f[CR]M\-x table\-insert\f[R]).
 .SS Extension: \f[CR]pipe_tables\f[R]
 Pipe tables look like this:
@@ -4773,7 +4879,7 @@ contents will not be wrapped, and the cells will be sized to their
 contents.
 .PP
 Note: pandoc also recognizes pipe tables of the following form, as can
-be produced by Emacs\[cq] orgtbl\-mode:
+be produced by Emacs\(cq orgtbl\-mode:
 .IP
 .EX
 | One | Two   |
@@ -4784,7 +4890,7 @@ be produced by Emacs\[cq] orgtbl\-mode:
 .PP
 The difference is that \f[CR]+\f[R] is used instead of \f[CR]|\f[R].
 Other orgtbl features are not supported.
-In particular, to get non\-default column alignment, you\[cq]ll need to
+In particular, to get non\-default column alignment, you\(cqll need to
 add colons as above.
 .SS Metadata blocks
 .SS Extension: \f[CR]pandoc_title_block\f[R]
@@ -4799,7 +4905,7 @@ If the file begins with a title block
 it will be parsed as bibliographic information, not regular text.
 (It will be used, for example, in the title of standalone LaTeX or HTML
 output.)
-The block may contain just a title, a title and an author, or all three
+The block may contain just a title, a date and an author, or all three
 elements.
 If you want to include an author but no title, or a title and a date but
 no author, you need a blank line:
@@ -4849,12 +4955,12 @@ All three metadata fields may contain standard inline formatting
 Title blocks will always be parsed, but they will affect the output only
 when the \f[CR]\-\-standalone\f[R] (\f[CR]\-s\f[R]) option is chosen.
 In HTML output, titles will appear twice: once in the document
-head\[em]this is the title that will appear at the top of the window in
-a browser\[em]and once at the beginning of the document body.
+head\(emthis is the title that will appear at the top of the window in a
+browser\(emand once at the beginning of the document body.
 The title in the document head can have an optional prefix attached
 (\f[CR]\-\-title\-prefix\f[R] or \f[CR]\-T\f[R] option).
-The title in the body appears as an H1 element with class
-\[lq]title\[rq], so it can be suppressed or reformatted with CSS.
+The title in the body appears as an H1 element with class \(lqtitle\(rq,
+so it can be suppressed or reformatted with CSS.
 If a title prefix is specified with \f[CR]\-T\f[R] and no title block
 appears in the document, the title prefix will be used by itself as the
 HTML title.
@@ -4879,13 +4985,13 @@ will yield a man page with the title \f[CR]PANDOC\f[R] and section 1.
 % PANDOC(1) Pandoc User Manuals
 .EE
 .PP
-will also have \[lq]Pandoc User Manuals\[rq] in the footer.
+will also have \(lqPandoc User Manuals\(rq in the footer.
 .IP
 .EX
 % PANDOC(1) Pandoc User Manuals | Version 4.0
 .EE
 .PP
-will also have \[lq]Version 4.0\[rq] in the header.
+will also have \(lqVersion 4.0\(rq in the header.
 .SS Extension: \f[CR]yaml_metadata_block\f[R]
 A YAML metadata block is a valid YAML object, delimited by a line of
 three hyphens (\f[CR]\-\-\-\f[R]) at the top and a line of three hyphens
@@ -4945,7 +5051,7 @@ block\-level formatting:
 .IP
 .EX
 \-\-\-
-title:  \[aq]This is the title: it contains a colon\[aq]
+title:  \(aqThis is the title: it contains a colon\(aq
 author:
 \- Author One
 \- Author Two
@@ -5006,7 +5112,7 @@ $endif$
 $endfor$
 .EE
 .PP
-Raw content to include in the document\[cq]s header may be specified
+Raw content to include in the document\(cqs header may be specified
 using \f[CR]header\-includes\f[R]; however, it is important to mark up
 this content as raw code for a particular output format, using the
 \f[CR]raw_attribute\f[R] extension, or it will be interpreted as
@@ -5016,25 +5122,25 @@ For example:
 .EX
 header\-includes:
 \- |
-  \[ga]\[ga]\[ga]{=latex}
-  \[rs]let\[rs]oldsection\[rs]section
-  \[rs]renewcommand{\[rs]section}[1]{\[rs]clearpage\[rs]oldsection{#1}}
-  \[ga]\[ga]\[ga]
+  \(ga\(ga\(ga{=latex}
+  \(rslet\(rsoldsection\(rssection
+  \(rsrenewcommand{\(rssection}[1]{\(rsclearpage\(rsoldsection{#1}}
+  \(ga\(ga\(ga
 .EE
 .PP
 Note: the \f[CR]yaml_metadata_block\f[R] extension works with
 \f[CR]commonmark\f[R] as well as \f[CR]markdown\f[R] (and it is enabled
 by default in \f[CR]gfm\f[R] and \f[CR]commonmark_x\f[R]).
 However, in these formats the following restrictions apply:
-.IP \[bu] 2
+.IP \(bu 2
 The YAML metadata block must occur at the beginning of the document (and
 there can be only one).
 If multiple files are given as arguments to pandoc, only the first can
 be a YAML metadata block.
-.IP \[bu] 2
+.IP \(bu 2
 The leaf nodes of the YAML structure are parsed in isolation from each
 other and from the rest of the document.
-So, for example, you can\[cq]t use a reference link in these contexts if
+So, for example, you can\(cqt use a reference link in these contexts if
 the link definition is somewhere else in the document.
 .SS Backslash escapes
 .SS Extension: \f[CR]all_symbols_escapable\f[R]
@@ -5044,7 +5150,7 @@ would normally indicate formatting.
 Thus, for example, if one writes
 .IP
 .EX
-*\[rs]*hello\[rs]**
+*\(rs*hello\(rs**
 .EE
 .PP
 one will get
@@ -5059,29 +5165,28 @@ instead of
 hello
 .EE
 .PP
-This rule is easier to remember than original Markdown\[cq]s rule, which
+This rule is easier to remember than original Markdown\(cqs rule, which
 allows only the following characters to be backslash\-escaped:
 .IP
 .EX
-\[rs]\[ga]*_{}[]()>#+\-.!
+\(rs\(ga*_{}[]()>#+\-.!
 .EE
 .PP
 (However, if the \f[CR]markdown_strict\f[R] format is used, the original
 Markdown rule will be used.)
 .PP
 A backslash\-escaped space is parsed as a nonbreaking space.
-In TeX output, it will appear as \f[CR]\[ti]\f[R].
+In TeX output, it will appear as \f[CR]\(ti\f[R].
 In HTML and XML output, it will appear as a literal unicode nonbreaking
-space character (note that it will thus actually look
-\[lq]invisible\[rq] in the generated HTML source; you can still use the
-\f[CR]\-\-ascii\f[R] command\-line option to make it appear as an
-explicit entity).
+space character (note that it will thus actually look \(lqinvisible\(rq
+in the generated HTML source; you can still use the \f[CR]\-\-ascii\f[R]
+command\-line option to make it appear as an explicit entity).
 .PP
 A backslash\-escaped newline (i.e.\ a backslash occurring at the end of
 a line) is parsed as a hard line break.
-It will appear in TeX output as \f[CR]\[rs]\[rs]\f[R] and in HTML as
+It will appear in TeX output as \f[CR]\(rs\(rs\f[R] and in HTML as
 \f[CR]
\f[R].
-This is a nice alternative to Markdown\[cq]s \[lq]invisible\[rq] way of
+This is a nice alternative to Markdown\(cqs \(lqinvisible\(rq way of
 indicating hard line breaks using two trailing spaces on a line.
 .PP
 Backslash escapes do not work in verbatim contexts.
@@ -5105,7 +5210,7 @@ A \f[CR]*\f[R] or \f[CR]_\f[R] character surrounded by spaces, or
 backslash\-escaped, will not trigger emphasis:
 .IP
 .EX
-This is * not emphasized *, and \[rs]*neither is this\[rs]*.
+This is * not emphasized *, and \(rs*neither is this\(rs*.
 .EE
 .SS Extension: \f[CR]intraword_underscores\f[R]
 Because \f[CR]_\f[R] is sometimes used inside words and identifiers,
@@ -5119,43 +5224,43 @@ feas*ible*, not feas*able*.
 .SS Strikeout
 .SS Extension: \f[CR]strikeout\f[R]
 To strike out a section of text with a horizontal line, begin and end it
-with \f[CR]\[ti]\[ti]\f[R].
+with \f[CR]\(ti\(ti\f[R].
 Thus, for example,
 .IP
 .EX
-This \[ti]\[ti]is deleted text.\[ti]\[ti]
+This \(ti\(tiis deleted text.\(ti\(ti
 .EE
 .SS Superscripts and subscripts
 .SS Extension: \f[CR]superscript\f[R], \f[CR]subscript\f[R]
 Superscripts may be written by surrounding the superscripted text by
-\f[CR]\[ha]\f[R] characters; subscripts may be written by surrounding
-the subscripted text by \f[CR]\[ti]\f[R] characters.
+\f[CR]\(ha\f[R] characters; subscripts may be written by surrounding the
+subscripted text by \f[CR]\(ti\f[R] characters.
 Thus, for example,
 .IP
 .EX
-H\[ti]2\[ti]O is a liquid.  2\[ha]10\[ha] is 1024.
+H\(ti2\(tiO is a liquid.  2\(ha10\(ha is 1024.
 .EE
 .PP
-The text between \f[CR]\[ha]...\[ha]\f[R] or \f[CR]\[ti]...\[ti]\f[R]
-may not contain spaces or newlines.
+The text between \f[CR]\(ha...\(ha\f[R] or \f[CR]\(ti...\(ti\f[R] may
+not contain spaces or newlines.
 If the superscripted or subscripted text contains spaces, these spaces
 must be escaped with backslashes.
 (This is to prevent accidental superscripting and subscripting through
-the ordinary use of \f[CR]\[ti]\f[R] and \f[CR]\[ha]\f[R], and also bad
+the ordinary use of \f[CR]\(ti\f[R] and \f[CR]\(ha\f[R], and also bad
 interactions with footnotes.)
 Thus, if you want the letter P with `a cat' in subscripts, use
-\f[CR]P\[ti]a\[rs] cat\[ti]\f[R], not \f[CR]P\[ti]a cat\[ti]\f[R].
+\f[CR]P\(tia\(rs cat\(ti\f[R], not \f[CR]P\(tia cat\(ti\f[R].
 .SS Verbatim
 To make a short span of text verbatim, put it inside backticks:
 .IP
 .EX
-What is the difference between \[ga]>>=\[ga] and \[ga]>>\[ga]?
+What is the difference between \(ga>>=\(ga and \(ga>>\(ga?
 .EE
 .PP
 If the verbatim text includes a backtick, use double backticks:
 .IP
 .EX
-Here is a literal backtick \[ga]\[ga] \[ga] \[ga]\[ga].
+Here is a literal backtick \(ga\(ga \(ga \(ga\(ga.
 .EE
 .PP
 (The spaces after the opening backticks and before the closing backticks
@@ -5169,14 +5274,14 @@ Note that backslash\-escapes (and other Markdown constructs) do not work
 in verbatim contexts:
 .IP
 .EX
-This is a backslash followed by an asterisk: \[ga]\[rs]*\[ga].
+This is a backslash followed by an asterisk: \(ga\(rs*\(ga.
 .EE
 .SS Extension: \f[CR]inline_code_attributes\f[R]
 Attributes can be attached to verbatim text, just as with fenced code
 blocks:
 .IP
 .EX
-\[ga]<$>\[ga]{.haskell}
+\(ga<$>\(ga{.haskell}
 .EE
 .SS Underline
 To underline text, use the \f[CR]underline\f[R] class:
@@ -5189,7 +5294,7 @@ Or, without the \f[CR]bracketed_spans\f[R] extension (but with
 \f[CR]native_spans\f[R]):
 .IP
 .EX
-Underline
+Underline
 .EE
 .PP
 This will work in all output formats that support underline.
@@ -5203,13 +5308,13 @@ To write small caps, use the \f[CR]smallcaps\f[R] class:
 Or, without the \f[CR]bracketed_spans\f[R] extension:
 .IP
 .EX
-Small caps
+Small caps
 .EE
 .PP
 For compatibility with other Markdown flavors, CSS is also supported:
 .IP
 .EX
-Small caps
+Small caps
 .EE
 .PP
 This will work in all output formats that support small caps.
@@ -5224,7 +5329,7 @@ Or, without the \f[CR]bracketed_spans\f[R] extension (but with
 \f[CR]native_spans\f[R]):
 .IP
 .EX
-Mark
+Mark
 .EE
 .PP
 This will work in all output formats that support highlighting.
@@ -5236,9 +5341,9 @@ The opening \f[CR]$\f[R] must have a non\-space character immediately to
 its right, while the closing \f[CR]$\f[R] must have a non\-space
 character immediately to its left, and must not be followed immediately
 by a digit.
-Thus, \f[CR]$20,000 and $30,000\f[R] won\[cq]t parse as math.
+Thus, \f[CR]$20,000 and $30,000\f[R] won\(cqt parse as math.
 If for some reason you need to enclose text in literal \f[CR]$\f[R]
-characters, backslash\-escape them and they won\[cq]t be treated as math
+characters, backslash\-escape them and they won\(cqt be treated as math
 delimiters.
 .PP
 For display math, use \f[CR]$$\f[R] delimiters.
@@ -5251,8 +5356,8 @@ TeX math will be printed in all output formats.
 How it is rendered depends on the output format:
 .TP
 LaTeX
-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).
+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
 It will appear verbatim surrounded by \f[CR]$...$\f[R] (for inline math)
@@ -5272,16 +5377,16 @@ For \f[CR]asciidoc_legacy\f[R] the bracketed material will also include
 inline or display math delimiters.
 .TP
 Texinfo
-It will be rendered inside a \f[CR]\[at]math\f[R] command.
+It will be rendered inside a \f[CR]\(atmath\f[R] command.
 .TP
 roff man, Jira markup
-It will be rendered verbatim without \f[CR]$\f[R]\[cq]s.
+It will be rendered verbatim without \f[CR]$\f[R]\(cqs.
 .TP
 MediaWiki, DokuWiki
 It will be rendered inside \f[CR]\f[R] tags.
 .TP
 Textile
-It will be rendered inside \f[CR]\f[R] tags.
+It will be rendered inside \f[CR]\f[R] tags.
 .TP
 RTF, OpenDocument
 It will be rendered, if possible, using Unicode characters, and will
@@ -5332,7 +5437,7 @@ 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.
 .SS Extension: \f[CR]markdown_in_html_blocks\f[R]
-Original Markdown allows you to include HTML \[lq]blocks\[rq]: blocks of
+Original Markdown allows you to include HTML \(lqblocks\(rq: blocks of
 HTML between balanced tags that are separated from the surrounding text
 with blank lines, and start and end at the left margin.
 Within these blocks, everything is interpreted as HTML, not Markdown; so
@@ -5358,7 +5463,7 @@ into
 
-
+

 

 onea linka link
 

 

 .EE
@@ -5394,18 +5499,18 @@ and ConTeXt writers.
 Thus, for example, you can use LaTeX to include BibTeX citations:
 .IP
 .EX
-This result was proved in \[rs]cite{jones.1967}.
+This result was proved in \(rscite{jones.1967}.
 .EE
 .PP
 Note that in LaTeX environments, like
 .IP
 .EX
-\[rs]begin{tabular}{|l|l|}\[rs]hline
-Age & Frequency \[rs]\[rs] \[rs]hline
-18\-\-25  & 15 \[rs]\[rs]
-26\-\-35  & 33 \[rs]\[rs]
-36\-\-45  & 22 \[rs]\[rs] \[rs]hline
-\[rs]end{tabular}
+\(rsbegin{tabular}{|l|l|}\(rshline
+Age & Frequency \(rs\(rs \(rshline
+18\-\-25  & 15 \(rs\(rs
+26\-\-35  & 33 \(rs\(rs
+36\-\-45  & 22 \(rs\(rs \(rshline
+\(rsend{tabular}
 .EE
 .PP
 the material between the begin and end tags will be interpreted as raw
@@ -5423,16 +5528,16 @@ will be parsed as raw content with the designated format.
 For example, the following produces a raw roff \f[CR]ms\f[R] block:
 .IP
 .EX
-\[ga]\[ga]\[ga]{=ms}
+\(ga\(ga\(ga{=ms}
 \&.MYMACRO
 blah blah
-\[ga]\[ga]\[ga]
+\(ga\(ga\(ga
 .EE
 .PP
 And the following produces a raw \f[CR]html\f[R] inline element:
 .IP
 .EX
-This is \[ga]html\[ga]{=html}
+This is \(gahtml\(ga{=html}
 .EE
 .PP
 This can be useful to insert raw xml into \f[CR]docx\f[R] documents,
@@ -5440,13 +5545,13 @@ e.g.
 a pagebreak:
 .IP
 .EX
-\[ga]\[ga]\[ga]{=openxml}
+\(ga\(ga\(ga{=openxml}
 
   
-    
+    
   
 
-\[ga]\[ga]\[ga]
+\(ga\(ga\(ga
 .EE
 .PP
 The format name should match the target format name (see
@@ -5474,9 +5579,9 @@ So, for example, the following will work in all output formats, not just
 LaTeX:
 .IP
 .EX
-\[rs]newcommand{\[rs]tuple}[1]{\[rs]langle #1 \[rs]rangle}
+\(rsnewcommand{\(rstuple}[1]{\(rslangle #1 \(rsrangle}
 
-$\[rs]tuple{a, b, c}$
+$\(rstuple{a, b, c}$
 .EE
 .PP
 Note that LaTeX macros will not be applied if they occur inside a raw
@@ -5499,7 +5604,7 @@ a link:
 .IP
 .EX
 
-
+
 .EE
 .SS Inline links
 An inline link consists of the link text in square brackets, followed by
@@ -5507,8 +5612,8 @@ the URL in parentheses.
 (Optionally, the URL can be followed by a link title, in quotes.)
 .IP
 .EX
-This is an [inline link](/url), and here\[aq]s [one with
-a title](https://fsf.org \[dq]click here for a good time!\[dq]).
+This is an [inline link](/url), and here\(aqs [one with
+a title](https://fsf.org \(dqclick here for a good time!\(dq).
 .EE
 .PP
 There can be no space between the bracketed part and the parenthesized
@@ -5520,7 +5625,7 @@ Email addresses in inline links are not autodetected, so they have to be
 prefixed with \f[CR]mailto\f[R]:
 .IP
 .EX
-[Write me!](mailto:sam\[at]green.eggs.ham)
+[Write me!](mailto:sam\(atgreen.eggs.ham)
 .EE
 .SS Reference links
 An \f[I]explicit\f[R] reference link has two parts, the link itself and
@@ -5541,10 +5646,10 @@ over link labels.
 Here are some examples:
 .IP
 .EX
-[my label 1]: /foo/bar.html  \[dq]My title, optional\[dq]
+[my label 1]: /foo/bar.html  \(dqMy title, optional\(dq
 [my label 2]: /foo
 [my label 3]: https://fsf.org (The Free Software Foundation)
-[my label 4]: /bar#special  \[aq]A title in single quotes\[aq]
+[my label 4]: /bar#special  \(aqA title in single quotes\(aq
 .EE
 .PP
 The URL may optionally be surrounded by angle brackets:
@@ -5557,7 +5662,7 @@ The title may go on the next line:
 .IP
 .EX
 [my label 3]: https://fsf.org
-  \[dq]The Free Software Foundation\[dq]
+  \(dqThe Free Software Foundation\(dq
 .EE
 .PP
 Note that link labels are not case sensitive.
@@ -5621,10 +5726,10 @@ slide shows and EPUB), LaTeX, and ConTeXt.
 .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\[cq]s alt text:
+The link text will be used as the image\(cqs alt text:
 .IP
 .EX
-![la lune](lalune.jpg \[dq]Voyage to the moon\[dq])
+![la lune](lalune.jpg \(dqVoyage to the moon\(dq)
 
 ![movie reel]
 
@@ -5633,7 +5738,7 @@ The link text will be used as the image\[cq]s alt text:
 .SS Extension: \f[CR]implicit_figures\f[R]
 An image with nonempty alt text, occurring by itself in a paragraph,
 will be rendered as a figure with a caption.
-The image\[cq]s alt text will be used as the caption.
+The image\(cqs alt text will be used as the caption.
 .IP
 .EX
 ![This is the caption](/url/of/image.png)
@@ -5641,7 +5746,7 @@ The image\[cq]s alt text will be used as the caption.
 .PP
 How this is rendered depends on the output format.
 Some output formats (e.g.\ RTF) do not yet support figures.
-In those formats, you\[cq]ll just get an image in a paragraph by itself,
+In those formats, you\(cqll just get an image in a paragraph by itself,
 with no caption.
 .PP
 If you just want a regular inline image, just make sure it is not the
@@ -5649,7 +5754,7 @@ only thing in the paragraph.
 One way to do this is to insert a nonbreaking space after the image:
 .IP
 .EX
-![This image won\[aq]t be a figure](/url/of/image.png)\[rs]
+![This image won\(aqt be a figure](/url/of/image.png)\(rs
 .EE
 .PP
 Note that in reveal.js slide shows, an image in a paragraph by itself
@@ -5662,7 +5767,7 @@ Attributes can be set on links and images:
 An inline ![image](foo.jpg){#id .class width=30 height=20px}
 and a reference ![image][ref] with attributes.
 
-[ref]: foo.jpg \[dq]optional title\[dq] {#id .class key=val key2=\[dq]val 2\[dq]}
+[ref]: foo.jpg \(dqoptional title\(dq {#id .class key=val key2=\(dqval 2\(dq}
 .EE
 .PP
 (This syntax is compatible with PHP Markdown Extra when only
@@ -5688,33 +5793,31 @@ For example:
 .EX
 ![](file.jpg){ width=50% }
 .EE
-.IP \[bu] 2
+.IP \(bu 2
 Dimensions may be converted to a form that is compatible with the output
 format (for example, dimensions given in pixels will be converted to
 inches when converting HTML to LaTeX).
 Conversion between pixels and physical measurements is affected by the
 \f[CR]\-\-dpi\f[R] option (by default, 96 dpi is assumed, unless the
 image itself contains dpi information).
-.IP \[bu] 2
+.IP \(bu 2
 The \f[CR]%\f[R] unit is generally relative to some available space.
 For example the above example will render to the following.
 .RS 2
-.IP \[bu] 2
-HTML:
-\f[CR]\f[R]
-.IP \[bu] 2
+.IP \(bu 2
+HTML: \f[CR]\f[R]
+.IP \(bu 2
 LaTeX:
-\f[CR]\[rs]includegraphics[width=0.5\[rs]textwidth,height=\[rs]textheight]{file.jpg}\f[R]
-(If you\[cq]re using a custom template, you need to configure
+\f[CR]\(rsincludegraphics[width=0.5\(rstextwidth,height=\(rstextheight]{file.jpg}\f[R]
+(If you\(cqre using a custom template, you need to configure
 \f[CR]graphicx\f[R] as in the default template.)
-.IP \[bu] 2
-ConTeXt:
-\f[CR]\[rs]externalfigure[file.jpg][width=0.5\[rs]textwidth]\f[R]
+.IP \(bu 2
+ConTeXt: \f[CR]\(rsexternalfigure[file.jpg][width=0.5\(rstextwidth]\f[R]
 .RE
-.IP \[bu] 2
+.IP \(bu 2
 Some output formats have a notion of a class (ConTeXt) or a unique
-identifier (LaTeX \f[CR]\[rs]caption\f[R]), or both (HTML).
-.IP \[bu] 2
+identifier (LaTeX \f[CR]\(rscaption\f[R]), or both (HTML).
+.IP \(bu 2
 When no \f[CR]width\f[R] or \f[CR]height\f[R] attributes are specified,
 the fallback is to look at the image resolution and the dpi metadata
 embedded in the image file.
@@ -5731,7 +5834,7 @@ plus some attributes.
 The attributes may optionally be followed by another string of
 consecutive colons.
 .PP
-Note: the \f[CR]commonmark\f[R] parser doesn\[cq]t permit colons after
+Note: the \f[CR]commonmark\f[R] parser doesn\(cqt permit colons after
 the attributes.
 .PP
 The attribute syntax is exactly as in fenced code blocks (see Extension:
@@ -5778,18 +5881,18 @@ be treated as a \f[CR]Span\f[R] with attributes if it is followed
 immediately by attributes:
 .IP
 .EX
-[This is *some text*]{.class key=\[dq]val\[dq]}
+[This is *some text*]{.class key=\(dqval\(dq}
 .EE
 .SS Footnotes
 .SS Extension: \f[CR]footnotes\f[R]
-Pandoc\[cq]s Markdown allows footnotes, using the following syntax:
+Pandoc\(cqs Markdown allows footnotes, using the following syntax:
 .IP
 .EX
-Here is a footnote reference,[\[ha]1] and another.[\[ha]longnote]
+Here is a footnote reference,[\(ha1] and another.[\(halongnote]
 
-[\[ha]1]: Here is the footnote.
+[\(ha1]: Here is the footnote.
 
-[\[ha]longnote]: Here\[aq]s one with multiple blocks.
+[\(halongnote]: Here\(aqs one with multiple blocks.
 
     Subsequent paragraphs are indented to show that they
 belong to the previous footnote.
@@ -5800,12 +5903,12 @@ belong to the previous footnote.
     line.  In this way, multi\-paragraph footnotes work like
     multi\-paragraph list items.
 
-This paragraph won\[aq]t be part of the note, because it
-isn\[aq]t indented.
+This paragraph won\(aqt be part of the note, because it
+isn\(aqt indented.
 .EE
 .PP
 The identifiers in footnote references may not contain spaces, tabs,
-newlines, or the characters \f[CR]\[ha]\f[R], \f[CR][\f[R], or
+newlines, or the characters \f[CR]\(ha\f[R], \f[CR][\f[R], or
 \f[CR]]\f[R].
 These identifiers are used only to correlate the footnote reference with
 the note itself; in the output, footnotes will be numbered sequentially.
@@ -5821,8 +5924,8 @@ cannot contain multiple paragraphs).
 The syntax is as follows:
 .IP
 .EX
-Here is an inline note.\[ha][Inline notes are easier to write, since
-you don\[aq]t have to pick an identifier and move down to type the
+Here is an inline note.\(ha[Inline notes are easier to write, since
+you don\(aqt have to pick an identifier and move down to type the
 note.]
 .EE
 .PP
@@ -5830,12 +5933,12 @@ Inline and regular footnotes may be mixed freely.
 .SS Citation syntax
 .SS Extension: \f[CR]citations\f[R]
 To cite a bibliographic item with an identifier foo, use the syntax
-\f[CR]\[at]foo\f[R].
+\f[CR]\(atfoo\f[R].
 Normal citations should be included in square brackets, with semicolons
 separating distinct items:
 .IP
 .EX
-Blah blah [\[at]doe99; \[at]smith2000; \[at]smith2004].
+Blah blah [\(atdoe99; \(atsmith2000; \(atsmith2004].
 .EE
 .PP
 How this is rendered depends on the citation style.
@@ -5848,11 +5951,11 @@ Blah blah (Doe 1999, Smith 2000, 2004).
 In a footnote style, it might render as
 .IP
 .EX
-Blah blah.[\[ha]1]
+Blah blah.[\(ha1]
 
-[\[ha]1]:  John Doe, \[dq]Frogs,\[dq] *Journal of Amphibians* 44 (1999);
-Susan Smith, \[dq]Flies,\[dq] *Journal of Insects* (2000);
-Susan Smith, \[dq]Bees,\[dq] *Journal of Insects* (2004).
+[\(ha1]:  John Doe, \(dqFrogs,\(dq *Journal of Amphibians* 44 (1999);
+Susan Smith, \(dqFlies,\(dq *Journal of Insects* (2000);
+Susan Smith, \(dqBees,\(dq *Journal of Insects* (2004).
 .EE
 .PP
 See the CSL user documentation for more information about CSL styles and
@@ -5860,23 +5963,23 @@ how they affect rendering.
 .PP
 Unless a citation key starts with a letter, digit, or \f[CR]_\f[R], and
 contains only alphanumerics and single internal punctuation characters
-(\f[CR]:.#$%&\-+?<>\[ti]/\f[R]), it must be surrounded by curly braces,
+(\f[CR]:.#$%&\-+?<>\(ti/\f[R]), it must be surrounded by curly braces,
 which are not considered part of the key.
-In \f[CR]\[at]Foo_bar.baz.\f[R], the key is \f[CR]Foo_bar.baz\f[R]
+In \f[CR]\(atFoo_bar.baz.\f[R], the key is \f[CR]Foo_bar.baz\f[R]
 because the final period is not \f[I]internal\f[R] punctuation, so it is
 not included in the key.
-In \f[CR]\[at]{Foo_bar.baz.}\f[R], the key is \f[CR]Foo_bar.baz.\f[R],
+In \f[CR]\(at{Foo_bar.baz.}\f[R], the key is \f[CR]Foo_bar.baz.\f[R],
 including the final period.
-In \f[CR]\[at]Foo_bar\-\-baz\f[R], the key is \f[CR]Foo_bar\f[R] because
+In \f[CR]\(atFoo_bar\-\-baz\f[R], the key is \f[CR]Foo_bar\f[R] because
 the repeated internal punctuation characters terminate the key.
 The curly braces are recommended if you use URLs as keys:
-\f[CR][\[at]{https://example.com/bib?name=foobar&date=2000}, p.  33]\f[R].
+\f[CR][\(at{https://example.com/bib?name=foobar&date=2000}, p.  33]\f[R].
 .PP
 Citation items may optionally include a prefix, a locator, and a suffix.
 In
 .IP
 .EX
-Blah blah [see \[at]doe99, pp. 33\-35 and *passim*; \[at]smith04, chap. 1].
+Blah blah [see \(atdoe99, pp. 33\-35 and *passim*; \(atsmith04, chap. 1].
 .EE
 .PP
 the first item (\f[CR]doe99\f[R]) has prefix \f[CR]see\f[R], locator
@@ -5907,36 +6010,36 @@ singular or plural forms, as \f[CR]book\f[R],
 \f[CR]v.\f[R]/\f[CR]vv.\f[R]; \f[CR]volume\f[R],
 \f[CR]vol.\f[R]/\f[CR]vols.\f[R]; \f[CR]¶\f[R]/\f[CR]¶¶\f[R];
 \f[CR]§\f[R]/\f[CR]§§\f[R].
-If no locator term is used, \[lq]page\[rq] is assumed.
+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:
 .IP
 .EX
-[\[at]smith{ii, A, D\-Z}, with a suffix]
-[\[at]smith, {pp. iv, vi\-xi, (xv)\-(xvii)} with suffix here]
-[\[at]smith{}, 99 years later]
+[\(atsmith{ii, A, D\-Z}, with a suffix]
+[\(atsmith, {pp. iv, vi\-xi, (xv)\-(xvii)} with suffix here]
+[\(atsmith{}, 99 years later]
 .EE
 .PP
-A minus sign (\f[CR]\-\f[R]) before the \f[CR]\[at]\f[R] will suppress
+A minus sign (\f[CR]\-\f[R]) before the \f[CR]\(at\f[R] will suppress
 mention of the author in the citation.
 This can be useful when the author is already mentioned in the text:
 .IP
 .EX
-Smith says blah [\-\[at]smith04].
+Smith says blah [\-\(atsmith04].
 .EE
 .PP
 You can also write an author\-in\-text citation, by omitting the square
 brackets:
 .IP
 .EX
-\[at]smith04 says blah.
+\(atsmith04 says blah.
 
-\[at]smith04 [p. 33] says blah.
+\(atsmith04 [p. 33] says blah.
 .EE
 .PP
-This will cause the author\[cq]s name to be rendered, followed by the
+This will cause the author\(cqs name to be rendered, followed by the
 bibliographical details.
 Use this form when you want to make the citation the subject of a
 sentence.
@@ -6002,32 +6105,32 @@ Allows attributes to be attached to any inline or block\-level element
 when parsing \f[CR]commonmark\f[R].
 The syntax for the attributes is the same as that used in
 \f[CR]header_attributes\f[R].
-.IP \[bu] 2
+.IP \(bu 2
 Attributes that occur immediately after an inline element affect that
 element.
 If they follow a space, then they belong to the space.
 (Hence, this option subsumes \f[CR]inline_code_attributes\f[R] and
 \f[CR]link_attributes\f[R].)
-.IP \[bu] 2
+.IP \(bu 2
 Attributes that occur immediately before a block element, on a line by
 themselves, affect that element.
-.IP \[bu] 2
+.IP \(bu 2
 Consecutive attribute specifiers may be used, either for blocks or for
 inlines.
 Their attributes will be combined.
-.IP \[bu] 2
+.IP \(bu 2
 Attributes that occur at the end of the text of a Setext or ATX heading
 (separated by whitespace from the text) affect the heading element.
 (Hence, this option subsumes \f[CR]header_attributes\f[R].)
-.IP \[bu] 2
+.IP \(bu 2
 Attributes that occur after the opening fence in a fenced code block
 affect the code block element.
 (Hence, this option subsumes \f[CR]fenced_code_attributes\f[R].)
-.IP \[bu] 2
+.IP \(bu 2
 Attributes that occur at the end of a reference link definition affect
 links that refer to that definition.
 .PP
-Note that pandoc\[cq]s AST does not currently allow attributes to be
+Note that pandoc\(cqs AST does not currently allow attributes to be
 attached to arbitrary elements.
 Hence a Span or Div container will be added if needed.
 .SS Extension: \f[CR]old_dashes\f[R]
@@ -6039,8 +6142,7 @@ It is selected automatically for \f[CR]textile\f[R] input.
 .SS Extension: \f[CR]angle_brackets_escapable\f[R]
 Allow \f[CR]<\f[R] and \f[CR]>\f[R] to be backslash\-escaped, as they
 can be in GitHub flavored Markdown but not original Markdown.
-This is implied by pandoc\[cq]s default
-\f[CR]all_symbols_escapable\f[R].
+This is implied by pandoc\(cqs default \f[CR]all_symbols_escapable\f[R].
 .SS Extension: \f[CR]lists_without_preceding_blankline\f[R]
 Allow a list to occur right after a paragraph, with no intervening blank
 space.
@@ -6073,26 +6175,26 @@ that include a mix of East Asian wide characters and other characters.
 Parses textual emojis like \f[CR]:smile:\f[R] as Unicode emoticons.
 .SS Extension: \f[CR]tex_math_gfm\f[R]
 Supports two GitHub\-specific formats for math.
-Inline math: \f[CR]$\[ga]e=mc\[ha]2\[ga]$\f[R].
+Inline math: \f[CR]$\(gae=mc\(ha2\(ga$\f[R].
 .PP
 Display math:
 .IP
 .EX
-\[ga]\[ga]\[ga] math
-e=mc\[ha]2
-\[ga]\[ga]\[ga]
+\(ga\(ga\(ga math
+e=mc\(ha2
+\(ga\(ga\(ga
 .EE
 .SS Extension: \f[CR]tex_math_single_backslash\f[R]
-Causes anything between \f[CR]\[rs](\f[R] and \f[CR]\[rs])\f[R] to be
-interpreted as inline TeX math, and anything between \f[CR]\[rs][\f[R]
-and \f[CR]\[rs]]\f[R] to be interpreted as display TeX math.
+Causes anything between \f[CR]\(rs(\f[R] and \f[CR]\(rs)\f[R] to be
+interpreted as inline TeX math, and anything between \f[CR]\(rs[\f[R]
+and \f[CR]\(rs]\f[R] to be interpreted as display TeX math.
 Note: a drawback of this extension is that it precludes escaping
 \f[CR](\f[R] and \f[CR][\f[R].
 .SS Extension: \f[CR]tex_math_double_backslash\f[R]
-Causes anything between \f[CR]\[rs]\[rs](\f[R] and
-\f[CR]\[rs]\[rs])\f[R] to be interpreted as inline TeX math, and
-anything between \f[CR]\[rs]\[rs][\f[R] and \f[CR]\[rs]\[rs]]\f[R] to be
-interpreted as display TeX math.
+Causes anything between \f[CR]\(rs\(rs(\f[R] and \f[CR]\(rs\(rs)\f[R] to
+be interpreted as inline TeX math, and anything between
+\f[CR]\(rs\(rs[\f[R] and \f[CR]\(rs\(rs]\f[R] to be interpreted as
+display TeX math.
 .SS Extension: \f[CR]markdown_attribute\f[R]
 By default, pandoc interprets material inside block\-level tags as
 Markdown.
@@ -6131,6 +6233,9 @@ 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].
@@ -6143,8 +6248,8 @@ This extension should not be confused with the
 .EX
 This is a reference ![image][ref] with MultiMarkdown attributes.
 
-[ref]: https://path.to/image \[dq]Image title\[dq] width=20px height=30px
-       id=myId class=\[dq]myClass1 myClass2\[dq]
+[ref]: https://path.to/image \(dqImage title\(dq width=20px height=30px
+       id=myId class=\(dqmyClass1 myClass2\(dq
 .EE
 .SS Extension: \f[CR]mmd_header_identifiers\f[R]
 Parses MultiMarkdown\-style heading identifiers (in square brackets,
@@ -6154,14 +6259,14 @@ heading).
 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
+.IP \(bu 2
 No blank line is required between consecutive items of the definition
 list.
-.IP \[bu] 2
-To get a \[lq]tight\[rq] or \[lq]compact\[rq] list, omit space between
+.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
+.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]
@@ -6175,18 +6280,18 @@ added; other elements are placed in a surrounding Div or Span element
 with a \f[CR]data\-pos\f[R] attribute.
 .SS Extension: \f[CR]short_subsuperscripts\f[R]
 Parse MultiMarkdown\-style subscripts and superscripts, which start with
-a `\[ti]' or `\[ha]' character, respectively, and include the
-alphanumeric sequence that follows.
+a `\(ti' or `\(ha' character, respectively, and include the alphanumeric
+sequence that follows.
 For example:
 .IP
 .EX
-x\[ha]2 = 4
+x\(ha2 = 4
 .EE
 .PP
 or
 .IP
 .EX
-Oxygen is O\[ti]2.
+Oxygen is O\(ti2.
 .EE
 .SS Extension: \f[CR]wikilinks_title_after_pipe\f[R]
 Pandoc supports multiple Markdown wikilink syntaxes, regardless of
@@ -6205,21 +6310,21 @@ results in
 [[title|URL]]
 .EE
 .SS Markdown variants
-In addition to pandoc\[cq]s extended Markdown, the following Markdown
+In addition to pandoc\(cqs extended Markdown, the following Markdown
 variants are supported:
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]markdown_phpextra\f[R] (PHP Markdown Extra)
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]markdown_github\f[R] (deprecated GitHub\-Flavored Markdown)
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]markdown_mmd\f[R] (MultiMarkdown)
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]markdown_strict\f[R] (Markdown.pl)
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]commonmark\f[R] (CommonMark)
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]gfm\f[R] (Github\-Flavored Markdown)
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]commonmark_x\f[R] (CommonMark with many pandoc extensions)
 .PP
 To see which extensions are supported for a given format, and which are
@@ -6247,12 +6352,12 @@ pandoc \-\-citeproc myinput.txt
 .EE
 .PP
 To use this feature, you will need to have
-.IP \[bu] 2
+.IP \(bu 2
 a document containing citations (see Citation syntax);
-.IP \[bu] 2
+.IP \(bu 2
 a source of bibliographic data: either an external bibliography file or
-a list of \f[CR]references\f[R] in the document\[cq]s YAML metadata;
-.IP \[bu] 2
+a list of \f[CR]references\f[R] in the document\(cqs YAML metadata;
+.IP \(bu 2
 optionally, a CSL citation style.
 .SS Specifying bibliographic data
 You can specify an external bibliography using the
@@ -6289,7 +6394,7 @@ italics
 \f[CR]...\f[R]
 bold
 .TP
-\f[CR]...\f[R] or \f[CR]...\f[R]
+\f[CR]...\f[R] or \f[CR]...\f[R]
 small capitals
 .TP
 \f[CR]...\f[R]
@@ -6298,13 +6403,13 @@ subscript
 \f[CR]...\f[R]
 superscript
 .TP
-\f[CR]...\f[R]
+\f[CR]...\f[R]
 prevent a phrase from being capitalized as title case
 .PP
 As an alternative to specifying a bibliography file using
 \f[CR]\-\-bibliography\f[R] or the YAML metadata field
 \f[CR]bibliography\f[R], you can include the citation data directly in
-the \f[CR]references\f[R] field of the document\[cq]s YAML metadata.
+the \f[CR]references\f[R] field of the document\(cqs YAML metadata.
 The field should contain an array of YAML\-encoded references, for
 example:
 .IP
@@ -6323,8 +6428,8 @@ references:
     \- \- 1953
       \- 4
       \- 25
-  title: \[aq]Molecular structure of nucleic acids: a structure for
-    deoxyribose nucleic acid\[aq]
+  title: \(aqMolecular structure of nucleic acids: a structure for
+    deoxyribose nucleic acid\(aq
   title\-short: Molecular structure of nucleic acids
   container\-title: Nature
   volume: 171
@@ -6367,7 +6472,7 @@ pandoc chem.bib \-s \-\-citeproc \-o chem.pdf
 .SS Capitalization in titles
 If you are using a bibtex or biblatex bibliography, then observe the
 following rules:
-.IP \[bu] 2
+.IP \(bu 2
 English titles should be in title case.
 Non\-English titles should be in sentence case, and the
 \f[CR]langid\f[R] field in biblatex should be set to the relevant
@@ -6376,9 +6481,9 @@ language.
 \f[CR]british\f[R], \f[CR]canadian\f[R], \f[CR]english\f[R],
 \f[CR]australian\f[R], \f[CR]newzealand\f[R], \f[CR]USenglish\f[R], or
 \f[CR]UKenglish\f[R].)
-.IP \[bu] 2
+.IP \(bu 2
 As is standard with bibtex/biblatex, proper names should be protected
-with curly braces so that they won\[cq]t be lowercased in styles that
+with curly braces so that they won\(cqt be lowercased in styles that
 call for sentence case.
 For example:
 .RS 2
@@ -6387,7 +6492,7 @@ For example:
 title = {My Dinner with {Andre}}
 .EE
 .RE
-.IP \[bu] 2
+.IP \(bu 2
 In addition, words that should remain lowercase (or camelCase) should be
 protected:
 .RS 2
@@ -6399,26 +6504,26 @@ title = {Spin Wave Dispersion on the {nm} Scale}
 Though this is not necessary in bibtex/biblatex, it is necessary with
 citeproc, which stores titles internally in sentence case, and converts
 to title case in styles that require it.
-Here we protect \[lq]nm\[rq] so that it doesn\[cq]t get converted to
-\[lq]Nm\[rq] at this stage.
+Here we protect \(lqnm\(rq so that it doesn\(cqt get converted to
+\(lqNm\(rq at this stage.
 .RE
 .PP
 If you are using a CSL bibliography (either JSON or YAML), then observe
 the following rules:
-.IP \[bu] 2
+.IP \(bu 2
 All titles should be in sentence case.
-.IP \[bu] 2
+.IP \(bu 2
 Use the \f[CR]language\f[R] field for non\-English titles to prevent
 their conversion to title case in styles that call for this.
 (Conversion happens only if \f[CR]language\f[R] begins with
 \f[CR]en\f[R] or is left empty.)
-.IP \[bu] 2
+.IP \(bu 2
 Protect words that should not be converted to title case using this
 syntax:
 .RS 2
 .IP
 .EX
-Spin wave dispersion on the nm scale
+Spin wave dispersion on the nm scale
 .EE
 .RE
 .SS Conference Papers, Published vs.\ Unpublished
@@ -6435,11 +6540,11 @@ use the biblatex entry type \f[CR]unpublished\f[R] with an
 \f[CR]eventtitle\f[R] field (this entry type will be mapped to CSL
 \f[CR]speech\f[R]).
 Use the biblatex \f[CR]type\f[R] field to indicate the type,
-e.g.\ \[lq]Paper\[rq], or \[lq]Poster\[rq].
+e.g.\ \(lqPaper\(rq, or \(lqPoster\(rq.
 \f[CR]venue\f[R] and \f[CR]eventdate\f[R] may be useful too, though
 \f[CR]eventdate\f[R] will not be rendered by most CSL styles.
-Note that \f[CR]venue\f[R] is for the event\[cq]s venue, unlike
-\f[CR]location\f[R] which describes the publisher\[cq]s location; do not
+Note that \f[CR]venue\f[R] is for the event\(cqs venue, unlike
+\f[CR]location\f[R] which describes the publisher\(cqs location; do not
 use the latter for an unpublished conference paper.
 .SS Specifying a citation style
 Citations and references can be formatted using any style supported by
@@ -6456,30 +6561,30 @@ styles.
 The \f[CR]\-\-citation\-abbreviations\f[R] option (or the
 \f[CR]citation\-abbreviations\f[R] metadata field) may be used to
 specify a JSON file containing abbreviations of journals that should be
-used in formatted bibliographies when \f[CR]form=\[dq]short\[dq]\f[R] is
+used in formatted bibliographies when \f[CR]form=\(dqshort\(dq\f[R] is
 specified.
 The format of the file can be illustrated with an example:
 .IP
 .EX
-{ \[dq]default\[dq]: {
-    \[dq]container\-title\[dq]: {
-            \[dq]Lloyd\[aq]s Law Reports\[dq]: \[dq]Lloyd\[aq]s Rep\[dq],
-            \[dq]Estates Gazette\[dq]: \[dq]EG\[dq],
-            \[dq]Scots Law Times\[dq]: \[dq]SLT\[dq]
+{ \(dqdefault\(dq: {
+    \(dqcontainer\-title\(dq: {
+            \(dqLloyd\(aqs Law Reports\(dq: \(dqLloyd\(aqs Rep\(dq,
+            \(dqEstates Gazette\(dq: \(dqEG\(dq,
+            \(dqScots Law Times\(dq: \(dqSLT\(dq
     }
   }
 }
 .EE
 .SS Citations in note styles
-Pandoc\[cq]s citation processing is designed to allow you to move
-between author\-date, numerical, and note styles without modifying the
-Markdown source.
-When you\[cq]re using a note style, avoid inserting footnotes manually.
+Pandoc\(cqs citation processing is designed to allow you to move between
+author\-date, numerical, and note styles without modifying the Markdown
+source.
+When you\(cqre using a note style, avoid inserting footnotes manually.
 Instead, insert citations just as you would in an author\-date
-style\[em]for example,
+style\(emfor example,
 .IP
 .EX
-Blah blah [\[at]foo, p. 33].
+Blah blah [\(atfoo, p. 33].
 .EE
 .PP
 The footnote will be created automatically.
@@ -6489,17 +6594,17 @@ or after the period, depending on the setting of
 relevant metadata fields.
 .PP
 In some cases you may need to put a citation inside a regular footnote.
-Normal citations in footnotes (such as \f[CR][\[at]foo, p. 33]\f[R])
-will be rendered in parentheses.
-In\-text citations (such as \f[CR]\[at]foo [p. 33]\f[R]) will be
-rendered without parentheses.
+Normal citations in footnotes (such as \f[CR][\(atfoo, p. 33]\f[R]) will
+be rendered in parentheses.
+In\-text citations (such as \f[CR]\(atfoo [p. 33]\f[R]) will be rendered
+without parentheses.
 (A comma will be added if appropriate.)
 Thus:
 .IP
 .EX
-[\[ha]1]:  Some studies [\[at]foo; \[at]bar, p. 33] show that
+[\(ha1]:  Some studies [\(atfoo; \(atbar, p. 33] show that
 frubulicious zoosnaps are quantical.  For a survey
-of the literature, see \[at]baz [chap. 1].
+of the literature, see \(atbaz [chap. 1].
 .EE
 .SS Placement of the bibliography
 If the style calls for a list of works cited, it will be placed in a div
@@ -6551,10 +6656,10 @@ field and put the citations there:
 .EX
 \-\-\-
 nocite: |
-  \[at]item1, \[at]item2
+  \(atitem1, \(atitem2
 \&...
 
-\[at]item3
+\(atitem3
 .EE
 .PP
 In this example, the document will contain a citation for
@@ -6567,7 +6672,7 @@ or not they appear in the document, by using a wildcard:
 .EX
 \-\-\-
 nocite: |
-  \[at]*
+  \(at*
 \&...
 .EE
 .PP
@@ -6608,15 +6713,15 @@ A BCP 47 language tag is expected: for example, \f[CR]en\f[R],
 The unicode extension syntax (after \f[CR]\-u\-\f[R]) may be used to
 specify options for collation (sorting) more precisely.
 Here are some examples:
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]zh\-u\-co\-pinyin\f[R]: Chinese with the Pinyin collation.
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]es\-u\-co\-trad\f[R]: Spanish with the traditional collation (with
 \f[CR]Ch\f[R] sorting after \f[CR]C\f[R]).
-.IP \[bu] 2
-\f[CR]fr\-u\-kb\f[R]: French with \[lq]backwards\[rq] accent sorting
-(with \f[CR]coté\f[R] sorting after \f[CR]côte\f[R]).
-.IP \[bu] 2
+.IP \(bu 2
+\f[CR]fr\-u\-kb\f[R]: French with \(lqbackwards\(rq accent sorting (with
+\f[CR]coté\f[R] sorting after \f[CR]côte\f[R]).
+.IP \(bu 2
 \f[CR]en\-US\-u\-kf\-upper\f[R]: English with uppercase letters sorting
 before lower (default is lower before upper).
 .RE
@@ -6625,10 +6730,9 @@ before lower (default is lower before upper).
 If true (the default for note styles), pandoc will put footnote
 references or superscripted numerical citations after following
 punctuation.
-For example, if the source contains
-\f[CR]blah blah [\[at]jones99].\f[R], the result will look like
-\f[CR]blah blah.[\[ha]1]\f[R], with the note moved after the period and
-the space collapsed.
+For example, if the source contains \f[CR]blah blah [\(atjones99].\f[R],
+the result will look like \f[CR]blah blah.[\(ha1]\f[R], with the note
+moved after the period and the space collapsed.
 If false, the space will still be collapsed, but the footnote will not
 be moved after the punctuation.
 The option may also be used in numerical styles that use superscripts
@@ -6642,7 +6746,7 @@ reveal.js.
 You can also produce a PDF slide show using LaTeX \f[CR]beamer\f[R], or
 slide shows in Microsoft PowerPoint format.
 .PP
-Here\[cq]s the Markdown source for a simple slide show,
+Here\(cqs the Markdown source for a simple slide show,
 \f[CR]habits.txt\f[R]:
 .IP
 .EX
@@ -6729,33 +6833,33 @@ This default can be overridden using the \f[CR]\-\-slide\-level\f[R]
 option.
 .PP
 The document is carved up into slides according to the following rules:
-.IP \[bu] 2
+.IP \(bu 2
 A horizontal rule always starts a new slide.
-.IP \[bu] 2
+.IP \(bu 2
 A heading at the slide level always starts a new slide.
-.IP \[bu] 2
+.IP \(bu 2
 Headings \f[I]below\f[R] the slide level in the hierarchy create
 headings \f[I]within\f[R] a slide.
-(In beamer, a \[lq]block\[rq] will be created.
+(In beamer, a \(lqblock\(rq will be created.
 If the heading has the class \f[CR]example\f[R], an
 \f[CR]exampleblock\f[R] environment will be used; if it has the class
 \f[CR]alert\f[R], an \f[CR]alertblock\f[R] will be used; otherwise a
 regular \f[CR]block\f[R] will be used.)
-.IP \[bu] 2
+.IP \(bu 2
 Headings \f[I]above\f[R] the slide level in the hierarchy create
-\[lq]title slides,\[rq] which just contain the section title and help to
+\(lqtitle slides,\(rq which just contain the section title and help to
 break the slide show into sections.
 Non\-slide content under these headings will be included on the title
 slide (for HTML slide shows) or in a subsequent slide with the same
 title (for beamer).
-.IP \[bu] 2
-A title page is constructed automatically from the document\[cq]s title
+.IP \(bu 2
+A title page is constructed automatically from the document\(cqs title
 block, if present.
 (In the case of beamer, this can be disabled by commenting out some
 lines in the default template.)
 .PP
 These rules are designed to support many different styles of slide show.
-If you don\[cq]t care about structuring your slides into sections and
+If you don\(cqt care about structuring your slides into sections and
 subsections, you can either just use level\-1 headings for all slides
 (in that case, level 1 will be the slide level) or you can set
 \f[CR]\-\-slide\-level=0\f[R].
@@ -6777,7 +6881,7 @@ from the metadata fields \f[CR]date\f[R], \f[CR]author\f[R], and
 \f[CR]title\f[R], if they are present.
 .TP
 Section Header
-This layout is used for what pandoc calls \[lq]title slides\[rq], i.e.
+This layout is used for what pandoc calls \(lqtitle slides\(rq, i.e.
 slides which start with a header which is above the slide level in the
 hierarchy.
 .TP
@@ -6787,7 +6891,7 @@ div with class \f[CR]columns\f[R] which contains at least two divs with
 class \f[CR]column\f[R].
 .TP
 Comparison
-This layout is used instead of \[lq]Two Content\[rq] for any two\-column
+This layout is used instead of \(lqTwo Content\(rq for any two\-column
 slides in which at least one column contains text followed by non\-text
 (e.g.\ an image or a table).
 .TP
@@ -6808,9 +6912,9 @@ These layouts are chosen from the default pptx reference doc included
 with pandoc, unless an alternative reference doc is specified using
 \f[CR]\-\-reference\-doc\f[R].
 .SS Incremental lists
-By default, these writers produce lists that display \[lq]all at
-once.\[rq] If you want your lists to display incrementally (one item at
-a time), use the \f[CR]\-i\f[R] option.
+By default, these writers produce lists that display \(lqall at
+once.\(rq If you want your lists to display incrementally (one item at a
+time), use the \f[CR]\-i\f[R] option.
 If you want a particular list to depart from the default, put it in a
 \f[CR]div\f[R] block with class \f[CR]incremental\f[R] or
 \f[CR]nonincremental\f[R].
@@ -6863,7 +6967,7 @@ direct child of the block quote:
 > :::
 .EE
 .SS Inserting pauses
-You can add \[lq]pauses\[rq] within a slide by including a paragraph
+You can add \(lqpauses\(rq within a slide by including a paragraph
 containing three dots, separated by spaces:
 .IP
 .EX
@@ -6883,7 +6987,7 @@ in \f[CR]$DATADIR/s5/default\f[R] (for S5), \f[CR]$DATADIR/slidy\f[R]
 (for Slidy), or \f[CR]$DATADIR/slideous\f[R] (for Slideous), where
 \f[CR]$DATADIR\f[R] is the user data directory (see
 \f[CR]\-\-data\-dir\f[R], above).
-The originals may be found in pandoc\[cq]s system data directory
+The originals may be found in pandoc\(cqs system data directory
 (generally \f[CR]$CABALDIR/pandoc\-VERSION/s5/default\f[R]).
 Pandoc will look there for any files it does not find in the user data
 directory.
@@ -6947,10 +7051,10 @@ attribute:
 .IP
 .EX
 :::::::::::::: {.columns}
-::: {.column width=\[dq]40%\[dq]}
+::: {.column width=\(dq40%\(dq}
 contents...
 :::
-::: {.column width=\[dq]60%\[dq]}
+::: {.column width=\(dq60%\(dq}
 contents...
 :::
 ::::::::::::::
@@ -6965,10 +7069,10 @@ attribute or an \f[CR]onlytextwidth\f[R] class.
 .IP
 .EX
 :::::::::::::: {.columns align=center totalwidth=8em}
-::: {.column width=\[dq]40%\[dq]}
+::: {.column width=\(dq40%\(dq}
 contents...
 :::
-::: {.column width=\[dq]60%\[dq] align=bottom}
+::: {.column width=\(dq60%\(dq align=bottom}
 contents...
 :::
 ::::::::::::::
@@ -6985,19 +7089,19 @@ the given value.
 .IP
 .EX
 :::::::::::::: {.columns align=top .onlytextwidth}
-::: {.column width=\[dq]40%\[dq] align=center}
+::: {.column width=\(dq40%\(dq align=center}
 contents...
 :::
-::: {.column width=\[dq]60%\[dq]}
+::: {.column width=\(dq60%\(dq}
 contents...
 :::
 ::::::::::::::
 .EE
 .PP
 The class \f[CR]onlytextwidth\f[R] sets the \f[CR]totalwidth\f[R] to
-\f[CR]\[rs]textwidth\f[R].
+\f[CR]\(rstextwidth\f[R].
 .PP
-See Section 12.7 of the Beamer User\[cq]s Guide for more details.
+See Section 12.7 of the Beamer User\(cqs Guide for more details.
 .SS Frame attributes in beamer
 Sometimes it is necessary to add the LaTeX \f[CR][fragile]\f[R] option
 to a frame in beamer (for example, when using the \f[CR]minted\f[R]
@@ -7010,7 +7114,7 @@ introducing the slide:
 .EE
 .PP
 All of the other frame attributes described in Section 8.1 of the Beamer
-User\[cq]s Guide may also be used: \f[CR]allowdisplaybreaks\f[R],
+User\(cqs Guide may also be used: \f[CR]allowdisplaybreaks\f[R],
 \f[CR]allowframebreaks\f[R], \f[CR]b\f[R], \f[CR]c\f[R], \f[CR]s\f[R],
 \f[CR]t\f[R], \f[CR]environment\f[R], \f[CR]label\f[R],
 \f[CR]plain\f[R], \f[CR]shrink\f[R], \f[CR]standout\f[R],
@@ -7027,7 +7131,7 @@ In addition, the \f[CR]frameoptions\f[R] attribute may be used to pass
 arbitrary frame options to a beamer slide:
 .IP
 .EX
-# Heading {frameoptions=\[dq]squeeze,shrink,customoption=foobar\[dq]}
+# Heading {frameoptions=\(dqsqueeze,shrink,customoption=foobar\(dq}
 .EE
 .SS Background in reveal.js, beamer, and pptx
 Background images can be added to self\-contained reveal.js slide shows,
@@ -7054,11 +7158,11 @@ behaviour.
 See the reveal.js documentation for more details about the meaning of
 these options.
 .PP
-In reveal.js\[cq]s overview mode, the parallaxBackgroundImage will show
+In reveal.js\(cqs overview mode, the parallaxBackgroundImage will show
 up only on the first slide.
 .SS On individual slides (reveal.js, pptx)
 To set an image for a particular reveal.js or pptx slide, add
-\f[CR]{background\-image=\[dq]/path/to/image\[dq]}\f[R] to the first
+\f[CR]{background\-image=\(dq/path/to/image\(dq}\f[R] to the first
 slide\-level heading on the slide (which may even be empty).
 .PP
 As the HTML writers pass unknown attributes through, other reveal.js
@@ -7069,18 +7173,18 @@ background settings also work on individual slides, including
 (The \f[CR]data\-\f[R] prefix will automatically be added.)
 .PP
 Note: \f[CR]data\-background\-image\f[R] is also supported in pptx for
-consistency with reveal.js \[en] if \f[CR]background\-image\f[R]
-isn\[cq]t found, \f[CR]data\-background\-image\f[R] will be checked.
+consistency with reveal.js \(en if \f[CR]background\-image\f[R] isn\(cqt
+found, \f[CR]data\-background\-image\f[R] will be checked.
 .SS On the title slide (reveal.js, pptx)
 To add a background image to the automatically generated title slide for
 reveal.js, use the \f[CR]title\-slide\-attributes\f[R] variable in the
 YAML metadata block.
 It must contain a map of attribute names and values.
-(Note that the \f[CR]data\-\f[R] prefix is required here, as it
-isn\[cq]t added automatically.)
+(Note that the \f[CR]data\-\f[R] prefix is required here, as it isn\(cqt
+added automatically.)
 .PP
 For pptx, pass a \f[CR]\-\-reference\-doc\f[R] with the background image
-set on the \[lq]Title Slide\[rq] layout.
+set on the \(lqTitle Slide\(rq layout.
 .SS Example (reveal.js)
 .IP
 .EX
@@ -7096,16 +7200,20 @@ title\-slide\-attributes:
 
 Slide 1 has background_image.png as its background.
 
-## {background\-image=\[dq]/path/to/special_image.jpg\[dq]}
+## {background\-image=\(dq/path/to/special_image.jpg\(dq}
 
 Slide 2 has a special image for its background, even though the heading has no content.
 .EE
 .SH EPUBS
 .SS EPUB Metadata
-EPUB metadata may be specified using the \f[CR]\-\-epub\-metadata\f[R]
-option, but if the source document is Markdown, it is better to use a
-YAML metadata block.
-Here is an example:
+There are two ways to specify metadata for an EPUB.
+The first is to use the \f[CR]\-\-epub\-metadata\f[R] option, which
+takes as its argument an XML file with Dublin Core elements.
+.PP
+The second way is to use YAML, either in a YAML metadata block in a
+Markdown document, or in a separate YAML file specified with
+\f[CR]\-\-metadata\-file\f[R].
+Here is an example of a YAML metadata block with EPUB metadata:
 .IP
 .EX
 \-\-\-
@@ -7152,8 +7260,8 @@ Valid values for \f[CR]type\f[R] are \f[CR]main\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.
 Valid values for \f[CR]role\f[R] are MARC relators, but pandoc will
-attempt to translate the human\-readable versions (like \[lq]author\[rq]
-and \[lq]editor\[rq]) to the appropriate marc relators.
+attempt to translate the human\-readable versions (like \(lqauthor\(rq
+and \(lqeditor\(rq) to the appropriate marc relators.
 .TP
 \f[CR]contributor\f[R]
 Same format as \f[CR]creator\f[R].
@@ -7219,15 +7327,15 @@ Specifies the \f[CR]page\-progression\-direction\f[R] attribute for the
 .TP
 \f[CR]accessModes\f[R]
 An array of strings (schema).
-Defaults to \f[CR][\[dq]textual\[dq]]\f[R].
+Defaults to \f[CR][\(dqtextual\(dq]\f[R].
 .TP
 \f[CR]accessModeSufficient\f[R]
 An array of strings (schema).
-Defaults to \f[CR][\[dq]textual\[dq]]\f[R].
+Defaults to \f[CR][\(dqtextual\(dq]\f[R].
 .TP
 \f[CR]accessibilityHazards\f[R]
 An array of strings (schema).
-Defaults to \f[CR][\[dq]none\[dq]]\f[R].
+Defaults to \f[CR][\(dqnone\(dq]\f[R].
 .TP
 \f[CR]accessibilityFeatures\f[R]
 An array of strings (schema).
@@ -7235,10 +7343,10 @@ Defaults to
 .RS
 .IP
 .EX
-\- \[dq]alternativeText\[dq]
-\- \[dq]readingOrder\[dq]
-\- \[dq]structuralNavigation\[dq]
-\- \[dq]tableOfContents\[dq]
+\- \(dqalternativeText\(dq
+\- \(dqreadingOrder\(dq
+\- \(dqstructuralNavigation\(dq
+\- \(dqtableOfContents\(dq
 .EE
 .RE
 .TP
@@ -7248,21 +7356,21 @@ A string value.
 \f[CR]ibooks\f[R]
 iBooks\-specific metadata, with the following fields:
 .RS
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]version\f[R]: (string)
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]specified\-fonts\f[R]: \f[CR]true\f[R]|\f[CR]false\f[R] (default
 \f[CR]false\f[R])
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]ipad\-orientation\-lock\f[R]:
 \f[CR]portrait\-only\f[R]|\f[CR]landscape\-only\f[R]
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]iphone\-orientation\-lock\f[R]:
 \f[CR]portrait\-only\f[R]|\f[CR]landscape\-only\f[R]
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]binding\f[R]: \f[CR]true\f[R]|\f[CR]false\f[R] (default
 \f[CR]true\f[R])
-.IP \[bu] 2
+.IP \(bu 2
 \f[CR]scroll\-axis\f[R]:
 \f[CR]vertical\f[R]|\f[CR]horizontal\f[R]|\f[CR]default\f[R]
 .RE
@@ -7279,12 +7387,12 @@ this Markdown:
 Which will result in:
 .IP
 .EX
-
-  

+
+  

     
My chapter

 .EE
 .PP
-Pandoc will output \f[CR]\f[R],
+Pandoc will output \f[CR]\f[R],
 unless you use one of the following values, in which case either
 \f[CR]frontmatter\f[R] or \f[CR]backmatter\f[R] will be output.
 .RS -14n
@@ -7322,25 +7430,25 @@ By default, pandoc will download media referenced from any
 \f[CR]\f[R] element present in the generated EPUB, and include
 it in the EPUB container, yielding a completely self\-contained EPUB.
 If you want to link to external media resources instead, use raw HTML in
-your source and add \f[CR]data\-external=\[dq]1\[dq]\f[R] to the tag
-with the \f[CR]src\f[R] attribute.
+your source and add \f[CR]data\-external=\(dq1\(dq\f[R] to the tag with
+the \f[CR]src\f[R] attribute.
 For example:
 .IP
 .EX
-