[svn] Document the new HTML formatter interface.

1 files changed, 56 insertions, 2 deletions

diff --git a/pygments/formatters/html.py b/pygments/formatters/html.py
index f1cd1a25..d5e9c3f7 100644
--- a/pygments/formatters/html.py
+++ b/pygments/formatters/html.py
@@ -206,6 +206,52 @@ class HtmlFormatter(Formatter):
         which is enough to break a line inside ``<pre>`` tags, but you can
         e.g. set it to ``"<br>"`` to get HTML line breaks. *New in Pygments
         0.7.*
+
+    Subclassing the HTML formatter
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    *New in Pygments 0.7.* 
+
+    The HTML formatter is now built in a way that allows easy subclassing, thus
+    customizing the output HTML code. The `format()` method creates a basic
+    generator by calling `self._format_lines()`. The resulting iterator yields
+    tuples of ``(code, text)``, where ``code`` is always ``1`` and indicates that
+    the ``text`` is a line of the formatted source code.
+
+    If the `nowrap` option is set, the generator is the iterated over and the
+    resulting HTML is output.
+
+    Otherwise, `format()` calls `self.wrap()`, which wraps the generator with other
+    generators. These add some HTML code to the one generated by `_format_lines()`,
+    either by modifying the lines generated by the latter, then yielding them again
+    with ``(1, line)``, and/or by yielding other code before or after the lines,
+    with ``(0, html)``. The distinction between source lines and other code makes it
+    possible to wrap the generator multiple times.
+
+    The default `wrap()` implementation adds a ``<div>`` and a ``<pre>`` tag.
+
+    A custom `HtmlFormatter` subclass could look like this:
+
+    .. sourcecode:: python
+
+        class CodeHtmlFormatter(HtmlFormatter):
+
+            def wrap(self, source, outfile):
+                return self._wrap_code(source)
+
+            def _wrap_code(self, source):
+                yield 0, '<code>'
+                for i, t in source:
+                    if i == 1:
+                        t += '<br>'
+                    yield i, t
+                yield 0, '</code>'
+
+    This results in wrapping the formatted lines with a ``<code>`` tag, where the
+    source lines are broken using ``<br>`` tags.
+
+    After calling `wrap()`, the `format()` method also adds the "line numbers"
+    and/or "full document" wrappers if the respective options are set.
     """
 
     def __init__(self, **options):
@@ -419,6 +465,14 @@ class HtmlFormatter(Formatter):
         if line:
             yield 1, line + (lspan and '</span>') + lsep
 
+    def wrap(self, source, outfile):
+        """
+        Wrap the ``source``, which is a generator yielding
+        individual lines, in custom generators. See docstring
+        for `format`. Can be overridden.
+        """
+        return self._wrap_div(self._wrap_pre(source))
+
     def format(self, tokensource, outfile):
         """
         The formatting process uses several nested generators; which of
@@ -427,7 +481,7 @@ class HtmlFormatter(Formatter):
         Each generator should take at least one argument, ``inner``,
         and wrap the pieces of text generated by this.
 
-        Always yield 2-tuples: (core, text). If "core" is 1, the text
+        Always yield 2-tuples: (code, text). If "code" is 1, the text
         is part of the original tokensource being highlighted, if it's
         0, the text is some piece of wrapping. This makes it possible to
         use several different wrappers that process the original source
@@ -435,7 +489,7 @@ class HtmlFormatter(Formatter):
         """
         source = self._format_lines(tokensource)
         if not self.nowrap:
-            source = self._wrap_div(self._wrap_pre(source))
+            source = self.wrap(source, outfile)
             if self.linenos:
                 source = self._wrap_linenos(source)
             if self.full: