From d7abe701a224d9fe4c4bbda9364517ae1dfc6b2f Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Mon, 29 Sep 2025 12:38:20 +0200 Subject: Update an pages and manual date. --- pandoc-cli/man/pandoc-lua.1 | 4 +- pandoc-cli/man/pandoc-server.1 | 4 +- pandoc-cli/man/pandoc.1 | 114 +++++++++++++++++++++++++++++++++++++++-- 3 files changed, 115 insertions(+), 7 deletions(-) (limited to 'pandoc-cli') diff --git a/pandoc-cli/man/pandoc-lua.1 b/pandoc-cli/man/pandoc-lua.1 index a5bdaf764..fbc74d42b 100644 --- a/pandoc-cli/man/pandoc-lua.1 +++ b/pandoc-cli/man/pandoc-lua.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.8 +.\" Automatically generated by Pandoc 3.8.1 .\" -.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.8" "Pandoc User\[cq]s Guide" +.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.8.1" "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]]] diff --git a/pandoc-cli/man/pandoc-server.1 b/pandoc-cli/man/pandoc-server.1 index 7a0d5e2c7..5ebd5f7fc 100644 --- a/pandoc-cli/man/pandoc-server.1 +++ b/pandoc-cli/man/pandoc-server.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.8 +.\" Automatically generated by Pandoc 3.8.1 .\" -.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.8" "Pandoc User\[cq]s Guide" +.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.8.1" "Pandoc User\[cq]s Guide" .SH SYNOPSIS \f[CR]pandoc\-server\f[R] [\f[I]options\f[R]] .SH DESCRIPTION diff --git a/pandoc-cli/man/pandoc.1 b/pandoc-cli/man/pandoc.1 index 7d2153ed6..1b0a647b5 100644 --- a/pandoc-cli/man/pandoc.1 +++ b/pandoc-cli/man/pandoc.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.8 +.\" Automatically generated by Pandoc 3.8.1 .\" -.TH "pandoc" "1" "2025\-09\-06" "pandoc 3.8" "Pandoc User\[cq]s Guide" +.TH "pandoc" "1" "2025\-09\-29" "pandoc 3.8.1" "Pandoc User\[cq]s Guide" .SH NAME pandoc - general markup converter .SH SYNOPSIS @@ -442,6 +442,8 @@ markup) .IP \(bu 2 \f[CR]typst\f[R] (typst) .IP \(bu 2 +\f[CR]vimdoc\f[R] (Vimdoc) +.IP \(bu 2 \f[CR]xml\f[R] (XML version of native AST) .IP \(bu 2 \f[CR]xwiki\f[R] (XWiki markup) @@ -3004,6 +3006,11 @@ geometry: .EE .RE .TP +\f[CR]shorthands\f[R] +Enable language\-specific shorthands when loading \f[CR]babel\f[R]. +(By default, pandoc includes \f[CR]shorthands=off\f[R] when loading +\f[CR]babel\f[R], disabling language\-specific shorthands.) +.TP \f[CR]hyperrefoptions\f[R] option for \f[CR]hyperref\f[R] package, e.g.\ \f[CR]linktoc=all\f[R]; repeat for multiple options: @@ -7670,12 +7677,113 @@ For example, \f[CR]\-\-wrap=preserve\f[R] will preserve soft line breaks in Markdown cells; \f[CR]\-\-markdown\-headings=setext\f[R] will cause Setext\-style headings to be used; and \f[CR]\-\-preserve\-tabs\f[R] will prevent tabs from being turned to spaces. +.SH VIMDOC +Vimdoc writer generates Vim help files and makes use of the following +metadata variables: +.IP +.EX +abstract\f[B]:\f[R] \(dqA short description\(dq +author\f[B]:\f[R] Author +title\f[B]:\f[R] Title + +\f[I]# Vimdoc\-specific\f[R] +filename\f[B]:\f[R] \(dqdefinition\-lists.txt\(dq +vimdoc\-prefix\f[B]:\f[R] pandoc +.EE +.PP +Complete header requires \f[CR]abstract\f[R], \f[CR]author\f[R], +\f[CR]title\f[R] and \f[CR]filename\f[R] to be set. +Compiling file with such metadata produces the following file (assumes +\f[CR]\-\-standalone\f[R], see Templates): +.IP +.EX +*definition\-lists.txt* A short description + + Title by Author + + + Type |gO| to see the table of contents. + +[...] + + vim:tw=72:sw=4:ts=4:ft=help:norl:et: +.EE +.PP +If \f[CR]vimdoc\-prefix\f[R] is set, all non\-command tags are prefixed +with its value, it is used to prevent tag collision: all headers have a +tag (either inferred or explicit) and multiple help pages can have the +same header names, therefore collision is to be expected. +Let our input be the following markdown file: +.IP +.EX +## Header + +\f[BI]\(ga:[range]Fnl {expr}\(ga\f[R]{#:Fnl} +: Evaluates {expr} or range + +\f[BI]\(gavim.b\(ga\f[R]{#vim.b} +: Buffer\-scoped (\f[BI]\(ga:h b:\(ga\f[R]) variables for the current buffer. Invalid or unset + key returns \f[BI]\(ganil\(ga\f[R]. Can be indexed with an integer to access variables for a + specific buffer. + +\f[I][\f[R]Span\f[I]]\f[R]{#span} +: generic inline container for phrasing content, which does not inherently + represent anything. +.EE +.PP +Convert it to vimdoc: +.IP +.EX +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +Header *header* + +:[range]Fnl {expr} *:Fnl* + Evaluates {expr} or range +\(gavim.b\(ga *vim.b* + Buffer\-scoped (|b:|) variables for the current buffer. Invalid or + unset key returns \(ganil\(ga. Can be indexed with an integer to access + variables for a specific buffer. +Span *span* + generic inline container for phrasing content, which does not + inherently represent anything. +.EE +.PP +Convert it to vimdoc with metadata variable set (e.g.\ with +\f[CR]\-M vimdoc\-prefix=pandoc\f[R]) +.IP +.EX +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +Header *pandoc\-header* + +:[range]Fnl {expr} *:Fnl* + Evaluates {expr} or range +\(gavim.b\(ga *pandoc\-vim.b* + Buffer\-scoped (|b:|) variables for the current buffer. Invalid or + unset key returns \(ganil\(ga. Can be indexed with an integer to access + variables for a specific buffer. +Span *pandoc\-span* + generic inline container for phrasing content, which does not + inherently represent anything. +.EE +.PP +\f[CR]vim.b\f[R] and \f[CR]Span\f[R] got their prefixes but not +\f[CR]:Fnl\f[R] because ex\-commands (those starting with \f[CR]:\f[R]) +don\(cqt get a prefix, since they are considered unique across help +pages. +.PP +In both cases \f[CR]:help b:\f[R] became reference \f[CR]|b:|\f[R] (also +works with \f[CR]:h b:\f[R]). +Links pointing to either https://vimhelp.org/ or +https://neovim.io/doc/user become references too. +.PP +Vim traditionally wraps at 78, but Pandoc defaults to 72. +Use \f[CR]\-\-columns 78\f[R] to match Vim. .SH SYNTAX HIGHLIGHTING Pandoc will automatically highlight syntax in fenced code blocks that are marked with a language name. The Haskell library skylighting is used for highlighting. Currently highlighting is supported only for HTML, EPUB, Docx, Ms, Man, -and LaTeX/PDF output. +Typst, and LaTeX/PDF output. To see a list of language names that pandoc will recognize, type \f[CR]pandoc \-\-list\-highlight\-languages\f[R]. .PP -- cgit v1.2.3