Reorganized documentation of options, grouping into categories.

1 files changed, 170 insertions, 148 deletions

diff --git a/README b/README
index eab0f1bcb..a01297193 100644
--- a/README
+++ b/README
@@ -128,6 +128,9 @@ problems with its simulation of symbolic links.
 Options
 =======
 
+General options
+---------------
+
 `-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
 :   Specify input format.  *FORMAT* can be `native` (native Haskell),
     `json` (JSON version of native AST), `markdown` (markdown),
@@ -153,29 +156,44 @@ Options
     using the `-o/--output` option. If `+lhs` is appended to `markdown`, `rst`,
     `latex`, `html`, or `html5`, the output will be rendered as literate Haskell
     source: see [Literate Haskell support](#literate-haskell-support), below.
+
     Production of `pdf` output requires that a LaTeX engine be installed
     (see `--latex-engine`, below), and assumes that the following LaTeX
     packages are available: `amssymb`, `amsmath`, `ifxetex`, `ifluatex`,
     `listings` (if the `--listings` option is used), `fancyvrb`,
     `enumerate`, `ctable`, `url`, `graphicx`, `hyperref`, `ulem`,
-    `babel` (if the `lang` variable is set)`, `fontspec` (if `xelatex`
+    `babel` (if the `lang` variable is set), `fontspec` (if `xelatex`
     or `lualatex` is used as the LaTeX engine), `xltxtra` and
     `xunicode` (if `xelatex` is used).
 
-`-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*
 :   Write output to *FILE* instead of *stdout*.  If *FILE* is
     `-`, output will go to *stdout*.  (Exception: if the output
     format is `odt`, `docx`, `pdf`, or `epub`, output to stdout is disabled.)
 
-`-p`, `--preserve-tabs`
-:   Preserve tabs instead of converting them to spaces (the default).
+`--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:
 
-`--tab-stop=`*NUMBER*
-:   Specify the number of spaces per tab (default is 4).
+        $HOME/.pandoc
+
+    in unix and
+
+        C:\Documents And Settings\USERNAME\Application Data\pandoc
+
+    in Windows. A `reference.odt`, `reference.docx`, `default.csl`,
+    `epub.css`, `templates`, `slidy`, or `s5` directory placed in this
+    directory will override pandoc's normal defaults.
+
+`-v`, `--version`
+:   Print version.
+
+`-h`, `--help`
+:   Show usage message.
+
+Reader options
+--------------
 
 `--strict`
 :   Use strict markdown syntax, with no pandoc extensions or variants.
@@ -183,14 +201,6 @@ Options
     equivalents in standard markdown (e.g. definition lists or strikeout
     text) will be parsed as raw HTML.
 
-`--normalize`
-:   Normalize the document after reading:  merge adjacent
-    `Str` or `Emph` elements, for example, and remove repeated `Space`s.
-
-`--reference-links`
-:   Use reference-style links, rather than inline links, in writing markdown
-    or reStructuredText.  By default inline links are used.
-
 `-R`, `--parse-raw`
 :   Parse untranslatable HTML codes and LaTeX environments as raw HTML
     or LaTeX, instead of ignoring them.  Affects only HTML and LaTeX
@@ -215,9 +225,65 @@ Options
     a numeral is an en-dash, and `--` is an em-dash.  This option is selected
     automatically for `textile` input.
 
-`-5`, `--html5`
-:   Produce HTML5 instead of HTML4.  This option has no effect for writers
-    other than `html`. (*Deprecated:*  Use the `html5` output format instead.)
+`--base-header-level=`*NUMBER*
+:   Specify the base level for headers (defaults to 1).
+
+`--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.
+
+`--normalize`
+:   Normalize the document after reading:  merge adjacent
+    `Str` or `Emph` elements, for example, and remove repeated `Space`s.
+
+`-p`, `--preserve-tabs`
+:   Preserve tabs instead of converting them to spaces (the default).
+
+`--tab-stop=`*NUMBER*
+:   Specify the number of spaces per tab (default is 4).
+
+General writer options
+----------------------
+
+`-s`, `--standalone`
+:   Produce output with an appropriate header and footer (e.g. a
+    standalone HTML, LaTeX, or RTF file, not a fragment).
+
+`--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 no extension is specified, an extension
+    corresponding to the writer will be added, so that `--template=special`
+    looks for `special.html` for HTML output.  If the template is not
+    found, pandoc will search for it in the user data directory
+    (see `--data-dir`). If this option is not used, a default
+    template appropriate for the output format will be used (see
+    `-D/--print-default-template`).
+
+`-V` *KEY=VAL*, `--variable=`*KEY:VAL*
+:   Set the template variable *KEY* to the value *VAL* when rendering the
+    document in standalone mode. This is generally only useful when the
+    `--template` option is used to specify a custom template, since
+    pandoc automatically sets the variables used in the default
+    templates.
+
+`-D` *FORMAT*, `--print-default-template=`*FORMAT*
+:   Print the default template for an output *FORMAT*. (See `-t`
+    for a list of possible *FORMAT*s.)
+
+`--no-wrap`
+:   Disable text wrapping in output. By default, text is wrapped
+    appropriately for the output format.
+
+`--columns`=*NUMBER*
+:   Specify length of lines in characters (for text wrapping).
+
+`--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.
 
 `--no-highlight`
 :   Disables syntax highlighting for code blocks and inlines, even when
@@ -228,51 +294,30 @@ Options
     Options are `pygments` (the default), `kate`, `monochrome`,
     `espresso`, `haddock`, and `tango`.
 
-`-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.
-
-`--mathml`[=*URL*]
-:   Convert TeX math to MathML.  In standalone mode, a small javascript
-    (or a link to such a script if a *URL* is supplied) 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 (e.g.
-    `jsMath/easy/load.js`); if provided, it will be linked to in
-    the header of standalone HTML documents. If a *URL* is not provided,
-    no link to the jsMath load script will be inserted; it is then
-    up to the author to provide such a link in the HTML template.
-
-`--mathjax`[=*URL*]
-:   Use [MathJax] to display embedded TeX math in HTML output.
-    The *URL* should point to the `MathJax.js` load script.
-    If a *URL* is not provided, a link to the MathJax CDN will
-    be inserted.
-
-`--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. 
+`-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`.
 
-`--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`.
+`-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`.
 
-`--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.
+`-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`.
 
-`-i`, `--incremental`
-:   Make list items in Slidy, DZSlides or S5 display incrementally (one by one).
-    The default is for lists to be displayed all at once.
+Options affecting specific writers
+----------------------------------
 
 `--self-contained`
 :   Produce a standalone HTML file with no external dependencies, using
@@ -289,6 +334,14 @@ Options
 `--offline`
 :   Deprecated synonym for `--self-contained`.
 
+`-5`, `--html5`
+:   Produce HTML5 instead of HTML4.  This option has no effect for writers
+    other than `html`. (*Deprecated:*  Use the `html5` output format instead.)
+
+`--reference-links`
+:   Use reference-style links, rather than inline links, in writing markdown
+    or reStructuredText.  By default inline links are used.
+
 `--chapters`
 :   Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook
     output.  When the LaTeX template uses the report, book, or
@@ -306,6 +359,10 @@ Options
 :   Produce LaTeX output for the `beamer` document class.
     This has an effect only for `latex` or `pdf` output.
 
+`-i`, `--incremental`
+:   Make list items in slide shows display incrementally (one by one).
+    The default is for lists to be displayed all at once.
+
 `--slide-level`=*NUMBER*
 :   Specifies that headers with the specified level create
     slides (for `beamer`, `s5`, `slidy`, `dzslides`).  Headers
@@ -321,13 +378,6 @@ Options
     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.
-
-`--columns`=*NUMBER*
-:   Specify length of lines in characters (for text wrapping).
-
 `--email-obfuscation=`*none|javascript|references*
 :   Specify a method for obfuscating `mailto:` links in HTML documents.
     *none* leaves `mailto:` links as they are.  *javascript* obfuscates
@@ -341,63 +391,15 @@ Options
     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=`*NUMBER*
-:   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 no extension is specified, an extension
-    corresponding to the writer will be added, so that `--template=special`
-    looks for `special.html` for HTML output.  If the template is not
-    found, pandoc will search for it in the user data directory
-    (see `--data-dir`). If this option is not used, a default
-    template appropriate for the output format will be used (see
-    `-D/--print-default-template`).
-
-`-V` *KEY=VAL*, `--variable=`*KEY:VAL*
-:   Set the template variable *KEY* to the value *VAL* when rendering the
-    document in standalone mode. This is generally only useful when the
-    `--template` option is used to specify a custom template, since
-    pandoc automatically sets the variables used in the default
-    templates.
+`-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`.
 
 `-c` *URL*, `--css=`*URL*
 :   Link to a CSS style sheet.
 
-`-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*, 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*, 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=`*FILE*
 :   Use the specified file as a style reference in producing an ODT.
     For best results, the reference ODT should be a modified version
@@ -421,7 +423,7 @@ Options
 `--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
+    user data directory (see `--data-dir`).  If it is not
     found there, sensible defaults will be used.
 
 `--epub-cover-image=`*FILE*
@@ -450,15 +452,8 @@ Options
     The default is `pdflatex`.  If the engine is not in your PATH,
     the full path of the engine may be specified here.
 
-`-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 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`.
+Citations
+---------
 
 `--bibliography=`*FILE*
 :   Specify bibliography database to be used in resolving
@@ -509,20 +504,53 @@ Options
 `--biblatex`
 :   Use biblatex for citations in LaTeX output.
 
-`--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:
+Math rendering in HTML
+----------------------
 
-        $HOME/.pandoc
+`-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.
 
-    in unix and
+`--mathml`[=*URL*]
+:   Convert TeX math to MathML.  In standalone mode, a small javascript
+    (or a link to such a script if a *URL* is supplied) will be inserted that
+    allows the MathML to be viewed on some browsers.
 
-        C:\Documents And Settings\USERNAME\Application Data\pandoc
+`--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. If a *URL* is not provided,
+    no link to the jsMath load script will be inserted; it is then
+    up to the author to provide such a link in the HTML template.
 
-    in Windows. A `reference.odt`, `reference.docx`,
-    `epub.css`, `templates` directory, or `s5` directory placed in this
-    directory will override pandoc's normal defaults.
+`--mathjax`[=*URL*]
+:   Use [MathJax] to display embedded TeX math in HTML output.
+    The *URL* should point to the `MathJax.js` load script.
+    If a *URL* is not provided, a link to the MathJax CDN will
+    be inserted.
+
+`--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.
+
+Options for wrapper scripts
+---------------------------
 
 `--dump-args`
 :   Print information about command-line arguments to *stdout*, then exit.
@@ -544,12 +572,6 @@ Options
 
         pandoc -o foo.html -s
 
-`-v`, `--version`
-:   Print version.
-
-`-h`, `--help`
-:   Show usage message.
-
 [LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/
 [jsMath]:  http://www.math.union.edu/~dpvc/jsmath/
 [MathJax]: http://www.mathjax.org/