From 5ca99f2cea6e3ced61066b16328d6fe4e1871780 Mon Sep 17 00:00:00 2001
From: John MacFarlane <jgm@berkeley.edu>
Date: Sun, 7 Jan 2018 21:27:30 -0800
Subject: [PATCH] Update changelog and man page.
---
AUTHORS.md | 1 +
MANUAL.txt | 2 +-
changelog | 160 +++++++++++++++++++++++++-
man/pandoc.1 | 309 ++++++++++++++++++++++++++-------------------------
4 files changed, 316 insertions(+), 156 deletions(-)
diff --git a/AUTHORS.md b/AUTHORS.md
index 16c2a3e8a..db500d555 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -147,6 +147,7 @@
- RyanGlScott
- Sascha Wilde
- Scott Morrison
+- Sebastian Talmon
- Sergei Trofimovich
- Sergey Astanin
- Shahbaz Youssefi
diff --git a/MANUAL.txt b/MANUAL.txt
index f7932df8c..8904f0dc5 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -1,6 +1,6 @@
% Pandoc User's Guide
% John MacFarlane
-% December 27, 2017
+% January 7, 2018
Synopsis
========
diff --git a/changelog b/changelog
index 39de8534b..eba1335d5 100644
--- a/changelog
+++ b/changelog
@@ -1,15 +1,165 @@
pandoc (2.1)
- * Text.Pandoc.App: Filter changes (#4196). Previously we ran all lua
- filters before JSON filters. Now we run filters in the order they are
- presented on the command line, whether lua or JSON. There are two
- incompatible API changes: The type of `applyFilters` has changed, and
- `applyLuaFilters` has been removed. `Filter` is also now exported.
+ * Allow filters and lua filters to be interspersed (#4196). Previously
+ we ran all lua filters before JSON filters. Now we run filters in
+ the order they are presented on the command line, whether lua or JSON.
+ There are two incompatible API changes: The type of `applyFilters`
+ has changed, and `applyLuaFilters` has been removed. `Filter` is
+ also now exported.
+
+ * Use latest skylighting and omit the `missingIncludes` check, fixing
+ a major performance regression in earlier releases of the 2.x series
+ (#4226). Behavior change: If you use a custom syntax definition that
+ refers to a syntax you haven't loaded, pandoc will now complain when
+ it is highlighting the text, rather than doing a check at the start.
+ This change dramatically speeds up invocations of pandoc on short
+ inputs.
* Text.Pandoc.Class: make `FileTree` opaque (don't export
`FileTree` constructor). This forces users to interact with it using
`insertInFileTree` and `getFileInfo`, which normalize file names.
+ * Markdown reader:
+
+ + Rewrite `inlinesInBalancedBrackets`. The rewrite is much more
+ direct, avoiding `parseFromString`. And it performs significantly
+ better; unfortunately, parsing time still increases exponentially
+ (see #1735).
+ + Avoid parsing raw tex unless `\` + letter seen. This seems to
+ help with the performance problem, #4216.
+
+ * LaTeX reader: Simplified a check for raw tex command.
+
+ * Muse reader (Alexander Krotov):
+
+ + Enable round trip test (#4107).
+ + Automatically translate `#cover` into `#cover-image`.
+ Amusewiki uses #cover directive to specify cover image.
+
+ * Docx reader (Jesse Rosenthal):
+
+ + Allow for insertion/deletion of paragraphs (#3927).
+ If the paragraph has a deleted or inserted paragraph break (depending
+ on the track-changes setting) we hold onto it until the next
+ paragraph. This takes care of accept and reject. For this we introduce
+ a new state which holds the ils from the previous para if necessary.
+ For `--track-changes=all`, we add an empty span with class
+ `paragraph-insertion`/`paragraph-deletion` at the end of the paragraph
+ prior to the break to be inserted or deleted.
+ + Remove unused anchors (#3679). Docx produces a lot of anchors with
+ nothing pointing to them---we now remove these to produce cleaner
+ output. Note that this has to occur at the end of the process
+ because it has to follow link/anchor rewriting.
+ + Read multiple children of `w:sdtContents`.
+ + Combine adjacent anchors. There isn't any reason to have numerous
+ anchors in the same place, since we can't maintain docx's
+ non-nesting overlapping. So we reduce to a single anchor.
+ + Improved tests.
+
+ * Muse writer (Alexander Krotov): don't escape URIs from AST
+
+ * Docx writer:
+
+ + Removed redundant subtitle in title (Sebastian Talmon).
+ + `firstRow` table definition compatibility for Word 2016 (Sebastian
+ Talmon). Word 2016 seems to use a default value of "1" for table
+ headers, if there is no firstRow definition (although a default
+ value of 0 is documented), so all tables get the first Row formatted
+ as header. Setting the parameter to 0 if the table has no header
+ row fixes this for Word 2016
+ + Fix custom styles with spaces in the name (#3290).
+
+ * Powerpoint writer (Jesse Rosenthal):
+
+ + Ignore Notes div for parity with other slide outputs.
+ + Set default slidelevel correctly. We had previously defaulted to
+ slideLevel 2. Now we use the correct behavior of defaulting to the
+ highest level header followed by content. We change an expected test
+ result to match this behavior.
+ + Split blocks correctly for linked images.
+ + Combine adjacent runs.
+ + Make inline code inherit code size. Previously (a) the code size
+ wasn't set when we force size, and (b) the properties was set from
+ the default, instead of inheriting.
+ + Simplify `replaceNamedChildren` function.
+ + Allow linked images. The following markdown:
+ `[](http://www.example.com)`
+ will now produce a linked image in the resulting PowerPoint file.
+ + Fix error with empty table cell. We require an empty `<a:p>` tag,
+ even if the cell contains no paragraphs---otherwise PowerPoint
+ complains of corruption.
+ + Implement two-column slides. This uses the columns/column div
+ format described in the pandoc manual. At the moment, only two
+ columns (half the screen each) are allowed. Custom widths are not
+ supported.
+ + Added more tests.
+
+ * Lua filters (Albert Krewinkel):
+
+ + `data/pandoc.lua`: drop 'pandoc-api-version' from Pandoc objects
+ + The current pandoc-types version is made available to Lua programs in
+ the global `PANDOC_API_VERSION`. It contains the version as a list of
+ numbers.
+ + The pandoc version available as a global `PANDOC_VERSION` (a list
+ of numbers).
+ + `data/pandoc.lua`: make `Attr` an `AstElement`.
+ + `data/pandoc.lua`: make all types subtypes of `AstElement`.
+ `Pandoc`, `Meta`, and `Citation` were just plain functions and did
+ not set a metatable on the returned value, which made it difficult
+ to amend objects of these types with new behavior. They are now
+ subtypes of AstElement, meaning that all their objects can gain
+ new features when a method is added to the behavior object
+ (e.g., `pandoc.Pandoc.behavior`).
+ + `data/pandoc.lua`: split type and behavior tables. Clearly distinguish
+ between a type and the behavioral properties of an instance of that
+ type. The behavior of a type (and all its subtypes) can now be
+ amended by adding methods to that types `behavior` object, without
+ exposing the type objects internals. E.g.:
+ ```lua
+ pandoc.Inline.behavior.frob = function () print'42' end
+ local str = pandoc.Str'hello'
+ str.frob() -- outputs '42'
+ ```
+ + `data/pandoc.lua`: fix Element inheritance. Extending all elements
+ of a given type (e.g., all inline elements) was difficult, as the
+ table used to lookup unknown methods would be reset every time a
+ new element of that type was created, preventing recursive property
+ lookup. This is was changed in that all methods and attributes of
+ supertypes are now available to their subtypes.
+ + `data/pandoc.lua`: fix attribute names of Citation (#4222). The
+ fields were named like the Haskell fields, not like the documented,
+ shorter version. The names are changed to match the documentation
+ and Citations are given a shared metatable to enable simple
+ extensibility.
+ + `data/pandoc.lua`: drop function `pandoc.global_filter`.
+ + Bump `hslua` version to 0.9.5. This version fixes a bug that made it
+ difficult to handle failures while getting lists or a Map from Lua.
+ A bug in pandoc, which made it necessary to always pass a tag when
+ using MetaList or MetaBlock, is fixed as a result. Using the pandoc
+ module's constructor functions for these values is now optional
+ (if still recommended).
+ + Stop exporting `pushPandocModule` (API change). The introduction
+ of `runPandocLua` renders direct use of this function obsolete.
+ + Update generation of module docs for lua filters.
+ + `Lua.Module.Utils`: make stringify work on `MetaValues` (John
+ MacFarlane). I'm sure this was intended in the first place,
+ but currently only `Meta` is supported.
+
+ * Improve benchmarks.
+
+ + Set the default extensions properly.
+ + Improve benchmark argument parsing. You can now say
+ `make bench BENCHARGS="markdown latex reader"` and both the
+ markdown and latex readers will be benchmarked.
+
+ * MANUAL.txt simplify and add more structure (Mauro Bieg).
+
+ * Generate README.md from template and MANUAL.txt.
+ `make README.md` will generate the README.md after changes
+ to MANUAL.txt have been made.
+
+ * Update copyright notices to include 2018 (Albert Krewinkel).
+
pandoc (2.0.6)
* Added `jats` as an input format.
diff --git a/man/pandoc.1 b/man/pandoc.1
index bd6a85002..8e3c9ffef 100644
--- a/man/pandoc.1
+++ b/man/pandoc.1
@@ -1,5 +1,5 @@
.\"t
-.TH PANDOC 1 "December 27, 2017" "pandoc 2.1"
+.TH PANDOC 1 "January 7, 2018" "pandoc 2.1"
.SH NAME
pandoc - general markup converter
.SH SYNOPSIS
@@ -9,38 +9,39 @@ pandoc - general markup converter
.PP
Pandoc is a Haskell library for converting from one markup format to
another, and a command\-line tool that uses this library.
-It can read Markdown, CommonMark, PHP Markdown Extra, GitHub\-Flavored
-Markdown, MultiMarkdown, and (subsets of) Textile, reStructuredText,
-HTML, LaTeX, MediaWiki markup, TWiki markup, TikiWiki markup, Creole
-1.0, Haddock markup, OPML, Emacs Org mode, DocBook, JATS, Muse,
-txt2tags, Vimwiki, EPUB, ODT, and Word docx; and it can write plain
-text, Markdown, CommonMark, PHP Markdown Extra, GitHub\-Flavored
-Markdown, MultiMarkdown, reStructuredText, XHTML, HTML5, LaTeX
-(including \f[C]beamer\f[] slide shows), ConTeXt, RTF, OPML, DocBook,
-JATS, OpenDocument, ODT, Word docx, GNU Texinfo, MediaWiki markup,
-DokuWiki markup, ZimWiki markup, Haddock markup, EPUB (v2 or v3),
-FictionBook2, Textile, groff man, groff ms, Emacs Org mode, AsciiDoc,
-InDesign ICML, TEI Simple, Muse, PowerPoint slide shows and Slidy,
-Slideous, DZSlides, reveal.js or S5 HTML slide shows.
+.PP
+Pandoc can read Markdown, CommonMark, PHP Markdown Extra,
+GitHub\-Flavored Markdown, MultiMarkdown, and (subsets of) Textile,
+reStructuredText, HTML, LaTeX, MediaWiki markup, TWiki markup, TikiWiki
+markup, Creole 1.0, Haddock markup, OPML, Emacs Org mode, DocBook, JATS,
+Muse, txt2tags, Vimwiki, EPUB, ODT, and Word docx.
+.PP
+Pandoc can write plain text, Markdown, CommonMark, PHP Markdown Extra,
+GitHub\-Flavored Markdown, MultiMarkdown, reStructuredText, XHTML,
+HTML5, LaTeX (including \f[C]beamer\f[] slide shows), ConTeXt, RTF,
+OPML, DocBook, JATS, OpenDocument, ODT, Word docx, GNU Texinfo,
+MediaWiki markup, DokuWiki markup, ZimWiki markup, Haddock markup, EPUB
+(v2 or v3), FictionBook2, Textile, groff man, groff ms, Emacs Org mode,
+AsciiDoc, InDesign ICML, TEI Simple, Muse, PowerPoint slide shows and
+Slidy, Slideous, DZSlides, reveal.js or S5 HTML slide shows.
It can also produce PDF output on systems where LaTeX, ConTeXt,
\f[C]pdfroff\f[], \f[C]wkhtmltopdf\f[], \f[C]prince\f[], or
\f[C]weasyprint\f[] is installed.
.PP
-Pandoc\[aq]s enhanced version of Markdown includes syntax for footnotes,
-tables, flexible ordered lists, definition lists, fenced code blocks,
-superscripts and subscripts, strikeout, metadata blocks, automatic
-tables of contents, embedded LaTeX math, citations, and Markdown inside
-HTML block elements.
-(These enhancements, described further under Pandoc\[aq]s Markdown, can
-be disabled using the \f[C]markdown_strict\f[] input or output format.)
+Pandoc\[aq]s enhanced version of Markdown includes syntax for tables,
+definition lists, metadata blocks, \f[C]Div\f[] blocks, footnotes and
+citations, embedded LaTeX (including math), Markdown inside HTML block
+elements, and much more.
+These enhancements, described further under Pandoc\[aq]s Markdown, can
+be disabled using the \f[C]markdown_strict\f[] format.
.PP
-In contrast to most existing tools for converting Markdown to HTML,
-which use regex substitutions, pandoc has a modular design: it consists
-of a set of readers, which parse text in a given format and produce a
-native representation of the document, and a set of writers, which
-convert this native representation into a target format.
+Pandoc has a modular design: it consists of a set of readers, which
+parse text in a given format and produce a native representation of the
+document (like an \f[I]abstract syntax tree\f[] or AST), and a set of
+writers, which convert this native representation into a target format.
Thus, adding an input or output format requires only adding a reader or
writer.
+Users can also run custom pandoc filters to modify the intermediate AST.
.PP
Because pandoc\[aq]s intermediate representation of a document is less
expressive than many of the formats it converts between, one should not
@@ -54,14 +55,9 @@ perfect, conversions from formats more expressive than pandoc\[aq]s
Markdown can be expected to be lossy.
.SS Using \f[C]pandoc\f[]
.PP
-If no \f[I]input\-file\f[] is specified, input is read from
+If no \f[I]input\-files\f[] are specified, input is read from
\f[I]stdin\f[].
-Otherwise, the \f[I]input\-files\f[] are concatenated (with a blank line
-between each) and used as input.
-Output goes to \f[I]stdout\f[] by default (though output to the terminal
-is disabled for the \f[C]odt\f[], \f[C]docx\f[], \f[C]epub2\f[], and
-\f[C]epub3\f[] output formats, unless it is forced using
-\f[C]\-o\ \-\f[]).
+Output goes to \f[I]stdout\f[] by default.
For output to a file, use the \f[C]\-o\f[] option:
.IP
.nf
@@ -70,10 +66,10 @@ pandoc\ \-o\ output.html\ input.txt
\f[]
.fi
.PP
-By default, pandoc produces a document fragment, not a standalone
-document with a proper header and footer.
-To produce a standalone document, use the \f[C]\-s\f[] or
-\f[C]\-\-standalone\f[] flag:
+By default, pandoc produces a document fragment.
+To produce a standalone document (e.g.
+a valid HTML file including \f[C]<head>\f[] and \f[C]<body>\f[]), use
+the \f[C]\-s\f[] or \f[C]\-\-standalone\f[] flag:
.IP
.nf
\f[C]
@@ -82,37 +78,17 @@ pandoc\ \-s\ \-o\ output.html\ input.txt
.fi
.PP
For more information on how standalone documents are produced, see
-Templates, below.
-.PP
-Instead of a file, an absolute URI may be given.
-In this case pandoc will fetch the content using HTTP:
-.IP
-.nf
-\f[C]
-pandoc\ \-f\ html\ \-t\ markdown\ http://www.fsf.org
-\f[]
-.fi
-.PP
-It is possible to supply a custom User\-Agent string or other header
-when requesting a document from a URL:
-.IP
-.nf
-\f[C]
-pandoc\ \-f\ html\ \-t\ markdown\ \-\-request\-header\ User\-Agent:"Mozilla/5.0"\ \\
-\ \ http://www.fsf.org
-\f[]
-.fi
+Templates below.
.PP
If multiple input files are given, \f[C]pandoc\f[] will concatenate them
all (with blank lines between them) before parsing.
-This feature is disabled for binary input formats such as \f[C]EPUB\f[],
-\f[C]odt\f[], and \f[C]docx\f[].
+(Use \f[C]\-\-file\-scope\f[] to parse files individually.)
+.SS Specifying formats
.PP
The format of the input and output can be specified explicitly using
command\-line options.
-The input format can be specified using the \f[C]\-r/\-\-read\f[] or
-\f[C]\-f/\-\-from\f[] options, the output format using the
-\f[C]\-w/\-\-write\f[] or \f[C]\-t/\-\-to\f[] options.
+The input format can be specified using the \f[C]\-f/\-\-from\f[]
+option, the output format using the \f[C]\-t/\-\-to\f[] option.
Thus, to convert \f[C]hello.txt\f[] from Markdown to LaTeX, you could
type:
.IP
@@ -130,17 +106,15 @@ pandoc\ \-f\ html\ \-t\ markdown\ hello.html
\f[]
.fi
.PP
-Supported output formats are listed below under the \f[C]\-t/\-\-to\f[]
-option.
-Supported input formats are listed below under the \f[C]\-f/\-\-from\f[]
-option.
-Note that the \f[C]rst\f[], \f[C]textile\f[], \f[C]latex\f[], and
-\f[C]html\f[] readers are not complete; there are some constructs that
-they do not parse.
+Supported input and output formats are listed below under Options (see
+\f[C]\-f\f[] for input formats and \f[C]\-t\f[] for output formats).
+You can also use \f[C]pandoc\ \-\-list\-input\-formats\f[] and
+\f[C]pandoc\ \-\-list\-output\-formats\f[] to print lists of supported
+formats.
.PP
If the input or output format is not specified explicitly,
\f[C]pandoc\f[] will attempt to guess it from the extensions of the
-input and output filenames.
+filenames.
Thus, for example,
.IP
.nf
@@ -155,7 +129,8 @@ or if the output file\[aq]s extension is unknown, the output format will
default to HTML.
If no input file is specified (so that input comes from \f[I]stdin\f[]),
or if the input files\[aq] extensions are unknown, the input format will
-be assumed to be Markdown unless explicitly specified.
+be assumed to be Markdown.
+.SS Character encoding
.PP
Pandoc uses the UTF\-8 character encoding for both input and output.
If your local character encoding is not UTF\-8, you should pipe input
@@ -174,8 +149,7 @@ the \f[C]\-s/\-\-standalone\f[] option.
.SS Creating a PDF
.PP
To produce a PDF, specify an output file with a \f[C]\&.pdf\f[]
-extension.
-By default, pandoc will use LaTeX to create the PDF:
+extension:
.IP
.nf
\f[C]
@@ -183,10 +157,34 @@ pandoc\ test.txt\ \-o\ test.pdf
\f[]
.fi
.PP
-Production of a PDF requires that a LaTeX engine be installed (see
-\f[C]\-\-pdf\-engine\f[], below), and assumes that the following LaTeX
-packages are available: \f[C]amsfonts\f[], \f[C]amsmath\f[],
-\f[C]lm\f[], \f[C]unicode\-math\f[], \f[C]ifxetex\f[],
+By default, pandoc will use LaTeX to create the PDF, which requires that
+a LaTeX engine be installed (see \f[C]\-\-pdf\-engine\f[] below).
+.PP
+Alternatively, pandoc can use ConTeXt, \f[C]pdfroff\f[], or any of the
+following HTML/CSS\-to\-PDF\-engines, to create a PDF:
+\f[C]wkhtmltopdf\f[], \f[C]weasyprint\f[] or \f[C]prince\f[].
+To do this, specify an output file with a \f[C]\&.pdf\f[] extension, as
+before, but add the \f[C]\-\-pdf\-engine\f[] option or
+\f[C]\-t\ context\f[], \f[C]\-t\ html\f[], or \f[C]\-t\ ms\f[] to the
+command line (\f[C]\-t\ html\f[] defaults to
+\f[C]\-\-pdf\-engine=wkhtmltopdf\f[]).
+.PP
+PDF output can be controlled using variables for LaTeX (if LaTeX is
+used) and variables for ConTeXt (if ConTeXt is used).
+When using an HTML/CSS\-to\-PDF\-engine, \f[C]\-\-css\f[] affects the
+output.
+If \f[C]wkhtmltopdf\f[] is used, then the variables
+\f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[],
+\f[C]margin\-bottom\f[], and \f[C]papersize\f[] will affect the output.
+.PP
+To debug the PDF creation, it can be useful to look at the intermediate
+representation: instead of \f[C]\-o\ test.pdf\f[], use for example
+\f[C]\-s\ \-o\ test.tex\f[] to output the generated LaTeX.
+You can then test it with \f[C]pdflatex\ test.tex\f[].
+.PP
+When using LaTeX, the following packages need to be available (they are
+included with all recent versions of TeX Live): \f[C]amsfonts\f[],
+\f[C]amsmath\f[], \f[C]lm\f[], \f[C]unicode\-math\f[], \f[C]ifxetex\f[],
\f[C]ifluatex\f[], \f[C]listings\f[] (if the \f[C]\-\-listings\f[]
option is used), \f[C]fancyvrb\f[], \f[C]longtable\f[],
\f[C]booktabs\f[], \f[C]graphicx\f[] and \f[C]grffile\f[] (if the
@@ -205,24 +203,26 @@ available, and \f[C]csquotes\f[] will be used for typography if added to
the template or included in any header file.
The \f[C]natbib\f[], \f[C]biblatex\f[], \f[C]bibtex\f[], and
\f[C]biber\f[] packages can optionally be used for citation rendering.
-These are included with all recent versions of TeX Live.
+.SS Reading from the Web
.PP
-Alternatively, pandoc can use ConTeXt, \f[C]pdfroff\f[], or any of the
-following HTML/CSS\-to\-PDF\-engines, to create a PDF:
-\f[C]wkhtmltopdf\f[], \f[C]weasyprint\f[] or \f[C]prince\f[].
-To do this, specify an output file with a \f[C]\&.pdf\f[] extension, as
-before, but add the \f[C]\-\-pdf\-engine\f[] option or
-\f[C]\-t\ context\f[], \f[C]\-t\ html\f[], or \f[C]\-t\ ms\f[] to the
-command line (\f[C]\-t\ html\f[] defaults to
-\f[C]\-\-pdf\-engine=wkhtmltopdf\f[]).
+Instead of an input file, an absolute URI may be given.
+In this case pandoc will fetch the content using HTTP:
+.IP
+.nf
+\f[C]
+pandoc\ \-f\ html\ \-t\ markdown\ http://www.fsf.org
+\f[]
+.fi
.PP
-PDF output can be controlled using variables for LaTeX (if LaTeX is
-used) and variables for ConTeXt (if ConTeXt is used).
-When using an HTML/CSS\-to\-PDF\-engine, \f[C]\-\-css\f[] affects the
-output.
-If \f[C]wkhtmltopdf\f[] is used, then the variables
-\f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[],
-\f[C]margin\-bottom\f[], and \f[C]papersize\f[] will affect the output.
+It is possible to supply a custom User\-Agent string or other header
+when requesting a document from a URL:
+.IP
+.nf
+\f[C]
+pandoc\ \-f\ html\ \-t\ markdown\ \-\-request\-header\ User\-Agent:"Mozilla/5.0"\ \\
+\ \ http://www.fsf.org
+\f[]
+.fi
.SH OPTIONS
.SS General options
.TP
@@ -283,9 +283,8 @@ show) or the path of a custom lua writer (see Custom writers, below).
(\f[C]markdown_github\f[] provides deprecated and less accurate support
for Github\-Flavored Markdown; please use \f[C]gfm\f[] instead, unless
you use extensions that do not work with \f[C]gfm\f[].) Note that
-\f[C]odt\f[], \f[C]epub\f[], and \f[C]epub3\f[] output will not be
-directed to \f[I]stdout\f[]; an output filename must be specified using
-the \f[C]\-o/\-\-output\f[] option.
+\f[C]odt\f[], \f[C]docx\f[], and \f[C]epub\f[] output will not be
+directed to \f[I]stdout\f[] unless forced with \f[C]\-o\ \-\f[].
Extensions can be individually enabled or disabled by appending
\f[C]+EXTENSION\f[] or \f[C]\-EXTENSION\f[] to the format name.
See Extensions below, for a list of extensions and their names.
@@ -386,8 +385,8 @@ List supported output formats, one per line.
.RE
.TP
.B \f[C]\-\-list\-extensions\f[][\f[C]=\f[]\f[I]FORMAT\f[]]
-List supported Markdown extensions, one per line, preceded by a
-\f[C]+\f[] or \f[C]\-\f[] indicating whether it is enabled by default in
+List supported extensions, one per line, preceded by a \f[C]+\f[] or
+\f[C]\-\f[] indicating whether it is enabled by default in
\f[I]FORMAT\f[].
If \f[I]FORMAT\f[] is not specified, defaults for pandoc\[aq]s Markdown
are given.
@@ -574,6 +573,10 @@ respectively.
The author and time of change is included.
\f[C]all\f[] is useful for scripting: only accepting changes from a
certain reviewer, say, or before a certain date.
+If a paragraph is inserted or deleted, \f[C]track\-changes=all\f[]
+produces a span with the class
+\f[C]paragraph\-insertion\f[]/\f[C]paragraph\-deletion\f[] before the
+affected paragraph break.
This option only affects the docx reader.
.RS
.RE
@@ -4071,55 +4074,6 @@ Use native pandoc \f[C]Span\f[] blocks for content inside
For the most part this should give the same output as \f[C]raw_html\f[],
but it makes it easier to write pandoc filters to manipulate groups of
inlines.
-.SS Extension: \f[C]fenced_divs\f[]
-.PP
-Allow special fenced syntax for native \f[C]Div\f[] blocks.
-A Div starts with a fence containing at least three consecutive colons
-plus some attributes.
-The attributes may optionally be followed by another string of
-consecutive colons.
-The attribute syntax is exactly as in fenced code blocks (see Extension:
-\f[C]fenced_code_attributes\f[]).
-As with fenced code blocks, one can use either attributes in curly
-braces or a single unbraced word, which will be treated as a class name.
-The Div ends with another line containing a string of at least three
-consecutive colons.
-The fenced Div should be separated by blank lines from preceding and
-following blocks.
-.PP
-Example:
-.IP
-.nf
-\f[C]
-:::::\ {#special\ .sidebar}
-Here\ is\ a\ paragraph.
-
-And\ another.
-:::::
-\f[]
-.fi
-.PP
-Fenced divs can be nested.
-Opening fences are distinguished because they \f[I]must\f[] have
-attributes:
-.IP
-.nf
-\f[C]
-:::\ Warning\ ::::::
-This\ is\ a\ warning.
-
-:::\ Danger
-This\ is\ a\ warning\ within\ a\ warning.
-:::
-::::::::::::::::::
-\f[]
-.fi
-.PP
-Fences without attributes are always closing fences.
-Unlike with fenced code blocks, the number of colons in the closing
-fence need not match the number in the opening fence.
-However, it can be helpful for visual clarity to use fences of different
-lengths to distinguish nested divs from their parents.
.SS Extension: \f[C]raw_tex\f[]
.PP
In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
@@ -4467,12 +4421,67 @@ identifier (LaTeX \f[C]\\caption\f[]), or both (HTML).
When no \f[C]width\f[] or \f[C]height\f[] attributes are specified, the
fallback is to look at the image resolution and the dpi metadata
embedded in the image file.
-.SS Spans
+.SS Divs and Spans
+.PP
+Using the \f[C]native_divs\f[] and \f[C]native_spans\f[] extensions (see
+above), HTML syntax can be used as part of markdown to create native
+\f[C]Div\f[] and \f[C]Span\f[] elements in the pandoc AST (as opposed to
+raw HTML).
+However, there is also nicer syntax available:
+.SS Extension: \f[C]fenced_divs\f[]
+.PP
+Allow special fenced syntax for native \f[C]Div\f[] blocks.
+A Div starts with a fence containing at least three consecutive colons
+plus some attributes.
+The attributes may optionally be followed by another string of
+consecutive colons.
+The attribute syntax is exactly as in fenced code blocks (see Extension:
+\f[C]fenced_code_attributes\f[]).
+As with fenced code blocks, one can use either attributes in curly
+braces or a single unbraced word, which will be treated as a class name.
+The Div ends with another line containing a string of at least three
+consecutive colons.
+The fenced Div should be separated by blank lines from preceding and
+following blocks.
+.PP
+Example:
+.IP
+.nf
+\f[C]
+:::::\ {#special\ .sidebar}
+Here\ is\ a\ paragraph.
+
+And\ another.
+:::::
+\f[]
+.fi
+.PP
+Fenced divs can be nested.
+Opening fences are distinguished because they \f[I]must\f[] have
+attributes:
+.IP
+.nf
+\f[C]
+:::\ Warning\ ::::::
+This\ is\ a\ warning.
+
+:::\ Danger
+This\ is\ a\ warning\ within\ a\ warning.
+:::
+::::::::::::::::::
+\f[]
+.fi
+.PP
+Fences without attributes are always closing fences.
+Unlike with fenced code blocks, the number of colons in the closing
+fence need not match the number in the opening fence.
+However, it can be helpful for visual clarity to use fences of different
+lengths to distinguish nested divs from their parents.
.SS Extension: \f[C]bracketed_spans\f[]
.PP
A bracketed sequence of inlines, as one would use to begin a link, will
-be treated as a span with attributes if it is followed immediately by
-attributes:
+be treated as a \f[C]Span\f[] with attributes if it is followed
+immediately by attributes:
.IP
.nf
\f[C]