@@ -219,130 +219,146 @@ Command-line options
219219Various command-line options can be used to customize the output.
220220For further documentation, see the `pandoc(1)` man page.
221221
222−`-f`, `--from`, `-r`, or `--read` can be used to specify the input
223−format -- the format Pandoc will be converting *from*. Available
224−formats are `native`, `markdown`, `rst`, `html`, and `latex`.
225−
226−`-t`, `--to`, `-w`, or `--write` can be used to specify the output
227−format -- the format Pandoc will be converting *to*. Available formats
228−are `native`, `html`, `s5`, `docbook`, `latex`, `context`, `markdown`,
229−`rst`, and `rtf`.
230−
231−`-s` or `--standalone` indicates that a standalone document is to be
232−produced (with appropriate headers and footers), rather than a fragment.
233−
234−`-o` or `--output` specifies the name of the output file. If this
235−option is not specified, or if its argument is `-`, output will be sent
236−to STDOUT.
237−
238−`-p` or `--preserve-tabs` causes tabs in the source text to be
239−preserved, rather than converted to spaces (the default).
240−
241−`--tabstop` allows the user to set the tab stop (which defaults to 4).
242−
243−`--strict` specifies that strict markdown syntax is to be used, without
244−pandoc's usual extensions and variants (described below). When the
245−input format is HTML, this means that constructs that have no
246−equivalents in standard markdown (e.g. definition lists or strikeout
247−text) will be parsed as raw HTML.
248−
249−`--reference-links` causes reference-style links to be used in markdown
250−and reStructuredText output. By default inline links are used.
251−
252−`-R` or `--parse-raw` causes the HTML and LaTeX readers to parse HTML
253−codes and LaTeX environments that it can't translate as raw HTML or
254−LaTeX. Raw HTML can be printed in markdown, reStructuredText, HTML,
255−and S5 output; raw LaTeX can be printed in markdown, reStructuredText,
256−LaTeX, and ConTeXt output. The default is for the readers to omit
257−untranslatable HTML codes and LaTeX environments. (The LaTeX reader
258−does pass through untranslatable LaTeX commands, even if `-R` is not
259−specified.)
260−
261−`-C` or `--custom-header` can be used to specify a custom document
262−header. To see the headers used by default, use the `-D` option:
263−for example, `pandoc -D html` prints the default HTML header.
264−
265−`--toc` or `--table-of-contents` includes an automatically generated
266−table of contents (or, in the case of `latex`, `context`, and `rst`, an
267−instruction to create one) in the output document. This option has no
268−effect with `man`, `docbook`, or `s5` output formats.
269−
270−`-c` or `--css` allows the user to specify a custom stylesheet that
271−will be linked to in HTML and S5 output.
272−
273−`-H` or `--include-in-header` specifies a file to be included
274−(verbatim) at the end of the document header. This can be used, for
275−example, to include special CSS or javascript in HTML documents.
276−
277−`-B` or `--include-before-body` specifies a file to be included
278−(verbatim) at the beginning of the document body (e.g. after the `<body>`
279−tag in HTML, or the `\begin{document}` command in LaTeX). This can be
280−used to include navigation bars or banners in HTML documents.
281−
282−`-A` or `--include-after-body` specifies a file to be included
283−(verbatim) at the end of the document body (before the `</body>` tag in
284−HTML, or the `\end{document}` command in LaTeX).
285−
286−`-T` or `--title-prefix` specifies a string to be included as a prefix
287−at the beginning of the title that appears in the HTML header (but not
288−in the title as it appears at the beginning of the HTML body). (See
289−below on Titles.)
290−
291−`-S` or `--smart` causes `pandoc` to produce typographically
292−correct output, along the lines of John Gruber's [Smartypants].
293−Straight quotes are converted to curly quotes, `---` to dashes, and
294−`...` to ellipses. (Note: This option is only significant when
295−the input format is `markdown`. It is selected automatically
296−when the output format is `latex` or `context`.)
222+`-f`, `--from`, `-r`, or `--read` *format*
223+: specifies the input format (the format Pandoc will be converting
224+ *from*). *format* can be `native`, `markdown`, `rst`, `html`, or
225+ `latex`.
226+
227+`-t`, `--to`, `-w`, or `--write` *format*
228+: specifies the output format -- the format Pandoc will
229+ be converting *to*. *format* can be `native`, `html`, `s5`,
230+ `docbook`, `latex`, `context`, `markdown`, `man`, `rst`, and `rtf`.
231+
232+`-s` or `--standalone`
233+: indicates that a standalone document is to be produced (with
234+ appropriate headers and footers), rather than a fragment.
235+
236+`-o` or `--output` *filename*
237+: sends output to *filename*. If this option is not specified,
238+ or if its argument is `-`, output will be sent to STDOUT.
239+
240+`-p` or `--preserve-tabs`
241+: causes tabs in the source text to be preserved, rather than converted
242+ to spaces (the default).
243+
244+`--tabstop` *tabstop*
245+: sets the number of spaces per tab to *tabstop* (defaults to 4).
246+
247+`--strict`
248+: specifies that strict markdown syntax is to be used, without
249+ pandoc's usual extensions and variants (described below). When the
250+ input format is HTML, this means that constructs that have no
251+ equivalents in standard markdown (e.g. definition lists or strikeout
252+ text) will be parsed as raw HTML.
253+
254+`--reference-links`
255+: causes reference-style links to be used in markdown
256+ and reStructuredText output. By default inline links are used.
257+
258+`-R` or `--parse-raw`
259+: causes the HTML and LaTeX readers to parse HTML codes and LaTeX
260+ environments that it can't translate as raw HTML or LaTeX. Raw HTML can
261+ be printed in markdown, reStructuredText, HTML, and S5 output; raw LaTeX
262+ can be printed in markdown, reStructuredText, LaTeX, and ConTeXt output.
263+ The default is for the readers to omit untranslatable HTML codes and
264+ LaTeX environments. (The LaTeX reader does pass through untranslatable
265+ LaTeX *commands*, even if `-R` is not specified.)
266+
267+`-C` or `--custom-header` *filename*
268+: can be used to specify a custom document header. To see the headers
269+ used by default, use the `-D` option: for example, `pandoc -D html`
270+ prints the default HTML header.
271+
272+`--toc` or `--table-of-contents`
273+: includes an automatically generated table of contents (or, in the
274+ case of `latex`, `context`, and `rst`, an instruction to create
275+ one) in the output document. This option has no effect with `man`,
276+ `docbook`, or `s5` output formats.
277+
278+`-c` or `--css` *filename*
279+: allows the user to specify a custom stylesheet that will be linked to
280+ in HTML and S5 output.
281+
282+`-H` or `--include-in-header` *filename*
283+: includes the contents of *filename* (verbatim) at the end of the
284+ document header. This can be used, for example, to include special
285+ CSS or javascript in HTML documents.
286+
287+`-B` or `--include-before-body` *filename*
288+: includes the contents of *filename* (verbatim) at the beginning of
289+ the document body (e.g. after the `<body>` tag in HTML, or the
290+ `\begin{document}` command in LaTeX). This can be used to include
291+ navigation bars or banners in HTML documents.
292+
293+`-A` or `--include-after-body` *filename*
294+: includes the contents of *filename* (verbatim) at the end of
295+ the document body (before the `</body>` tag in HTML, or the
296+ `\end{document}` command in LaTeX).
297+
298+`-T` or `--title-prefix` *string*
299+: includes *string* as a prefix at the beginning of the title that
300+ appears in the HTML header (but not in the title as it appears at
301+ the beginning of the HTML body). (See below on
302+ [Title Blocks](#title-blocks).)
303+
304+`-S` or `--smart`
305+: causes `pandoc` to produce typographically correct output, along the
306+ lines of John Gruber's [Smartypants]. Straight quotes are converted
307+ to curly quotes, `---` to dashes, and `...` to ellipses. (Note: This
308+ option is only significant when the input format is `markdown`.
309+ It is selected automatically when the output format is `latex` or
310+ `context`.)
311+
312+`-m` or `--asciimathml`
313+: will cause LaTeX formulas (between $ signs) in HTML or S5 to display
314+ as formulas rather than as code. The trick will not work in all
315+ browsers, but it works in Firefox. Peter Jipsen's [ASCIIMathML]
316+ script is used to do the magic.
317+
318+`-i` or `--incremental`
319+: causes all lists in S5 output to be displayed incrementally by
320+ default (one item at a time). The normal default is for lists to be
321+ displayed all at once.
322+
323+`-N` or `--number-sections`
324+: causes sections to be numbered in LaTeX or ConTeXt output. By default,
325+ sections are not numbered.
326+
327+`--dump-args`
328+: is intended to make it easier to create wrapper scripts that use
329+ Pandoc. It causes Pandoc to dump information about the arguments
330+ with which it was called to STDOUT, then exit. The first line
331+ printed is the name of the output file specified using the `-o`
332+ or `--output` option, or `-` if output would go to STDOUT. The
333+ remaining lines, if any, list command-line arguments. These will
334+ include the names of input files and any special options passed
335+ after ` -- ` on the command line. So, for example,
336+
337+: pandoc --dump-args -o foo.html -s foo.txt appendix.txt -- -e latin1
338+
339+: will cause the following to be printed to STDOUT:
340+
341+: foo.html foo.txt appendix.txt -e latin1
342+
343+`--ignore-args`
344+: causes Pandoc to ignore all command-line arguments.
345+ Regular Pandoc options are not ignored. Thus, for example,
346+
347+: pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
348+
349+: is equivalent to
350+
351+: pandoc -o foo.html -s
352+
353+`-v` or `--version`
354+: prints the version number to STDERR.
355+
356+`-h` or `--help`
357+: prints a usage message to STDERR.
297358
298359[Smartypants]: http://daringfireball.net/projects/smartypants/
299−
300−`-m` or `--asciimathml` will cause LaTeX formulas (between $ signs) in
301−HTML or S5 to display as formulas rather than as code. The trick will
302−not work in all browsers, but it works in Firefox. Peter Jipsen's
303−[ASCIIMathML] script is used to do the magic.
304−
305360[ASCIIMathML]: http://www1.chapman.edu/~jipsen/mathml/asciimath.html
306361
307−`-i` or `--incremental` causes all lists in S5 output to be displayed
308−incrementally by default (one item at a time). The normal default
309−is for lists to be displayed all at once.
310−
311−`-N` or `--number-sections` causes sections to be numbered in LaTeX
312−or ConTeXt output. By default, sections are not numbered.
313−
314−`--dump-args` is intended to make it easier to create wrapper scripts
315−that use Pandoc. It causes Pandoc to dump information about the arguments
316−with which it was called to STDOUT, then exit. The first line printed
317−is the name of the output file specified using the `-o` or `--output`
318−option, or `-` if output would go to STDOUT. The remaining lines, if any,
319−list command-line arguments. These will include the names of input
320−files and any special options passed after ` -- ` on the command line.
321−So, for example,
322−
323− pandoc --dump-args -o foo.html -s foo.txt appendix.txt -- -e latin1
324−
325−will cause the following to be printed to STDOUT:
326−
327− foo.html
328− foo.txt
329− appendix.txt
330− -e
331− latin1
332−
333−`--ignore-args` causes Pandoc to ignore all command-line arguments.
334−Regular Pandoc options are not ignored. Thus, for example,
335−
336− pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
337−
338−is equivalent to
339−
340− pandoc -o foo.html -s
341−
342−`-v` or `--version` prints the version number to STDERR.
343−
344−`-h` or `--help` prints a usage message to STDERR.
345−
346362Pandoc's markdown vs. standard markdown
347363=======================================
348364