diff options
| -rw-r--r-- | MANUAL.txt | 2 | ||||
| -rw-r--r-- | pandoc-cli/man/pandoc-lua.1 | 4 | ||||
| -rw-r--r-- | pandoc-cli/man/pandoc-server.1 | 4 | ||||
| -rw-r--r-- | pandoc-cli/man/pandoc.1 | 131 |
4 files changed, 93 insertions, 48 deletions
diff --git a/MANUAL.txt b/MANUAL.txt index dec217801..48a048320 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -1,7 +1,7 @@ --- title: Pandoc User's Guide author: John MacFarlane -date: April 7, 2024 +date: May 11, 2024 --- # Synopsis diff --git a/pandoc-cli/man/pandoc-lua.1 b/pandoc-cli/man/pandoc-lua.1 index 02bfbeba1..88c087320 100644 --- a/pandoc-cli/man/pandoc-lua.1 +++ b/pandoc-cli/man/pandoc-lua.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.1.13 +.\" Automatically generated by Pandoc 3.2 .\" -.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.1.13" "Pandoc User\[cq]s Guide" +.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.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]]] diff --git a/pandoc-cli/man/pandoc-server.1 b/pandoc-cli/man/pandoc-server.1 index c2f82f1c7..242de0ed7 100644 --- a/pandoc-cli/man/pandoc-server.1 +++ b/pandoc-cli/man/pandoc-server.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.1.13 +.\" Automatically generated by Pandoc 3.2 .\" -.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.1.13" "Pandoc User\[cq]s Guide" +.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.2" "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 9ed75ec6a..d175ac9bb 100644 --- a/pandoc-cli/man/pandoc.1 +++ b/pandoc-cli/man/pandoc.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.1.13 +.\" Automatically generated by Pandoc 3.2 .\" -.TH "pandoc" "1" "April 7, 2024" "pandoc 3.1.13" "Pandoc User\[cq]s Guide" +.TH "pandoc" "1" "May 11, 2024" "pandoc 3.2" "Pandoc User\[cq]s Guide" .SH NAME pandoc - general markup converter .SH SYNOPSIS @@ -151,15 +151,18 @@ included with all recent versions of TeX Live): \f[CR]amsfonts\f[R], \f[CR]amsmath\f[R], \f[CR]lm\f[R], \f[CR]unicode\-math\f[R], \f[CR]iftex\f[R], \f[CR]listings\f[R] (if the \f[CR]\-\-listings\f[R] option is used), \f[CR]fancyvrb\f[R], \f[CR]longtable\f[R], -\f[CR]booktabs\f[R], \f[CR]graphicx\f[R] (if the document contains -images), \f[CR]bookmark\f[R], \f[CR]xcolor\f[R], \f[CR]soul\f[R], -\f[CR]geometry\f[R] (with the \f[CR]geometry\f[R] variable set), -\f[CR]setspace\f[R] (with \f[CR]linestretch\f[R]), and \f[CR]babel\f[R] -(with \f[CR]lang\f[R]). +\f[CR]booktabs\f[R], [\f[CR]multirow\f[R]] (if the document contains a +table with cells that cross multiple rows), \f[CR]graphicx\f[R] (if the +document contains images), \f[CR]bookmark\f[R], \f[CR]xcolor\f[R], +\f[CR]soul\f[R], \f[CR]geometry\f[R] (with the \f[CR]geometry\f[R] +variable set), \f[CR]setspace\f[R] (with \f[CR]linestretch\f[R]), and +\f[CR]babel\f[R] (with \f[CR]lang\f[R]). If \f[CR]CJKmainfont\f[R] is set, \f[CR]xeCJK\f[R] is needed. +\f[CR]framed\f[R] is required if code is highlighted in a scheme that +use a colored background. The use of \f[CR]xelatex\f[R] or \f[CR]lualatex\f[R] as the PDF engine requires \f[CR]fontspec\f[R]. -\f[CR]lualatex\f[R] uses \f[CR]selnolig\f[R]. +\f[CR]lualatex\f[R] uses \f[CR]selnolig\f[R] and \f[CR]lua\-ul\f[R]. \f[CR]xelatex\f[R] uses \f[CR]bidi\f[R] (with the \f[CR]dir\f[R] variable set). If the \f[CR]mathspec\f[R] variable is set, \f[CR]xelatex\f[R] will use @@ -265,7 +268,7 @@ if you need extensions not supported in \f[CR]gfm\f[R]. .IP \[bu] 2 \f[CR]native\f[R] (native Haskell) .IP \[bu] 2 -\f[CR]odt\f[R] (ODT) +\f[CR]odt\f[R] (OpenOffice text document) .IP \[bu] 2 \f[CR]opml\f[R] (OPML) .IP \[bu] 2 @@ -564,7 +567,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\[en]for example, +Specify classes to use for indented code blocks\[em]for example, \f[CR]perl,numberLines\f[R] or \f[CR]haskell\f[R]. Multiple classes may be separated by spaces or commas. .TP @@ -590,10 +593,6 @@ disambiguate them, and internal links will be adjusted accordingly. For example, a header with identifier \f[CR]foo\f[R] in \f[CR]subdir/file1.txt\f[R] will have its identifier changed to \f[CR]subdir__file1.txt__foo\f[R]. -.PP -In addition, a Div with an identifier based on the filename will be -added around the file\[cq]s content, so that internal links to the -filename will point to this Div\[cq]s identifier. .RE .TP \f[CR]\-F\f[R] \f[I]PROGRAM\f[R], \f[CR]\-\-filter=\f[R]\f[I]PROGRAM\f[R] @@ -1112,8 +1111,8 @@ The default is for lists to be displayed all at once. .TP \f[CR]\-\-slide\-level=\f[R]\f[I]NUMBER\f[R] Specifies that headings with the specified level create slides (for -\f[CR]beamer\f[R], \f[CR]s5\f[R], \f[CR]slidy\f[R], \f[CR]slideous\f[R], -\f[CR]dzslides\f[R]). +\f[CR]beamer\f[R], \f[CR]revealjs\f[R], \f[CR]pptx\f[R], \f[CR]s5\f[R], +\f[CR]slidy\f[R], \f[CR]slideous\f[R], \f[CR]dzslides\f[R]). Headings above this level in the hierarchy are used to divide the slide show into sections; headings below this level create subheads within a slide. @@ -2188,9 +2187,26 @@ delimiters) and ends with \f[CR]endif\f[R] (enclosed in matched delimiters). It may optionally contain an \f[CR]else\f[R] (enclosed in matched delimiters). -The \f[CR]if\f[R] section is used if \f[CR]variable\f[R] has a -non\-empty value, otherwise the \f[CR]else\f[R] section is used (if -present). +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 +any map +.IP \[bu] 2 +any array containing at least one true value +.IP \[bu] 2 +any nonempty string +.IP \[bu] 2 +boolean True +.PP +Note that in YAML metadata (and metadata specified on the command line +using \f[CR]\-M/\-\-metadata\f[R]), unquoted \f[CR]true\f[R] and +\f[CR]false\f[R] will be interpreted as Boolean values. +But a variable specified on the command line using +\f[CR]\-V/\-\-variable\f[R] will always be given a string value. +Hence a conditional \f[CR]if(foo)\f[R] will be triggered if you use +\f[CR]\-V foo=false\f[R], but not if you use \f[CR]\-M foo=false\f[R]. +.PP Examples: .IP .EX @@ -2745,6 +2761,9 @@ options for LaTeX beamer themes (a list). .TP \f[CR]titlegraphic\f[R] image for title slide +.TP +\f[CR]titlegraphicoptions\f[R] +options for title slide image .SS Variables for PowerPoint These variables control the visual aspects of a slide show that are not easily controlled via templates. @@ -2859,6 +2878,10 @@ option or \f[CR]numbersections\f[R] variable) .TP \f[CR]beamerarticle\f[R] produce an article from Beamer slides +.TP +\f[CR]handout\f[R] +produce a handout version of Beamer slides (with overlays condensed into +single slides) .SS Fonts .TP \f[CR]fontenc\f[R] @@ -3251,7 +3274,9 @@ specified .TP \f[CR]toc\-title\f[R] title of table of contents (works only with EPUB, HTML, revealjs, -opendocument, odt, docx, pptx, beamer, LaTeX) +opendocument, odt, docx, pptx, beamer, LaTeX). +Note that in docx and pptx a custom \f[CR]toc\-title\f[R] will be picked +up from metadata, but cannot be set as a variable. .SH EXTENSIONS The behavior of some of the readers and writers can be adjusted by enabling or disabling various extensions. @@ -3654,6 +3679,9 @@ easy to read: A Markdown\-formatted document should be publishable as\-is, as plain text, without looking like it\[cq]s been marked up with tags or formatting instructions. +.PD 0 +.P +.PD \[en] John Gruber .RE .PP @@ -4343,12 +4371,28 @@ As (\[at]good) illustrates, ... The label can be any string of alphanumeric characters, underscores, or hyphens. .PP -Note: continuation paragraphs in example lists must always be indented -four spaces, regardless of the length of the list marker. +Continuation paragraphs in example lists must always be indented four +spaces, regardless of the length of the list marker. That is, example lists always behave as if the \f[CR]four_space_rule\f[R] extension is set. This is because example labels tend to be long, and indenting content to the first non\-space character after the label would be awkward. +.PP +You can repeat an earlier numbered example by re\-using its label: +.IP +.EX +(\[at]foo) Sample sentence. + +Intervening text... + +This theory can explain the case we saw earlier (repeated): + +(\[at]foo) Sample sentence. +.EE +.PP +This only works reliably, though, if the repeated item is in a list by +itself, because each numbered example list will be numbered continuously +from its starting number. .SS Ending a list What if you want to put an indented code block after a list? .IP @@ -4732,9 +4776,9 @@ All three metadata fields may contain standard inline formatting .PP 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 -\[en] this is the title that will appear at the top of the window in a -browser \[en] and once at the beginning of the document body. +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. 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 @@ -6493,16 +6537,16 @@ 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 -\f[CR]zh\-u\-co\-pinyin\f[R] \[en] Chinese with the Pinyin collation. +\f[CR]zh\-u\-co\-pinyin\f[R]: Chinese with the Pinyin collation. .IP \[bu] 2 -\f[CR]es\-u\-co\-trad\f[R] \[en] Spanish with the traditional collation -(with \f[CR]Ch\f[R] sorting after \f[CR]C\f[R]). +\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] \[en] French with \[lq]backwards\[rq] accent -sorting (with \f[CR]coté\f[R] sorting after \f[CR]côte\f[R]). +\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 -\f[CR]en\-US\-u\-kf\-upper\f[R] \[en] English with uppercase letters -sorting before lower (default is lower before upper). +\f[CR]en\-US\-u\-kf\-upper\f[R]: English with uppercase letters sorting +before lower (default is lower before upper). .RE .TP \f[CR]notes\-after\-punctuation\f[R] @@ -7421,13 +7465,13 @@ definitions. .PP To disable highlighting, use the \f[CR]\-\-no\-highlight\f[R] option. .SH CUSTOM STYLES -Custom styles can be used in the docx and ICML formats. +Custom styles can be used in the docx, odt and ICML formats. .SS Output -By default, pandoc\[cq]s docx and ICML output applies a predefined set -of styles for blocks such as paragraphs and block quotes, and uses +By default, pandoc\[cq]s odt, docx and ICML output applies a predefined +set of styles for blocks such as paragraphs and block quotes, and uses largely default formatting (italics, bold) for inlines. -This will work for most purposes, especially alongside a -\f[CR]reference.docx\f[R] file. +This will work for most purposes, especially alongside a reference doc +file. However, if you need to apply your own styles to blocks, or match a preexisting set of styles, pandoc allows you to define custom styles for blocks and text using \f[CR]div\f[R]s and \f[CR]span\f[R]s, @@ -7443,8 +7487,8 @@ So, for example, using the \f[CR]bracketed_spans\f[R] syntax, [Get out]{custom\-style=\[dq]Emphatically\[dq]}, he said. .EE .PP -would produce a docx file with \[lq]Get out\[rq] styled with character -style \f[CR]Emphatically\f[R]. +would produce a file with \[lq]Get out\[rq] styled with character style +\f[CR]Emphatically\f[R]. Similarly, using the \f[CR]fenced_divs\f[R] syntax, .IP .EX @@ -7459,8 +7503,9 @@ Dickinson starts the poem simply: would style the two contained lines with the \f[CR]Poetry\f[R] paragraph style. .PP -For docx output, styles will be defined in the output file as inheriting -from normal text, if the styles are not yet in your reference.docx. +Styles will be defined in the output file as inheriting from normal text +(docx) or Default Paragraph Style (odt), if the styles are not yet in +your reference doc. If they are already defined, pandoc will not alter the definition. .PP This feature allows for greatest customization in conjunction with @@ -7472,8 +7517,8 @@ character style (perhaps to change their color), you can write a filter which will transform all italicized inlines to inlines within an \f[CR]Emphasis\f[R] custom\-style \f[CR]span\f[R]. .PP -For docx output, you don\[cq]t need to enable any extensions for custom -styles to work. +For docx or odt output, you don\[cq]t need to enable any extensions for +custom styles to work. .SS Input The docx reader, by default, only reads those styles that it can convert into pandoc elements, either by direct conversion or interpreting the |