some compile docs

diff --git a/lib/sqlalchemy/ext/compiler.py b/lib/sqlalchemy/ext/compiler.py
index 0e3db00e02aeeec2e34143d22684e33ce6eda446..f893538e8ee036e23698d6427e3faae317edfedc 100644 (file)
--- a/lib/sqlalchemy/ext/compiler.py
+++ b/lib/sqlalchemy/ext/compiler.py
@@ -30,6 +30,9 @@ Produces::
 
     SELECT [x], [y]
 
+Dialect-specific compilation rules
+==================================
+
 Compilers can also be made dialect-specific.  The appropriate compiler will be invoked
 for the dialect in use::
 
@@ -51,6 +54,9 @@ for the dialect in use::
 
 The second ``visit_alter_table`` will be invoked when any ``postgres`` dialect is used.
 
+Compiling sub-elements of a custom expression construct
+=======================================================
+
 The ``compiler`` argument is the :class:`~sqlalchemy.engine.base.Compiled` object
 in use.  This object can be inspected for any information about the in-progress 
 compilation, including ``compiler.dialect``, ``compiler.statement`` etc.
@@ -76,6 +82,24 @@ Produces::
 
     "INSERT INTO mytable (SELECT mytable.x, mytable.y, mytable.z FROM mytable WHERE mytable.x > :x_1)"
 
+Changing the default compilation of existing constructs
+=======================================================
+
+The compiler extension applies just as well to the existing constructs.  When overriding
+the compilation of a built in SQL construct, the @compiles decorator is invoked upon
+the appropriate class (be sure to use the class, i.e. ``Insert`` or ``Select``, instead of the creation function such as ``insert()`` or ``select()``).
+
+Within the new compilation function, to get at the "original" compilation routine,
+use the appropriate visit_XXX method - this because compiler.process() will call upon the 
+overriding routine and cause an endless loop.   Such as, to add "prefix" to all insert statements::
+
+from sqlalchemy.sql.expression import Insert
+
+@compiles(Insert)
+def prefix_inserts(insert, compiler, **kw)
+    return compiler.visit_insert(insert.prefix_with("some prefix"), **kw)
+
+The above compiler will prefix all INSERT statements with "some prefix" when compiled.
 
 """