diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 326 |
1 files changed, 223 insertions, 103 deletions
@@ -7,7 +7,9 @@ another, and a command-line tool that uses this library. It can read [markdown] and (subsets of) [reStructuredText], [HTML], and [LaTeX]; and it can write plain text, [markdown], [reStructuredText], [HTML], [LaTeX], [ConTeXt], [RTF], [DocBook XML], [OpenDocument XML], [ODT], [GNU Texinfo], -[MediaWiki markup], [Textile], [groff man] pages, and [S5] HTML slide shows. +[MediaWiki markup], [EPUB], [Textile], [groff man] pages, and [Slidy] +or [S5] HTML slide shows. + Pandoc's enhanced version of markdown includes syntax for footnotes, tables, flexible ordered lists, definition lists, delimited code blocks, superscript, subscript, strikeout, title blocks, automatic tables of @@ -22,22 +24,6 @@ representation of the document, 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. -[Textile]: http://thresholdstate.com/articles/4312/the-textile-reference-manual -[markdown]: http://daringfireball.net/projects/markdown/ -[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html -[S5]: http://meyerweb.com/eric/tools/s5/ -[HTML]: http://www.w3.org/TR/html40/ -[LaTeX]: http://www.latex-project.org/ -[ConTeXt]: http://www.pragma-ade.nl/ -[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format -[DocBook XML]: http://www.docbook.org/ -[OpenDocument XML]: http://opendocument.xml.org/ -[ODT]: http://en.wikipedia.org/wiki/OpenDocument -[MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting -[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/ - © 2006-2010 John MacFarlane (jgm at berkeley dot edu). Released under the [GPL], version 2 or greater. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.) @@ -45,8 +31,6 @@ Other contributors include Recai Oktaş, Paulo Tanimoto, Peter Wang, Andrea Rossato, Eric Kow, infinity0x, Luke Plant, shreevatsa.public, rodja.trappe, Bradley Kuhn, thsutton, Justin Bogner. -[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License" - Using Pandoc ============ @@ -57,8 +41,8 @@ If you want to write to a file, use the `-o` option: pandoc -o hello.html hello.txt -[^1]: The exception is for `odt`. Since this is a binary output format, - an output file must be specified explicitly. +[^1]: The exceptions are for `odt` and `epub`. Since these are + a binary output formats, an output file must be specified explicitly. Note that you can specify multiple input files on the command line. `pandoc` will concatenate them all (with blank lines between them) @@ -91,9 +75,9 @@ Supported output formats include `markdown`, `latex`, `context` (ConTeXt), `html`, `rtf` (rich text format), `rst` (reStructuredText), `docbook` (DocBook XML), `opendocument` (OpenDocument XML), `odt` (OpenOffice text document), `texinfo`, (GNU -Texinfo), `mediawiki` (MediaWiki markup), `textile` (Textile), `man` -(groff man), and `s5` (which produces an HTML file that acts like -powerpoint). +Texinfo), `mediawiki` (MediaWiki markup), `textile` (Textile), +`epub` (EPUB ebook), `man` (groff man), `slidy` (slidy HTML and +javascript slide show), or `s5` (S5 HTML and javascript slide show). Supported input formats include `markdown`, `html`, `latex`, and `rst`. Note that the `rst` reader only parses a subset of reStructuredText @@ -191,7 +175,7 @@ For further documentation, see the `pandoc(1)` man page. `-t`, `--to`, `-w`, or `--write` *format* : specifies the output format -- the format Pandoc will - be converting *to*. *format* can be `native`, `html`, `s5`, + be converting *to*. *format* can be `native`, `html`, `slidy`, `s5`, `docbook`, `opendocument`, `latex`, `context`, `markdown`, `man`, `plain`, `rst`, and `rtf`. (`+lhs` can be appended to indicate that the output should be treated as literate Haskell source. See @@ -204,8 +188,8 @@ For further documentation, see the `pandoc(1)` man page. `-o` or `--output` *filename* : sends output to *filename*. If this option is not specified, or if its argument is `-`, output will be sent to stdout. - (Exception: if the output format is `odt`, output to stdout - is disabled.) + (Exception: if the output format is `odt` or `epub`, output to + stdout is disabled.) `-p` or `--preserve-tabs` : causes tabs in the source text to be preserved, rather than converted @@ -228,11 +212,12 @@ For further documentation, see the `pandoc(1)` man page. `-R` or `--parse-raw` : causes the HTML and LaTeX readers to parse HTML codes and LaTeX environments that it can't translate as raw HTML or LaTeX. Raw HTML can - be printed in markdown, reStructuredText, HTML, and S5 output; raw LaTeX - can be printed in markdown, reStructuredText, LaTeX, and ConTeXt output. - The default is for the readers to omit untranslatable HTML codes and - LaTeX environments. (The LaTeX reader does pass through untranslatable - LaTeX *commands*, even if `-R` is not specified.) + be printed in markdown, reStructuredText, HTML, Slidy, and S5 + output; raw LaTeX can be printed in markdown, reStructuredText, + LaTeX, and ConTeXt output. The default is for the readers to omit + untranslatable HTML codes and LaTeX environments. (The LaTeX reader + does pass through untranslatable LaTeX *commands*, even if `-R` is + not specified.) `-C` or `--custom-header` *filename* : can be used to specify a custom document header. Implies `--standalone`. @@ -242,7 +227,7 @@ For further documentation, see the `pandoc(1)` man page. : includes an automatically generated table of contents (or, in the case of `latex`, `context`, and `rst`, an instruction to create one) in the output document. This option has no effect with `man`, - `docbook`, or `s5` output formats. + `docbook`, `slidy`, or `s5` output formats. `--base-header-level` *level* : specifies the base level for headers (defaults to 1). @@ -263,9 +248,9 @@ For further documentation, see the `pandoc(1)` man page. `-c` or `--css` *filename* : allows the user to specify a custom stylesheet that will be linked to - in HTML and S5 output. This option can be used repeatedly to include - multiple stylesheets. They will be included in the order specified. - Implies `--standalone`. + in HTML, Slidy, and S5 output. This option can be used repeatedly + to include multiple stylesheets. They will be included in the order + specified. Implies `--standalone`. `-H` or `--include-in-header` *filename* : includes the contents of *filename* (verbatim) at the end of the @@ -299,6 +284,26 @@ For further documentation, see the `pandoc(1)` man page. `--data-dir`, below). If it is not found there, sensible defaults will be used. +`--epub-stylesheet` *filename* +: uses the specified CSS file to style the EPUB. If no stylesheet + is specified, pandoc will look for a file `epub.css` in the + user data directory (see `--data-dir`, below). If it is not + found there, sensible defaults will be used. + +`--epub-metadata` *filename* +: looks in the specified XML file for metadata for the EPUB. + The file should contain a series of [Dublin Core elements], + for example: + + <dc:rights>Creative Commons</dc:rights> + <dc:language>es-AR</dc:language> + + By default, pandoc will include the following metadata elements: + `<dc:title>` (from the document title), `<dc:creator>` (from the + document authors), `<dc:language>` (from the locale), and + `<dc:identifier id="BookId">` (a randomly generated UUID). Any of + these may be overridden by elements in the metadata file. + `-D` or `--print-default-template` *format* : prints the default template for an output *format*. (See `-t` for a list of possible *format*s.) @@ -320,15 +325,13 @@ For further documentation, see the `pandoc(1)` man page. `-m`*[url]* or `--latexmathml`*[=url]* : causes `pandoc` to use the [LaTeXMathML] script to display - TeX math in HTML or S5. If a local copy of `LaTeXMathML.js` is - available on the webserver where the page will be viewed, provide a - *url* and a link will be inserted in the generated HTML or S5. If + TeX math in HTML, Slidy, or S5. If a local copy of `LaTeXMathML.js` + is available on the webserver where the page will be viewed, provide + a *url* and a link will be inserted in the generated HTML. If no *url* is provided, the contents of the script will be inserted directly; this provides portability at the price of efficiency. If you plan to use math on several pages, it is much better to link to - a copy of `LaTeXMathML.js`, which can be cached. (See `--jsmath`, - `--gladtex`, and `--mimetex` for alternative ways of dealing with - math in HTML.) + a copy of `LaTeXMathML.js`, which can be cached. `--mathml` : causes `pandoc` to convert all TeX math to MathML. @@ -337,29 +340,40 @@ For further documentation, see the `pandoc(1)` man page. `--jsmath`*=[url]* : causes `pandoc` to use the [jsMath] script to display - TeX math in HTML or S5. The *url* should point to the jsMath load - script (e.g. `jsMath/easy/load.js`). If it is provided, a link to it - will be included in the header of standalone HTML documents. - (See `--latexmathml`, `--mimetex`, and `--gladtex` for alternative - ways of dealing with math in HTML.) + TeX math in HTML, Slidy, or S5. The *url* should point to the jsMath + load script (e.g. `jsMath/easy/load.js`). If it is provided, a link + to it will be included in the header of standalone HTML documents. + +\--mathjax=*URL* +: causes `pandoc` to use [MathJax] to display embedded TeX math in HTML + output. The *URL* should point to the `MathJax.js` load script. `--gladtex`*[=url]* -: causes TeX formulas to be enclosed in `<eq>` tags in HTML or S5 output. - This output can then be processed by [gladTeX] to produce links to - images with the typeset formulas. (See `--latexmathml`, `--jsmath`, and - `--mimetex` for alternative ways of dealing with math in HTML.) +: causes TeX formulas to be enclosed in `<eq>` tags in HTML, Slidy, or + S5 output. This output can then be processed by [gladTeX] to produce + links to images with the typeset formulas. `--mimetex`*[=url]* : causes TeX formulas to be replaced by `<img>` tags linking to the [mimeTeX] CGI script, which will produce images with the typeset - formulas. (See `--latexmathml`, `--jsmath`, and `--gladtex` for alternative - ways of dealing with math in HTML.) + formulas. + +`--webtex`*[=url]* +: causes TeX formulas to be replaced by `<img>` tags linking to an + external service that converts TeX formulas to images. The formula + will be concatenated with the URL provided. If no URL + is specified, the Google Chart API is used. `-i` or `--incremental` -: causes all lists in S5 output to be displayed incrementally by +: causes all lists in Slidy or S5 output to be displayed incrementally by default (one item at a time). The normal default is for lists to be displayed all at once. +`--offline` +: causes all the CSS and javascript needed for a Slidy or S5 slide show + to be included in the output, so that the slide show will work even + when no internet connection is available. + `--xetex` : creates LaTeX outut suitable for processing by XeTeX. @@ -367,6 +381,11 @@ For further documentation, see the `pandoc(1)` man page. : causes sections to be numbered in LaTeX, ConTeXt, or HTML output. By default, sections are not numbered. +`--section-divs` +: causes sections to be wrapped in `<div>` tags. In this case, + [section identifiers](#header-identifiers-in-html) + are attached to the enclosing `<div>` rather than the header itself. + `--no-wrap` : disables text-wrapping in output. By default, text is wrapped appropriately for the output format. @@ -406,8 +425,9 @@ For further documentation, see the `pandoc(1)` man page. C:\Documents And Settings\USERNAME\Application Data\pandoc - in Windows. A reference ODT, `templates` directory, `s5` directory - placed in this directory will override pandoc's normal defaults. + in Windows. A `reference.odt`, `epub.css`, `templates` directory, + or `s5` directory placed in this directory will override pandoc's + normal defaults. `--dump-args` : is intended to make it easier to create wrapper scripts that use @@ -445,8 +465,10 @@ For further documentation, see the `pandoc(1)` man page. [Smartypants]: http://daringfireball.net/projects/smartypants/ [LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/ [jsMath]: http://www.math.union.edu/~dpvc/jsmath/ +[MathJax]: http://www.mathjax.org/ [gladTeX]: http://www.math.uio.no/~martingu/gladtex/index.html [mimeTeX]: http://www.forkosh.com/mimetex.html +[Dublin Core elements]: http://dublincore.org/documents/dces/ Templates ========= @@ -562,12 +584,12 @@ which allows only the following characters to be backslash-escaped: \`*_{}[]()>#+-.! A backslash-escaped space is parsed as a nonbreaking space. It will -appear in TeX output as '`~`' and in HTML and XML as '`\ `' or -'`\ `'. +appear in TeX output as `~` and in HTML and XML as `\ ` or +`\ `. A backslash-escaped newline (i.e. a backslash occurring at the end of a line) is parsed as a hard line break. It will appear in TeX output as -'`\\`' and in HTML as '`<br />`'. This is a nice alternative to +`\\` and in HTML as `<br />`. This is a nice alternative to markdown's "invisible" way of indicating hard line breaks using two trailing spaces on a line. @@ -645,7 +667,7 @@ capital letter with a period, by at least two spaces.[^2] escape can be used: (C\) 2007 Joe Smith - + 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 output format. Thus, the following yields a list with numbers followed @@ -667,12 +689,38 @@ So, the following yields a list numbered sequentially starting from 2: 1. Four * Five -If default list markers are desired, use '`#.`': +If default list markers are desired, use `#.`: #. one #. two #. three +Numbered examples +----------------- + +The special list marker `@` can be used for sequentially numbered +examples. The first list item with a `@` marker will be numbered '1', +the next '2', and so on, throughout the document. The numbered examples +need not occur in a single list; each new list using `@` will take up +where the last stopped. So, for example: + + (@) My first example will be numbered (1). + (@) My second example will be numbered (2). + + Explanation of examples. + + (@) My third example will be numbered (3). + +Numbered examples can be labeled and referred to elsewhere in the +document: + + (@good) This is a good example. + + As (@good) illustrates, ... + +The label can be any string of alphanumeric characters, underscores, +or hyphens. + Definition lists ---------------- @@ -771,10 +819,10 @@ Inline and regular footnotes may be mixed freely. Tables ------ -Two kinds of tables may be used. Both kinds presuppose the use of +Three kinds of tables may be used. All three kinds presuppose the use of a fixed-width font, such as Courier. -Simple tables look like this: +**Simple tables** look like this: Right Left Center Default ------- ------ ---------- ------- @@ -803,7 +851,8 @@ to the dashed line below it:[^4] 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:`, which will be stripped off. +`Table:` (or just `:`), which will be stripped off. It may appear either +before or after the table. The column headers may be omitted, provided a dashed line is used to end the table. For example: @@ -818,8 +867,9 @@ 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 allow headers and table rows to span multiple lines -of text. Here is an example: +**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 +not supported). Here is an example: ------------------------------------------------------------- Centered Default Right Left @@ -859,12 +909,34 @@ Headers may be omitted in multiline tables as well as simple tables: rows. ------------------------------------------------------------- - Table: Here's a multiline table without headers. + : Here's a multiline table without headers. 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** look like this: + + : Sample grid table. + + +---------------+---------------+--------------------+ + | Fruit | Price | Advantages | + +===============+===============+====================+ + | Bananas | $1.34 | - built-in wrapper | + | | | - bright color | + +---------------+---------------+--------------------+ + | Oranges | $2.10 | - cures scurvy | + | | | - tasty | + +---------------+---------------+--------------------+ + +The row of `=`s separates the header from the table body, and can be +omitted for a headerless table. The cells of grid tables may contain +arbitrary block elements (multiple paragraphs, code blocks, lists, +etc.). Alignments are not supported, nor are cells that span multiple +columns or rows. Grid tables can be created easily using [Emacs table mode]. + + [Emacs table mode]: http://table.sourceforge.net/ + Delimited Code blocks --------------------- @@ -1087,6 +1159,12 @@ another. A link to this section, for example, might look like this: Note, however, that this method of providing links to sections works only in HTML. +If the `--section-divs` option is specified, then each section will +be wrapped in a `div`, and the identifier will be attached to the +enclosing `<div>` tag rather than the header itself. This allows entire +sections to be manipulated using javascript or treated differently in +CSS. + Blank lines before headers and blockquotes ------------------------------------------ @@ -1132,7 +1210,7 @@ Unknown commands and symbols, and commands that cannot be dealt with this way (like `\frac`), will be rendered verbatim. So the results may be a mix of raw TeX code and properly rendered unicode math. -In HTML and S5 output, the way math is rendered will depend on the +In HTML, Slidy, and S5 output, the way math is rendered will depend on the command-line options selected: 1. The default is to render TeX math as far as possible using unicode @@ -1168,6 +1246,24 @@ command-line options selected: gladtex -d myfile-images myfile.htex # produces myfile.html and images in myfile-images +6. If the `--webtex` option is used, TeX formulas will be converted + to `<img>` tags that link to an external script that converts + formulas to images. The formula will be URL-encoded and concatenated + with the URL provided. If no URL is specified, the Google Chart + API will be used (`http://chart.apis.google.com/chart?cht=tx&chl=`). + +LaTeX Macros +------------ + +For output formats other than LaTeX, pandoc will parse LaTeX `\newcommand` and +`\renewcommand` definitions and apply the resulting macros to all LaTeX +math. So, for example, the following will work in all output formats, +not just LaTeX: + + \newcommand{\tuple}[1]{\langle #1 \rangle} + + $\tuple{a, b, c}$ + Inline TeX ---------- @@ -1192,14 +1288,12 @@ LaTeX, not as markdown. Inline LaTeX is ignored in output formats other than Markdown, LaTeX, and ConTeXt. -Producing S5 with Pandoc -======================== +Producing HTML slide shows with Pandoc +====================================== -Producing an [S5] web-based slide show with Pandoc is easy. A title -page is constructed automatically from the document's title block (see -above). Each section (with a level-one header) produces a single slide. -(Note that if the section is too big, the slide will not fit on the page; -S5 is not smart enough to produce multiple pages.) +You can use Pandoc to produce an HTML + javascript slide presentation +that can be viewed via a web browser. There are two ways to do this, +using [S5] or [Slidy]. Here's the markdown source for a simple slide show, `eating.txt`: @@ -1217,18 +1311,45 @@ Here's the markdown source for a simple slide show, `eating.txt`: - Eat spaghetti - Drink wine + -------------------------- + +  + To produce the slide show, simply type pandoc -w s5 -s eating.txt > eating.html -and open up `eating.html` in a browser. +for S5, or + + pandoc -w slidy -s eating.txt > eating.html + +for Slidy. + +A title page is constructed automatically from the document's title +block. Each level-one header and horizontal rule begins a new slide. + +The file produced by pandoc with the `-s/--standalone` option embeds a +link to javascripts and CSS files, which are assumed to be available at +the relative path `ui/default` (for S5) or at the Slidy website at +`w3.org` (for Slidy). If the `--offline` option is specified, the +scripts and CSS will be included directly in the generated file, so that +it may be used offline. -Note that by default, the S5 writer produces lists that display -"all at once." If you want your lists to display incrementally -(one item at a time), use the `-i` option. If you want a -particular list to depart from the default (that is, to display -incrementally without the `-i` option and all at once with the -`-i` option), put it in a block quote: +You can change the style of the slides by putting customized CSS files +in `$DATADIR/s5/default` (for S5) or `$DATADIR/slidy` (for Slidy), +where `$DATADIR` is the user data directory (see `--data-dir`, above). +The originals may be found in pandoc's system data directory (generally +`$CABALDIR/pandoc-VERSION/s5/default`). Pandoc will look there for any +files it does not find in the user data directory. + +Incremental lists +----------------- + +By default, these writers produces lists that display "all at once." +If you want your lists to display incrementally (one item at a time), +use the `-i` option. If you want a particular list to depart from the +default (that is, to display incrementally without the `-i` option and +all at once with the `-i` option), put it in a block quote: > - Eat spaghetti > - Drink wine @@ -1236,27 +1357,6 @@ incrementally without the `-i` option and all at once with the In this way incremental and nonincremental lists can be mixed in a single document. -Note: the S5 file produced by pandoc with the `-s/--standalone` option -embeds the javascript and CSS required to show the slides. Thus it -does not depend on any additional files: you can send the HTML file to -others, and they will be able to view the slide show just by opening -it. However, if you intend to produce several S5 slide shows, and you -are displaying them on your own website, it is better to keep the S5 -javascript and CSS files separate from the slide shows themselves, so -that they may be cached. The best approach in this case is to use pandoc -without the `-s` option to produce the body of the S5 document, which -can then be inserted into an HTML template that links to the javascript -and CSS files required by S5. (See the instructions on the S5 website.) -Alternatively, you may use `-s` together with the `--template` -option to specify a custom template. - -You can change the style of the slides by putting customized CSS files -in `$DATADIR/s5/default`, where `$DATADIR` is the user data directory -(see `--data-dir`, above). The originals may be found in pandoc's system -data directory (generally `$CABALDIR/pandoc-VERSION/s5/default`). Pandoc -will look there for any files it does not find in the user data -directory. - Literate Haskell support ======================== @@ -1302,3 +1402,23 @@ ordinary HTML (without bird tracks). writes HTML with the Haskell code in bird tracks, so it can be copied and pasted as literate Haskell source. + +[markdown]: http://daringfireball.net/projects/markdown/ +[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html +[S5]: http://meyerweb.com/eric/tools/s5/ +[Slidy]: http://www.w3.org/Talks/Tools/Slidy/ +[HTML]: http://www.w3.org/TR/html40/ +[LaTeX]: http://www.latex-project.org/ +[ConTeXt]: http://www.pragma-ade.nl/ +[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format +[DocBook XML]: http://www.docbook.org/ +[OpenDocument XML]: http://opendocument.xml.org/ +[ODT]: http://en.wikipedia.org/wiki/OpenDocument +[Textile]: http://redcloth.org/textile +[MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting +[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/ +[EPUB]: http://www.idpf.org/ +[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License" + |