Tissevert/pandoc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Update changelog and man page.

Browse source
This commit is contained in:
John MacFarlane 2018-01-07 21:27:30 -08:00
parent ae6ba1533b
commit 5ca99f2cea
4 changed files with 316 additions and 156 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
AUTHORS.md
View file

@ -147,6 +147,7 @@
- RyanGlScott
- Sascha Wilde
- Scott Morrison
- Sebastian Talmon
- Sergei Trofimovich
- Sergey Astanin
- Shahbaz Youssefi

2
MANUAL.txt
View file

@ -1,6 +1,6 @@
% Pandoc User's Guide
% John MacFarlane
% December 27, 2017
% January 7, 2018
Synopsis
========

160
changelog
View file

@ -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:
`[![Image Title](image.jpg)](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.

309
man/pandoc.1
View file

@ -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]