diff options
| -rw-r--r-- | MANUAL.txt | 2 | ||||
| -rw-r--r-- | man/pandoc.1 | 105 |
2 files changed, 91 insertions, 16 deletions
diff --git a/MANUAL.txt b/MANUAL.txt index 9f4289a21..dca629159 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -1,6 +1,6 @@ % Pandoc User's Guide % John MacFarlane -% November 01, 2018 +% November 25, 2018 Synopsis ======== diff --git a/man/pandoc.1 b/man/pandoc.1 index 8073e0efb..82311212f 100644 --- a/man/pandoc.1 +++ b/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), -roff ms (which use hexadecimal escapes), and to a limited degree LaTeX -(which uses standard commands for accented characters when possible). +of UTF\-8 when this option is selected), CommonMark, gfm, and Markdown +(which use entities), roff ms (which use hexadecimal escapes), and to a +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 -end of the document. -Normally, you will want to end your document with an appropriate header: +If the style calls for a list of works cited, it will be placed in a div +with id \f[C]refs\f[R], if one exists: +.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]hard_line_breaks\f[R], \f[C]emoji\f[R], -\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\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], +\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). |