@@ -1,5 +1,5 @@
11.\"t
2−.TH PANDOC 1 "November 01, 2018" "pandoc 2.4"
2+.TH PANDOC 1 "November 25, 2018" "pandoc 2.5"
33.SH NAME
44pandoc - general markup converter
55.SH SYNOPSIS
@@ -40,7 +40,7 @@ pandoc\[aq]s simple document model.
4040While conversions from pandoc\[aq]s Markdown to all formats aspire to be
4141perfect, conversions from formats more expressive than pandoc\[aq]s
4242Markdown can be expected to be lossy.
43−.SS Using \f[C]pandoc\f[R]
43+.SS Using pandoc
4444.PP
4545If no \f[I]input\-files\f[R] are specified, input is read from
4646\f[I]stdin\f[R].
@@ -258,6 +258,8 @@ if you need extensions not supported in \f[C]gfm\f[R].
258258.IP \[bu] 2
259259\f[C]mediawiki\f[R] (MediaWiki markup)
260260.IP \[bu] 2
261+\f[C]man\f[R] (roff man)
262+.IP \[bu] 2
261263\f[C]muse\f[R] (Muse)
262264.IP \[bu] 2
263265\f[C]native\f[R] (native Haskell)
@@ -898,9 +900,10 @@ Use \f[C]<q>\f[R] tags for quotes in HTML.
898900.B \f[C]\-\-ascii\f[R]
899901Use only ASCII characters in output.
900902Currently supported for XML and HTML formats (which use entities instead
901−of UTF\-8 when this option is selected), Markdown (which uses entities),
902−roff ms (which use hexadecimal escapes), and to a limited degree LaTeX
903−(which uses standard commands for accented characters when possible).
903+of UTF\-8 when this option is selected), CommonMark, gfm, and Markdown
904+(which use entities), roff ms (which use hexadecimal escapes), and to a
905+limited degree LaTeX (which uses standard commands for accented
906+characters when possible).
904907roff man output uses ASCII by default.
905908.TP
906909.B \f[C]\-\-reference\-links\f[R]
@@ -1955,7 +1958,8 @@ This extension can be enabled/disabled for the following formats:
19551958.B enabled by default in
19561959\f[C]markdown\f[R], \f[C]muse\f[R]
19571960.PP
1958−The algorithm used to derive the identifier from the header text is:
1961+The default algorithm used to derive the identifier from the header text
1962+is:
19591963.IP \[bu] 2
19601964Remove all formatting, links, etc.
19611965.IP \[bu] 2
@@ -2017,6 +2021,9 @@ the first will get an identifier as described above; the second will get
20172021the same identifier with \f[C]\-1\f[R] appended; the third with
20182022\f[C]\-2\f[R]; and so on.
20192023.PP
2024+(However, a different algorithm is used if
2025+\f[C]gfm_auto_identifiers\f[R] is enabled; see below.)
2026+.PP
20202027These identifiers are used to provide link targets in the table of
20212028contents generated by the \f[C]\-\-toc|\-\-table\-of\-contents\f[R]
20222029option.
@@ -2047,6 +2054,13 @@ Causes the identifiers produced by \f[C]auto_identifiers\f[R] to be pure
20472054ASCII.
20482055Accents are stripped off of accented Latin letters, and non\-Latin
20492056letters are omitted.
2057+.SS Extension: \f[C]gfm_auto_identifiers\f[R]
2058+.PP
2059+Changes the algorithm used by \f[C]auto_identifiers\f[R] to conform to
2060+GitHub\[aq]s method.
2061+Spaces are converted to dashes (\f[C]\-\f[R]), uppercase characters to
2062+lowercase characters, and punctuation characters other than \f[C]\-\f[R]
2063+and \f[C]_\f[R] are removed.
20502064.SS Math Input
20512065.PP
20522066The extensions \f[C]tex_math_dollars\f[R],
@@ -4025,7 +4039,7 @@ The raw attribute cannot be combined with regular attributes.
40254039.SS LaTeX macros
40264040.SS Extension: \f[C]latex_macros\f[R]
40274041.PP
4028−For output formats other than LaTeX, pandoc will parse LaTeX macro
4042+When this extension is enabled, pandoc will parse LaTeX macro
40294043definitions and apply the resulting macros to all LaTeX math and raw
40304044LaTeX.
40314045So, for example, the following will work in all output formats, not just
@@ -4650,6 +4664,18 @@ singular or plural forms, as \f[C]book\f[R],
46504664\f[C]\[sc]\f[R]/\f[C]\[sc]\[sc]\f[R].
46514665If no locator term is used, \[dq]page\[dq] is assumed.
46524666.PP
4667+\f[C]pandoc\-citeproc\f[R] will use heuristics to distinguish the
4668+locator from the suffix.
4669+In complex cases, the locator can be enclosed in curly braces (using
4670+\f[C]pandoc\-citeproc\f[R] 0.15 and higher only):
4671+.IP
4672+.nf
4673+\f[C]
4674+[\[at]smith{ii, A, D\-Z}, with a suffix]
4675+[\[at]smith, {pp. iv, vi\-xi, (xv)\-(xvii)} with suffix here]
4676+\f[R]
4677+.fi
4678+.PP
46534679A minus sign (\f[C]\-\f[R]) before the \f[C]\[at]\f[R] will suppress
46544680mention of the author in the citation.
46554681This can be useful when the author is already mentioned in the text:
@@ -4670,9 +4696,24 @@ You can also write an in\-text citation, as follows:
46704696\f[R]
46714697.fi
46724698.PP
4673−If the style calls for a list of works cited, it will be placed at the
4674−end of the document.
4675−Normally, you will want to end your document with an appropriate header:
4699+If the style calls for a list of works cited, it will be placed in a div
4700+with id \f[C]refs\f[R], if one exists:
4701+.IP
4702+.nf
4703+\f[C]
4704+::: #refs
4705+:::
4706+\f[R]
4707+.fi
4708+.PP
4709+Otherwise, it will be placed at the end of the document.
4710+Generation of the bibliography can be suppressed by setting
4711+\f[C]suppress\-bibliography: true\f[R] in the YAML metadata.
4712+.PP
4713+If you wish the bibliography to have a section header, you can set
4714+\f[C]reference\-section\-title\f[R] in the metadata, or put the header
4715+at the beginning of the div with id \f[C]refs\f[R] (if you are using it)
4716+or at the end of your document:
46764717.IP
46774718.nf
46784719\f[C]
@@ -4888,7 +4929,7 @@ variants are supported:
48884929.TP
48894930.B \f[C]markdown_github\f[R] (deprecated GitHub\-Flavored Markdown)
48904931\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]fenced_code_blocks\f[R],
4891−\f[C]gfm_auto_identifiers\f[R], \f[C]ascii_identifiers\f[R],
4932+\f[C]auto_identifiers\f[R], \f[C]gfm_auto_identifiers\f[R],
48924933\f[C]backtick_code_blocks\f[R], \f[C]autolink_bare_uris\f[R],
48934934\f[C]space_in_atx_header\f[R], \f[C]intraword_underscores\f[R],
48944935\f[C]strikeout\f[R], \f[C]emoji\f[R],
@@ -4924,11 +4965,12 @@ Also, \f[C]raw_tex\f[R] only affects \f[C]gfm\f[R] output, not input.
49244965.TP
49254966.B \f[C]gfm\f[R] (GitHub\-Flavored Markdown)
49264967\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]fenced_code_blocks\f[R],
4927−\f[C]gfm_auto_identifiers\f[R], \f[C]ascii_identifiers\f[R],
4968+\f[C]auto_identifiers\f[R], \f[C]gfm_auto_identifiers\f[R],
49284969\f[C]backtick_code_blocks\f[R], \f[C]autolink_bare_uris\f[R],
4929−\f[C]intraword_underscores\f[R], \f[C]strikeout\f[R],
4930−\f[C]hard_line_breaks\f[R], \f[C]emoji\f[R],
4931−\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R].
4970+\f[C]space_in_atx_header\f[R], \f[C]intraword_underscores\f[R],
4971+\f[C]strikeout\f[R], \f[C]emoji\f[R],
4972+\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R],
4973+\f[C]lists_without_preceding_blankline\f[R].
49324974.SH PRODUCING SLIDE SHOWS WITH PANDOC
49334975.PP
49344976You can use pandoc to produce an HTML + JavaScript slide presentation
@@ -5732,6 +5774,39 @@ needs, do
57325774pandoc \-\-print\-default\-data\-file sample.lua
57335775\f[R]
57345776.fi
5777+.SH A NOTE ON SECURITY
5778+.PP
5779+If you use pandoc to convert user\-contributed content in a web
5780+application, here are some things to keep in mind:
5781+.IP "1." 3
5782+Although pandoc itself will not create or modify any files other than
5783+those you explicitly ask it create (with the exception of temporary
5784+files used in producing PDFs), a filter or custom writer could in
5785+principle do anything on your file system.
5786+Please audit filters and custom writers very carefully before using
5787+them.
5788+.IP "2." 3
5789+If your application uses pandoc as a Haskell library (rather than
5790+shelling out to the executable), it is possible to use it in a mode that
5791+fully isolates pandoc from your file system, by running the pandoc
5792+operations in the \f[C]PandocPure\f[R] monad.
5793+See the document Using the pandoc API for more details.
5794+.IP "3." 3
5795+Pandoc\[aq]s parsers can exhibit pathological performance on some corner
5796+cases.
5797+It is wise to put any pandoc operations under a timeout, to avoid DOS
5798+attacks that exploit these issues.
5799+If you are using the pandoc executable, you can add the command line
5800+options \f[C]+RTS \-M512M \-RTS\f[R] (for example) to limit the heap
5801+size to 512MB.
5802+.IP "4." 3
5803+The HTML generated by pandoc is not guaranteed to be safe.
5804+If \f[C]raw_html\f[R] is enabled for the Markdown input, users can
5805+inject arbitrary HTML.
5806+Even if \f[C]raw_html\f[R] is disabled, users can include dangerous
5807+content in attributes for headers, spans, and code blocks.
5808+To be safe, you should run all the generated HTML through an HTML
5809+sanitizer.
57355810.SH AUTHORS
57365811.PP
57375812Copyright 2006\-2017 John MacFarlane (jgm\[at]berkeley.edu).