@@ -39,24 +39,24 @@ STDIN. If you run it with file names as arguments, it will take input
3939from those files. It accepts several command-line options. For a
4040list, type
4141
42− pandoc -h
42+ pandoc -h
4343
4444The most important options specify the format of the source file and
4545the output. The default reader is markdown; the default writer is
4646HTML. So if you don't specify a reader or writer, `pandoc` will
4747convert markdown to HTML. For example,
4848
49− pandoc hello.txt
49+ pandoc hello.txt
5050
5151will convert `hello.txt` from markdown to HTML. For other conversions,
5252you must specify a reader and/or a writer using the `-r` and `-w`
5353flags. To convert markdown to LaTeX, you would write:
5454
55− pandoc -w latex hello.txt
55+ pandoc -w latex hello.txt
5656
5757To convert html to markdown:
5858
59− pandoc -r html -w markdown hello.txt
59+ pandoc -r html -w markdown hello.txt
6060
6161Supported writers include `markdown`, `latex`, `html`, `rtf` (rich text
6262format), `rst` (reStructuredText), and `s5` (which produces an HTML
@@ -120,72 +120,74 @@ before the files can be found by TeX.)
120120
121121# The shell scripts
122122
123−For convenience, five shell scripts have been included that make it
124−easy to run `pandoc` without remembering all the command-line options.
125−All of the scripts use `iconv` to convert to and from the local
126−character encoding. All of the scripts presuppose that `pandoc`
127−is in the path, and some have additional requirements. (For example,
128−`html2markdown` uses `tidy`, and `markdown2pdf` uses `pdflatex`.)
123+Five shell scripts have been included that make it easy to run
124+`pandoc` without worrying about character encodings, and without
125+remembering all the command-line options:
129126
130−1. `markdown2html` converts markdown to HTML. (This can be used
131− as a replacement for `Markdown.pl`.)
127+- `markdown2html` converts markdown-formatted text to HTML
128+- `markdown2latex` converts markdown-formatted text to LaTeX
129+- `markdown2pdf` produces a PDF file from markdown-formatted
130+ text, using `pdflatex`.
131+- `html2markdown` converts HTML to markdown-formatted text
132+- `latex2markdown` converts LaTeX to markdown-formatted text
132133
133−2. `html2markdown` can take either a filename or a URL as argument. If
134− it is given a URL, it uses `curl`, `wget`, or an available text-based
135− browser to fetch the contents of the specified URL, then filters this
136− through `tidy` to straighten up the HTML, and finally passes
137− this HTML to `pandoc` to produce markdown text:
134+All of the scripts use `iconv` (if available) to convert to and from
135+the local character encoding. All of the scripts presuppose that
136+`pandoc` is in the path, and some have additional requirements. (For
137+example, `html2markdown` uses `tidy`, and `markdown2pdf` uses
138+`pdflatex`.)
138139
139− html2markdown http://www.fsf.org
140+When no arguments are specified, text will be read from standard
141+input. Arguments specify input files (limited to one in the case of
142+`latex2markdown` and `html2markdown`; the other scripts accept any number
143+of arguments). `html2markdown` may take a URL as argument instead of
144+a filename; in this case, `curl`, `wget`, or an available text-based
145+browser will be used to fetch the contents of the URL. (The `-n` option
146+inhibits this behavior; the `-g` option allows the user to specify a
147+custom command that will be used to fetch from a URL.)
140148
141− html2markdown www.fsf.org
149+With the exception of `markdown2pdf`, the scripts write to standard output.
150+Output can be sent to a file using shell output redirection:
142151
143− html2markdown subdir/mylocalfile.html
152+ latex2markdown sample.tex > sample.txt
144153
145−3. `latex2markdown` converts a LaTeX file to markdown:
154+The default behavior of `markdown2pdf` is to create a file with the same
155+base name as the first argument and the extension `pdf`; thus, for example,
146156
147− latex2markdown mytexfile.tex
157+ markdown2pdf sample.txt endnotes.txt
148158
149−4. `markdown2latex` converts markdown to LaTeX:
159+will produce `sample.pdf`. (If `sample.pdf` exists already, it will be
160+backed up before being overwritten.) An output file name can be specified
161+explicitly using the `-o` option:
150162
151− markdown2latex mytextfile.txt
163+ markdown2pdf -o "My Book.pdf" chap1.txt chap2.txt chap3.txt
152164
153−5. `markdown2pdf` converts markdown to PDF using `pdflatex`:
165+Options specific to the scripts, like `-o`, `-g`, and `-n`, must
166+be specified *before* any command-line arguments (file names or URLs).
167+Any options specified *after* the command-line arguments will be
168+passed directly to `pandoc`. For example,
154169
155− markdown2pdf mytextfile.txt
170+ markdown2html tusks.txt -S -T Elephants
156171
157− creates a file `mytextfile.pdf`. To specify a different
158− name for the output file, use the `-o` option:
172+will convert `tusks.txt` to `tusks.html` using smart quotes, ellipses,
173+and dashes, with "Elephants" as the page title prefix. (For a
174+complete list of `pandoc` options, see below.) When there are no
175+command-line arguments (because input is from STDIN), `pandoc`
176+options must be preceded by ` -- `:
159177
160− markdown2pdf -o final-draft.pdf mytextfile.txt
178+ cat tusks.txt | markdown2html -- -S -T Elephants
161179
162−If you want to use `pandoc`'s command-line options in these scripts,
163−put the options in the environment variable `PANDOC_OPTS`. For
164−example, to convert `tusks.txt` to `tusks.html` using smart quotes,
165−ellipses, and dashes, with "Elephants" as the page title prefix:
180+The ` -- ` separator may optionally be used when there are command-line
181+arguments:
166182
167− PANDOC_OPTS="-S -T Elephants" markdown2html tusks.txt > tusks.html
168−
169−To make these options persistent, use `export`:
170−
171− export PANDOC_OPTS="-S -T Elephants"
172− markdown2html tusks.txt > tusks.html
173− markdown2html trunk.txt > trunk.html
174−
175−You may also specify options on the command line, separating them
176−from the arguments with '` -- `':
177−
178− markdown2html tusks.txt -- -S -T Elephants
179−
180−Options specified in this way will override any options set in
181−`PANDOC_OPTS`.
183+ markdown2html -- tusks.txt -S -T Elephants
182184
183185# Command-line options
184186
185187Various command-line options can be used to customize the output.
186188For a complete list, type
187189
188− pandoc --help
190+ pandoc --help
189191
190192`-p` or `--preserve-tabs` causes tabs in the source text to be
191193preserved, rather than converted to spaces (the default).
@@ -264,13 +266,13 @@ markdown test suite, type `make test-markdown`.)
264266Pandoc behaves differently from standard markdown on some "edge
265267cases" involving lists. Consider this source:
266268
267− 1. First
268− 2. Second:
269− - Fee
270− - Fie
271− - Foe
269+ 1. First
270+ 2. Second:
271+ - Fee
272+ - Fie
273+ - Foe
272274
273− 3. Third
275+ 3. Third
274276
275277Pandoc transforms this into a "compact list" (with no `<p>` tags
276278around "First", "Second", or "Third"), while markdown puts `<p>`
@@ -286,20 +288,20 @@ is followed by a blank line is irrelevant.
286288Standard markdown allows unescaped literal quotes in titles, as
287289in
288290
289− [foo]: "bar "embedded" baz"
291+ [foo]: "bar "embedded" baz"
290292
291293Pandoc requires all quotes within titles to be escaped:
292294
293− [foo]: "bar \"embedded\" baz"
295+ [foo]: "bar \"embedded\" baz"
294296
295297## Reference links
296298
297299Pandoc allows implicit reference links in either of two styles:
298300
299− 1. Here's my [link]
300− 2. Here's my [link][]
301+ 1. Here's my [link]
302+ 2. Here's my [link][]
301303
302− [link]: linky.com
304+ [link]: linky.com
303305
304306If there's no corresponding reference, the implicit reference link
305307will appear as regular bracketed text. Note: even `[link][]` will
@@ -313,18 +315,18 @@ Pandoc's markdown allows footnotes, using the following syntax:
313315 here is a footnote reference,^(1) and another.^(longnote)
314316
315317 ^(1) Here is the footnote. It can go anywhere in the document,
316− except in embedded contexts like block quotes or lists.
318+ except in embedded contexts like block quotes or lists.
317319
318320 ^(longnote) Here's the other note. This one contains multiple
319321 blocks.
320322 ^
321323 ^ Caret characters are used to indicate that the blocks all belong
322− to a single footnote (as with block quotes).
324+ to a single footnote (as with block quotes).
323325 ^
324326 ^ If you want, you can use a caret at the beginning of every line,
325− ^ as with blockquotes, but all that you need is a caret at the
326− ^ beginning of the first line of the block and any preceding
327− ^ blank lines.
327+ ^ as with blockquotes, but all that you need is a caret at the
328+ ^ beginning of the first line of the block and any preceding
329+ ^ blank lines.
328330
329331Footnote references may not contain spaces, tabs, or newlines.
330332
@@ -335,21 +337,21 @@ Markdown 1.0. While Markdown 1.0 leaves HTML blocks exactly as they
335337are, Pandoc treats text between HTML tags as markdown. Thus, for
336338example, Pandoc will turn
337339
338− <table>
339− <tr>
340− <td>*one*</td>
341− <td>[a link](http://google.com)</td>
342− </tr>
343− </table>
340+ <table>
341+ <tr>
342+ <td>*one*</td>
343+ <td>[a link](http://google.com)</td>
344+ </tr>
345+ </table>
344346
345347into
346348
347− <table>
348− <tr>
349− <td><em>one</em></td>
350− <td><a href="http://google.com">a link</a></td>
351− </tr>
352− </table>
349+ <table>
350+ <tr>
351+ <td><em>one</em></td>
352+ <td><a href="http://google.com">a link</a></td>
353+ </tr>
354+ </table>
353355
354356whereas Markdown 1.0 will preserve it as is.
355357
@@ -426,10 +428,10 @@ include BibTeX citations:
426428You can also use LaTeX environments. For example,
427429
428430 \begin{tabular}{|l|l|}\hline
429− Age & Frequency \\ \hline
431+ Age & Frequency \\ \hline
430432 18--25 & 15 \\
431− 26--35 & 33 \\
432− 36--45 & 22 \\ \hline
433+ 26--35 & 33 \\
434+ 36--45 & 22 \\ \hline
433435 \end{tabular}
434436
435437Note, however, that material between the begin and end tags will
@@ -441,14 +443,14 @@ When run with the "standalone" option (`-s`), `pandoc` creates a
441443standalone file, complete with an appropriate header. To see the
442444default headers used for html and latex, use the following commands:
443445
444− pandoc -D html
446+ pandoc -D html
445447
446− pandoc -D latex
448+ pandoc -D latex
447449
448450If you want to use a different header, just create a file containing
449451it and specify it on the command line as follows:
450452
451− pandoc --header=MyHeaderFile
453+ pandoc --header=MyHeaderFile
452454
453455# Producing S5 with Pandoc
454456