@@ -1,5 +1,5 @@
2−.TH PANDOC 1 "January 30, 2019" "pandoc 2.6"
2+.TH PANDOC 1 "March 2, 2019" "pandoc 2.7"
4pandoc - general markup converter
4pandoc - general markup converter
5.SH SYNOPSIS
5.SH SYNOPSIS
@@ -300,7 +300,7 @@ Specify output format.
300\f[I]FORMAT\f[R] can be:
300\f[I]FORMAT\f[R] can be:
302.IP \[bu] 2
302.IP \[bu] 2
303−\f[C]asciidoc\f[R] (AsciiDoc)
303+\f[C]asciidoc\f[R] (AsciiDoc) or \f[C]asciidoctor\f[R] (AsciiDoctor)
304.IP \[bu] 2
304.IP \[bu] 2
305\f[C]beamer\f[R] (LaTeX beamer slide show)
305\f[C]beamer\f[R] (LaTeX beamer slide show)
306.IP \[bu] 2
306.IP \[bu] 2
@@ -417,38 +417,20 @@ even if a non-textual format (\f[C]docx\f[R], \f[C]odt\f[R],
417Specify the user data directory to search for pandoc data files.
417Specify the user data directory to search for pandoc data files.
418If this option is not specified, the default user data directory will be
418If this option is not specified, the default user data directory will be
420−This is, in UNIX:
420+On *nix and macOS systems this will be the \f[C]pandoc\f[R] subdirectory
421−.RS
421+of the XDG data directory (by default, \f[C]$HOME/.local/share\f[R],
422−.IP
422+overridable by setting the \f[C]XDG_DATA_HOME\f[R] environment
424−\f[C]
424+If that directory does not exist, \f[C]$HOME/.pandoc\f[R] will be used
425−$HOME/.pandoc
425+(for backwards compatibility).
426−\f[R]
426+In Windows the default user data directory is
433−C:\[rs]Documents And Settings\[rs]USERNAME\[rs]Application Data\[rs]pandoc
437−and in Windows Vista or later:
441−C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc
427+\f[C]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R].
445You can find the default user data directory on your system by looking
428You can find the default user data directory on your system by looking
446at the output of \f[C]pandoc --version\f[R].
429at the output of \f[C]pandoc --version\f[R].
447A \f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
430A \f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
448\f[C]templates\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R], or
431\f[C]templates\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R], or
449\f[C]s5\f[R] directory placed in this directory will override
432\f[C]s5\f[R] directory placed in this directory will override
450pandoc\[aq]s normal defaults.
433pandoc\[aq]s normal defaults.
453.B \f[C]--bash-completion\f[R]
435.B \f[C]--bash-completion\f[R]
454Generate a bash completion script.
436Generate a bash completion script.
@@ -1275,8 +1257,21 @@ EPUB-specific contents.
1275The default is \f[C]EPUB\f[R].
1257The default is \f[C]EPUB\f[R].
1276To put the EPUB contents in the top level, use an empty string.
1258To put the EPUB contents in the top level, use an empty string.
1278−.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]
1260+.B \f[C]--ipynb-output=all|none|best\f[R]
1261+Determines how ipynb output cells are treated.
1262+\f[C]all\f[R] means that all of the data formats included in the
1263+original are preserved.
1264+\f[C]none\f[R] means that the contents of data cells are omitted.
1265+\f[C]best\f[R] causes pandoc to try to pick the richest data block in
1266+each output cell that is compatible with the output format.
1267+The default is \f[C]best\f[R].
1269+.B \f[C]--pdf-engine=\f[R]\f[I]PROGRAM\f[R]
1279Use the specified engine when producing PDF output.
1270Use the specified engine when producing PDF output.
1271+Valid values are \f[C]pdflatex\f[R], \f[C]lualatex\f[R],
1272+\f[C]xelatex\f[R], \f[C]latexmk\f[R], \f[C]wkhtmltopdf\f[R],
1273+\f[C]weasyprint\f[R], \f[C]prince\f[R], \f[C]context\f[R], and
1280The default is \f[C]pdflatex\f[R].
1275The default is \f[C]pdflatex\f[R].
1281If the engine is not in your PATH, the full path of the engine may be
1276If the engine is not in your PATH, the full path of the engine may be
1282specified here.
1277specified here.
@@ -1284,8 +1279,9 @@ specified here.
1284.B \f[C]--pdf-engine-opt=\f[R]\f[I]STRING\f[R]
1279.B \f[C]--pdf-engine-opt=\f[R]\f[I]STRING\f[R]
1285Use the given string as a command-line argument to the
1280Use the given string as a command-line argument to the
1286\f[C]pdf-engine\f[R].
1281\f[C]pdf-engine\f[R].
1287−If used multiple times, the arguments are provided with spaces between
1282+For example, to use a persistent directory \f[C]foo\f[R] for
1288−them.
1283+\f[C]latexmk\f[R]\[aq]s auxiliary files, use
1284+\f[C]--pdf-engine-opt=-outdir=foo\f[R].
1289Note that no check for duplicate options is done.
1285Note that no check for duplicate options is done.
1290.SS Citation rendering
1286.SS Citation rendering
@@ -1500,7 +1496,7 @@ list of keywords to be included in HTML, PDF, ODT, pptx, docx and
1500AsciiDoc metadata; repeat as for \f[C]author\f[R], above
1496AsciiDoc metadata; repeat as for \f[C]author\f[R], above
1502.B \f[C]subject\f[R]
1498.B \f[C]subject\f[R]
1503−document subject, included in ODT, docx and pptx metadata
1499+document subject, included in ODT, PDF, docx and pptx metadata
1505.B \f[C]description\f[R]
1501.B \f[C]description\f[R]
1506document description, included in ODT, docx and pptx metadata.
1502document description, included in ODT, docx and pptx metadata.
@@ -2073,6 +2069,9 @@ $author.name$ ($author.affiliation$)
2072+The value of a variable will be indented to the same level as the
2076If you use custom templates, you may need to revise them as pandoc
2075If you use custom templates, you may need to revise them as pandoc
2078We recommend tracking the changes in the default templates, and
2077We recommend tracking the changes in the default templates, and
@@ -2412,9 +2411,9 @@ This extension can be enabled/disabled for the following formats:
2412\f[C]docx\f[R], \f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]html\f[R]
2411\f[C]docx\f[R], \f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]html\f[R]
2413.SS Extension: \f[C]styles\f[R]
2412.SS Extension: \f[C]styles\f[R]
2415−Read all docx styles as divs (for paragraph styles) and spans (for
2414+When converting from docx, read all docx styles as divs (for paragraph
2416−character styles) regardless of whether pandoc understands the meaning
2415+styles) and spans (for character styles) regardless of whether pandoc
2417−of these styles.
2416+understands the meaning of these styles.
2418This can be used with docx custom styles.
2417This can be used with docx custom styles.
2419Disabled by default.
2418Disabled by default.
@@ -4053,7 +4052,11 @@ or \f[C]$$...$$\f[R] (for display math).
4053It will be rendered using an interpreted text role \f[C]:math:\f[R].
4052It will be rendered using an interpreted text role \f[C]:math:\f[R].
4055.B AsciiDoc
4054.B AsciiDoc
4056−It will be rendered as \f[C]latexmath:[...]\f[R].
4055+For AsciiDoc output format (\f[C]-t asciidoc\f[R]) it will appear
4056+verbatim surrounded by \f[C]latexmath:[$...$]\f[R] (for inline math) or
4057+\f[C][latexmath]++++\[rs][...\[rs]]+++\f[R] (for display math).
4058+For AsciiDoctor output format (\f[C]-t asciidoctor\f[R]) the LaTex
4059+delimiters (\f[C]$..$\f[R] and \f[C]\[rs][..\[rs]]\f[R]) are omitted.
4058.B Texinfo
4061.B Texinfo
4059It will be rendered inside a \f[C]\[at]math\f[R] command.
4062It 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
5313Headers \f[I]above\f[R] the slide level in the hierarchy create
5316Headers \f[I]above\f[R] the slide level in the hierarchy create
5314\[dq]title slides,\[dq] which just contain the section title and help to
5317\[dq]title slides,\[dq] which just contain the section title and help to
5315break the slide show into sections.
5318break the slide show into sections.
5316−.IP \[bu] 2
5319+Non-slide content under these headers will be included on the title
5317−Content \f[I]above\f[R] the slide level will not appear in the slide
5320+slide (for HTML slide shows) or in a subsequent slide with the same
5318−show.
5321+title (for beamer).
5319.IP \[bu] 2
5322.IP \[bu] 2
5320A title page is constructed automatically from the document\[aq]s title
5323A title page is constructed automatically from the document\[aq]s title
5321block, if present.
5324block, if present.
@@ -5980,6 +5983,61 @@ To disable highlighting, use the \f[C]--no-highlight\f[R] option.
5980.SH CUSTOM STYLES
5983.SH CUSTOM STYLES
5982Custom styles can be used in the docx and ICML formats.
5985Custom styles can be used in the docx and ICML formats.
5988+By default, pandoc\[aq]s docx and ICML output applies a predefined set
5989+of styles for blocks such as paragraphs and block quotes, and uses
5990+largely default formatting (italics, bold) for inlines.
5991+This will work for most purposes, especially alongside a
5992+\f[C]reference.docx\f[R] file.
5993+However, if you need to apply your own styles to blocks, or match a
5994+preexisting set of styles, pandoc allows you to define custom styles for
5995+blocks and text using \f[C]div\f[R]s and \f[C]span\f[R]s, respectively.
5997+If you define a \f[C]div\f[R] or \f[C]span\f[R] with the attribute
5998+\f[C]custom-style\f[R], pandoc will apply your specified style to the
6000+So, for example using the \f[C]bracketed_spans\f[R] syntax,
6004+[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said.
6008+would produce a docx file with \[dq]Get out\[dq] styled with character
6009+style \f[C]Emphatically\f[R].
6010+Similarly, using the \f[C]fenced_divs\f[R] syntax,
6014+Dickinson starts the poem simply:
6016+::: {custom-style=\[dq]Poetry\[dq]}
6017+| A Bird came down the Walk---
6018+| He did not know I saw---
6023+would style the two contained lines with the \f[C]Poetry\f[R] paragraph
6026+For docx output, styles will be defined in the output file as inheriting
6027+from normal text, if the styles are not yet in your reference.docx.
6028+If they are already defined, pandoc will not alter the definition.
6030+This feature allows for greatest customization in conjunction with
6032+If you want all paragraphs after block quotes to be indented, you can
6033+write a filter to apply the styles necessary.
6034+If you want all italics to be transformed to the \f[C]Emphasis\f[R]
6035+character style (perhaps to change their color), you can write a filter
6036+which will transform all italicized inlines to inlines within an
6037+\f[C]Emphasis\f[R] custom-style \f[C]span\f[R].
6039+For docx output, you don\[aq]t need to enable any extensions for custom
5983.SS Input
6041.SS Input
5985The docx reader, by default, only reads those styles that it can convert
6043The docx reader, by default, only reads those styles that it can convert
@@ -6034,58 +6092,6 @@ text style.
6034With these custom styles, you can use your input document as a
6092With these custom styles, you can use your input document as a
6035reference-doc while creating docx output (see below), and maintain the
6093reference-doc while creating docx output (see below), and maintain the
6036same styles in your input and output files.
6094same styles in your input and output files.
6039−By default, pandoc\[aq]s docx and ICML output applies a predefined set
6040−of styles for blocks such as paragraphs and block quotes, and uses
6041−largely default formatting (italics, bold) for inlines.
6042−This will work for most purposes, especially alongside a
6043−\f[C]reference.docx\f[R] file.
6044−However, if you need to apply your own styles to blocks, or match a
6045−preexisting set of styles, pandoc allows you to define custom styles for
6046−blocks and text using \f[C]div\f[R]s and \f[C]span\f[R]s, respectively.
6048−If you define a \f[C]div\f[R] or \f[C]span\f[R] with the attribute
6049−\f[C]custom-style\f[R], pandoc will apply your specified style to the
6051−So, for example using the \f[C]bracketed_spans\f[R] syntax,
6055−[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said.
6059−would produce a docx file with \[dq]Get out\[dq] styled with character
6060−style \f[C]Emphatically\f[R].
6061−Similarly, using the \f[C]fenced_divs\f[R] syntax,
6065−Dickinson starts the poem simply:
6067−::: {custom-style=\[dq]Poetry\[dq]}
6068−| A Bird came down the Walk---
6069−| He did not know I saw---
6074−would style the two contained lines with the \f[C]Poetry\f[R] paragraph
6077−For docx output, styles will be defined in the output file as inheriting
6078−from normal text, if the styles are not yet in your reference.docx.
6079−If they are already defined, pandoc will not alter the definition.
6081−This feature allows for greatest customization in conjunction with
6083−If you want all paragraphs after block quotes to be indented, you can
6084−write a filter to apply the styles necessary.
6085−If you want all italics to be transformed to the \f[C]Emphasis\f[R]
6086−character style (perhaps to change their color), you can write a filter
6087−which will transform all italicized inlines to inlines within an
6088−\f[C]Emphasis\f[R] custom-style \f[C]span\f[R].
6089.SH CUSTOM WRITERS
6095.SH CUSTOM WRITERS
6091Pandoc can be extended with custom writers written in lua.
6097Pandoc can be extended with custom writers written in lua.