diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 190 |
1 files changed, 161 insertions, 29 deletions
@@ -108,7 +108,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). @@ -278,17 +278,22 @@ Reader options Filters may be written in any language. `Text.Pandoc.JSON` exports `toJSONFilter` to facilitate writing filters in Haskell. Those who would prefer to write filters in python can use the - module `pandoc.py`: see <http://github.com/jgm/pandoc-filters-python> - for the module and several examples. Note that the *EXECUTABLE* - will be sought in the user's `PATH`, and not in the working directory, - if no directory is provided. If you want to run a script in the - working directory, preface the filename with `./`. + module `pandocfilters`, installable from PyPI. See + <http://github.com/jgm/pandocfilters> for the module and several + examples. Note that the *EXECUTABLE* will be sought in the user's + `PATH`, and not in the working directory, if no directory is + provided. If you want to run a script in the working directory, + preface the filename with `./`. `-M` *KEY[=VAL]*, `--metadata=`*KEY[:VAL]* -: Set the metadata field *KEY* to the value *VAL* after - parsing. A value specified on the command line overrides a value - specified in the document. Values will be interpreted as raw strings. - If no value is specified, the value will be treated as Boolean true. +: Set the metadata field *KEY* to the value *VAL*. A value specified + on the command line overrides a value specified in the document. + Values will be parsed as YAML boolean or string values. If no value is + specified, the value will be treated as Boolean true. Like + `--variable`, `--metadata` causes template variables to be set. + But unlike `--variable`, `--metadata` affects the metadata of the + underlying document (which is accessible from filters and may be + printed in some output formats). `--normalize` : Normalize the document after reading: merge adjacent @@ -429,8 +434,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. @@ -536,7 +541,9 @@ Options affecting specific writers `--epub-cover-image=`*FILE* : Use the specified image as the EPUB cover. It is recommended - that the image be less than 1000px in width and height. + that the image be less than 1000px in width and height. Note that + in a markdown source document you can also specify `cover-image` + in a YAML metadata block (see [EPUB Metadata], below). `--epub-metadata=`*FILE* : Look in the specified XML file for metadata for the EPUB. @@ -555,6 +562,10 @@ Options affecting specific writers id="BookId">` (a randomly generated UUID). Any of these may be overridden by elements in the metadata file. + Note: if the source document is markdown, a YAML metadata block + in the document can be used instead. See below under + [EPUB Metadata]. + `--epub-embed-font=`*FILE* : Embed the specified font in the EPUB. This option can be repeated to embed multiple fonts. To use embedded fonts, you @@ -606,10 +617,9 @@ Citation rendering `--bibliography=`*FILE* : Set the `bibliography` field in the document's metadata to *FILE*, - overriding any value set in the metadata, and tell pandoc to - use the `pandoc-citeproc` filter. (This is equivalent to the - combination `--metadata bibliography=FILE --filter pandoc-citeproc`.) - Note that an error will result unless `pandoc-citeproc` is installed. + overriding any value set in the metadata, and process citations + using `pandoc-citeproc`. (This is equivalent to + `--metadata bibliography=FILE --filter pandoc-citeproc`.) `--csl=`*FILE* : Set the `csl` field in the document's metadata to *FILE*, @@ -791,6 +801,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` @@ -884,6 +896,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 ------- @@ -1267,7 +1282,7 @@ one tab: + pears + peaches * vegetables - + brocolli + + broccoli + chard As noted above, markdown allows you to write list items "lazily," instead of @@ -1833,6 +1848,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 ----------------- @@ -2081,7 +2108,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.) @@ -2454,6 +2481,10 @@ 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`**\ +Allow a list to occur right after a paragraph, with no intervening +blank space. + **Extension: `hard_line_breaks`**\ Causes all newlines within a paragraph to be interpreted as hard line breaks instead of spaces. @@ -2490,10 +2521,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/ @@ -2551,6 +2581,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 ================================= @@ -2676,9 +2720,8 @@ a single document. Inserting pauses ---------------- -In reveal.js and beamer slide shows, you can add "pauses" within -a slide by including a paragraph containing three dots, separated -by spaces: +You can add "pauses" within a slide by including a paragraph containing +three dots, separated by spaces: # Slide with a pause @@ -2724,11 +2767,99 @@ bibliographies: # References {.allowframebreaks} +Speaker notes +------------- + +reveal.js has good support for speaker notes. You can add notes to your +markdown document thus: + + <div class="notes"> + This is my note. + + - It can contain markdown + - like this list + + </div> + +To show the notes window, press `s` while viewing the presentation. +Notes are not yet supported for other slide formats, but the notes +will not appear on the slides themselves. + +EPUB Metadata +============= + +EPUB metadata may be specified using the `--epub-metadata` option, but +if the source document is markdown, it is better to use a YAML metadata +block. Here is an example: + + --- + title: + - type: main + text: My Book + - type: subtitle + text: An investigation of metadata + creator: + - role: author + text: John Smith + - role: editor + text: Sarah Jones + identifier: + - scheme: DOI + text: doi:10.234234.234/33 + publisher: My Press + rights: (c) 2007 John Smith, CC BY-NC + ... + +The following fields are recognized: + +`identifier` + ~ Either a string value or an object with fields `text` and + `scheme`. Valid values for `scheme` are `ISBN-10`, + `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). + 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 @@ -2834,5 +2965,6 @@ Jamie F. Olson. [PDF]: http://www.adobe.com/pdf/ [reveal.js]: http://lab.hakim.se/reveal-js/ [FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1 -[lua]: TODO - +[lua]: http://www.lua.org +[marc relators]: http://www.loc.gov/marc/relators/relaterm.html +[RFC5646]: http://tools.ietf.org/html/rfc5646 |