Update date in manual and update man page.

MANUAL.txt

@@ -1,6 +1,6 @@
 % Pandoc User's Guide
 % John MacFarlane
-% November 01, 2018
+% November 25, 2018
 
 Synopsis
 ========

man/pandoc.1

@@ -1,5 +1,5 @@
 .\"t
-.TH PANDOC 1 "November 01, 2018" "pandoc 2.4"
+.TH PANDOC 1 "November 25, 2018" "pandoc 2.5"
 .SH NAME
 pandoc - general markup converter
 .SH SYNOPSIS
@@ -40,7 +40,7 @@ pandoc\[aq]s simple document model.
 While conversions from pandoc\[aq]s Markdown to all formats aspire to be
 perfect, conversions from formats more expressive than pandoc\[aq]s
 Markdown can be expected to be lossy.
-.SS Using \f[C]pandoc\f[R]
+.SS Using pandoc
 .PP
 If no \f[I]input\-files\f[R] are specified, input is read from
 \f[I]stdin\f[R].
@@ -258,6 +258,8 @@ if you need extensions not supported in \f[C]gfm\f[R].
 .IP \[bu] 2
 \f[C]mediawiki\f[R] (MediaWiki markup)
 .IP \[bu] 2
+\f[C]man\f[R] (roff man)
+.IP \[bu] 2
 \f[C]muse\f[R] (Muse)
 .IP \[bu] 2
 \f[C]native\f[R] (native Haskell)
@@ -898,9 +900,10 @@ Use \f[C]<q>\f[R] tags for quotes in HTML.
 .B \f[C]\-\-ascii\f[R]
 Use only ASCII characters in output.
 Currently supported for XML and HTML formats (which use entities instead
-of UTF\-8 when this option is selected), Markdown (which uses entities),
+of UTF\-8 when this option is selected), CommonMark, gfm, and Markdown
-roff ms (which use hexadecimal escapes), and to a limited degree LaTeX
+(which use entities), roff ms (which use hexadecimal escapes), and to a
-(which uses standard commands for accented characters when possible).
+limited degree LaTeX (which uses standard commands for accented
+characters when possible).
 roff man output uses ASCII by default.
 .TP
 .B \f[C]\-\-reference\-links\f[R]
@@ -1955,7 +1958,8 @@ This extension can be enabled/disabled for the following formats:
 .B enabled by default in
 \f[C]markdown\f[R], \f[C]muse\f[R]
 .PP
-The algorithm used to derive the identifier from the header text is:
+The default algorithm used to derive the identifier from the header text
+is:
 .IP \[bu] 2
 Remove all formatting, links, etc.
 .IP \[bu] 2
@@ -2017,6 +2021,9 @@ the first will get an identifier as described above; the second will get
 the same identifier with \f[C]\-1\f[R] appended; the third with
 \f[C]\-2\f[R]; and so on.
 .PP
+(However, a different algorithm is used if
+\f[C]gfm_auto_identifiers\f[R] is enabled; see below.)
+.PP
 These identifiers are used to provide link targets in the table of
 contents generated by the \f[C]\-\-toc|\-\-table\-of\-contents\f[R]
 option.
@@ -2047,6 +2054,13 @@ Causes the identifiers produced by \f[C]auto_identifiers\f[R] to be pure
 ASCII.
 Accents are stripped off of accented Latin letters, and non\-Latin
 letters are omitted.
+.SS Extension: \f[C]gfm_auto_identifiers\f[R]
+.PP
+Changes the algorithm used by \f[C]auto_identifiers\f[R] to conform to
+GitHub\[aq]s method.
+Spaces are converted to dashes (\f[C]\-\f[R]), uppercase characters to
+lowercase characters, and punctuation characters other than \f[C]\-\f[R]
+and \f[C]_\f[R] are removed.
 .SS Math Input
 .PP
 The extensions \f[C]tex_math_dollars\f[R],
@@ -4025,7 +4039,7 @@ The raw attribute cannot be combined with regular attributes.
 .SS LaTeX macros
 .SS Extension: \f[C]latex_macros\f[R]
 .PP
-For output formats other than LaTeX, pandoc will parse LaTeX macro
+When this extension is enabled, pandoc will parse LaTeX macro
 definitions and apply the resulting macros to all LaTeX math and raw
 LaTeX.
 So, 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],
 \f[C]\[sc]\f[R]/\f[C]\[sc]\[sc]\f[R].
 If no locator term is used, \[dq]page\[dq] is assumed.
 .PP
