some core cross linkage

4 files changed, 56 insertions, 20 deletions

diff --git a/doc/build/core/schema.rst b/doc/build/core/schema.rst
index 1ddf494bb..78fa6ee9c 100644
--- a/doc/build/core/schema.rst
+++ b/doc/build/core/schema.rst
@@ -148,9 +148,6 @@ table include::
     # get the table related by a foreign key
     list(employees.c.employee_dept.foreign_keys)[0].column.table
 
-.. _metadata_binding:
-
-
 Creating and Dropping Database Tables
 -------------------------------------
 
@@ -253,6 +250,7 @@ To enable the "check first for the table existing" logic, add the
     employees.create(engine, checkfirst=True)
     employees.drop(engine, checkfirst=False)
 
+.. _metadata_binding:
 
 Binding MetaData to an Engine or Connection
 --------------------------------------------
diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index dbac1c2fd..c615167d6 100644
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -188,6 +188,8 @@ each table first before creating, so it's safe to call multiple times:
     TABLE statements on a particular set of backends with more stringent
     requirements.
 
+.. _coretutorial_insert_expressions:
+
 Insert Expressions
 ==================
 
@@ -385,6 +387,8 @@ attached:
 Detailed examples of connectionless and implicit execution are available in
 the "Engines" chapter: :ref:`dbengine_implicit`.
 
+.. _coretutorial_selecting:
+
 Selecting
 ==========
 
diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py
index 25c7e30a2..7b5b3ab70 100644
--- a/lib/sqlalchemy/schema.py
+++ b/lib/sqlalchemy/schema.py
@@ -92,12 +92,16 @@ class Table(SchemaItem, expression.TableClause):
                    )
 
     The :class:`.Table` object constructs a unique instance of itself based on its
-    name and optionl schema name within the given :class:`.MetaData` object.   
+    name and optional schema name within the given :class:`.MetaData` object.   
     Calling the :class:`.Table`
     constructor with the same name and same :class:`.MetaData` argument 
     a second time will return the *same* :class:`.Table` object - in this way
     the :class:`.Table` constructor acts as a registry function.
     
+    See also:
+    
+    :ref:`metadata_describing` - Introduction to database metadata
+    
     Constructor arguments are as follows:
 
     :param name: The name of this table as represented in the database. 
@@ -2180,14 +2184,15 @@ class Index(ColumnCollectionMixin, SchemaItem):
                       (self.unique and ', unique=True') or '')
 
 class MetaData(SchemaItem):
-    """A collection of Tables and their associated schema constructs.
+    """A collection of :class:`.Table` objects and their associated schema constructs.
 
-    Holds a collection of Tables and an optional binding to an ``Engine`` or
-    ``Connection``.  If bound, the :class:`~sqlalchemy.schema.Table` objects
+    Holds a collection of :class:`.Table` objects as well as 
+    an optional binding to an :class:`.Engine` or
+    :class:`.Connection`.  If bound, the :class:`.Table` objects
     in the collection and their columns may participate in implicit SQL
     execution.
 
-    The `Table` objects themselves are stored in the `metadata.tables`
+    The :class:`.Table` objects themselves are stored in the ``metadata.tables``
     dictionary.
 
     The ``bind`` property may be assigned to dynamically.  A common pattern is
@@ -2202,6 +2207,12 @@ class MetaData(SchemaItem):
 
     MetaData is a thread-safe object after tables have been explicitly defined
     or loaded via reflection.
+    
+    See also:
+    
+    :ref:`metadata_describing` - Introduction to database metadata
+    
+    :ref:`metadata_binding` - Information on binding connectables to :class:`.MetaData`
 
     .. index::
       single: thread safety; MetaData
diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index fa0586e2d..dc8714371 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -170,6 +170,10 @@ def select(columns=None, whereclause=None, from_obj=[], **kwargs):
     string arguments, which will be converted as appropriate into
     either :func:`text()` or :func:`literal_column()` constructs.
 
+    See also:
+    
+    :ref:`coretutorial_selecting` - Core Tutorial description of :func:`.select`.
+    
     :param columns:
       A list of :class:`.ClauseElement` objects, typically
       :class:`.ColumnElement` objects or subclasses, which will form the
@@ -309,8 +313,12 @@ def subquery(alias, *args, **kwargs):
 def insert(table, values=None, inline=False, **kwargs):
     """Return an :class:`.Insert` clause element.
 
-    Similar functionality is available via the :func:`insert()` method on
-    :class:`~sqlalchemy.schema.Table`.
+    Similar functionality is available via the :meth:`~.schema.Table.insert` method on
+    :class:`~.schema.Table`.
+
+    See also:
+    
+    :ref:`coretutorial_insert_expressions` - Core Tutorial description of the :func:`.insert` construct.
 
     :param table: The table to be inserted into.
 
@@ -4063,7 +4071,7 @@ class _SelectBase(Executable, FromClause):
         """return a 'scalar' representation of this selectable, embedded as a
         subquery with a label.
 
-        See also ``as_scalar()``.
+        See also :meth:`~._SelectBase.as_scalar`.
 
         """
         return self.as_scalar().label(name)
@@ -4282,8 +4290,11 @@ class CompoundSelect(_SelectBase):
 class Select(_SelectBase):
     """Represents a ``SELECT`` statement.
 
-    Select statements support appendable clauses, as well as the
-    ability to execute themselves and return a result set.
+    See also:
+    
+    :func:`~.expression.select` - the function which creates a :class:`.Select` object.
+    
+    :ref:`coretutorial_selecting` - Core Tutorial description of :func:`.select`.
 
     """
 
@@ -4861,13 +4872,21 @@ class ValuesBase(UpdateBase):
         """specify the VALUES clause for an INSERT statement, or the SET
         clause for an UPDATE.
 
-            \**kwargs
-                key=<somevalue> arguments
+        :param \**kwargs: key value pairs representing the string key 
+          of a :class:`.Column` mapped to the value to be rendered into the
+          VALUES or SET clause::
 
-            \*args
-                A single dictionary can be sent as the first positional
-                argument. This allows non-string based keys, such as Column
-                objects, to be used.
+                users.insert().values(name="some name")
+
+                users.update().where(users.c.id==5).values(name="some name")
+
+        :param \*args: A single dictionary can be sent as the first positional
+            argument. This allows non-string based keys, such as Column
+            objects, to be used::
+            
+                users.insert().values({users.c.name : "some name"})
+
+                users.update().where(users.c.id==5).values({users.c.name : "some name"})
 
         """
         if args:
@@ -4886,7 +4905,11 @@ class ValuesBase(UpdateBase):
 class Insert(ValuesBase):
     """Represent an INSERT construct.
 
-    The :class:`.Insert` object is created using the :func:`insert()` function.
+    The :class:`.Insert` object is created using the :func:`~.expression.insert()` function.
+    
+    See also:
+    
+    :ref:`coretutorial_insert_expressions`
 
     """
     __visit_name__ = 'insert'