@@ -558,6 +558,9 @@ noting differences from standard markdown. Except where noted, these
558558differences can be suppressed by specifying the `--strict` command-line
559559option.
560560
561+Philosophy
562+----------
563+
561564Gruber designed markdown to be easy to write, and, even more importantly,
562565easy to read:
563566
@@ -619,6 +622,15 @@ As with setext-style headers, the header text can contain formatting:
619622
620623 # A level-one header with a [link](/url) and *emphasis*
621624
625+Standard markdown syntax does not require a blank line before a header.
626+Pandoc does require this (except, of course, at the beginning of the
627+document). The reason for the requirement is that it is all too easy for a
628+`#` to end up at the beginning of a line by accident (perhaps through line
629+wrapping). Consider, for example:
630+
631+ I like several of their flavors of ice cream:
632+ #22, for example, and #5.
633+
622634
623635### Header identifiers in HTML ###
624636
@@ -657,7 +669,8 @@ contents generated by the `--toc|--table-of-contents` option. They
657669also make it easy to provide links from one section of a document to
658670another. A link to this section, for example, might look like this:
659671
660− See the section on [header identifiers](#header-identifiers-in-html).
672+ See the section on
673+ [header identifiers](#header-identifiers-in-html).
661674
662675Note, however, that this method of providing links to sections works
663676only in HTML.
@@ -701,19 +714,15 @@ other block quotes. That is, block quotes can be nested:
701714 >
702715 > > A block quote within a block quote.
703716
717+Standard markdown syntax does not require a blank line before a block
718+quote. Pandoc does require this (except, of course, at the beginning of the
719+document). The reason for the requirement is that it is all too easy for a
720+`>` to end up at the beginning of a line by accident (perhaps through line
721+wrapping). So, unless `--strict` is used, the following does not produce
722+a nested block quote in pandoc:
704723
705−*** TODO: decide whether pandoc should require a blank
706−line btw nested ***
707−
708−Standard markdown syntax does not require a blank line before a header
709−or blockquote. Pandoc does require this (except, of course, at the
710−beginning of the document). The reason for the requirement is that
711−it is all too easy for a `>` or `#` to end up at the beginning of a
712−line by accident (perhaps through line wrapping). Consider, for
713−example:
714−
715− I like several of their flavors of ice cream:
716− #22, for example, and #5.
724+ > This is a block quote.
725+ >> Nested.
717726
718727
719728Verbatim (code) blocks
@@ -721,7 +730,18 @@ Verbatim (code) blocks
721730
722731### Indented code blocks ###
723732
724−TODO
733+A block of text indented four spaces (or one tab) is treated as verbatim
734+text: that is, special characters do not trigger special formatting,
735+and all spaces and line breaks are preserved. For example,
736+
737+ if (a > 3) {
738+ moveShip(5 * gravity, DOWN);
739+ }
740+
741+The initial (four space or one tab) indentation is not considered part
742+of the verbatim text, and is removed in the output.
743+
744+Note: blank lines in the verbatim text need not begin with four spaces.
725745
726746
727747### Delimited code blocks ###
@@ -735,7 +755,9 @@ as long as the starting row. Everything between the tilde-lines
735755is treated as code. No indentation is necessary:
736756
737757 ~~~~~~~
738− {code here}
758+ if (a > 3) {
759+ moveShip(5 * gravity, DOWN);
760+ }
739761 ~~~~~~~
740762
741763Like regular code blocks, delimited code blocks must be separated
@@ -783,6 +805,7 @@ Lists
783805
784806TODO
785807
808+TODO - rules for tight and loose
786809
787810### Ordered lists ###
788811
@@ -939,7 +962,12 @@ even though it is different from that of `Markdown.pl`.)
939962Horizontal rules
940963----------------
941964
942−TODO
965+A line containing a row of three or more `*`, `-`, or `_` characters
966+(optionally separated by spaces) produces a horizontal rule:
967+
968+ * * * *
969+
970+ ---------------
943971
944972
945973Tables
@@ -1046,7 +1074,7 @@ the table), or the table may be interpreted as a simple table.
10461074**Grid tables** look like this:
10471075
10481076 : Sample grid table.
1049−
1077+
10501078 +---------------+---------------+--------------------+
10511079 | Fruit | Price | Advantages |
10521080 +===============+===============+====================+
@@ -1244,69 +1272,74 @@ closing `$` must have a character immediately to its left. Thus,
12441272you need to enclose text in literal `$` characters, backslash-escape
12451273them and they won't be treated as math delimiters.
12461274
1247−TeX math will be printed in all output formats. In Markdown,
1248−reStructuredText, LaTeX, Org-Mode, and ConTeXt output, it will appear
1249−verbatim between `$` characters.
1275+TeX math will be printed in all output formats. How it is rendered
1276+depends on the output format:
1277+
1278+Markdown, reStructuredText, LaTeX, Org-Mode, ConTeXt
1279+ ~ It will appear verbatim between `$` characters.
12501280
1251−In reStructuredText output, it will be rendered using an interpreted
1252−text role `:math:`, as described
1253−[here](http://www.american.edu/econ/itex2mml/mathhack.rst).
1281+reStructuredText
1282+ ~ It will be rendered using an interpreted text role `:math:`, as described
1283+ [here](http://www.american.edu/econ/itex2mml/mathhack.rst).
12541284
1255−In Texinfo output, it will be rendered inside a `@math` command.
1285+Texinfo
1286+ ~ It will be rendered inside a `@math` command.
12561287
1257−In groff man output, it will be rendered verbatim without `$`'s.
1288+groff man
1289+ ~ It will be rendered verbatim without `$`'s.
12581290
1259−In MediaWiki output, it will be rendered inside `<math>` tags.
1291+MediaWiki
1292+ ~ It will be rendered inside `<math>` tags.
12601293
1261−In Textile output, it will be rendered inside `<span class="math">` tags.
1294+Textile
1295+ ~ It will be rendered inside `<span class="math">` tags.
12621296
1263−In RTF, Docbook, and OpenDocument output, it will be rendered, as far as
1264−possible, using unicode characters, and will otherwise appear verbatim.
1265−Unknown commands and symbols, and commands that cannot be dealt with
1266−this way (like `\frac`), will be rendered verbatim. So the results may
1267−be a mix of raw TeX code and properly rendered unicode math.
1297+RTF, Docbook, OpenDocument, ODT
1298+ ~ It will be rendered, if possible, using unicode characters,
1299+ and will otherwise appear verbatim.
12681300
1269−In HTML, Slidy, and S5 output, the way math is rendered will depend on the
1270−command-line options selected:
1301+HTML, Slidy, S5, EPUB
1302+ ~ The way math is rendered in HTML will depend on the
1303+ command-line options selected:
12711304
1272−1. The default is to render TeX math as far as possible using unicode
1273− characters, as with RTF, Docbook, and OpenDocument output. Formulas
1274− are put inside a `span` with `class="math"`, so that they may be
1275− styled differently from the surrounding text if needed.
1305+ 1. The default is to render TeX math as far as possible using unicode
1306+ characters, as with RTF, Docbook, and OpenDocument output. Formulas
1307+ are put inside a `span` with `class="math"`, so that they may be
1308+ styled differently from the surrounding text if needed.
12761309
1277−2. If the `--latexmathml` option is used, TeX math will be displayed
1278− between $ or $$ characters and put in `<span>` tags with class `LaTeX`.
1279− The [LaTeXMathML] script will be used to render it as formulas.
1280− (This trick does not work in all browsers, but it works in Firefox.
1281− In browsers that do not support LaTeXMathML, TeX math will appear
1282− verbatim between $ characters.)
1310+ 2. If the `--latexmathml` option is used, TeX math will be displayed
1311+ between $ or $$ characters and put in `<span>` tags with class `LaTeX`.
1312+ The [LaTeXMathML] script will be used to render it as formulas.
1313+ (This trick does not work in all browsers, but it works in Firefox.
1314+ In browsers that do not support LaTeXMathML, TeX math will appear
1315+ verbatim between $ characters.)
12831316
1284−3. If the `--jsmath` option is used, TeX math will be put inside
1285− `<span>` tags (for inline math) or `<div>` tags (for display math)
1286− with class `math`. The [jsMath] script will be used to render
1287− it.
1317+ 3. If the `--jsmath` option is used, TeX math will be put inside
1318+ `<span>` tags (for inline math) or `<div>` tags (for display math)
1319+ with class `math`. The [jsMath] script will be used to render
1320+ it.
12881321
1289−4. If the `--mimetex` option is used, the [mimeTeX] CGI script will
1290− be called to generate images for each TeX formula. This should
1291− work in all browsers. The `--mimetex` option takes an optional URL
1292− as argument. If no URL is specified, it will be assumed that the
1293− mimeTeX CGI script is at `/cgi-bin/mimetex.cgi`.
1322+ 4. If the `--mimetex` option is used, the [mimeTeX] CGI script will
1323+ be called to generate images for each TeX formula. This should
1324+ work in all browsers. The `--mimetex` option takes an optional URL
1325+ as argument. If no URL is specified, it will be assumed that the
1326+ mimeTeX CGI script is at `/cgi-bin/mimetex.cgi`.
12941327
1295−5. If the `--gladtex` option is used, TeX formulas will be enclosed
1296− in `<eq>` tags in the HTML output. The resulting `htex` file may then
1297− be processed by [gladTeX], which will produce image files for each
1298− formula and an `html` file with links to these images. So, the
1299− procedure is:
1328+ 5. If the `--gladtex` option is used, TeX formulas will be enclosed
1329+ in `<eq>` tags in the HTML output. The resulting `htex` file may then
1330+ be processed by [gladTeX], which will produce image files for each
1331+ formula and an `html` file with links to these images. So, the
1332+ procedure is:
13001333
1301− pandoc -s --gladtex myfile.txt -o myfile.htex
1302− gladtex -d myfile-images myfile.htex
1303− # produces myfile.html and images in myfile-images
1334+ pandoc -s --gladtex myfile.txt -o myfile.htex
1335+ gladtex -d myfile-images myfile.htex
1336+ # produces myfile.html and images in myfile-images
13041337
1305−6. If the `--webtex` option is used, TeX formulas will be converted
1306− to `<img>` tags that link to an external script that converts
1307− formulas to images. The formula will be URL-encoded and concatenated
1308− with the URL provided. If no URL is specified, the Google Chart
1309− API will be used (`http://chart.apis.google.com/chart?cht=tx&chl=`).
1338+ 6. If the `--webtex` option is used, TeX formulas will be converted
1339+ to `<img>` tags that link to an external script that converts
1340+ formulas to images. The formula will be URL-encoded and concatenated
1341+ with the URL provided. If no URL is specified, the Google Chart
1342+ API will be used (`http://chart.apis.google.com/chart?cht=tx&chl=`).
13101343
13111344
13121345Raw TeX
@@ -1404,7 +1437,16 @@ brackets. So, the following links are equivalent:
14041437Images
14051438------
14061439
1407−TODO
1440+A link immediately preceded by a `!` will be treated as an image.
1441+The link text will be used as the image's alt text:
1442+
1443+ 
1444+
1445+ ![movie reel]
1446+
1447+ [movie reel]: movie.gif
1448+
1449+*Pandoc extension*.
14081450
14091451An image occurring by itself in a paragraph will be rendered as
14101452a 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:
14471489 line. In this way, multi-paragraph footnotes work like
14481490 multi-paragraph list items.
14491491
1450− This paragraph won't be part of the note, because it isn't indented.
1492+ This paragraph won't be part of the note, because it
1493+ isn't indented.
14511494
14521495The identifiers in footnote references may not contain spaces, tabs,
14531496or newlines. These identifiers are used only to correlate the