diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 347 |
1 files changed, 253 insertions, 94 deletions
@@ -14,12 +14,12 @@ 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] and (subsets of) [Textile], [reStructuredText], [HTML], [LaTeX], [MediaWiki markup], [Haddock markup], [OPML], [Emacs -Org-mode], [DocBook], and [Word docx]; and it can write plain text, +Org-mode], [DocBook], [txt2tags], [EPUB] and [Word docx]; and it can write plain text, [markdown], [reStructuredText], [XHTML], [HTML 5], [LaTeX] (including [beamer] slide shows), [ConTeXt], [RTF], [OPML], [DocBook], [OpenDocument], [ODT], [Word docx], [GNU Texinfo], [MediaWiki markup], -[Haddock markup], [EPUB] (v2 or v3), [FictionBook2], [Textile], -[groff man] pages, [Emacs Org-Mode], [AsciiDoc], [InDesign ICML], +[DokuWiki markup], [Haddock markup], [EPUB] (v2 or v3), [FictionBook2], +[Textile], [groff man] pages, [Emacs Org-Mode], [AsciiDoc], [InDesign ICML], and [Slidy], [Slideous], [DZSlides], [reveal.js] or [S5] HTML slide shows. It can also produce [PDF] output on systems where LaTeX is installed. @@ -56,7 +56,8 @@ pandoc will fetch the content using HTTP: pandoc -f html -t markdown http://www.fsf.org If multiple input files are given, `pandoc` will concatenate them all (with -blank lines between them) before parsing. +blank lines between them) before parsing. This feature is disabled for + binary input formats such as `EPUB` and `docx`. The format of the input and output can be specified explicitly using command-line options. The input format can be specified using the @@ -144,9 +145,10 @@ General options `markdown_phpextra` (PHP Markdown Extra extended markdown), `markdown_github` (github extended markdown), `textile` (Textile), `rst` (reStructuredText), `html` (HTML), - `docbook` (DocBook), `opml` (OPML), `org` (Emacs Org-mode), - `mediawiki` (MediaWiki markup), `haddock` (Haddock markup), or - `latex` (LaTeX). If `+lhs` is appended to `markdown`, `rst`, + `docbook` (DocBook), `t2t` (txt2tags), `docx` (docx), `epub` (EPUB), + `opml` (OPML), `org` (Emacs Org-mode), `mediawiki` (MediaWiki markup), + `haddock` (Haddock markup), or `latex` (LaTeX). If `+lhs` is appended + to `markdown`, `rst`, `latex`, or `html`, the input will be treated as literate Haskell source: see [Literate Haskell support](#literate-haskell-support), below. Markdown syntax extensions can be individually enabled or @@ -167,6 +169,7 @@ General options `rst` (reStructuredText), `html` (XHTML 1), `html5` (HTML 5), `latex` (LaTeX), `beamer` (LaTeX beamer slide show), `context` (ConTeXt), `man` (groff man), `mediawiki` (MediaWiki markup), + `dokuwiki` (DokuWiki markup), `textile` (Textile), `org` (Emacs Org-Mode), `texinfo` (GNU Texinfo), `opml` (OPML), `docbook` (DocBook), `opendocument` (OpenDocument), `odt` (OpenOffice text document), `docx` (Word docx), `haddock` (Haddock @@ -308,6 +311,23 @@ Reader options `--tab-stop=`*NUMBER* : Specify the number of spaces per tab (default is 4). +`--track-changes=`*accept|reject|all* +: Specifies what to do with insertions and deletions produced by the MS + Word "track-changes" feature. *accept* (the default), inserts all + insertions, and ignores all deletions. *reject* inserts all + deletions and ignores insertions. *all* puts in both insertions + and deletions, wrapped in spans with `insertion` and `deletion` + classes, respectively. The author and time of change is + included. *all* is useful for scripting: only accepting changes + from a certain reviewer, say, or before a certain date. This + option only affects the docx reader. + +`--extract-media=`*DIR* +: Extract images and other media contained in a docx or epub container + to the path *DIR*, creating it if necessary, and adjust the images + references in the document so they point to the extracted files. + This option only affects the docx and epub readers. + General writer options ---------------------- @@ -529,9 +549,9 @@ Options affecting specific writers for a file `reference.docx` in the user data directory (see `--data-dir`). If this is not found either, sensible defaults will be used. The following styles are used by pandoc: [paragraph] - Normal, Compact, Title, Authors, Date, Heading 1, Heading 2, Heading 3, - Heading 4, Heading 5, Block Quote, Definition Term, Definition, - Body Text, Table Caption, Image Caption; [character] Default + Normal, Compact, Title, Subtitle, Authors, Date, Abstract, Heading 1, + Heading 2, Heading 3, Heading 4, Heading 5, Block Quote, Definition Term, + Definition, Body Text, Table Caption, Image Caption; [character] Default Paragraph Font, Body Text Char, Verbatim Char, Footnote Ref, Link. @@ -756,43 +776,60 @@ as `title`, `author`, and `date`) as well as the following: `header-includes` : contents specified by `-H/--include-in-header` (may have multiple values) + `toc` : non-null value if `--toc/--table-of-contents` was specified + `include-before` : contents specified by `-B/--include-before-body` (may have multiple values) + `include-after` : contents specified by `-A/--include-after-body` (may have multiple values) + `body` : body of document + `lang` : language code for HTML or LaTeX documents + `slidy-url` : base URL for Slidy documents (defaults to `http://www.w3.org/Talks/Tools/Slidy2`) + `slideous-url` : base URL for Slideous documents (defaults to `slideous`) + `s5-url` : base URL for S5 documents (defaults to `s5/default`) + `revealjs-url` : base URL for reveal.js documents (defaults to `reveal.js`) + `theme` : reveal.js or LaTeX beamer theme + `transition` : reveal.js transition + `fontsize` : font size (10pt, 11pt, 12pt) for LaTeX documents + `documentclass` : document class for LaTeX documents + `classoption` : option for LaTeX documentclass, e.g. `oneside`; may be repeated for multiple options + `geometry` : options for LaTeX `geometry` class, e.g. `margin=1in`; may be repeated for multiple options + `linestretch` : adjusts line spacing (requires the `setspace` package) + `fontfamily` : font package to use for LaTeX documents (with pdflatex): TeXLive has `bookman` (Bookman), `utopia` or `fourier` (Utopia), @@ -800,30 +837,54 @@ as `title`, `author`, and `date`) as well as the following: `mathpazo` or `pxfonts` or `mathpple` (Palatino), `libertine` (Linux Libertine), `arev` (Arev Sans), and the default `lmodern`, among others. + `mainfont`, `sansfont`, `monofont`, `mathfont` : fonts for LaTeX documents (works only with xelatex and lualatex) + `colortheme` : colortheme for LaTeX beamer documents + `fonttheme` : fonttheme for LaTeX beamer documents + `linkcolor` : color for internal links in LaTeX documents (`red`, `green`, `magenta`, `cyan`, `blue`, `black`) + `urlcolor` : color for external links in LaTeX documents + `citecolor` : color for citation links in LaTeX documents + `links-as-notes` : causes links to be printed as footnotes in LaTeX documents + +`toc` +: include table of contents in LaTeX documents + +`toc-depth` +: level of section to include in table of contents in LaTeX documents + +`lof` +: include list of figures in LaTeX documents + +`lot` +: include list of tables in LaTeX documents + `biblio-style` : bibliography style in LaTeX, when used with `--natbib` + `biblio-files` : bibliography files to use in LaTeX, with `--natbib` or `--biblatex` + `section` : section number in man pages + `header` : header in man pages + `footer` : footer in man pages @@ -910,7 +971,7 @@ A paragraph is one or more lines of text followed by one or more blank line. Newlines are treated as spaces, so you can reflow your paragraphs as you like. If you need a hard line break, put two or more spaces at the end of a line. -**Extension: `escaped_line_breaks`** +#### Extension: `escaped_line_breaks` #### A backslash followed by a newline is also a hard line break. Note: in multiline and grid table cells, this is the only way @@ -951,7 +1012,7 @@ As with setext-style headers, the header text can contain formatting: # A level-one header with a [link](/url) and *emphasis* -**Extension: `blank_before_header`** +#### Extension: `blank_before_header` #### Standard markdown syntax does not require a blank line before a header. Pandoc does require this (except, of course, at the beginning of the @@ -965,7 +1026,7 @@ wrapping). Consider, for example: ### Header identifiers in HTML, LaTeX, and ConTeXt ### -**Extension: `header_attributes`** +#### Extension: `header_attributes` #### Headers can be assigned attributes using this syntax at the end of the line containing the header text: @@ -1001,7 +1062,7 @@ is just the same as # My header {.unnumbered} -**Extension: `auto_identifiers`** +#### Extension: `auto_identifiers` #### A header without an explicitly specified identifier will be automatically assigned a unique identifier based on the header text. @@ -1050,7 +1111,7 @@ and the identifier will be attached to the enclosing `<div>` sections to be manipulated using javascript or treated differently in CSS. -**Extension: `implicit_header_references`** +#### Extension: `implicit_header_references` #### Pandoc behaves as if reference links have been defined for each header. So, instead of @@ -1109,7 +1170,7 @@ other block quotes. That is, block quotes can be nested: > > > A block quote within a block quote. -**Extension: `blank_before_blockquote`** +#### Extension: `blank_before_blockquote` #### Standard markdown syntax does not require a blank line before a block quote. Pandoc does require this (except, of course, at the beginning of the @@ -1143,7 +1204,7 @@ Note: blank lines in the verbatim text need not begin with four spaces. ### Fenced code blocks ### -**Extension: `fenced_code_blocks`** +#### Extension: `fenced_code_blocks` #### In addition to standard indented code blocks, Pandoc supports *fenced* code blocks. These begin with a row of three or more @@ -1169,6 +1230,8 @@ row of tildes or backticks at the start and end: ~~~~~~~~~~ ~~~~~~~~~~~~~~~~ +#### Extension: `fenced_code_attributes` #### + Optionally, you may attach attributes to the code block using this syntax: @@ -1205,13 +1268,18 @@ This is equivalent to: qsort [] = [] ``` +If the `fenced_code_attributes` extension is disabled, but +input contains class attribute(s) for the codeblock, the first +class attribute will be printed after the opening fence as a bare +word. + To prevent all highlighting, use the `--no-highlight` flag. To set the highlighting style, use `--highlight-style`. Line blocks ----------- -**Extension: `line_blocks`** +#### Extension: `line_blocks` #### A line block is a sequence of lines beginning with a vertical bar (`|`) followed by a space. The division into lines will be preserved in @@ -1353,7 +1421,7 @@ and this one: 7. two 1. three -**Extension: `fancy_lists`** +#### Extension: `fancy_lists` #### Unlike standard markdown, Pandoc allows ordered list items to be marked with uppercase and lowercase letters and roman numerals, in addition to @@ -1384,7 +1452,7 @@ ordered list marker in place of a numeral: #. one #. two -**Extension: `startnum`** +#### Extension: `startnum` #### Pandoc also pays attention to the type of list marker used, and to the starting number, and both of these are preserved where possible in the @@ -1416,10 +1484,10 @@ If default list markers are desired, use `#.`: ### Definition lists ### -**Extension: `definition_lists`** +#### Extension: `definition_lists` #### -Pandoc supports definition lists, using a syntax inspired by -[PHP Markdown Extra] and [reStructuredText]:[^3] +Pandoc supports definition lists, using the syntax of +[PHP Markdown Extra] with some extensions.[^3] Term 1 @@ -1436,32 +1504,48 @@ Pandoc supports definition lists, using a syntax inspired by Each term must fit on one line, which may optionally be followed by a blank line, and must be followed by one or more definitions. A definition begins with a colon or tilde, which may be indented one -or two spaces. The body of the definition (including the first line, -aside from the colon or tilde) should be indented four spaces. A term may have -multiple definitions, and each definition may consist of one or more block -elements (paragraph, code block, list, etc.), each indented four spaces or one -tab stop. - -If you leave space after the definition (as in the example above), -the blocks of the definitions will be considered paragraphs. In some +or two spaces. + +A term may have multiple definitions, and each definition may consist of one or +more block elements (paragraph, code block, list, etc.), each indented four +spaces or one tab stop. The body of the definition (including the first line, +aside from the colon or tilde) should be indented four spaces. However, +as with other markdown lists, you can "lazily" omit indentation except +at the beginning of a paragraph or other block element: + + Term 1 + + : Definition + with lazy continuation. + + Second paragraph of the definition. + +If you leave space before the definition (as in the example above), +the text of the definition will be treated as a paragraph. In some output formats, this will mean greater spacing between term/definition -pairs. For a compact definition list, do not leave space between the -definition and the next term: +pairs. For a more compact definition list, omit the space before the +definition: Term 1 ~ Definition 1 + Term 2 ~ Definition 2a ~ Definition 2b -[^3]: I have also been influenced by the suggestions of [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html). +Note that space between items in a definition list is required. +(A variant that loosens this requirement, but disallows "lazy" +hard wrapping, can be activated with `compact_definition_lists`: see +[Non-pandoc extensions](#non-pandoc-extensions), below.) + +[^3]: I have been influenced by the suggestions of [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html). [PHP Markdown Extra]: http://www.michelf.com/projects/php-markdown/extra/ ### Numbered example lists ### -**Extension: `example_lists`** +#### Extension: `example_lists` #### The special list marker `@` can be used for sequentially numbered examples. The first list item with a `@` marker will be numbered '1', @@ -1567,9 +1651,14 @@ Four kinds of tables may be used. The first three kinds presuppose the use of a fixed-width font, such as Courier. The fourth kind can be used with proportionally spaced fonts, as it does not require lining up columns. -### Simple tables +#### Extension: `table_captions` #### + +A caption may optionally be provided with all 4 kinds of tables (as +illustrated in the examples below). A caption is a paragraph beginning +with the string `Table:` (or just `:`), which will be stripped off. +It may appear either before or after the table. -**Extension: `simple_tables`, `table_captions`** +#### Extension: `simple_tables` #### Simple tables look like this: @@ -1598,10 +1687,7 @@ to the dashed line below it:[^4] [Markdown discussion list](http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html). The table must end with a blank line, or a line of dashes followed by -a blank line. A caption may optionally be provided (as illustrated in -the example above). A caption is a paragraph beginning with the string -`Table:` (or just `:`), which will be stripped off. It may appear either -before or after the table. +a blank line. The column headers may be omitted, provided a dashed line is used to end the table. For example: @@ -1616,9 +1702,7 @@ When headers are omitted, column alignments are determined on the basis of the first line of the table body. So, in the tables above, the columns would be right, left, center, and right aligned, respectively. -### Multiline tables - -**Extension: `multiline_tables`, `table_captions`** +#### Extension: `multiline_tables` #### Multiline tables allow headers and table rows to span multiple lines of text (but cells that span multiple columns or rows of the table are @@ -1668,9 +1752,7 @@ It is possible for a multiline table to have just one row, but the row should be followed by a blank line (and then the row of dashes that ends the table), or the table may be interpreted as a simple table. -### Grid tables - -**Extension: `grid_tables`, `table_captions`** +#### Extension: `grid_tables` #### Grid tables look like this: @@ -1694,9 +1776,7 @@ columns or rows. Grid tables can be created easily using [Emacs table mode]. [Emacs table mode]: http://table.sourceforge.net/ -### Pipe tables - -**Extension: `pipe_tables`, `table_captions`** +#### Extension: `pipe_tables` #### Pipe tables look like this: @@ -1706,7 +1786,7 @@ Pipe tables look like this: | 123 | 123 | 123 | 123 | | 1 | 1 | 1 | 1 | - : Demonstration of simple table syntax. + : Demonstration of pipe table syntax. The syntax is [the same as in PHP markdown extra]. The beginning and ending pipe characters are optional, but pipes are required between all @@ -1725,7 +1805,10 @@ legal (though ugly) pipe table: orange|3.09 The cells of pipe tables cannot contain block elements like paragraphs -and lists, and cannot span multiple lines. +and lists, and cannot span multiple lines. Note also that in LaTeX/PDF +output, the cells produced by pipe tables will not wrap, since there +is no information available about relative widths. If you want content +to wrap within cells, use multiline or grid tables. [the same as in PHP markdown extra]: http://michelf.ca/projects/php-markdown/extra/#table @@ -1742,10 +1825,10 @@ The difference is that `+` is used instead of `|`. Other orgtbl features are not supported. In particular, to get non-default column alignment, you'll need to add colons as above. -Title block ------------ +Metadata blocks +--------------- -**Extension: `pandoc_title_block`** +#### Extension: `pandoc_title_block` #### If the file begins with a title block @@ -1821,16 +1904,20 @@ will also have "Pandoc User Manuals" in the footer. will also have "Version 4.0" in the header. -YAML metadata block -------------------- - -**Extension: `yaml_metadata_block`** +#### Extension: `yaml_metadata_block` #### A YAML metadata block is a valid YAML object, delimited by a line of three hyphens (`---`) at the top and a line of three hyphens (`---`) or three dots (`...`) at the bottom. A YAML metadata block may occur anywhere in the document, but if it is not at the beginning, it must be preceded by a blank -line. +line. (Note that, because of the way pandoc concatenates input files when +several are provided, you may also keep the metadata in a separate YAML file +and pass it to pandoc as an argument, along with your markdown files: + + pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html + +Just be sure that the YAML file begins with `---` and ends with `---` or +`...`.) Metadata will be taken from the fields of the YAML object and added to any existing document metadata. Metadata can contain lists and objects (nested @@ -1885,7 +1972,7 @@ custom template. For example: Backslash escapes ----------------- -**Extension: `all_symbols_escapable`** +#### Extension: `all_symbols_escapable` #### Except inside a code block or inline code, any punctuation or space character preceded by a backslash will be treated literally, even if it @@ -1924,7 +2011,7 @@ Backslash escapes do not work in verbatim contexts. Smart punctuation ----------------- -**Extension** +#### Extension #### If the `--smart` option is specified, pandoc will produce typographically correct output, converting straight quotes to curly quotes, `---` to @@ -1953,7 +2040,7 @@ will not trigger emphasis: This is * not emphasized *, and \*neither is this\*. -**Extension: `intraword_underscores`** +#### Extension: `intraword_underscores` #### Because `_` is sometimes used inside words and identifiers, pandoc does not interpret a `_` surrounded by alphanumeric @@ -1965,7 +2052,7 @@ just part of a word, use `*`: ### Strikeout ### -**Extension: `strikeout`** +#### Extension: `strikeout` #### To strikeout a section of text with a horizontal line, begin and end it with `~~`. Thus, for example, @@ -1975,7 +2062,7 @@ with `~~`. Thus, for example, ### Superscripts and subscripts ### -**Extension: `superscript`, `subscript`** +#### Extension: `superscript`, `subscript` #### Superscripts may be written by surrounding the superscripted text by `^` characters; subscripts may be written by surrounding the subscripted @@ -2013,7 +2100,7 @@ work in verbatim contexts: This is a backslash followed by an asterisk: `\*`. -**Extension: `inline_code_attributes`** +#### Extension: `inline_code_attributes` #### Attributes can be attached to verbatim text, just as with [fenced code blocks](#fenced-code-blocks): @@ -2026,12 +2113,13 @@ To write small caps, you can use an HTML span tag: <span style="font-variant:small-caps;">Small caps</span> -This will work in all output formats that support small caps. +(The semicolon is optional and there may be space after the +colon.) This will work in all output formats that support small caps. Math ---- -**Extension: `tex_math_dollars`** +#### Extension: `tex_math_dollars` #### Anything between two `$` characters will be treated as TeX math. The opening `$` must have a character immediately to its right, while the @@ -2059,7 +2147,7 @@ Texinfo groff man ~ It will be rendered verbatim without `$`'s. -MediaWiki +MediaWiki, DokuWiki ~ It will be rendered inside `<math>` tags. Textile @@ -2133,7 +2221,7 @@ HTML, Slidy, DZSlides, S5, EPUB Raw HTML -------- -**Extension: `raw_html`** +#### Extension: `raw_html` #### Markdown allows you to insert raw HTML (or DocBook) anywhere in a document (except verbatim contexts, where `<`, `>`, and `&` are interpreted @@ -2145,7 +2233,7 @@ The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown, and Textile output, and suppressed in other formats. -**Extension: `markdown_in_html_blocks`** +#### Extension: `markdown_in_html_blocks` #### Standard markdown allows you to include HTML "blocks": blocks of HTML between balanced tags that are separated from the surrounding text @@ -2183,10 +2271,24 @@ markdown with HTML block elements. For example, one can surround a block of markdown text with `<div>` tags without preventing it from being interpreted as markdown. +#### Extension: `native_divs` #### + +Use native pandoc `Div` blocks for content inside `<div>` tags. +For the most part this should give the same output as +`markdown_in_html_blocks`, but it makes it easier to write pandoc +filters to manipulate groups of blocks. + +#### Extension: `native_spans` #### + +Use native pandoc `Span` blocks for content inside `<span>` tags. +For the most part this should give the same output as `raw_html`, +but it makes it easier to write pandoc filters to manipulate groups +of inlines. + Raw TeX ------- -**Extension: `raw_tex`** +#### Extension: `raw_tex` #### In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be included in a document. Inline TeX commands will be preserved and passed @@ -2213,7 +2315,7 @@ and ConTeXt. LaTeX macros ------------ -**Extension: `latex_macros`** +#### Extension: `latex_macros` #### For output formats other than LaTeX, pandoc will parse LaTeX `\newcommand` and `\renewcommand` definitions and apply the resulting macros to all LaTeX @@ -2305,7 +2407,7 @@ not in most other implementations: > > [quote]: /foo -### Internal links +### Internal links ### To link to another section of the same document, use the automatically generated identifier (see [Header identifiers in HTML, LaTeX, and @@ -2335,9 +2437,7 @@ The link text will be used as the image's alt text: [movie reel]: movie.gif -### Pictures with captions ### - -**Extension: `implicit_figures`** +#### Extension: `implicit_figures` #### An image occurring by itself in a paragraph will be rendered as a figure with a caption.[^5] (In LaTeX, a figure environment will be @@ -2361,7 +2461,7 @@ nonbreaking space after the image: Footnotes --------- -**Extension: `footnotes`** +#### Extension: `footnotes` #### Pandoc's markdown allows footnotes, using the following syntax: @@ -2392,7 +2492,7 @@ The footnotes themselves need not be placed at the end of the document. They may appear anywhere except inside other block elements (lists, block quotes, tables, etc.). -**Extension: `inline_notes`** +#### Extension: `inline_notes` #### Inline footnotes are also allowed (though, unlike regular notes, they cannot contain multiple paragraphs). The syntax is as follows: @@ -2407,7 +2507,7 @@ Inline and regular footnotes may be mixed freely. Citations --------- -**Extension: `citations`** +#### Extension: `citations` #### Using an external filter, `pandoc-citeproc`, pandoc can automatically generate citations and a bibliography in a number of styles. Basic usage is @@ -2529,37 +2629,44 @@ in pandoc, but may be enabled by adding `+EXTENSION` to the format name, where `EXTENSION` is the name of the extension. Thus, for example, `markdown+hard_line_breaks` is markdown with hard line breaks. -**Extension: `lists_without_preceding_blankline`**\ +#### Extension: `lists_without_preceding_blankline` #### + Allow a list to occur right after a paragraph, with no intervening blank space. -**Extension: `hard_line_breaks`**\ +#### Extension: `hard_line_breaks` #### + Causes all newlines within a paragraph to be interpreted as hard line breaks instead of spaces. -**Extension: `ignore_line_breaks`**\ +#### Extension: `ignore_line_breaks` #### + Causes newlines within a paragraph to be ignored, rather than being treated as spaces or as hard line breaks. This option is intended for use with East Asian languages where spaces are not used between words, but text is divided into lines for readability. -**Extension: `tex_math_single_backslash`**\ +#### Extension: `tex_math_single_backslash` #### + Causes anything between `\(` and `\)` to be interpreted as inline TeX math, and anything between `\[` and `\]` to be interpreted as display TeX math. Note: a drawback of this extension is that it precludes escaping `(` and `[`. -**Extension: `tex_math_double_backslash`**\ +#### Extension: `tex_math_double_backslash` #### + Causes anything between `\\(` and `\\)` to be interpreted as inline TeX math, and anything between `\\[` and `\\]` to be interpreted as display TeX math. -**Extension: `markdown_attribute`**\ +#### Extension: `markdown_attribute` #### + By default, pandoc interprets material inside block-level tags as markdown. This extension changes the behavior so that markdown is only parsed inside block-level tags if the tags have the attribute `markdown=1`. -**Extension: `mmd_title_block`**\ +#### Extension: `mmd_title_block` #### + Enables a [MultiMarkdown] style title block at the top of the document, for example: @@ -2575,7 +2682,8 @@ See the MultiMarkdown documentation for details. If `pandoc_title_block` or [MultiMarkdown]: http://fletcherpenney.net/multimarkdown/ -**Extension: `abbreviations`**\ +#### Extension: `abbreviations` #### + Parses PHP Markdown Extra abbreviation keys, like *[HTML]: Hyper Text Markup Language @@ -2584,24 +2692,55 @@ Note that the pandoc document model does not support abbreviations, so if this extension is enabled, abbreviation keys are simply skipped (as opposed to being parsed as paragraphs). -**Extension: `autolink_bare_uris`**\ +#### Extension: `autolink_bare_uris` #### + Makes all absolute URIs into links, even when not surrounded by pointy braces `<...>`. -**Extension: `ascii_identifiers`**\ +#### Extension: `ascii_identifiers` #### + Causes the identifiers produced by `auto_identifiers` to be pure ASCII. Accents are stripped off of accented latin letters, and non-latin letters are omitted. -**Extension: `link_attributes`**\ +#### Extension: `link_attributes` #### + Parses multimarkdown style key-value attributes on link and image references. Note that pandoc's internal document model provides nowhere to put these, so they are presently just ignored. -**Extension: `mmd_header_identifiers`**\ +#### Extension: `mmd_header_identifiers` #### + Parses multimarkdown style header identifiers (in square brackets, after the header but before any trailing `#`s in an ATX header). +#### Extension: `compact_definition_lists` #### + +Activates the definition list syntax of pandoc 1.12.x and earlier. +This syntax differs from the one described [above](#definition-lists) +in several respects: + + - No blank line is required between consecutive items of the + definition list. + - To get a "tight" or "compact" list, omit space between consecutive + items; the space between a term and its definition does not affect + anything. + - Lazy wrapping of paragraphs is not allowed: the entire definition must + be indented four spaces.[^6] + +[^6]: To see why laziness is incompatible with relaxing the requirement + of a blank line between items, consider the following example: + + bar + : definition + foo + : definition + + Is this a single list item with two definitions of "bar," the first of + which is lazily wrapped, or two list items? To remove the ambiguity + we must either disallow lazy wrapping or require a blank line between + list items. + Markdown variants ----------------- @@ -2615,7 +2754,7 @@ variants are supported: `markdown_github` (Github-flavored Markdown) : `pipe_tables`, `raw_html`, `tex_math_single_backslash`, - `fenced_code_blocks`, `fenced_code_attributes`, `auto_identifiers`, + `fenced_code_blocks`, `auto_identifiers`, `ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`, `intraword_underscores`, `strikeout`, `hard_line_breaks` @@ -2866,43 +3005,60 @@ The following fields are recognized: `GTIN-13`, `UPC`, `ISMN-10`, `DOI`, `LCCN`, `GTIN-14`, `ISBN-13`, `Legal deposit number`, `URN`, `OCLC`, `ISMN-13`, `ISBN-A`, `JP`, `OLCC`. + `title` ~ Either a string value, or an object with fields `file-as` and `type`, or a list of such objects. Valid values for `type` are `main`, `subtitle`, `short`, `collection`, `edition`, `extended`. + `creator` ~ Either a string value, or an object with fields `role`, `file-as`, and `text`, or a list of such objects. Valid values for `role` are [marc relators](http://www.loc.gov/marc/relators/relaterm.html), but pandoc will attempt to translate the human-readable versions (like "author" and "editor") to the appropriate marc relators. + `contributor` ~ Same format as `creator`. + `date` ~ A string value in `YYYY-MM-DD` format. (Only the year is necessary.) Pandoc will attempt to convert other common date formats. + `language` ~ A string value in [RFC5646] format. Pandoc will default to the local language if nothing is specified. + `subject` ~ A string value or a list of such values. + `description` ~ A string value. + `type` ~ A string value. + `format` ~ A string value. + `relation` ~ A string value. + `coverage` ~ A string value. + `rights` ~ A string value. + `cover-image` ~ A string value (path to cover image). + `stylesheet` ~ A string value (path to CSS stylesheet). +`page-progression-direction` + ~ Either `ltr` or `rtl`. Specifies the synonymous spine [attribute][EPUBspine]. + Literate Haskell support ======================== @@ -3000,13 +3156,13 @@ Rosenthal. [ODT]: http://en.wikipedia.org/wiki/OpenDocument [Textile]: http://redcloth.org/textile [MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting +[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki [Haddock markup]: http://www.haskell.org/haddock/doc/html/ch03s08.html [groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html [Haskell]: http://www.haskell.org/ [GNU Texinfo]: http://www.gnu.org/software/texinfo/ [Emacs Org-Mode]: http://orgmode.org [AsciiDoc]: http://www.methods.co.nz/asciidoc/ -[EPUB]: http://www.idpf.org/ [GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License" [DZSlides]: http://paulrouget.com/dzslides/ [ISO 8601 format]: http://www.w3.org/TR/NOTE-datetime @@ -3018,3 +3174,6 @@ Rosenthal. [marc relators]: http://www.loc.gov/marc/relators/relaterm.html [RFC5646]: http://tools.ietf.org/html/rfc5646 [InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf +[txt2tags]: http://txt2tags.org/ +[EPUB]: http://idpf.org/epub +[EPUBspine]: http://www.idpf.org/epub/301/spec/epub-publications.html#sec-spine-elem |