- Another pass through the series of error messages

emitted when relationship() is configured with
ambiguous arguments.   The "foreign_keys"
setting is no longer mentioned, as it is almost
never needed and it is preferable users set up
correct ForeignKey metadata, which is now the
recommendation.  If 'foreign_keys'
is used and is incorrect, the message suggests
the attribute is probably unnecessary.  Docs
for the attribute are beefed up.  This
because all confused relationship() users on the
ML appear to be attempting to use foreign_keys
due to the message, which only confuses them
further since Table metadata is much clearer.

- If the "secondary" table has no ForeignKey metadata
and no foreign_keys is set, even though the
user is passing screwed up information, it is assumed
that primary/secondaryjoin expressions should
consider only and all cols in "secondary" to be
foreign.  It's not possible with "secondary" for
the foreign keys to be elsewhere in any case.
A warning is now emitted instead of an error,
and the mapping succeeds. [ticket:1877]

- fixed incorrect "Alternate Collection Mappings" reference
in the docs, not sure if someone wants to reference
"Rows that Point to Themselves" function
- "Collection Mapping" is "Advanced Collection Mapping", this
section is troublesome since nobody really needs it but it
is public API

3 files changed, 4 insertions, 5 deletions

diff --git a/doc/build/mappers.rst b/doc/build/mappers.rst
index 97677aa08..71f71a8cf 100644
--- a/doc/build/mappers.rst
+++ b/doc/build/mappers.rst
@@ -1490,7 +1490,6 @@ Theres no restriction on how many times you can relate from parent to child.  SQ
                     addresses_table.c.city=='New York')),
     })
 
-.. _alternate_collection_implementations:
 
 Rows that point to themselves / Mutually Dependent Rows
 -------------------------------------------------------
@@ -1528,7 +1527,7 @@ To enable the UPDATE after INSERT / UPDATE before DELETE behavior on :func:`~sql
 When a structure using the above mapping is flushed, the "widget" row will be INSERTed minus the "favorite_entry_id" value, then all the "entry" rows will be INSERTed referencing the parent "widget" row, and then an UPDATE statement will populate the "favorite_entry_id" column of the "widget" table (it's one row at a time for the time being).
 
 
-.. _advdatamapping_entitycollections:
+.. _alternate_collection_implementations:
 
 Alternate Collection Implementations
 -------------------------------------
diff --git a/doc/build/ormtutorial.rst b/doc/build/ormtutorial.rst
index 2d6a3325e..6f38a35c9 100644
--- a/doc/build/ormtutorial.rst
+++ b/doc/build/ormtutorial.rst
@@ -781,7 +781,7 @@ We'll need to create the ``addresses`` table in the database, so we will issue a
 Working with Related Objects
 =============================
 
-Now when we create a ``User``, a blank ``addresses`` collection will be present.  Various collection types, such as sets and dictionaries, are possible here (see :ref:`advdatamapping_entitycollections` for details), but by default, the collection is a Python list.
+Now when we create a ``User``, a blank ``addresses`` collection will be present.  Various collection types, such as sets and dictionaries, are possible here (see :ref:`alternate_collection_implementations` for details), but by default, the collection is a Python list.
 
 .. sourcecode:: python+sql
 
diff --git a/doc/build/reference/orm/collections.rst b/doc/build/reference/orm/collections.rst
index 350e63125..818f11498 100644
--- a/doc/build/reference/orm/collections.rst
+++ b/doc/build/reference/orm/collections.rst
@@ -1,5 +1,5 @@
-Collection Mapping
-==================
+Advanced Collection Mapping
+===========================
 
 This is an in-depth discussion of collection mechanics.  For simple examples, see :ref:`alternate_collection_implementations`.