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
====================
Various command-line options can be used to customize the output.
For further documentation, see the `pandoc(1)` man page.
`-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
: 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*
: specifies the input format (the format Pandoc will be converting
*from*). *format* can be `native`, `markdown`, `textile`, `rst`, `html`,
or `latex`. (`+lhs` can be appended to `html`, `markdown`, `latex`,
or `rst` to indicate that the input should be treated as literate Haskell
source. See [Literate Haskell support](#literate-haskell-support),
below.)
`-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT*
: Specify output format. *FORMAT* can be `native` (native Haskell),
`plain` (plain text), `markdown` (markdown), `rst` (reStructuredText),
`html` (HTML), `latex` (LaTeX), `context` (ConTeXt), `man` (groff man),
`mediawiki` (MediaWiki markup), `textile` (Textile), `org` (Emacs
Org-Mode), `texinfo` (GNU Texinfo), `docbook` (DocBook XML),
`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*
: specifies the output format -- the format Pandoc will
be converting *to*. *format* can be `native`, `html`, `slidy`, `s5`,
`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`, `--standalone`
: Produce output with an appropriate header and footer (e.g. a
standalone HTML, LaTeX, or RTF file, not a fragment).
`-s` or `--standalone`
: indicates that a standalone document is to be produced (with
appropriate headers and footers), rather than a fragment.
`-o` *FILE*, `--output=`*FILE*
: Write output to *FILE* instead of *stdout*. If *FILE* is
`-`, output will go to *stdout*. (Exception: if the output
format is `odt` or `epub`, output to stdout is disabled.)
`-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` or `epub`, output to
stdout is disabled.)
`-p`, `--preserve-tabs`
: Preserve tabs instead of converting them to spaces (the default).
`-p` or `--preserve-tabs`
: causes tabs in the source text to be preserved, rather than converted
to spaces (the default).
`--tab-stop` *tabstop*
: sets the number of spaces per tab to *tabstop* (defaults to 4).
`--tab-stop=`*TABSTOP*
: Specify the number of spaces per tab (default is 4).
`--strict`
: specifies that strict markdown syntax is to be used, without
pandoc's usual extensions and variants (described below). When the
input format is HTML, this means that constructs that have no
: 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`
: causes reference-style links to be used in markdown
and reStructuredText output. By default inline links are used.
: Use reference-style links, rather than inline links, in writing markdown
or reStructuredText. By default inline links are used.
`-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, Slidy, and S5
output; raw LaTeX can be printed in markdown, reStructuredText,
`-R`, `--parse-raw`
: Parse untranslatable HTML codes and LaTeX environments as raw HTML
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.)
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`.
*Note: this option is deprecated. Use of `--template` is preferred.*
`-S`, `--smart`
: Produce typographically correct output, converting straight quotes
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`
: 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`, `slidy`, or `s5` output formats.
`-m` *URL*, `--latexmathml=`*URL*
: 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,
provide a *URL*. If no *URL* is provided, the contents of the
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*
: specifies the base level for headers (defaults to 1).
`--mathml`
: 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*
: uses *file* as a custom template for the generated document. Implies
`-s`. See [Templates](#templates) below for a description
`--jsmath=`*URL*
: Use [jsMath] to display embedded TeX math in HTML output.
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
template appropriate for the output format will be used. See also
`-D/--print-default-template`.
`-V` *key=val*, `--variable=`*key:val*
: sets the template variable *key* to the value *val* when rendering the
`-V` *KEY=VAL*, `--variable=`*KEY:VAL*
: Set the template variable *KEY* to the value *VAL* when rendering the
document in standalone mode. This is only useful when the
`--template` option is used to specify a custom template, since
pandoc automatically sets the variables used in the default
templates.
`-c` or `--css` *filename*
: allows the user to specify a custom stylesheet that will be linked to
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`.
`-c` *URL*, `--css=`*URL*
: Link to a CSS style sheet.
`-H` or `--include-in-header` *filename*
: includes the contents of *filename* (verbatim) at the end of the
document header. This can be used, for example, to include special
`-H` *FILE*, `--include-in-header=`*FILE*
: 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` or `--include-before-body` *filename*
: includes the contents of *filename* (verbatim) at the beginning of
the document body (e.g. after the `<body>` tag in HTML, or the
`-B` *FILE*, `--include-before-body=`*FILE*
: Include contents of *FILE*, verbatim, at the beginning of the
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` or `--include-after-body` *filename*
: includes the contents of *filename* (verbatim) at the end of
the document body (before the `</body>` tag in HTML, or the
`-A` *FILE*, `--include-after-body=`*FILE*
: Include contents of *FILE*, verbatim, at the end of the document
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`.
`--reference-odt` *filename*
: uses the specified file as a style reference in producing an ODT.
`-C` *FILE*, `--custom-header=`*FILE*
: 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
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
reference ODT is specified on the command line, pandoc will look
for a file `reference.odt` in the user data directory (see
`--data-dir`, below). If it is not found there, sensible defaults
will be used.
`--data-dir`). If this is not found either, sensible defaults will be
used.
`--epub-stylesheet` *filename*
: uses the specified CSS file to style the EPUB. If no stylesheet
`--epub-stylesheet=`*FILE*
: Use 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:
`--epub-metadata=`*FILE*
: Look in the specified XML file for metadata for the EPUB.
The file should contain a series of Dublin Core elements,
as documented at <http://dublincore.org/documents/dces/>.
For example:
<dc:rights>Creative Commons</dc:rights>
<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
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.)
`-D` *FORMAT*, `--print-default-template=`*FORMAT*
: Print the default template for an output *FORMAT*. (See `-t`
for a list of possible *FORMAT*s.)
`-T` or `--title-prefix` *string*
: includes *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). (See below on
[Title Blocks](#title-blocks).) Implies `--standalone`.
`-T` *STRING*, `--title-prefix=*STRING*
: 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`.
`-S` or `--smart`
: causes `pandoc` to produce typographically correct output, along the
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
`--bibliography=`*FILE*
: Specify bibliography database to be used in resolving
citations. The database type will be determined from the
extension of *FILE*, which may be `.mods` (MODS 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
bibliographies, just use this option repeatedly.
`--csl`*=FILE*
: specifies [CSL] style to be used in formatting citations and
`--csl=`*FILE*
: Specify [CSL] style to be used in formatting citations and
the bibliography. If *FILE* is not found, pandoc will look
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
not present, the Chicago author-date style.
`--data-dir`*=directory*
: specifies the user data directory to search for pandoc data files.
`--data-dir=`*DIRECTORY*
: Specify the user data directory to search for pandoc data files.
If this option is not specified, the default user data directory
will be used:
@ -463,24 +457,17 @@ For further documentation, see the `pandoc(1)` man page.
normal defaults.
`--dump-args`
: is intended to make it easier to create wrapper scripts that use
Pandoc. It causes Pandoc to dump information about the arguments
with which it was called to stdout, then exit. The first line
printed is the name of the output file specified using the `-o`
or `--output` option, or `-` if output would go to stdout. The
remaining lines, if any, list command-line arguments. These will
include the names of input files and any special options passed
after ` -- ` on the command line. So, for example,
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
: 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
with the `-o` option, or `-` (for *stdout*) if no output file was
specified. The remaining lines contain the command-line arguments,
one per line, in the order they appear. These do not include regular
Pandoc options and their arguments, but do include any options appearing
after a `--` separator at the end of the line.
`--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,
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
`-v` or `--version`
: prints the version number to STDERR.
`-v`, `--version`
: Print version.
`-h` or `--help`
: prints a usage message to STDERR.
`-h`, `--help`
: Show usage message.
[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/
[CSL]: http://CitationStyles.org
Templates

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

@ -62,14 +62,16 @@ should pipe input and output through `iconv`:
# OPTIONS
-f *FORMAT*, -r *FORMAT*, \--from=*FORMAT*, \--read=*FORMAT*
`-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
: 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.
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),
`plain` (plain text), `markdown` (markdown), `rst` (reStructuredText),
`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
*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.
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
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
\``-`', 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
: Preserve tabs instead of converting them to spaces.
`-p`, `--preserve-tabs`
: Preserve tabs instead of converting them to spaces (the default).
\--tab-stop=*TABSTOP*
: Specify tab stop (default is 4).
`--tab-stop=`*TABSTOP*
: Specify the number of spaces per tab (default is 4).
\--strict
: Use strict markdown syntax, with no extensions or variants.
`--strict`
: 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
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
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
: Use smart quotes, dashes, and ellipses. (This option is significant
only when the input format is `markdown`. It is selected automatically
when the output format is `latex` or `context`.)
`-S`, `--smart`
: Produce typographically correct output, converting straight quotes
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`.)
-m*URL*, \--latexmathml=*URL*
: Use LaTeXMathML to display embedded TeX math in HTML output.
`-m` *URL*, `--latexmathml=`*URL*
: 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,
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
will be inserted that allows the MathML to be viewed on some browsers.
\--jsmath=*URL*
: Use jsMath to display embedded TeX math in HTML output.
The *URL* should point to the jsMath load script; if provided,
it will be linked to in the header of standalone HTML documents.
`--jsmath=`*URL*
: Use [jsMath] to display embedded TeX math in HTML output.
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.
`--mathjax=`*URL*
: Use [MathJax] to display embedded TeX math in HTML output.
The *URL* should point to the `MathJax.js` load script.
\--gladtex
`--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
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`.
`--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 math using an external script. The formula will be
concatenated with the URL provided. If *URL* is not specified, the
Google Chart API will be used.
`--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
`-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
`--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
`--xetex`
: Create LaTeX outut suitable for processing by XeTeX.
-N, \--number-sections
`-N`, `--number-sections`
: 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
enclosing `<div>` rather than the header itself.
See [Section identifiers](#header-identifiers-in-html), below.
\--no-wrap
: Disable text wrapping in output. (Default is to wrap text.)
`--no-wrap`
: 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.
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*
`--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
@ -182,56 +206,70 @@ should pipe input and output through `iconv`:
If `--strict` is specified, *references* is used regardless of the
presence of this option.
\--id-prefix*=string*
`--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*
`--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 (HTML, markdown,
RTF) or an instruction to create one (LaTeX, reStructuredText).
This option has no effect on man, DocBook, Slidy, or S5 output.
`--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*
`--base-header-level=`*LEVEL*
: Specify the base level for headers (defaults to 1).
\--template=*FILE*
`--template=`*FILE*
: Use *FILE* as a custom template for the generated document. Implies
`-s`. See TEMPLATES below for a description of template syntax. If
this option is not used, a default template appropriate for the
output format will be used. See also `-D/--print-default-template`.
`--standalone`. See [Templates](#templates) below for a description
of template syntax. If this option is not used, a default
template appropriate for the output format will be used. See also
`-D/--print-default-template`.
-V KEY=VAL, \--variable=*KEY:VAL*
: Set the template variable KEY to the value VAL when rendering the
`-V` *KEY=VAL*, `--variable=`*KEY:VAL*
: Set the template variable *KEY* to the value *VAL* when rendering the
document in standalone mode. This is only useful when the
`--template` option is used to specify a custom template, since
pandoc automatically sets the variables used in the default
templates.
-c *CSS*, \--css=*CSS*
: Link to a CSS style sheet. *CSS* is the pathname of the style sheet.
`-c` *URL*, `--css=`*URL*
: Link to a CSS style sheet.
-H *FILE*, \--include-in-header=*FILE*
: Include contents of *FILE* at the end of the header. Implies `-s`.
`-H` *FILE*, `--include-in-header=`*FILE*
: 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*
: Include contents of *FILE* at the beginning of the document body.
Implies `-s`.
`-B` *FILE*, `--include-before-body=`*FILE*
: Include contents of *FILE*, verbatim, at the beginning of the
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*
: Include contents of *FILE* at the end of the document body.
Implies `-s`.
`-A` *FILE*, `--include-after-body=`*FILE*
: Include contents of *FILE*, verbatim, at the end of the document
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*
: Use contents of *FILE* as the document header. *Note: This option is
deprecated. Users should transition to using `--template` instead.*
`-C` *FILE*, `--custom-header=`*FILE*
: Use contents of *FILE* as the document header. Implies `--standalone`.
*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.
For best results, the reference ODT should be a modified version
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
used.
\--epub-stylesheet=*filename*
`--epub-stylesheet=`*FILE*
: Use 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*
`--epub-metadata=`*FILE*
: Look in the specified XML file for metadata for the EPUB.
The file should contain a series of Dublin Core elements
(http://dublincore.org/documents/dces/), for example:
The file should contain a series of Dublin Core elements,
as documented at <http://dublincore.org/documents/dces/>.
For example:
<dc:rights>Creative Commons</dc:rights>
<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
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`
for a list of possible *FORMAT*s.)
-T *STRING*, \--title-prefix=*STRING*
: Specify *STRING* as a prefix to the HTML window title.
`-T` *STRING*, `--title-prefix=*STRING*
: 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
citations. The database type will be determined from the
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
bibliographies, just use this option repeatedly.
\--csl=*FILE*
`--csl=`*FILE*
: Specify [CSL] style to be used in formatting citations and
the bibliography. If *FILE* is not found, pandoc will look
for it in
@ -295,7 +337,7 @@ should pipe input and output through `iconv`:
user data directory (see `--data-dir`), or, if that is
not present, the Chicago author-date style.
\--data-dir*=DIRECTORY*
`--data-dir=`*DIRECTORY*
: Specify the user data directory to search for pandoc data files.
If this option is not specified, the default user data directory
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
normal defaults.
\--dump-args
`--dump-args`
: 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
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,
one per line, in the order they appear. These do not include regular
Pandoc options and their arguments, but do include any options appearing
after a \``--`' separator at the end of the line.
This option is intended primarily for use in wrapper scripts.
after a `--` separator at the end of the line.
\--ignore-args
`--ignore-args`
: Ignore command-line arguments (for use in wrapper scripts).
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
-v, \--version
`-v`, `--version`
: Print version.
-h, \--help
`-h`, `--help`
: 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
When the `-s/--standalone` option is used, pandoc uses a template to