# HG changeset patch
# User cmlenz
# Date 1174583649 0
# Node ID e7a4d43c438a2967bd5448cef9a7b6e2f4a0f5fb
# Parent  6911f3c5a7e8c9666482f6e0710b028f6b6ff885
Moved the `builder` document into the API docs.

diff --git a/doc/builder.txt b/doc/builder.txt
deleted file mode 100644
--- a/doc/builder.txt
+++ /dev/null
@@ -1,72 +0,0 @@
-.. -*- mode: rst; encoding: utf-8 -*-
-
-==================================
-Generating Markup Programmatically
-==================================
-
-Genshi provides a ``builder`` module which lets you generate markup from Python
-code using a very simple syntax. The main entry point to the ``builder`` module
-is the ``tag`` object (which is actually an instance of the ``ElementFactory``
-class). You should rarely (if ever) need to directly import and use any of the
-other classes in the ``builder`` module.
-
-
-.. contents:: Contents
-   :depth: 2
-.. sectnum::
-
-
-Creating Elements
-=================
-
-Elements can be created through the `tag` object using attribute access, for
-example::
-
-  >>> from genshi.builder import tag
-  >>> doc = tag.p('Some text and ', tag.a('a link', href='http://example.org/'), '.')
-  >>> doc
-  <Element "p">
-
-This produces an ``Element`` instance which can be further modified to add child
-nodes and attributes. This is done by “calling” the element: positional
-arguments are added as child nodes (alternatively, the ``append`` method can be
-used for that purpose), whereas keywords arguments are added as attributes::
-
-  >>> doc(tag.br)
-  <Element "p">
-  >>> print doc
-  <p>Some text and <a href="http://example.org/">a link</a>.<br/></p>
-
-If an attribute name collides with a Python keyword, simply append an underscore
-to the name::
-
-  >>> doc(class_='intro')
-  <Element "p">
-  >>> print doc
-  <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
-
-As shown above, an ``Element`` can easily be directly rendered to XML text by
-printing it or using the Python ``str()`` function. This is basically a
-shortcut for converting the ``Element`` to a stream and serializing that
-stream::
-
-  >>> stream = doc.generate()
-  >>> stream
-  <genshi.core.Stream object at ...>
-  >>> print stream
-  <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
-
-
-Creating Fragments
-==================
-
-The ``tag`` object also allows creating “fragments”, which are basically lists
-of nodes (elements or text) that don't have a parent element. This can be useful
-for creating snippets of markup that are attached to a parent element later (for
-example in a template). Fragments are created by calling the ``tag`` object::
-
-  >>> fragment = tag('Hello, ', tag.em('world'), '!')
-  >>> fragment
-  <Fragment>
-  >>> print fragment
-  Hello, <em>world</em>!
diff --git a/doc/index.txt b/doc/index.txt
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -21,7 +21,6 @@
 which is heavily inspired by Kid.
 
 * `Markup Streams <streams.html>`_
-* `Generating Markup Programmatically <builder.html>`_
 * `Genshi XML Template Language <xml-templates.html>`_
 * `Genshi Text Template Language <text-templates.html>`_
 * `Using XPath in Genshi <xpath.html>`_
diff --git a/doc/style/apidoc.css b/doc/style/apidoc.css
--- a/doc/style/apidoc.css
+++ b/doc/style/apidoc.css
@@ -110,7 +110,7 @@
 .py-string, .variable-string, .variable-quote { color: #093; }
 .py-comment { color: #06f; font-style: italic; }
 .py-keyword { color: #00f; }
-.py-output { background: #f6f6f0; font-weight: bold; }
+.py-output { background: #f6f6f0; color: #666; font-weight: bold; }
 
 /* Index */
 
diff --git a/genshi/builder.py b/genshi/builder.py
--- a/genshi/builder.py
+++ b/genshi/builder.py
@@ -11,7 +11,62 @@
 # individuals. For the exact contribution history, see the revision
 # history and logs, available at http://genshi.edgewall.org/log/.
 
-"""Support for programmatically generating markup streams."""
+"""Support for programmatically generating markup streams from Python code using
+a very simple syntax. The main entry point to this module is the `tag` object
+(which is actually an instance of the ``ElementFactory`` class). You should
+rarely (if ever) need to directly import and use any of the other classes in
+this module.
+
+Elements can be created using the `tag` object using attribute access. For
+example:
+
+>>> doc = tag.p('Some text and ', tag.a('a link', href='http://example.org/'), '.')
+>>> doc
+<Element "p">
+
+This produces an `Element` instance which can be further modified to add child
+nodes and attributes. This is done by "calling" the element: positional
+arguments are added as child nodes (alternatively, the `Element.append` method
+can be used for that purpose), whereas keywords arguments are added as
+attributes:
+
+>>> doc(tag.br)
+<Element "p">
+>>> print doc
+<p>Some text and <a href="http://example.org/">a link</a>.<br/></p>
+
+If an attribute name collides with a Python keyword, simply append an underscore
+to the name:
+
+>>> doc(class_='intro')
+<Element "p">
+>>> print doc
+<p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
+
+As shown above, an `Element` can easily be directly rendered to XML text by
+printing it or using the Python ``str()`` function. This is basically a
+shortcut for converting the `Element` to a stream and serializing that
+stream:
+
+>>> stream = doc.generate()
+>>> stream
+<genshi.core.Stream object at ...>
+>>> print stream
+<p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
+
+
+The `tag` object also allows creating "fragments", which are basically lists
+of nodes (elements or text) that don't have a parent element. This can be useful
+for creating snippets of markup that are attached to a parent element later (for
+example in a template). Fragments are created by calling the `tag` object, which
+returns an object of type `Fragment`:
+
+>>> fragment = tag('Hello, ', tag.em('world'), '!')
+>>> fragment
+<Fragment>
+>>> print fragment
+Hello, <em>world</em>!
+"""
 
 from genshi.core import Attrs, Namespace, QName, Stream, START, END, TEXT