diff options
| -rw-r--r-- | AUTHORS.md | 1 | ||||
| -rw-r--r-- | MANUAL.txt | 2 | ||||
| -rw-r--r-- | changelog | 160 | ||||
| -rw-r--r-- | man/pandoc.1 | 311 |
4 files changed, 317 insertions, 157 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 ======== @@ -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.) -.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\[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 +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] |