From 9a511660ab8222e8c6e5d5f08d119514436e6a79 Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Sun, 3 Mar 2019 09:46:21 -0800 Subject: Update manual date, man page, README.md. --- MANUAL.txt | 2 +- README.md | 3 +- man/pandoc.1 | 188 ++++++++++++++++++++++++++++++----------------------------- 3 files changed, 100 insertions(+), 93 deletions(-) diff --git a/MANUAL.txt b/MANUAL.txt index 50ca91300..89280e0e0 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -1,6 +1,6 @@ % Pandoc User's Guide % John MacFarlane -% January 30, 2019 +% March 2, 2019 Synopsis ======== diff --git a/README.md b/README.md index 652315110..bd6b620ff 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,8 @@ It can convert *to*
- - `asciidoc` ([AsciiDoc](http://www.methods.co.nz/asciidoc/)) or `asciidoctor` ([AsciiDoctor](https://asciidoctor.org/)) + - `asciidoc` ([AsciiDoc](http://www.methods.co.nz/asciidoc/)) or + `asciidoctor` ([AsciiDoctor](https://asciidoctor.org/)) - `beamer` ([LaTeX beamer](https://ctan.org/pkg/beamer) slide show) - `commonmark` ([CommonMark](http://commonmark.org) Markdown) - `context` ([ConTeXt](http://www.contextgarden.net/)) diff --git a/man/pandoc.1 b/man/pandoc.1 index d1a17b187..515d12098 100644 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -1,5 +1,5 @@ .\"t -.TH PANDOC 1 "January 30, 2019" "pandoc 2.6" +.TH PANDOC 1 "March 2, 2019" "pandoc 2.7" .SH NAME pandoc - general markup converter .SH SYNOPSIS @@ -300,7 +300,7 @@ Specify output format. \f[I]FORMAT\f[R] can be: .RS .IP \[bu] 2 -\f[C]asciidoc\f[R] (AsciiDoc) +\f[C]asciidoc\f[R] (AsciiDoc) or \f[C]asciidoctor\f[R] (AsciiDoctor) .IP \[bu] 2 \f[C]beamer\f[R] (LaTeX beamer slide show) .IP \[bu] 2 @@ -417,38 +417,20 @@ even if a non-textual format (\f[C]docx\f[R], \f[C]odt\f[R], Specify the user data directory to search for pandoc data files. If this option is not specified, the default user data directory will be used. -This is, in UNIX: -.RS -.IP -.nf -\f[C] -$HOME/.pandoc -\f[R] -.fi -.PP -in Windows XP: -.IP -.nf -\f[C] -C:\[rs]Documents And Settings\[rs]USERNAME\[rs]Application Data\[rs]pandoc -\f[R] -.fi -.PP -and in Windows Vista or later: -.IP -.nf -\f[C] -C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc -\f[R] -.fi -.PP +On *nix and macOS systems this will be the \f[C]pandoc\f[R] subdirectory +of the XDG data directory (by default, \f[C]$HOME/.local/share\f[R], +overridable by setting the \f[C]XDG_DATA_HOME\f[R] environment +variable). +If that directory does not exist, \f[C]$HOME/.pandoc\f[R] will be used +(for backwards compatibility). +In Windows the default user data directory is +\f[C]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R]. You can find the default user data directory on your system by looking at the output of \f[C]pandoc --version\f[R]. A \f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R], \f[C]templates\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R], or \f[C]s5\f[R] directory placed in this directory will override pandoc\[aq]s normal defaults. -.RE .TP .B \f[C]--bash-completion\f[R] Generate a bash completion script. @@ -1275,8 +1257,21 @@ EPUB-specific contents. The default is \f[C]EPUB\f[R]. To put the EPUB contents in the top level, use an empty string. .TP -.B \f[C]--pdf-engine=pdflatex\f[R]|\f[C]lualatex\f[R]|\f[C]xelatex\f[R]|\f[C]wkhtmltopdf\f[R]|\f[C]weasyprint\f[R]|\f[C]prince\f[R]|\f[C]context\f[R]|\f[C]pdfroff\f[R] +.B \f[C]--ipynb-output=all|none|best\f[R] +Determines how ipynb output cells are treated. +\f[C]all\f[R] means that all of the data formats included in the +original are preserved. +\f[C]none\f[R] means that the contents of data cells are omitted. +\f[C]best\f[R] causes pandoc to try to pick the richest data block in +each output cell that is compatible with the output format. +The default is \f[C]best\f[R]. +.TP +.B \f[C]--pdf-engine=\f[R]\f[I]PROGRAM\f[R] Use the specified engine when producing PDF output. +Valid values are \f[C]pdflatex\f[R], \f[C]lualatex\f[R], +\f[C]xelatex\f[R], \f[C]latexmk\f[R], \f[C]wkhtmltopdf\f[R], +\f[C]weasyprint\f[R], \f[C]prince\f[R], \f[C]context\f[R], and +\f[C]pdfroff\f[R]. The default is \f[C]pdflatex\f[R]. If the engine is not in your PATH, the full path of the engine may be specified here. @@ -1284,8 +1279,9 @@ specified here. .B \f[C]--pdf-engine-opt=\f[R]\f[I]STRING\f[R] Use the given string as a command-line argument to the \f[C]pdf-engine\f[R]. -If used multiple times, the arguments are provided with spaces between -them. +For example, to use a persistent directory \f[C]foo\f[R] for +\f[C]latexmk\f[R]\[aq]s auxiliary files, use +\f[C]--pdf-engine-opt=-outdir=foo\f[R]. Note that no check for duplicate options is done. .SS Citation rendering .TP @@ -1500,7 +1496,7 @@ list of keywords to be included in HTML, PDF, ODT, pptx, docx and AsciiDoc metadata; repeat as for \f[C]author\f[R], above .TP .B \f[C]subject\f[R] -document subject, included in ODT, docx and pptx metadata +document subject, included in ODT, PDF, docx and pptx metadata .TP .B \f[C]description\f[R] document description, included in ODT, docx and pptx metadata. @@ -2073,6 +2069,9 @@ $author.name$ ($author.affiliation$) \f[R] .fi .PP +The value of a variable will be indented to the same level as the +variable. +.PP If you use custom templates, you may need to revise them as pandoc changes. We recommend tracking the changes in the default templates, and @@ -2412,9 +2411,9 @@ This extension can be enabled/disabled for the following formats: \f[C]docx\f[R], \f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]html\f[R] .SS Extension: \f[C]styles\f[R] .PP -Read all docx styles as divs (for paragraph styles) and spans (for -character styles) regardless of whether pandoc understands the meaning -of these 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. Disabled by default. .TP @@ -4053,7 +4052,11 @@ or \f[C]$$...$$\f[R] (for display math). It will be rendered using an interpreted text role \f[C]:math:\f[R]. .TP .B AsciiDoc -It will be rendered as \f[C]latexmath:[...]\f[R]. +For AsciiDoc output format (\f[C]-t asciidoc\f[R]) it will appear +verbatim surrounded by \f[C]latexmath:[$...$]\f[R] (for inline math) or +\f[C][latexmath]++++\[rs][...\[rs]]+++\f[R] (for display math). +For AsciiDoctor output format (\f[C]-t asciidoctor\f[R]) the LaTex +delimiters (\f[C]$..$\f[R] and \f[C]\[rs][..\[rs]]\f[R]) are omitted. .TP .B Texinfo It will be rendered inside a \f[C]\[at]math\f[R] command. @@ -5313,9 +5316,9 @@ Headers \f[I]below\f[R] the slide level in the hierarchy create headers Headers \f[I]above\f[R] the slide level in the hierarchy create \[dq]title slides,\[dq] which just contain the section title and help to break the slide show into sections. -.IP \[bu] 2 -Content \f[I]above\f[R] the slide level will not appear in the slide -show. +Non-slide content under these headers 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\[aq]s title block, if present. @@ -5980,6 +5983,61 @@ To disable highlighting, use the \f[C]--no-highlight\f[R] option. .SH CUSTOM STYLES .PP Custom styles can be used in the docx and ICML formats. +.SS Output +.PP +By default, pandoc\[aq]s 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[C]reference.docx\f[R] 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[C]div\f[R]s and \f[C]span\f[R]s, respectively. +.PP +If you define a \f[C]div\f[R] or \f[C]span\f[R] with the attribute +\f[C]custom-style\f[R], pandoc will apply your specified style to the +contained elements. +So, for example using the \f[C]bracketed_spans\f[R] syntax, +.IP +.nf +\f[C] +[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said. +\f[R] +.fi +.PP +would produce a docx file with \[dq]Get out\[dq] styled with character +style \f[C]Emphatically\f[R]. +Similarly, using the \f[C]fenced_divs\f[R] syntax, +.IP +.nf +\f[C] +Dickinson starts the poem simply: + +::: {custom-style=\[dq]Poetry\[dq]} +| A Bird came down the Walk--- +| He did not know I saw--- +::: +\f[R] +.fi +.PP +would style the two contained lines with the \f[C]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. +If they are already defined, pandoc will not alter the definition. +.PP +This feature allows for greatest customization in conjunction with +pandoc filters. +If you want all paragraphs after block quotes to be indented, you can +write a filter to apply the styles necessary. +If you want all italics to be transformed to the \f[C]Emphasis\f[R] +character style (perhaps to change their color), you can write a filter +which will transform all italicized inlines to inlines within an +\f[C]Emphasis\f[R] custom-style \f[C]span\f[R]. +.PP +For docx output, you don\[aq]t need to enable any extensions for custom +styles to work. .SS Input .PP The docx reader, by default, only reads those styles that it can convert @@ -6034,58 +6092,6 @@ text style. With these custom styles, you can use your input document as a reference-doc while creating docx output (see below), and maintain the same styles in your input and output files. -.SS Output -.PP -By default, pandoc\[aq]s 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[C]reference.docx\f[R] 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[C]div\f[R]s and \f[C]span\f[R]s, respectively. -.PP -If you define a \f[C]div\f[R] or \f[C]span\f[R] with the attribute -\f[C]custom-style\f[R], pandoc will apply your specified style to the -contained elements. -So, for example using the \f[C]bracketed_spans\f[R] syntax, -.IP -.nf -\f[C] -[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said. -\f[R] -.fi -.PP -would produce a docx file with \[dq]Get out\[dq] styled with character -style \f[C]Emphatically\f[R]. -Similarly, using the \f[C]fenced_divs\f[R] syntax, -.IP -.nf -\f[C] -Dickinson starts the poem simply: - -::: {custom-style=\[dq]Poetry\[dq]} -| A Bird came down the Walk--- -| He did not know I saw--- -::: -\f[R] -.fi -.PP -would style the two contained lines with the \f[C]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. -If they are already defined, pandoc will not alter the definition. -.PP -This feature allows for greatest customization in conjunction with -pandoc filters. -If you want all paragraphs after block quotes to be indented, you can -write a filter to apply the styles necessary. -If you want all italics to be transformed to the \f[C]Emphasis\f[R] -character style (perhaps to change their color), you can write a filter -which will transform all italicized inlines to inlines within an -\f[C]Emphasis\f[R] custom-style \f[C]span\f[R]. .SH CUSTOM WRITERS .PP Pandoc can be extended with custom writers written in lua. -- cgit v1.2.3