diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 100 |
1 files changed, 74 insertions, 26 deletions
@@ -13,14 +13,15 @@ Description 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], and [DocBook]; 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], -[EPUB] (v2 or v3), [FictionBook2], [Textile], [groff man] pages, [Emacs -Org-Mode], [AsciiDoc], and [Slidy], [Slideous], [DZSlides], [reveal.js] -or [S5] HTML slide shows. It can also produce [PDF] output on systems -where LaTeX is installed. +[LaTeX], [MediaWiki markup], [Haddock markup], [OPML], [Emacs Org-mode] +and [DocBook]; 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], [EPUB] (v2 or v3), +[FictionBook2], [Textile], [groff man] pages, [Emacs Org-Mode], +[AsciiDoc], and [Slidy], [Slideous], [DZSlides], [reveal.js] or [S5] +HTML slide shows. It can also produce [PDF] output on systems where +LaTeX is installed. Pandoc's enhanced version of markdown includes syntax for footnotes, tables, flexible ordered lists, definition lists, fenced code blocks, @@ -108,7 +109,7 @@ to PDF: Production of a PDF requires that a LaTeX engine be installed (see `--latex-engine`, below), and assumes that the following LaTeX packages are available: `amssymb`, `amsmath`, `ifxetex`, `ifluatex`, `listings` (if the -`--listings` option is used), `fancyvrb`, `longtable`, `url`, +`--listings` option is used), `fancyvrb`, `longtable`, `booktabs`, `url`, `graphicx`, `hyperref`, `ulem`, `babel` (if the `lang` variable is set), `fontspec` (if `xelatex` or `lualatex` is used as the LaTeX engine), `xltxtra` and `xunicode` (if `xelatex` is used). @@ -143,14 +144,14 @@ General options `markdown_phpextra` (PHP Markdown Extra extended markdown), `markdown_github` (github extended markdown), `textile` (Textile), `rst` (reStructuredText), `html` (HTML), - `docbook` (DocBook), `opml` (OPML), `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 disabled - by appending `+EXTENSION` or `-EXTENSION` to the format name. - So, for example, `markdown_strict+footnotes+definition_lists` + `docbook` (DocBook), `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 + disabled by appending `+EXTENSION` or `-EXTENSION` to the format + name. So, for example, `markdown_strict+footnotes+definition_lists` is strict markdown with footnotes and definition lists enabled, and `markdown-pipe_tables+hard_line_breaks` is pandoc's markdown without pipe tables and with hard line breaks. See [Pandoc's @@ -434,8 +435,8 @@ Options affecting specific writers `--chapters` : Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook output. When the LaTeX template uses the report, book, or - memoir class, this option is implied. If `--beamer` is used, - top-level headers will become `\part{..}`. + memoir class, this option is implied. If `beamer` is the output + format, top-level headers will become `\part{..}`. `-N`, `--number-sections` : Number section headings in LaTeX, ConTeXt, HTML, or EPUB output. @@ -801,6 +802,8 @@ as `title`, `author`, and `date`) as well as the following: : causes links to be printed as footnotes 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` @@ -894,6 +897,9 @@ If you need a hard line break, put two or more spaces at the end of a line. **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 +to create a hard line break, since trailing spaces in the cells +are ignored. Headers ------- @@ -1277,7 +1283,7 @@ one tab: + pears + peaches * vegetables - + brocolli + + broccoli + chard As noted above, markdown allows you to write list items "lazily," instead of @@ -1843,6 +1849,18 @@ equivalent of the markdown in the `abstract` field: <p>This is the abstract.</p> <p>It consists of two paragraphs.</p> +Note: The `author` variable in the default templates expects a simple list or +string. To use the structured authors in the example, you would need a +custom template. For example: + + $for(author)$ + $if(author.name)$ + $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$ + $else$ + $author$ + $endif$ + $endfor$ + Backslash escapes ----------------- @@ -2091,7 +2109,7 @@ Raw HTML Markdown allows you to insert raw HTML (or DocBook) anywhere in a document (except verbatim contexts, where `<`, `>`, and `&` are interpreted -literally). (Techncially this is not an extension, since standard +literally). (Technically this is not an extension, since standard markdown allows it, but it has been made an extension so that it can be disabled if desired.) @@ -2456,6 +2474,21 @@ document with an appropriate header: The bibliography will be inserted after this header. +If you want to include items in the bibliography without actually +citing them in the body text, you can define a dummy `nocite` metadata +field and put the citations there: + + --- + nocite: + | @item1, @item2 + ... + + @item3 + +In this example, the document will contain a citation for `item3` +only, but the bibliography will contain entries for `item1`, `item2`, and +`item3`. + Non-pandoc extensions --------------------- @@ -2504,10 +2537,9 @@ the document, for example: Comment: This is a sample mmd title block, with a field spanning multiple lines. -See the MultiMarkdown documentation for details. Note that only title, -author, and date are recognized; other fields are simply ignored by -pandoc. If `pandoc_title_block` or `yaml_metadata_block` is enabled, -it will take precedence over `mmd_title_block`. +See the MultiMarkdown documentation for details. If `pandoc_title_block` or +`yaml_metadata_block` is enabled, it will take precedence over +`mmd_title_block`. [MultiMarkdown]: http://fletcherpenney.net/multimarkdown/ @@ -2565,6 +2597,20 @@ variants are supported: `markdown_strict` (Markdown.pl) : `raw_html` +Extensions with formats other than markdown +------------------------------------------- + +Some of the extensions discussed above can be used with formats +other than markdown: + +* `auto_identifiers` can be used with `latex`, `rst`, `mediawiki`, + and `textile` input (and is used by default). + +* `tex_math_dollars`, `tex_math_single_backslash`, and + `tex_math_double_backslash` can be used with `html` input. + (This is handy for reading web pages formatted using MathJax, + for example.) + Producing slide shows with Pandoc ================================= @@ -2822,12 +2868,14 @@ The following fields are recognized: ~ A string value. `cover-image` ~ A string value (path to cover image). +`stylesheet` + ~ A string value (path to CSS stylesheet). Literate Haskell support ======================== If you append `+lhs` (or `+literate_haskell`) to an appropriate input or output -format (`markdown`, `mardkown_strict`, `rst`, or `latex` for input or output; +format (`markdown`, `markdown_strict`, `rst`, or `latex` for input or output; `beamer`, `html` or `html5` for output only), pandoc will treat the document as literate Haskell source. This means that |