- work to bridge between core/ORM tutorials regarding the text() construct

2 files changed, 31 insertions, 8 deletions

diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index c164dea4f..c15279236 100644
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -754,8 +754,8 @@ method calls is called :term:`method chaining`.
 
 .. _sqlexpression_text:
 
-Using Text
-===========
+Using Textual SQL
+=================
 
 Our last example really became a handful to type. Going from what one
 understands to be a textual SQL expression into a Python construct which
@@ -794,7 +794,27 @@ construct using the :meth:`~.TextClause.bindparams` method; if we are
 using datatypes that need special handling as they are received in Python,
 or we'd like to compose our :func:`~.expression.text` object into a larger
 expression, we may also wish to use the :meth:`~.TextClause.columns` method
-in order to specify column return types and names.
+in order to specify column return types and names:
+
+.. sourcecode:: pycon+sql
+
+    >>> s = text(
+    ...     "SELECT users.fullname || ', ' || addresses.email_address AS title "
+    ...         "FROM users, addresses "
+    ...         "WHERE users.id = addresses.user_id "
+    ...         "AND users.name BETWEEN :x AND :y "
+    ...         "AND (addresses.email_address LIKE :e1 "
+    ...             "OR addresses.email_address LIKE :e2)")
+    >>> s = s.columns(title=String)
+    >>> s = s.bindparams(x='m', y='z', e1='%@aol.com', e2='%@msn.com')
+    >>> conn.execute(s).fetchall() # doctest:+NORMALIZE_WHITESPACE
+    SELECT users.fullname || ', ' || addresses.email_address AS title
+    FROM users, addresses
+    WHERE users.id = addresses.user_id AND users.name BETWEEN ? AND ? AND
+    (addresses.email_address LIKE ? OR addresses.email_address LIKE ?)
+    ('m', 'z', '%@aol.com', '%@msn.com')
+    {stop}[(u'Wendy Williams, wendy@aol.com',)]
+
 
 :func:`~.expression.text` can also be used freely within a
 :func:`~.expression.select` object, which accepts :func:`~.expression.text`
@@ -841,6 +861,11 @@ need to refer to any pre-established :class:`.Table` metadata:
     the less flexibility and ability for manipulation/transformation
     the statement will have.
 
+.. seealso::
+
+    :ref:`orm_tutorial_literal_sql` - integrating ORM-level queries with
+    :func:`.text`
+
 .. versionchanged:: 1.0.0
    The :func:`.select` construct emits warnings when string SQL
    fragments are coerced to :func:`.text`, and :func:`.text` should
diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index 527481334..b3d6e2042 100644
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -908,7 +908,7 @@ database results.  Here's a brief tour:
 
 .. _orm_tutorial_literal_sql:
 
-Using Literal SQL
+Using Textual SQL
 -----------------
 
 Literal strings can be used flexibly with
@@ -994,10 +994,8 @@ We can choose columns to return individually as well, as in any other case:
 
 .. seealso::
 
-    :ref:`sqlexpression_text` - Core description of textual segments.  The
-    behavior of the ORM :class:`.Query` object with regards to
-    :func:`.text` and related constructs is very similar to that of the
-    Core :func:`.select` object.
+    :ref:`sqlexpression_text` - The :func:`.text` construct explained
+    from the perspective of Core-only queries.
 
 .. versionchanged:: 1.0.0
    The :class:`.Query` construct emits warnings when string SQL