diff options
| -rw-r--r-- | README | 179 |
1 files changed, 111 insertions, 68 deletions
@@ -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: + +Markdown, reStructuredText, LaTeX, Org-Mode, ConTeXt + ~ It will appear verbatim between `$` characters. -In reStructuredText output, it will be rendered using an interpreted -text role `:math:`, as described -[here](http://www.american.edu/econ/itex2mml/mathhack.rst). +reStructuredText + ~ It will be rendered using an interpreted text role `:math:`, as described + [here](http://www.american.edu/econ/itex2mml/mathhack.rst). -In Texinfo output, it will be rendered inside a `@math` command. +Texinfo + ~ It will be rendered inside a `@math` command. -In groff man output, it will be rendered verbatim without `$`'s. +groff man + ~ It will be rendered verbatim without `$`'s. -In MediaWiki output, it will be rendered inside `<math>` tags. +MediaWiki + ~ It will be rendered inside `<math>` tags. -In Textile output, it will be rendered inside `<span class="math">` tags. +Textile + ~ It will be rendered inside `<span class="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. +RTF, Docbook, OpenDocument, ODT + ~ It will be rendered, if possible, using unicode characters, + and will otherwise appear verbatim. -In HTML, Slidy, and S5 output, the way math is rendered will depend on the -command-line options selected: +HTML, Slidy, S5, EPUB + ~ The way math is rendered in HTML will depend on the + command-line options selected: -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. + 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. -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.) + 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.) -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. + 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. -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`. + 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`. -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: + 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: - pandoc -s --gladtex myfile.txt -o myfile.htex - gladtex -d myfile-images myfile.htex - # produces myfile.html and images in myfile-images + 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=`). + 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 |