+\f[C]pandoc\-citeproc\f[R] will use heuristics to distinguish the
+locator from the suffix.
+In complex cases, the locator can be enclosed in curly braces (using
+\f[C]pandoc\-citeproc\f[R] 0.15 and higher only):
+.IP
+.nf
+\f[C]
+[\[at]smith{ii, A, D\-Z}, with a suffix]
+[\[at]smith, {pp. iv, vi\-xi, (xv)\-(xvii)} with suffix here]
+\f[R]
+.fi
+.PP
 A minus sign (\f[C]\-\f[R]) before the \f[C]\[at]\f[R] will suppress
 mention of the author in the citation.
 This 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:
 \f[R]
 .fi
 .PP
-If the style calls for a list of works cited, it will be placed at the
+If the style calls for a list of works cited, it will be placed in a div
-end of the document.
+with id \f[C]refs\f[R], if one exists:
-Normally, you will want to end your document with an appropriate header:
+.IP
+.nf
+\f[C]
+::: #refs
+:::
+\f[R]
+.fi
+.PP
+Otherwise, it will be placed at the end of the document.
+Generation of the bibliography can be suppressed by setting
+\f[C]suppress\-bibliography: true\f[R] in the YAML metadata.
+.PP
+If you wish the bibliography to have a section header, you can set
+\f[C]reference\-section\-title\f[R] in the metadata, or put the header
+at the beginning of the div with id \f[C]refs\f[R] (if you are using it)
+or at the end of your document:
 .IP
 .nf
 \f[C]
@@ -4888,7 +4929,7 @@ variants are supported:
 .TP
 .B \f[C]markdown_github\f[R] (deprecated GitHub\-Flavored Markdown)
 \f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]fenced_code_blocks\f[R],
-\f[C]gfm_auto_identifiers\f[R], \f[C]ascii_identifiers\f[R],
+\f[C]auto_identifiers\f[R], \f[C]gfm_auto_identifiers\f[R],
 \f[C]backtick_code_blocks\f[R], \f[C]autolink_bare_uris\f[R],
 \f[C]space_in_atx_header\f[R], \f[C]intraword_underscores\f[R],
 \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.
 .TP
 .B \f[C]gfm\f[R] (GitHub\-Flavored Markdown)
 \f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]fenced_code_blocks\f[R],
-\f[C]gfm_auto_identifiers\f[R], \f[C]ascii_identifiers\f[R],
+\f[C]auto_identifiers\f[R], \f[C]gfm_auto_identifiers\f[R],
 \f[C]backtick_code_blocks\f[R], \f[C]autolink_bare_uris\f[R],
-\f[C]intraword_underscores\f[R], \f[C]strikeout\f[R],
+\f[C]space_in_atx_header\f[R], \f[C]intraword_underscores\f[R],
-\f[C]hard_line_breaks\f[R], \f[C]emoji\f[R],
+\f[C]strikeout\f[R], \f[C]emoji\f[R],
-\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R].
+\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R],
+\f[C]lists_without_preceding_blankline\f[R].
 .SH PRODUCING SLIDE SHOWS WITH PANDOC
 .PP
 You can use pandoc to produce an HTML + JavaScript slide presentation
@@ -5732,6 +5774,39 @@ needs, do
 pandoc \-\-print\-default\-data\-file sample.lua
 \f[R]
 .fi
+.SH A NOTE ON SECURITY
+.PP
+If you use pandoc to convert user\-contributed content in a web
+application, here are some things to keep in mind:
+.IP "1." 3
+Although pandoc itself will not create or modify any files other than
+those you explicitly ask it create (with the exception of temporary
+files used in producing PDFs), a filter or custom writer could in
+principle do anything on your file system.
+Please audit filters and custom writers very carefully before using
+them.
+.IP "2." 3
+If your application uses pandoc as a Haskell library (rather than
+shelling out to the executable), it is possible to use it in a mode that
+fully isolates pandoc from your file system, by running the pandoc
+operations in the \f[C]PandocPure\f[R] monad.
+See the document Using the pandoc API for more details.
+.IP "3." 3
+Pandoc\[aq]s parsers can exhibit pathological performance on some corner
+cases.
+It is wise to put any pandoc operations under a timeout, to avoid DOS
+attacks that exploit these issues.
+If you are using the pandoc executable, you can add the command line
+options \f[C]+RTS \-M512M \-RTS\f[R] (for example) to limit the heap
+size to 512MB.
+.IP "4." 3
+The HTML generated by pandoc is not guaranteed to be safe.
+If \f[C]raw_html\f[R] is enabled for the Markdown input, users can
+inject arbitrary HTML.
+Even if \f[C]raw_html\f[R] is disabled, users can include dangerous
+content in attributes for headers, spans, and code blocks.
+To be safe, you should run all the generated HTML through an HTML
+sanitizer.
 .SH AUTHORS
 .PP
 Copyright 2006\-2017 John MacFarlane (jgm\[at]berkeley.edu).