@@ -597,40 +597,6 @@ These work like simple tables, but with the following differences:
597597 - They must end with a row of dashes, then a blank line.
598598 - The rows must be separated by blank lines.
599599
600−Embedded HTML
601−-------------
602−
603−Pandoc treats embedded HTML in markdown a bit differently than
604−Markdown 1.0. While Markdown 1.0 leaves HTML blocks exactly as they
605−are, Pandoc treats text between HTML tags as markdown. Thus, for
606−example, Pandoc will turn
607−
608− <table>
609− <tr>
610− <td>*one*</td>
611− <td>[a link](http://google.com)</td>
612− </tr>
613− </table>
614−
615−into
616−
617− <table>
618− <tr>
619− <td><em>one</em></td>
620− <td><a href="http://google.com">a link</a></td>
621− </tr>
622− </table>
623−
624−whereas `Markdown.pl` will preserve it as is.
625−
626−There is one exception to this rule: text between `<script>` and
627−`</script>` tags is not interpreted as markdown.
628−
629−This departure from standard markdown should make it easier to mix
630−markdown with HTML block elements. For example, one can surround
631−a block of markdown text with `<div>` tags without preventing it
632−from being interpreted as markdown.
633−
634600Title blocks
635601------------
636602
@@ -675,6 +641,75 @@ For example,
675641
676642The middle of the man page footer is used for the date.
677643
644+Markdown in HTML blocks
645+-----------------------
646+
647+While standard markdown leaves HTML blocks exactly as they are, Pandoc
648+treats text between HTML tags as markdown. Thus, for example, Pandoc
649+will turn
650+
651+ <table>
652+ <tr>
653+ <td>*one*</td>
654+ <td>[a link](http://google.com)</td>
655+ </tr>
656+ </table>
657+
658+into
659+
660+ <table>
661+ <tr>
662+ <td><em>one</em></td>
663+ <td><a href="http://google.com">a link</a></td>
664+ </tr>
665+ </table>
666+
667+whereas `Markdown.pl` will preserve it as is.
668+
669+There is one exception to this rule: text between `<script>` and
670+`</script>` tags is not interpreted as markdown.
671+
672+This departure from standard markdown should make it easier to mix
673+markdown with HTML block elements. For example, one can surround
674+a block of markdown text with `<div>` tags without preventing it
675+from being interpreted as markdown.
676+
677+Header identifiers in HTML
678+--------------------------
679+
680+Each header element in pandoc's HTML output is given a unique
681+identifier. This identifier is based on the text of the header. To
682+derive the identifier from the header text,
683+
684+ - Remove all formatting, links, etc.
685+ - Remove all punctuation, except dashes and hyphens.
686+ - Replace all spaces, dashes, newlines, and hyphens with hyphens.
687+ - Convert all alphabetic characters to lowercase.
688+
689+Thus,
690+
691+ Header text Identifier
692+ --------------------------------- --- ----------------------------
693+ Header identifiers in HTML → `header-identifiers-in-html`
694+ *Dogs*?--in *my* house? → `dogs--in-my-house`
695+ [HTML], [S5], or [RTF]? → `html-s5-or-rtf`
696+
697+These rules should, in most cases, allow one to determine the identifier
698+from the header text. The exception is when several headers have the
699+same text; in this case, the first will get an identifier as described
700+above; the second will get the same identifier with `-1` appended; the
701+third with `-2`; and so on.
702+
703+These identifiers are used to provide link targets in the table of
704+contents generated by the `--toc|--table-of-contents` option. They
705+also make it easy to provide links from one section of a document to
706+another. A link to this section, for example, might look like this:
707+
708+ See the section on [header identifiers](#header-identifiers-in-html).
709+
710+Note, however, that this method of providing links to sections works
711+only in HTML.
712+
678713Box-style blockquotes
679714---------------------
680715