aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README103
1 files changed, 69 insertions, 34 deletions
diff --git a/README b/README
index c41aa4bd5..1c732e511 100644
--- a/README
+++ b/README
@@ -597,40 +597,6 @@ These work like simple tables, but with the following differences:
- They must end with a row of dashes, then a blank line.
- The rows must be separated by blank lines.
-Embedded HTML
--------------
-
-Pandoc treats embedded HTML in markdown a bit differently than
-Markdown 1.0. While Markdown 1.0 leaves HTML blocks exactly as they
-are, Pandoc treats text between HTML tags as markdown. Thus, for
-example, Pandoc will turn
-
- <table>
- <tr>
- <td>*one*</td>
- <td>[a link](http://google.com)</td>
- </tr>
- </table>
-
-into
-
- <table>
- <tr>
- <td><em>one</em></td>
- <td><a href="http://google.com">a link</a></td>
- </tr>
- </table>
-
-whereas `Markdown.pl` will preserve it as is.
-
-There is one exception to this rule: text between `<script>` and
-`</script>` tags is not interpreted as markdown.
-
-This departure from standard markdown should make it easier to mix
-markdown with HTML block elements. For example, one can surround
-a block of markdown text with `<div>` tags without preventing it
-from being interpreted as markdown.
-
Title blocks
------------
@@ -675,6 +641,75 @@ For example,
The middle of the man page footer is used for the date.
+Markdown in HTML blocks
+-----------------------
+
+While standard markdown leaves HTML blocks exactly as they are, Pandoc
+treats text between HTML tags as markdown. Thus, for example, Pandoc
+will turn
+
+ <table>
+ <tr>
+ <td>*one*</td>
+ <td>[a link](http://google.com)</td>
+ </tr>
+ </table>
+
+into
+
+ <table>
+ <tr>
+ <td><em>one</em></td>
+ <td><a href="http://google.com">a link</a></td>
+ </tr>
+ </table>
+
+whereas `Markdown.pl` will preserve it as is.
+
+There is one exception to this rule: text between `<script>` and
+`</script>` tags is not interpreted as markdown.
+
+This departure from standard markdown should make it easier to mix
+markdown with HTML block elements. For example, one can surround
+a block of markdown text with `<div>` tags without preventing it
+from being interpreted as markdown.
+
+Header identifiers in HTML
+--------------------------
+
+Each header element in pandoc's HTML output is given a unique
+identifier. This identifier is based on the text of the header. To
+derive the identifier from the header text,
+
+ - Remove all formatting, links, etc.
+ - Remove all punctuation, except dashes and hyphens.
+ - Replace all spaces, dashes, newlines, and hyphens with hyphens.
+ - Convert all alphabetic characters to lowercase.
+
+Thus,
+
+ Header text Identifier
+ --------------------------------- --- ----------------------------
+ Header identifiers in HTML → `header-identifiers-in-html`
+ *Dogs*?--in *my* house? → `dogs--in-my-house`
+ [HTML], [S5], or [RTF]? → `html-s5-or-rtf`
+
+These rules should, in most cases, allow one to determine the identifier
+from the header text. The exception is when several headers have the
+same text; in this case, the first will get an identifier as described
+above; the second will get the same identifier with `-1` appended; the
+third with `-2`; and so on.
+
+These identifiers are used to provide link targets in the table of
+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).
+
+Note, however, that this method of providing links to sections works
+only in HTML.
+
Box-style blockquotes
---------------------