mirror of
https://github.com/jgm/pandoc.git
synced 2026-09-24 15:44:59 +08:00
More README improvements.
This commit is contained in:
John MacFarlane
@@ -558,6 +558,9 @@ noting differences from standard markdown. Except where noted, these
|
||||
differences can be suppressed by specifying the `--strict` command-line
|
||||
option.
|
||||
|
||||
Philosophy
|
||||
----------
|
||||
|
||||
Gruber designed markdown to be easy to write, and, even more importantly,
|
||||
easy to read:
|
||||
|
||||
@@ -619,6 +622,15 @@ As with setext-style headers, the header text can contain formatting:
|
||||
|
||||
# A level-one header with a [link](/url) and *emphasis*
|
||||
|
||||
Standard markdown syntax does not require a blank line before a header.
|
||||
Pandoc does require this (except, of course, at the beginning of the
|
||||
document). The reason for the requirement is that it is all too easy for a
|
||||
`#` to end up at the beginning of a line by accident (perhaps through line
|
||||
wrapping). Consider, for example:
|
||||
|
||||
I like several of their flavors of ice cream:
|
||||
#22, for example, and #5.
|
||||
|
||||
|
||||
### Header identifiers in HTML ###
|
||||
|
||||
@@ -657,7 +669,8 @@ contents generated by the `--toc|--table-of-contents` option. They
|
||||
also make it easy to provide links from one section of a document to
|
||||
another. A link to this section, for example, might look like this:
|
||||
|
||||
See the section on [header identifiers](#header-identifiers-in-html).
|
||||
See the section on
|
||||
[header identifiers](#header-identifiers-in-html).
|
||||
|
||||
Note, however, that this method of providing links to sections works
|
||||
only in HTML.
|
||||
@@ -701,19 +714,15 @@ other block quotes. That is, block quotes can be nested:
|
||||
>
|
||||
> > A block quote within a block quote.
|
||||
|
||||
Standard markdown syntax does not require a blank line before a block
|
||||
quote. Pandoc does require this (except, of course, at the beginning of the
|
||||
document). The reason for the requirement is that it is all too easy for a
|
||||
`>` to end up at the beginning of a line by accident (perhaps through line
|
||||
wrapping). So, unless `--strict` is used, the following does not produce
|
||||
a nested block quote in pandoc:
|
||||
|
||||
*** TODO: decide whether pandoc should require a blank
|
||||
line btw nested ***
|
||||
|
||||
Standard markdown syntax does not require a blank line before a header
|
||||
or blockquote. Pandoc does require this (except, of course, at the
|
||||
beginning of the document). The reason for the requirement is that
|
||||
it is all too easy for a `>` or `#` to end up at the beginning of a
|
||||
line by accident (perhaps through line wrapping). Consider, for
|
||||
example:
|
||||
|
||||
I like several of their flavors of ice cream:
|
||||
#22, for example, and #5.
|
||||
> This is a block quote.
|
||||
>> Nested.
|
||||
|
||||
|
||||
Verbatim (code) blocks
|
||||
@@ -721,7 +730,18 @@ Verbatim (code) blocks
|
||||
|
||||
### Indented code blocks ###
|
||||
|
||||
TODO
|
||||
A block of text indented four spaces (or one tab) is treated as verbatim
|
||||
text: that is, special characters do not trigger special formatting,
|
||||
and all spaces and line breaks are preserved. For example,
|
||||
|
||||
if (a > 3) {
|
||||
moveShip(5 * gravity, DOWN);
|
||||
}
|
||||
|
||||
The initial (four space or one tab) indentation is not considered part
|
||||
of the verbatim text, and is removed in the output.
|
||||
|
||||
Note: blank lines in the verbatim text need not begin with four spaces.
|
||||
|
||||
|
||||
### Delimited code blocks ###
|
||||
@@ -735,7 +755,9 @@ as long as the starting row. Everything between the tilde-lines
|
||||
is treated as code. No indentation is necessary:
|
||||
|
||||
~~~~~~~
|
||||
{code here}
|
||||
if (a > 3) {
|
||||
moveShip(5 * gravity, DOWN);
|
||||
}
|
||||
~~~~~~~
|
||||
|
||||
Like regular code blocks, delimited code blocks must be separated
|
||||
@@ -783,6 +805,7 @@ Lists
|
||||
|
||||
TODO
|
||||
|
||||
TODO - rules for tight and loose
|
||||
|
||||
### Ordered lists ###
|
||||
|
||||
@@ -939,7 +962,12 @@ even though it is different from that of `Markdown.pl`.)
|
||||
Horizontal rules
|
||||
----------------
|
||||
|
||||
TODO
|
||||
A line containing a row of three or more `*`, `-`, or `_` characters
|
||||
(optionally separated by spaces) produces a horizontal rule:
|
||||
|
||||
* * * *
|
||||
|
||||
---------------
|
||||
|
||||
|
||||
Tables
|
||||
@@ -1046,7 +1074,7 @@ the table), or the table may be interpreted as a simple table.
|
||||
**Grid tables** look like this:
|
||||
|
||||
: Sample grid table.
|
||||
|
||||
|
||||
+---------------+---------------+--------------------+
|
||||
| Fruit | Price | Advantages |
|
||||
+===============+===============+====================+
|
||||
@@ -1244,69 +1272,74 @@ closing `$` must have a character immediately to its left. Thus,
|
||||
you need to enclose text in literal `$` characters, backslash-escape
|
||||
them and they won't be treated as math delimiters.
|
||||
|
||||
TeX math will be printed in all output formats. In Markdown,
|
||||
reStructuredText, LaTeX, Org-Mode, and ConTeXt output, it will appear
|
||||
verbatim between `$` characters.
|
||||
TeX math will be printed in all output formats. How it is rendered
|
||||
depends on the output format:
|
||||
|
||||
In reStructuredText output, it will be rendered using an interpreted
|
||||
text role `:math:`, as described
|
||||
[here](http://www.american.edu/econ/itex2mml/mathhack.rst).
|
||||
Markdown, reStructuredText, LaTeX, Org-Mode, ConTeXt
|
||||
~ It will appear verbatim between `$` characters.
|
||||
|
||||
In Texinfo output, it will be rendered inside a `@math` command.
|
||||
reStructuredText
|
||||
~ It will be rendered using an interpreted text role `:math:`, as described
|
||||
[here](http://www.american.edu/econ/itex2mml/mathhack.rst).
|
||||
|
||||
In groff man output, it will be rendered verbatim without `$`'s.
|
||||
Texinfo
|
||||
~ It will be rendered inside a `@math` command.
|
||||
|
||||
In MediaWiki output, it will be rendered inside `<math>` tags.
|
||||
groff man
|
||||
~ It will be rendered verbatim without `$`'s.
|
||||
|
||||
In Textile output, it will be rendered inside `<span class="math">` tags.
|
||||
MediaWiki
|
||||
~ It will be rendered inside `<math>` tags.
|
||||
|
||||
In RTF, Docbook, and OpenDocument output, it will be rendered, as far as
|
||||
possible, using unicode characters, and will otherwise appear verbatim.
|
||||
Unknown commands and symbols, and commands that cannot be dealt with
|
||||
this way (like `\frac`), will be rendered verbatim. So the results may
|
||||
be a mix of raw TeX code and properly rendered unicode math.
|
||||
Textile
|
||||
~ It will be rendered inside `<span class="math">` tags.
|
||||
|
||||
In HTML, Slidy, and S5 output, the way math is rendered will depend on the
|
||||
command-line options selected:
|
||||
RTF, Docbook, OpenDocument, ODT
|
||||
~ It will be rendered, if possible, using unicode characters,
|
||||
and will otherwise appear verbatim.
|
||||
|
||||
1. The default is to render TeX math as far as possible using unicode
|
||||
characters, as with RTF, Docbook, and OpenDocument output. Formulas
|
||||
are put inside a `span` with `class="math"`, so that they may be
|
||||
styled differently from the surrounding text if needed.
|
||||
HTML, Slidy, S5, EPUB
|
||||
~ The way math is rendered in HTML will depend on the
|
||||
command-line options selected:
|
||||
|
||||
2. If the `--latexmathml` option is used, TeX math will be displayed
|
||||
between $ or $$ characters and put in `<span>` tags with class `LaTeX`.
|
||||
The [LaTeXMathML] script will be used to render it as formulas.
|
||||
(This trick does not work in all browsers, but it works in Firefox.
|
||||
In browsers that do not support LaTeXMathML, TeX math will appear
|
||||
verbatim between $ characters.)
|
||||
1. The default is to render TeX math as far as possible using unicode
|
||||
characters, as with RTF, Docbook, and OpenDocument output. Formulas
|
||||
are put inside a `span` with `class="math"`, so that they may be
|
||||
styled differently from the surrounding text if needed.
|
||||
|
||||
3. If the `--jsmath` option is used, TeX math will be put inside
|
||||
`<span>` tags (for inline math) or `<div>` tags (for display math)
|
||||
with class `math`. The [jsMath] script will be used to render
|
||||
it.
|
||||
2. If the `--latexmathml` option is used, TeX math will be displayed
|
||||
between $ or $$ characters and put in `<span>` tags with class `LaTeX`.
|
||||
The [LaTeXMathML] script will be used to render it as formulas.
|
||||
(This trick does not work in all browsers, but it works in Firefox.
|
||||
In browsers that do not support LaTeXMathML, TeX math will appear
|
||||
verbatim between $ characters.)
|
||||
|
||||
4. If the `--mimetex` option is used, the [mimeTeX] CGI script will
|
||||
be called to generate images for each TeX formula. This should
|
||||
work in all browsers. The `--mimetex` option takes an optional URL
|
||||
as argument. If no URL is specified, it will be assumed that the
|
||||
mimeTeX CGI script is at `/cgi-bin/mimetex.cgi`.
|
||||
3. If the `--jsmath` option is used, TeX math will be put inside
|
||||
`<span>` tags (for inline math) or `<div>` tags (for display math)
|
||||
with class `math`. The [jsMath] script will be used to render
|
||||
it.
|
||||
|
||||
5. If the `--gladtex` option is used, TeX formulas will be enclosed
|
||||
in `<eq>` tags in the HTML output. The resulting `htex` file may then
|
||||
be processed by [gladTeX], which will produce image files for each
|
||||
formula and an `html` file with links to these images. So, the
|
||||
procedure is:
|
||||
4. If the `--mimetex` option is used, the [mimeTeX] CGI script will
|
||||
be called to generate images for each TeX formula. This should
|
||||
work in all browsers. The `--mimetex` option takes an optional URL
|
||||
as argument. If no URL is specified, it will be assumed that the
|
||||
mimeTeX CGI script is at `/cgi-bin/mimetex.cgi`.
|
||||
|
||||
pandoc -s --gladtex myfile.txt -o myfile.htex
|
||||
gladtex -d myfile-images myfile.htex
|
||||
# produces myfile.html and images in myfile-images
|
||||
5. If the `--gladtex` option is used, TeX formulas will be enclosed
|
||||
in `<eq>` tags in the HTML output. The resulting `htex` file may then
|
||||
be processed by [gladTeX], which will produce image files for each
|
||||
formula and an `html` file with links to these images. So, the
|
||||
procedure is:
|
||||
|
||||
6. If the `--webtex` option is used, TeX formulas will be converted
|
||||
to `<img>` tags that link to an external script that converts
|
||||
formulas to images. The formula will be URL-encoded and concatenated
|
||||
with the URL provided. If no URL is specified, the Google Chart
|
||||
API will be used (`http://chart.apis.google.com/chart?cht=tx&chl=`).
|
||||
pandoc -s --gladtex myfile.txt -o myfile.htex
|
||||
gladtex -d myfile-images myfile.htex
|
||||
# produces myfile.html and images in myfile-images
|
||||
|
||||
6. If the `--webtex` option is used, TeX formulas will be converted
|
||||
to `<img>` tags that link to an external script that converts
|
||||
formulas to images. The formula will be URL-encoded and concatenated
|
||||
with the URL provided. If no URL is specified, the Google Chart
|
||||
API will be used (`http://chart.apis.google.com/chart?cht=tx&chl=`).
|
||||
|
||||
|
||||
Raw TeX
|
||||
@@ -1404,7 +1437,16 @@ brackets. So, the following links are equivalent:
|
||||
Images
|
||||
------
|
||||
|
||||
TODO
|
||||
A link immediately preceded by a `!` will be treated as an image.
|
||||
The link text will be used as the image's alt text:
|
||||
|
||||
|
||||
|
||||
![movie reel]
|
||||
|
||||
[movie reel]: movie.gif
|
||||
|
||||
*Pandoc extension*.
|
||||
|
||||
An image occurring by itself in a paragraph will be rendered as
|
||||
a figure with a caption.[^5] (In LaTeX, a figure environment will be
|
||||
@@ -1447,7 +1489,8 @@ Pandoc's markdown allows footnotes, using the following syntax:
|
||||
line. In this way, multi-paragraph footnotes work like
|
||||
multi-paragraph list items.
|
||||
|
||||
This paragraph won't be part of the note, because it isn't indented.
|
||||
This paragraph won't be part of the note, because it
|
||||
isn't indented.
|
||||
|
||||
The identifiers in footnote references may not contain spaces, tabs,
|
||||
or newlines. These identifiers are used only to correlate the
|
||||
|
||||
Reference in New Issue
Block a user