@@ -1,5 +1,5 @@
11.\"t
2−.TH PANDOC 1 "January 30, 2019" "pandoc 2.6"
2+.TH PANDOC 1 "March 2, 2019" "pandoc 2.7"
33.SH NAME
44pandoc - general markup converter
55.SH SYNOPSIS
@@ -300,7 +300,7 @@ Specify output format.
300300\f[I]FORMAT\f[R] can be:
301301.RS
302302.IP \[bu] 2
303−\f[C]asciidoc\f[R] (AsciiDoc)
303+\f[C]asciidoc\f[R] (AsciiDoc) or \f[C]asciidoctor\f[R] (AsciiDoctor)
304304.IP \[bu] 2
305305\f[C]beamer\f[R] (LaTeX beamer slide show)
306306.IP \[bu] 2
@@ -417,38 +417,20 @@ even if a non-textual format (\f[C]docx\f[R], \f[C]odt\f[R],
417417Specify the user data directory to search for pandoc data files.
418418If this option is not specified, the default user data directory will be
419419used.
420−This is, in UNIX:
421−.RS
422−.IP
423−.nf
424−\f[C]
425−$HOME/.pandoc
426−\f[R]
427−.fi
428−.PP
429−in Windows XP:
430−.IP
431−.nf
432−\f[C]
433−C:\[rs]Documents And Settings\[rs]USERNAME\[rs]Application Data\[rs]pandoc
434−\f[R]
435−.fi
436−.PP
437−and in Windows Vista or later:
438−.IP
439−.nf
440−\f[C]
441−C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc
442−\f[R]
443−.fi
444−.PP
420+On *nix and macOS systems this will be the \f[C]pandoc\f[R] subdirectory
421+of the XDG data directory (by default, \f[C]$HOME/.local/share\f[R],
422+overridable by setting the \f[C]XDG_DATA_HOME\f[R] environment
423+variable).
424+If that directory does not exist, \f[C]$HOME/.pandoc\f[R] will be used
425+(for backwards compatibility).
426+In Windows the default user data directory is
427+\f[C]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R].
445428You can find the default user data directory on your system by looking
446429at the output of \f[C]pandoc --version\f[R].
447430A \f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
448431\f[C]templates\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R], or
449432\f[C]s5\f[R] directory placed in this directory will override
450433pandoc\[aq]s normal defaults.
451−.RE
452434.TP
453435.B \f[C]--bash-completion\f[R]
454436Generate a bash completion script.
@@ -1275,8 +1257,21 @@ EPUB-specific contents.
12751257The default is \f[C]EPUB\f[R].
12761258To put the EPUB contents in the top level, use an empty string.
12771259.TP
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].
1268+.TP
1269+.B \f[C]--pdf-engine=\f[R]\f[I]PROGRAM\f[R]
12791270Use 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
1274+\f[C]pdfroff\f[R].
12801275The default is \f[C]pdflatex\f[R].
12811276If the engine is not in your PATH, the full path of the engine may be
12821277specified here.
@@ -1284,8 +1279,9 @@ specified here.
12841279.B \f[C]--pdf-engine-opt=\f[R]\f[I]STRING\f[R]
12851280Use the given string as a command-line argument to the
12861281\f[C]pdf-engine\f[R].
1287−If used multiple times, the arguments are provided with spaces between
1288−them.
1282+For example, to use a persistent directory \f[C]foo\f[R] for
1283+\f[C]latexmk\f[R]\[aq]s auxiliary files, use
1284+\f[C]--pdf-engine-opt=-outdir=foo\f[R].
12891285Note that no check for duplicate options is done.
12901286.SS Citation rendering
12911287.TP
@@ -1500,7 +1496,7 @@ list of keywords to be included in HTML, PDF, ODT, pptx, docx and
15001496AsciiDoc metadata; repeat as for \f[C]author\f[R], above
15011497.TP
15021498.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
15041500.TP
15051501.B \f[C]description\f[R]
15061502document description, included in ODT, docx and pptx metadata.
@@ -2073,6 +2069,9 @@ $author.name$ ($author.affiliation$)
20732069\f[R]
20742070.fi
20752071.PP
2072+The value of a variable will be indented to the same level as the
2073+variable.
2074+.PP
20762075If you use custom templates, you may need to revise them as pandoc
20772076changes.
20782077We recommend tracking the changes in the default templates, and
@@ -2412,9 +2411,9 @@ This extension can be enabled/disabled for the following formats:
24122411\f[C]docx\f[R], \f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]html\f[R]
24132412.SS Extension: \f[C]styles\f[R]
24142413.PP
2415−Read all docx styles as divs (for paragraph styles) and spans (for
2416−character styles) regardless of whether pandoc understands the meaning
2417−of these styles.
2414+When converting from docx, read all docx styles as divs (for paragraph
2415+styles) and spans (for character styles) regardless of whether pandoc
2416+understands the meaning of these styles.
24182417This can be used with docx custom styles.
24192418Disabled by default.
24202419.TP
@@ -4053,7 +4052,11 @@ or \f[C]$$...$$\f[R] (for display math).
40534052It will be rendered using an interpreted text role \f[C]:math:\f[R].
40544053.TP
40554054.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.
40574060.TP
40584061.B Texinfo
40594062It 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
53135316Headers \f[I]above\f[R] the slide level in the hierarchy create
53145317\[dq]title slides,\[dq] which just contain the section title and help to
53155318break the slide show into sections.
5316−.IP \[bu] 2
5317−Content \f[I]above\f[R] the slide level will not appear in the slide
5318−show.
5319+Non-slide content under these headers will be included on the title
5320+slide (for HTML slide shows) or in a subsequent slide with the same
5321+title (for beamer).
53195322.IP \[bu] 2
53205323A title page is constructed automatically from the document\[aq]s title
53215324block, if present.
@@ -5980,6 +5983,61 @@ To disable highlighting, use the \f[C]--no-highlight\f[R] option.
59805983.SH CUSTOM STYLES
59815984.PP
59825985Custom styles can be used in the docx and ICML formats.
5986+.SS Output
5987+.PP
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.
5996+.PP
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
5999+contained elements.
6000+So, for example using the \f[C]bracketed_spans\f[R] syntax,
6001+.IP
6002+.nf
6003+\f[C]
6004+[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said.
6005+\f[R]
6006+.fi
6007+.PP
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,
6011+.IP
6012+.nf
6013+\f[C]
6014+Dickinson starts the poem simply:
6015+
6016+::: {custom-style=\[dq]Poetry\[dq]}
6017+| A Bird came down the Walk---
6018+| He did not know I saw---
6019+:::
6020+\f[R]
6021+.fi
6022+.PP
6023+would style the two contained lines with the \f[C]Poetry\f[R] paragraph
6024+style.
6025+.PP
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.
6029+.PP
6030+This feature allows for greatest customization in conjunction with
6031+pandoc filters.
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].
6038+.PP
6039+For docx output, you don\[aq]t need to enable any extensions for custom
6040+styles to work.
59836041.SS Input
59846042.PP
59856043The docx reader, by default, only reads those styles that it can convert
@@ -6034,58 +6092,6 @@ text style.
60346092With these custom styles, you can use your input document as a
60356093reference-doc while creating docx output (see below), and maintain the
60366094same styles in your input and output files.
6037−.SS Output
6038−.PP
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.
6047−.PP
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
6050−contained elements.
6051−So, for example using the \f[C]bracketed_spans\f[R] syntax,
6052−.IP
6053−.nf
6054−\f[C]
6055−[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said.
6056−\f[R]
6057−.fi
6058−.PP
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,
6062−.IP
6063−.nf
6064−\f[C]
6065−Dickinson starts the poem simply:
6066−
6067−::: {custom-style=\[dq]Poetry\[dq]}
6068−| A Bird came down the Walk---
6069−| He did not know I saw---
6070−:::
6071−\f[R]
6072−.fi
6073−.PP
6074−would style the two contained lines with the \f[C]Poetry\f[R] paragraph
6075−style.
6076−.PP
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.
6080−.PP
6081−This feature allows for greatest customization in conjunction with
6082−pandoc filters.
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].
60896095.SH CUSTOM WRITERS
60906096.PP
60916097Pandoc can be extended with custom writers written in lua.