Tissevert/pandoc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Use same options documentation in README and man page.

Browse source 
Later we will generate the man page from the README.
This commit is contained in:
John MacFarlane 2010-12-07 09:36:03 -08:00
parent 67445e7685
commit 315e236d6a
2 changed files with 347 additions and 313 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

423
README
View file

@ -166,140 +166,234 @@ problems with its simulation of symbolic links.
Command-line options Command-line options
==================== ====================
Various command-line options can be used to customize the output. `-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
For further documentation, see the `pandoc(1)` man page. : Specify input format. *FORMAT* can be
`native` (native Haskell), `markdown` (markdown or plain text),
`textile` (Textile), `rst` (reStructuredText), `html` (HTML),
or `latex` (LaTeX). If `+lhs` is appended to `markdown`, `rst`,
or `latex`, the input will be treated as literate Haskell source:
see [Literate Haskell support](#literate-haskell-support),
below.
`-f`, `--from`, `-r`, or `--read` *format* `-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT*
: specifies the input format (the format Pandoc will be converting : Specify output format. *FORMAT* can be `native` (native Haskell),
*from*). *format* can be `native`, `markdown`, `textile`, `rst`, `html`, `plain` (plain text), `markdown` (markdown), `rst` (reStructuredText),
or `latex`. (`+lhs` can be appended to `html`, `markdown`, `latex`, `html` (HTML), `latex` (LaTeX), `context` (ConTeXt), `man` (groff man),
or `rst` to indicate that the input should be treated as literate Haskell `mediawiki` (MediaWiki markup), `textile` (Textile), `org` (Emacs
source. See [Literate Haskell support](#literate-haskell-support), Org-Mode), `texinfo` (GNU Texinfo), `docbook` (DocBook XML),
below.) `opendocument` (OpenDocument XML), `odt` (OpenOffice text document),
`epub` (EPUB book), `slidy` (Slidy HTML and javascript slide show),
`s5` (S5 HTML and javascript slide show), or `rtf` (rich text
format). Note that `odt` and `epub` output will not be directed to
*stdout*; an output filename must be specified using the `-o/--output`
option. If `+lhs` is appended to `markdown`, `rst`, `latex`, or `html`,
the output will be rendered as literate Haskell source:
see [Literate Haskell support](#literate-haskell-support),
below.
`-t`, `--to`, `-w`, or `--write` *format* `-s`, `--standalone`
: specifies the output format -- the format Pandoc will : Produce output with an appropriate header and footer (e.g. a
be converting *to*. *format* can be `native`, `html`, `slidy`, `s5`, standalone HTML, LaTeX, or RTF file, not a fragment).
`docbook`, `opendocument`, `odt`, `epub`, `latex`, `context`,
`markdown`, `man`, `plain`, `mediawiki`, `texinfo`, `textile`, `org`,
`plain`, `rst`, and `rtf`. (`+lhs` can be appended to `html`,
`markdown`, `rst`, or `latex` to indicate that
the output should be treated as literate Haskell source. See
[Literate Haskell support](#literate-haskell-support), below.)
`-s` or `--standalone` `-o` *FILE*, `--output=`*FILE*
: indicates that a standalone document is to be produced (with : Write output to *FILE* instead of *stdout*. If *FILE* is
appropriate headers and footers), rather than a fragment. `-`, output will go to *stdout*. (Exception: if the output
format is `odt` or `epub`, output to stdout is disabled.)
`-o` or `--output` *filename* `-p`, `--preserve-tabs`
: sends output to *filename*. If this option is not specified, : Preserve tabs instead of converting them to spaces (the default).
or if its argument is `-`, output will be sent to stdout.
(Exception: if the output format is `odt` or `epub`, output to
stdout is disabled.)
`-p` or `--preserve-tabs` `--tab-stop=`*TABSTOP*
: causes tabs in the source text to be preserved, rather than converted : Specify the number of spaces per tab (default is 4).
to spaces (the default).
`--tab-stop` *tabstop*
: sets the number of spaces per tab to *tabstop* (defaults to 4).
`--strict` `--strict`
: specifies that strict markdown syntax is to be used, without : Use strict markdown syntax, with no pandoc extensions or variants.
pandoc's usual extensions and variants (described below). When the When the input format is HTML, this means that constructs that have no
input format is HTML, this means that constructs that have no
equivalents in standard markdown (e.g. definition lists or strikeout equivalents in standard markdown (e.g. definition lists or strikeout
text) will be parsed as raw HTML. text) will be parsed as raw HTML.
`--reference-links` `--reference-links`
: causes reference-style links to be used in markdown : Use reference-style links, rather than inline links, in writing markdown
and reStructuredText output. By default inline links are used. or reStructuredText. By default inline links are used.
`-R` or `--parse-raw` `-R`, `--parse-raw`
: causes the HTML and LaTeX readers to parse HTML codes and LaTeX : Parse untranslatable HTML codes and LaTeX environments as raw HTML
environments that it can't translate as raw HTML or LaTeX. Raw HTML can or LaTeX, instead of ignoring them. Affects only HTML and LaTeX
be printed in markdown, reStructuredText, HTML, Slidy, and S5 input. Raw HTML can be printed in markdown, reStructuredText, HTML, Slidy,
output; raw LaTeX can be printed in markdown, reStructuredText, and S5 output; raw LaTeX can be printed in markdown, reStructuredText,
LaTeX, and ConTeXt output. The default is for the readers to omit LaTeX, and ConTeXt output. The default is for the readers to omit
untranslatable HTML codes and LaTeX environments. (The LaTeX reader untranslatable HTML codes and LaTeX environments. (The LaTeX reader
does pass through untranslatable LaTeX *commands*, even if `-R` is does pass through untranslatable LaTeX *commands*, even if `-R` is not
not specified.) specified.)
`-C` or `--custom-header` *filename* `-S`, `--smart`
: can be used to specify a custom document header. Implies `--standalone`. : Produce typographically correct output, converting straight quotes
*Note: this option is deprecated. Use of `--template` is preferred.* to curly quotes, `---` and `--` to dashes, ande `...` to ellipses.
Nonbreaking spaces are inserted after certain abbreviations, such
as "Mr." (Note: This option is significant only when the input format is
`markdown` or `textile`. It is selected automatically when the input
format is `textile` or the output format is `latex` or `context`.)
`--toc` or `--table-of-contents` `-m` *URL*, `--latexmathml=`*URL*
: includes an automatically generated table of contents (or, in the : Use the [LaTeXMathML] script to display embedded TeX math in HTML output.
case of `latex`, `context`, and `rst`, an instruction to create To insert a link to a local copy of the `LaTeXMathML.js` script,
one) in the output document. This option has no effect with `man`, provide a *URL*. If no *URL* is provided, the contents of the
`docbook`, `slidy`, or `s5` output formats. script will be inserted directly into the HTML header, preserving
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 the script,
so it can be cached.
`--base-header-level` *level* `--mathml`
: specifies the base level for headers (defaults to 1). : Convert TeX math to MathML. In standalone mode, a small javascript
will be inserted that allows the MathML to be viewed on some browsers.
`--template=`*file* `--jsmath=`*URL*
: uses *file* as a custom template for the generated document. Implies : Use [jsMath] to display embedded TeX math in HTML output.
`-s`. See [Templates](#templates) below for a description The *URL* should point to the jsMath load script (e.g.
`jsMath/easy/load.js`); if provided, it will be linked to in
the header of standalone HTML documents.
`--mathjax=`*URL*
: Use [MathJax] to display embedded TeX math in HTML output.
The *URL* should point to the `MathJax.js` load script.
`--gladtex`
: Enclose TeX math in `<eq>` tags in HTML output. These can then
be processed by [gladTeX] to produce links to images of the typeset
formulas.
`--mimetex=`*URL*
: Render TeX math using the [mimeTeX] CGI script. If *URL* is not
specified, it is assumed that the script is at `/cgi-bin/mimetex.cgi`.
`--webtex=`*URL*
: Render TeX formulas using an external script that converts TeX
formulas to images. The formula will be concatenated with the URL
provided. If *URL* is not specified, the Google Chart API will be used.
`-i`, `--incremental`
: Make list items in Slidy or S5 display incrementally (one by one).
The default is for lists to be displayed all at once.
`--offline`
: Include all the CSS and javascript needed for a Slidy or S5 slide
show in the output, so that the slide show will work even when no
internet connection is available.
`--xetex`
: Create LaTeX outut suitable for processing by XeTeX.
`-N`, `--number-sections`
: Number section headings in LaTeX, ConTeXt, or HTML output.
By default, sections are not numbered.
`--section-divs`
: Wrap sections in `<div>` tags, and attach identifiers to the
enclosing `<div>` rather than the header itself.
See [Section identifiers](#header-identifiers-in-html), below.
`--no-wrap`
: Disable text wrapping in output. By default, text is wrapped
appropriately for the output format.
`--sanitize-html`
: Sanitizes HTML (in markdown or HTML input) using a whitelist.
Unsafe tags are replaced by HTML comments; unsafe attributes
are omitted. URIs in links and images are also checked against a
whitelist of URI schemes.
`--email-obfuscation=`*none|javascript|references*
: Specify a method for obfuscating `mailto:` links in HTML documents.
*none* leaves `mailto:` links as they are. *javascript* obfuscates
them using javascript. *references* obfuscates them by printing their
letters as decimal or hexadecimal character references.
If `--strict` is specified, *references* is used regardless of the
presence of this option.
`--id-prefix`=*STRING*
: Specify a prefix to be added to all automatically generated identifiers
in HTML output. This is useful for preventing duplicate identifiers
when generating fragments to be included in other pages.
`--indented-code-classes=`*CLASSES*
: Specify classes to use for indented code blocks--for example,
`perl,numberLines` or `haskell`. Multiple classes may be separated
by spaces or commas.
`--toc`, `--table-of-contents`
: Include 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 on `man`,
`docbook`, `slidy`, or `s5` output.
`--base-header-level=`*LEVEL*
: Specify the base level for headers (defaults to 1).
`--template=`*FILE*
: Use *FILE* as a custom template for the generated document. Implies
`--standalone`. See [Templates](#templates) below for a description
of template syntax. If this option is not used, a default of template syntax. If this option is not used, a default
template appropriate for the output format will be used. See also template appropriate for the output format will be used. See also
`-D/--print-default-template`. `-D/--print-default-template`.
`-V` *key=val*, `--variable=`*key:val* `-V` *KEY=VAL*, `--variable=`*KEY:VAL*
: sets the template variable *key* to the value *val* when rendering the : Set the template variable *KEY* to the value *VAL* when rendering the
document in standalone mode. This is only useful when the document in standalone mode. This is only useful when the
`--template` option is used to specify a custom template, since `--template` option is used to specify a custom template, since
pandoc automatically sets the variables used in the default pandoc automatically sets the variables used in the default
templates. templates.
`-c` or `--css` *filename* `-c` *URL*, `--css=`*URL*
: allows the user to specify a custom stylesheet that will be linked to : Link to a CSS style sheet.
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* `-H` *FILE*, `--include-in-header=`*FILE*
: includes the contents of *filename* (verbatim) at the end of the : Include contents of *FILE*, verbatim, at the end of the header.
document header. This can be used, for example, to include special This can be used, for example, to include special
CSS or javascript in HTML documents. This option can be used CSS or javascript in HTML documents. This option can be used
repeatedly to include multiple files in the header. They will be repeatedly to include multiple files in the header. They will be
included in the order specified. Implies `--standalone`. included in the order specified. Implies `--standalone`.
`-B` or `--include-before-body` *filename* `-B` *FILE*, `--include-before-body=`*FILE*
: includes the contents of *filename* (verbatim) at the beginning of : Include contents of *FILE*, verbatim, at the beginning of the
the document body (e.g. after the `<body>` tag in HTML, or the document body (e.g. after the `<body>` tag in HTML, or the
`\begin{document}` command in LaTeX). This can be used to include `\begin{document}` command in LaTeX). This can be used to include
navigation bars or banners in HTML documents. This option can be navigation bars or banners in HTML documents. This option can be
used repeatedly to include multiple files. They will be included in used repeatedly to include multiple files. They will be included in
the order specified. Implies `--standalone`. the order specified. Implies `--standalone`.
`-A` or `--include-after-body` *filename* `-A` *FILE*, `--include-after-body=`*FILE*
: includes the contents of *filename* (verbatim) at the end of : Include contents of *FILE*, verbatim, at the end of the document
the document body (before the `</body>` tag in HTML, or the body (before the `</body>` tag in HTML, or the
`\end{document}` command in LaTeX). This option can be be used `\end{document}` command in LaTeX). This option can be be used
repeatedly to include multiple files. They will be included in the repeatedly to include multiple files. They will be included in the
order specified. Implies `--standalone`. order specified. Implies `--standalone`.
`--reference-odt` *filename* `-C` *FILE*, `--custom-header=`*FILE*
: uses the specified file as a style reference in producing an ODT. : Use contents of *FILE* as the document header. Implies `--standalone`.
*Note: This option is deprecated. Users should transition to using
`--template` instead.*
`--reference-odt=`*FILE*
: Use the specified file as a style reference in producing an ODT.
For best results, the reference ODT should be a modified version For best results, the reference ODT should be a modified version
of an ODT produced using pandoc. The contents of the reference ODT of an ODT produced using pandoc. The contents of the reference ODT
are ignored, but its stylesheets are used in the new ODT. If no are ignored, but its stylesheets are used in the new ODT. If no
reference ODT is specified on the command line, pandoc will look reference ODT is specified on the command line, pandoc will look
for a file `reference.odt` in the user data directory (see for a file `reference.odt` in the user data directory (see
`--data-dir`, below). If it is not found there, sensible defaults `--data-dir`). If this is not found either, sensible defaults will be
will be used. used.
`--epub-stylesheet` *filename* `--epub-stylesheet=`*FILE*
: uses the specified CSS file to style the EPUB. If no stylesheet : Use the specified CSS file to style the EPUB. If no stylesheet
is specified, pandoc will look for a file `epub.css` in the is specified, pandoc will look for a file `epub.css` in the
user data directory (see `--data-dir`, below). If it is not user data directory (see `--data-dir`, below). If it is not
found there, sensible defaults will be used. found there, sensible defaults will be used.
`--epub-metadata` *filename* `--epub-metadata=`*FILE*
: looks in the specified XML file for metadata for the EPUB. : Look in the specified XML file for metadata for the EPUB.
The file should contain a series of [Dublin Core elements], The file should contain a series of Dublin Core elements,
for example: as documented at <http://dublincore.org/documents/dces/>.
For example:
<dc:rights>Creative Commons</dc:rights> <dc:rights>Creative Commons</dc:rights>
<dc:language>es-AR</dc:language> <dc:language>es-AR</dc:language>
@ -310,118 +404,18 @@ For further documentation, see the `pandoc(1)` man page.
`<dc:identifier id="BookId">` (a randomly generated UUID). Any of `<dc:identifier id="BookId">` (a randomly generated UUID). Any of
these may be overridden by elements in the metadata file. these may be overridden by elements in the metadata file.
`-D` or `--print-default-template` *format* `-D` *FORMAT*, `--print-default-template=`*FORMAT*
: prints the default template for an output *format*. (See `-t` : Print the default template for an output *FORMAT*. (See `-t`
for a list of possible *format*s.) for a list of possible *FORMAT*s.)
`-T` or `--title-prefix` *string* `-T` *STRING*, `--title-prefix=*STRING*
: includes *string* as a prefix at the beginning of the title that : Specify *STRING* as a prefix at the beginning of the title
appears in the HTML header (but not in the title as it appears at that appears in the HTML header (but not in the title as it
the beginning of the HTML body). (See below on appears at the beginning of the HTML body). Implies
[Title Blocks](#title-blocks).) Implies `--standalone`. `--standalone`.
`-S` or `--smart` `--bibliography=`*FILE*
: causes `pandoc` to produce typographically correct output, along the : Specify bibliography database to be used in resolving
lines of John Gruber's [Smartypants]. Straight quotes are converted
to curly quotes, `---` to dashes, and `...` to ellipses. Nonbreaking
spaces are inserted after certain abbreviations, such as "Mr."
(Note: This option is only significant when the input format is
`markdown`. It is selected automatically when the output format is
`latex` or `context`.)
`-m`*[url]* or `--latexmathml`*[=url]*
: causes `pandoc` to use the [LaTeXMathML] script to display
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.
`--mathml`
: causes `pandoc` to convert all TeX math to MathML.
In standalone mode, a small javascript will be inserted that allows
the MathML to be viewed on some browsers.
`--jsmath`*=[url]*
: causes `pandoc` to use the [jsMath] script to display
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, 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.
`--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 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.
`-N` or `--number-sections`
: 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.
`--sanitize-html`
: sanitizes HTML (in markdown or HTML input) using a whitelist.
Unsafe tags are replaced by HTML comments; unsafe attributes
are omitted. URIs in links and images are also checked against a
whitelist of URI schemes.
`--email-obfuscation`*=none|javascript|references*
: specifies a method for obfuscating `mailto:` links in HTML documents.
*none* leaves `mailto:` links as they are. *javascript* obfuscates
them using javascript. *references* obfuscates them by printing their
letters as decimal or hexadecimal character references. If `--strict`
is specified, *references* is used regardless of the presence
of this option.
`--id-prefix`*=string*
: specifies a prefix to be added to all automatically generated identifiers
in HTML output. This is useful for preventing duplicate identifiers
when generating fragments to be included in other pages.
`--indented-code-classes`*=classes*
: specifies classes to use for indented code blocks--for example,
`perl,numberLines` or `haskell`. Multiple classes may be separated
by spaces or commas.
`--bibliography`*=FILE*
: specifies bibliography database to be used in resolving
citations. The database type will be determined from the citations. The database type will be determined from the
extension of *FILE*, which may be `.mods` (MODS format), extension of *FILE*, which may be `.mods` (MODS format),
`.bib` (BibTeX format), `.bbx` (BibLaTeX format), `.bib` (BibTeX format), `.bbx` (BibLaTeX format),
@ -431,8 +425,8 @@ For further documentation, see the `pandoc(1)` man page.
or `.json` (citeproc JSON). If you want to use multiple or `.json` (citeproc JSON). If you want to use multiple
bibliographies, just use this option repeatedly. bibliographies, just use this option repeatedly.
`--csl`*=FILE* `--csl=`*FILE*
: specifies [CSL] style to be used in formatting citations and : Specify [CSL] style to be used in formatting citations and
the bibliography. If *FILE* is not found, pandoc will look the bibliography. If *FILE* is not found, pandoc will look
for it in for it in
@ -447,8 +441,8 @@ For further documentation, see the `pandoc(1)` man page.
user data directory (see `--data-dir`), or, if that is user data directory (see `--data-dir`), or, if that is
not present, the Chicago author-date style. not present, the Chicago author-date style.
`--data-dir`*=directory* `--data-dir=`*DIRECTORY*
: specifies the user data directory to search for pandoc data files. : Specify the user data directory to search for pandoc data files.
If this option is not specified, the default user data directory If this option is not specified, the default user data directory
will be used: will be used:
@ -463,24 +457,17 @@ For further documentation, see the `pandoc(1)` man page.
normal defaults. normal defaults.
`--dump-args` `--dump-args`
: is intended to make it easier to create wrapper scripts that use : Print information about command-line arguments to *stdout*, then exit.
Pandoc. It causes Pandoc to dump information about the arguments This option is intended primarily for use in wrapper scripts.
with which it was called to stdout, then exit. The first line The first line of output contains the name of the output file specified
printed is the name of the output file specified using the `-o` with the `-o` option, or `-` (for *stdout*) if no output file was
or `--output` option, or `-` if output would go to stdout. The specified. The remaining lines contain the command-line arguments,
remaining lines, if any, list command-line arguments. These will one per line, in the order they appear. These do not include regular
include the names of input files and any special options passed Pandoc options and their arguments, but do include any options appearing
after ` -- ` on the command line. So, for example, after a `--` separator at the end of the line.
pandoc --dump-args -o foo.html -s foo.txt \
appendix.txt -- -e latin1
will cause the following to be printed to stdout:
foo.html foo.txt appendix.txt -e latin1
`--ignore-args` `--ignore-args`
: causes Pandoc to ignore all command-line arguments. : Ignore command-line arguments (for use in wrapper scripts).
Regular Pandoc options are not ignored. Thus, for example, Regular Pandoc options are not ignored. Thus, for example,
pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1 pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
@ -489,19 +476,17 @@ For further documentation, see the `pandoc(1)` man page.
pandoc -o foo.html -s pandoc -o foo.html -s
`-v` or `--version` `-v`, `--version`
: prints the version number to STDERR. : Print version.
`-h` or `--help` `-h`, `--help`
: prints a usage message to STDERR. : Show usage message.
[Smartypants]: http://daringfireball.net/projects/smartypants/
[LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/ [LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/
[jsMath]: http://www.math.union.edu/~dpvc/jsmath/ [jsMath]: http://www.math.union.edu/~dpvc/jsmath/
[MathJax]: http://www.mathjax.org/ [MathJax]: http://www.mathjax.org/
[gladTeX]: http://www.math.uio.no/~martingu/gladtex/index.html [gladTeX]: http://www.math.uio.no/~martingu/gladtex/index.html
[mimeTeX]: http://www.forkosh.com/mimetex.html [mimeTeX]: http://www.forkosh.com/mimetex.html
[Dublin Core elements]: http://dublincore.org/documents/dces/
[CSL]: http://CitationStyles.org [CSL]: http://CitationStyles.org
Templates Templates

237
man/man1/pandoc.1.md
View file

@ -62,14 +62,16 @@ should pipe input and output through `iconv`:
# OPTIONS # OPTIONS
-f *FORMAT*, -r *FORMAT*, \--from=*FORMAT*, \--read=*FORMAT* `-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
: Specify input format. *FORMAT* can be : Specify input format. *FORMAT* can be
`native` (native Haskell), `markdown` (markdown or plain text), `native` (native Haskell), `markdown` (markdown or plain text),
`textile` (Textile), `rst` (reStructuredText), `html` (HTML), `textile` (Textile), `rst` (reStructuredText), `html` (HTML),
or `latex` (LaTeX). If `+lhs` is appended to `markdown`, `rst`, or `latex` (LaTeX). If `+lhs` is appended to `markdown`, `rst`,
or `latex`, the input will be treated as literate Haskell source. or `latex`, the input will be treated as literate Haskell source:
see [Literate Haskell support](#literate-haskell-support),
below.
-t *FORMAT*, -w *FORMAT*, \--to=*FORMAT*, \--write=*FORMAT* `-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT*
: Specify output format. *FORMAT* can be `native` (native Haskell), : Specify output format. *FORMAT* can be `native` (native Haskell),
`plain` (plain text), `markdown` (markdown), `rst` (reStructuredText), `plain` (plain text), `markdown` (markdown), `rst` (reStructuredText),
`html` (HTML), `latex` (LaTeX), `context` (ConTeXt), `man` (groff man), `html` (HTML), `latex` (LaTeX), `context` (ConTeXt), `man` (groff man),
@ -81,100 +83,122 @@ should pipe input and output through `iconv`:
format). Note that `odt` and `epub` output will not be directed to format). Note that `odt` and `epub` output will not be directed to
*stdout*; an output filename must be specified using the `-o/--output` *stdout*; an output filename must be specified using the `-o/--output`
option. If `+lhs` is appended to `markdown`, `rst`, `latex`, or `html`, option. If `+lhs` is appended to `markdown`, `rst`, `latex`, or `html`,
the output will be rendered as literate Haskell source. the output will be rendered as literate Haskell source:
see [Literate Haskell support](#literate-haskell-support),
below.
-s, \--standalone `-s`, `--standalone`
: Produce output with an appropriate header and footer (e.g. a : Produce output with an appropriate header and footer (e.g. a
standalone HTML, LaTeX, or RTF file, not a fragment). standalone HTML, LaTeX, or RTF file, not a fragment).
-o *FILE*, \--output=*FILE* `-o` *FILE*, `--output=`*FILE*
: Write output to *FILE* instead of *stdout*. If *FILE* is : Write output to *FILE* instead of *stdout*. If *FILE* is
\``-`', output will go to *stdout*. `-`, output will go to *stdout*. (Exception: if the output
format is `odt` or `epub`, output to stdout is disabled.)
-p, \--preserve-tabs `-p`, `--preserve-tabs`
: Preserve tabs instead of converting them to spaces. : Preserve tabs instead of converting them to spaces (the default).
\--tab-stop=*TABSTOP* `--tab-stop=`*TABSTOP*
: Specify tab stop (default is 4). : Specify the number of spaces per tab (default is 4).
\--strict `--strict`
: Use strict markdown syntax, with no extensions or variants. : Use strict markdown syntax, with no pandoc extensions or variants.
When the input format is HTML, this means that constructs that have no
equivalents in standard markdown (e.g. definition lists or strikeout
text) will be parsed as raw HTML.
\--reference-links `--reference-links`
: Use reference-style links, rather than inline links, in writing markdown : Use reference-style links, rather than inline links, in writing markdown
or reStructuredText. or reStructuredText. By default inline links are used.
-R, \--parse-raw `-R`, `--parse-raw`
: Parse untranslatable HTML codes and LaTeX environments as raw HTML : Parse untranslatable HTML codes and LaTeX environments as raw HTML
or LaTeX, instead of ignoring them. or LaTeX, instead of ignoring them. Affects only HTML and LaTeX
input. Raw HTML can 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.)
-S, \--smart `-S`, `--smart`
: Use smart quotes, dashes, and ellipses. (This option is significant : Produce typographically correct output, converting straight quotes
only when the input format is `markdown`. It is selected automatically to curly quotes, `---` and `--` to dashes, ande `...` to ellipses.
when the output format is `latex` or `context`.) Nonbreaking spaces are inserted after certain abbreviations, such
as "Mr." (Note: This option is significant only when the input format is
`markdown` or `textile`. It is selected automatically when the input
format is `textile` or the output format is `latex` or `context`.)
-m*URL*, \--latexmathml=*URL* `-m` *URL*, `--latexmathml=`*URL*
: Use LaTeXMathML to display embedded TeX math in HTML output. : Use the [LaTeXMathML] script to display embedded TeX math in HTML output.
To insert a link to a local copy of the `LaTeXMathML.js` script, To insert a link to a local copy of the `LaTeXMathML.js` script,
provide a *URL*. If no *URL* is provided, the contents of the provide a *URL*. If no *URL* is provided, the contents of the
script will be inserted directly into the HTML header. script will be inserted directly into the HTML header, preserving
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 the script,
so it can be cached.
\--mathml `--mathml`
: Convert TeX math to MathML. In standalone mode, a small javascript : Convert TeX math to MathML. In standalone mode, a small javascript
will be inserted that allows the MathML to be viewed on some browsers. will be inserted that allows the MathML to be viewed on some browsers.
\--jsmath=*URL* `--jsmath=`*URL*
: Use jsMath to display embedded TeX math in HTML output. : Use [jsMath] to display embedded TeX math in HTML output.
The *URL* should point to the jsMath load script; if provided, The *URL* should point to the jsMath load script (e.g.
it will be linked to in the header of standalone HTML documents. `jsMath/easy/load.js`); if provided, it will be linked to in
the header of standalone HTML documents.
\--mathjax=*URL* `--mathjax=`*URL*
: Use MathJax to display embedded TeX math in HTML output. : Use [MathJax] to display embedded TeX math in HTML output.
The *URL* should point to the `MathJax.js` load script. The *URL* should point to the `MathJax.js` load script.
\--gladtex `--gladtex`
: Enclose TeX math in `<eq>` tags in HTML output. These can then : Enclose TeX math in `<eq>` tags in HTML output. These can then
be processed by gladTeX to produce links to images of the typeset be processed by [gladTeX] to produce links to images of the typeset
formulas. formulas.
\--mimetex=*URL* `--mimetex=`*URL*
: Render TeX math using the mimeTeX CGI script. If *URL* is not specified, : Render TeX math using the [mimeTeX] CGI script. If *URL* is not
it is assumed that the script is at `/cgi-bin/mimetex.cgi`. specified, it is assumed that the script is at `/cgi-bin/mimetex.cgi`.
\--webtex=*URL* `--webtex=`*URL*
: Render TeX math using an external script. The formula will be : Render TeX formulas using an external script that converts TeX
concatenated with the URL provided. If *URL* is not specified, the formulas to images. The formula will be concatenated with the URL
Google Chart API will be used. provided. If *URL* is not specified, the Google Chart API will be used.
-i, \--incremental `-i`, `--incremental`
: Make list items in Slidy or S5 display incrementally (one by one). : Make list items in Slidy or S5 display incrementally (one by one).
The default is for lists to be displayed all at once.
\--offline `--offline`
: Include all the CSS and javascript needed for a Slidy or S5 slide : Include all the CSS and javascript needed for a Slidy or S5 slide
show in the output, so that the slide show will work even when no show in the output, so that the slide show will work even when no
internet connection is available. internet connection is available.
\--xetex `--xetex`
: Create LaTeX outut suitable for processing by XeTeX. : Create LaTeX outut suitable for processing by XeTeX.
-N, \--number-sections `-N`, `--number-sections`
: Number section headings in LaTeX, ConTeXt, or HTML output. : Number section headings in LaTeX, ConTeXt, or HTML output.
(Default is not to number them.) By default, sections are not numbered.
\--section-divs `--section-divs`
: Wrap sections in `<div>` tags, and attach identifiers to the : Wrap sections in `<div>` tags, and attach identifiers to the
enclosing `<div>` rather than the header itself. enclosing `<div>` rather than the header itself.
See [Section identifiers](#header-identifiers-in-html), below.
\--no-wrap `--no-wrap`
: Disable text wrapping in output. (Default is to wrap text.) : Disable text wrapping in output. By default, text is wrapped
appropriately for the output format.
\--sanitize-html `--sanitize-html`
: Sanitizes HTML (in markdown or HTML input) using a whitelist. : Sanitizes HTML (in markdown or HTML input) using a whitelist.
Unsafe tags are replaced by HTML comments; unsafe attributes Unsafe tags are replaced by HTML comments; unsafe attributes
are omitted. URIs in links and images are also checked against a are omitted. URIs in links and images are also checked against a
whitelist of URI schemes. whitelist of URI schemes.
\--email-obfuscation=*none|javascript|references* `--email-obfuscation=`*none|javascript|references*
: Specify a method for obfuscating `mailto:` links in HTML documents. : Specify a method for obfuscating `mailto:` links in HTML documents.
*none* leaves `mailto:` links as they are. *javascript* obfuscates *none* leaves `mailto:` links as they are. *javascript* obfuscates
them using javascript. *references* obfuscates them by printing their them using javascript. *references* obfuscates them by printing their
@ -182,56 +206,70 @@ should pipe input and output through `iconv`:
If `--strict` is specified, *references* is used regardless of the If `--strict` is specified, *references* is used regardless of the
presence of this option. presence of this option.
\--id-prefix*=string* `--id-prefix`=*STRING*
: Specify a prefix to be added to all automatically generated identifiers : Specify a prefix to be added to all automatically generated identifiers
in HTML output. This is useful for preventing duplicate identifiers in HTML output. This is useful for preventing duplicate identifiers
when generating fragments to be included in other pages. when generating fragments to be included in other pages.
\--indented-code-classes*=classes* `--indented-code-classes=`*CLASSES*
: Specify classes to use for indented code blocks--for example, : Specify classes to use for indented code blocks--for example,
`perl,numberLines` or `haskell`. Multiple classes may be separated `perl,numberLines` or `haskell`. Multiple classes may be separated
by spaces or commas. by spaces or commas.
\--toc, \--table-of-contents `--toc`, `--table-of-contents`
: Include an automatically generated table of contents (HTML, markdown, : Include an automatically generated table of contents (or, in
RTF) or an instruction to create one (LaTeX, reStructuredText). the case of `latex`, `context`, and `rst`, an instruction to create
This option has no effect on man, DocBook, Slidy, or S5 output. one) in the output document. This option has no effect on `man`,
`docbook`, `slidy`, or `s5` output.
\--base-header-level=*LEVEL* `--base-header-level=`*LEVEL*
: Specify the base level for headers (defaults to 1). : Specify the base level for headers (defaults to 1).
\--template=*FILE* `--template=`*FILE*
: Use *FILE* as a custom template for the generated document. Implies : Use *FILE* as a custom template for the generated document. Implies
`-s`. See TEMPLATES below for a description of template syntax. If `--standalone`. See [Templates](#templates) below for a description
this option is not used, a default template appropriate for the of template syntax. If this option is not used, a default
output format will be used. See also `-D/--print-default-template`. template appropriate for the output format will be used. See also
`-D/--print-default-template`.
-V KEY=VAL, \--variable=*KEY:VAL* `-V` *KEY=VAL*, `--variable=`*KEY:VAL*
: Set the template variable KEY to the value VAL when rendering the : Set the template variable *KEY* to the value *VAL* when rendering the
document in standalone mode. This is only useful when the document in standalone mode. This is only useful when the
`--template` option is used to specify a custom template, since `--template` option is used to specify a custom template, since
pandoc automatically sets the variables used in the default pandoc automatically sets the variables used in the default
templates. templates.
-c *CSS*, \--css=*CSS* `-c` *URL*, `--css=`*URL*
: Link to a CSS style sheet. *CSS* is the pathname of the style sheet. : Link to a CSS style sheet.
-H *FILE*, \--include-in-header=*FILE* `-H` *FILE*, `--include-in-header=`*FILE*
: Include contents of *FILE* at the end of the header. Implies `-s`. : Include contents of *FILE*, verbatim, at the end of the header.
This can be used, for example, to include special
CSS or javascript in HTML documents. This option can be used
repeatedly to include multiple files in the header. They will be
included in the order specified. Implies `--standalone`.
-B *FILE*, \--include-before-body=*FILE* `-B` *FILE*, `--include-before-body=`*FILE*
: Include contents of *FILE* at the beginning of the document body. : Include contents of *FILE*, verbatim, at the beginning of the
Implies `-s`. document body (e.g. after the `<body>` tag in HTML, or the
`\begin{document}` command in LaTeX). This can be used to include
navigation bars or banners in HTML documents. This option can be
used repeatedly to include multiple files. They will be included in
the order specified. Implies `--standalone`.
-A *FILE*, \--include-after-body=*FILE* `-A` *FILE*, `--include-after-body=`*FILE*
: Include contents of *FILE* at the end of the document body. : Include contents of *FILE*, verbatim, at the end of the document
Implies `-s`. body (before the `</body>` tag in HTML, or the
`\end{document}` command in LaTeX). This option can be be used
repeatedly to include multiple files. They will be included in the
order specified. Implies `--standalone`.
-C *FILE*, \--custom-header=*FILE* `-C` *FILE*, `--custom-header=`*FILE*
: Use contents of *FILE* as the document header. *Note: This option is : Use contents of *FILE* as the document header. Implies `--standalone`.
deprecated. Users should transition to using `--template` instead.* *Note: This option is deprecated. Users should transition to using
`--template` instead.*
\--reference-odt=*filename* `--reference-odt=`*FILE*
: Use the specified file as a style reference in producing an ODT. : Use the specified file as a style reference in producing an ODT.
For best results, the reference ODT should be a modified version For best results, the reference ODT should be a modified version
of an ODT produced using pandoc. The contents of the reference ODT of an ODT produced using pandoc. The contents of the reference ODT
@ -241,16 +279,17 @@ should pipe input and output through `iconv`:
`--data-dir`). If this is not found either, sensible defaults will be `--data-dir`). If this is not found either, sensible defaults will be
used. used.
\--epub-stylesheet=*filename* `--epub-stylesheet=`*FILE*
: Use the specified CSS file to style the EPUB. If no stylesheet : Use the specified CSS file to style the EPUB. If no stylesheet
is specified, pandoc will look for a file `epub.css` in the is specified, pandoc will look for a file `epub.css` in the
user data directory (see `--data-dir`, below). If it is not user data directory (see `--data-dir`, below). If it is not
found there, sensible defaults will be used. found there, sensible defaults will be used.
\--epub-metadata=*filename* `--epub-metadata=`*FILE*
: Look in the specified XML file for metadata for the EPUB. : Look in the specified XML file for metadata for the EPUB.
The file should contain a series of Dublin Core elements The file should contain a series of Dublin Core elements,
(http://dublincore.org/documents/dces/), for example: as documented at <http://dublincore.org/documents/dces/>.
For example:
<dc:rights>Creative Commons</dc:rights> <dc:rights>Creative Commons</dc:rights>
<dc:language>es-AR</dc:language> <dc:language>es-AR</dc:language>
@ -261,14 +300,17 @@ should pipe input and output through `iconv`:
`<dc:identifier id="BookId">` (a randomly generated UUID). Any of `<dc:identifier id="BookId">` (a randomly generated UUID). Any of
these may be overridden by elements in the metadata file. these may be overridden by elements in the metadata file.
-D *FORMAT*, \--print-default-template=*FORMAT* `-D` *FORMAT*, `--print-default-template=`*FORMAT*
: Print the default template for an output *FORMAT*. (See `-t` : Print the default template for an output *FORMAT*. (See `-t`
for a list of possible *FORMAT*s.) for a list of possible *FORMAT*s.)
-T *STRING*, \--title-prefix=*STRING* `-T` *STRING*, `--title-prefix=*STRING*
: Specify *STRING* as a prefix to the HTML window title. : Specify *STRING* as a prefix at the beginning of the title
that appears in the HTML header (but not in the title as it
appears at the beginning of the HTML body). Implies
`--standalone`.
\--bibliography=*FILE* `--bibliography=`*FILE*
: Specify bibliography database to be used in resolving : Specify bibliography database to be used in resolving
citations. The database type will be determined from the citations. The database type will be determined from the
extension of *FILE*, which may be `.mods` (MODS format), extension of *FILE*, which may be `.mods` (MODS format),
@ -279,7 +321,7 @@ should pipe input and output through `iconv`:
or `.json` (citeproc JSON). If you want to use multiple or `.json` (citeproc JSON). If you want to use multiple
bibliographies, just use this option repeatedly. bibliographies, just use this option repeatedly.
\--csl=*FILE* `--csl=`*FILE*
: Specify [CSL] style to be used in formatting citations and : Specify [CSL] style to be used in formatting citations and
the bibliography. If *FILE* is not found, pandoc will look the bibliography. If *FILE* is not found, pandoc will look
for it in for it in
@ -295,7 +337,7 @@ should pipe input and output through `iconv`:
user data directory (see `--data-dir`), or, if that is user data directory (see `--data-dir`), or, if that is
not present, the Chicago author-date style. not present, the Chicago author-date style.
\--data-dir*=DIRECTORY* `--data-dir=`*DIRECTORY*
: Specify the user data directory to search for pandoc data files. : Specify the user data directory to search for pandoc data files.
If this option is not specified, the default user data directory If this option is not specified, the default user data directory
will be used: will be used:
@ -310,17 +352,17 @@ should pipe input and output through `iconv`:
or `s5` directory placed in this directory will override pandoc's or `s5` directory placed in this directory will override pandoc's
normal defaults. normal defaults.
\--dump-args `--dump-args`
: Print information about command-line arguments to *stdout*, then exit. : Print information about command-line arguments to *stdout*, then exit.
This option is intended primarily for use in wrapper scripts.
The first line of output contains the name of the output file specified The first line of output contains the name of the output file specified
with the `-o` option, or \``-`' (for *stdout*) if no output file was with the `-o` option, or `-` (for *stdout*) if no output file was
specified. The remaining lines contain the command-line arguments, specified. The remaining lines contain the command-line arguments,
one per line, in the order they appear. These do not include regular one per line, in the order they appear. These do not include regular
Pandoc options and their arguments, but do include any options appearing Pandoc options and their arguments, but do include any options appearing
after a \``--`' separator at the end of the line. after a `--` separator at the end of the line.
This option is intended primarily for use in wrapper scripts.
\--ignore-args `--ignore-args`
: Ignore command-line arguments (for use in wrapper scripts). : Ignore command-line arguments (for use in wrapper scripts).
Regular Pandoc options are not ignored. Thus, for example, Regular Pandoc options are not ignored. Thus, for example,
@ -330,12 +372,19 @@ should pipe input and output through `iconv`:
pandoc -o foo.html -s pandoc -o foo.html -s
-v, \--version `-v`, `--version`
: Print version. : Print version.
-h, \--help `-h`, `--help`
: Show usage message. : Show usage message.
[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
[CSL]: http://CitationStyles.org
# TEMPLATES # TEMPLATES
When the `-s/--standalone` option is used, pandoc uses a template to When the `-s/--standalone` option is used, pandoc uses a template to