update the intro to accommodate for the 1.4/2.0 overview

Change-Id: Ida77a4d89a2cb8a67a4608831f66a5ab533e0472

diff --git a/doc/build/intro.rst b/doc/build/intro.rst
index af76b0caa1187e024275c23e36b07b88ece212d6..9451d92bd1ce38b4bf4f2e6188786787bf4cf76f 100644 (file)
--- a/doc/build/intro.rst
+++ b/doc/build/intro.rst
@@ -15,34 +15,59 @@ with component dependencies organized into layers:
 .. image:: sqla_arch_small.png
 
 Above, the two most significant front-facing portions of
-SQLAlchemy are the **Object Relational Mapper** and the
-**SQL Expression Language**. SQL Expressions can be used
-independently of the ORM. When using the ORM, the SQL
-Expression language remains part of the public facing API
-as it is used within object-relational configurations and
-queries.
+SQLAlchemy are the **Object Relational Mapper (ORM)** and the
+**Core**.
+
+Core contains the breadth of SQLAlchemy's SQL and database
+integration and description services, the most prominent part of this
+being the **SQL Expression Language**.
+
+The SQL Expression Language is a toolkit all its own, independent of the ORM
+package, which provides a system of constructing SQL expressions represented by
+composable objects, which can then be "executed" against a target database
+within the scope of a specific transaction, returning a result set.
+Inserts, updates and deletes (i.e. :term:`DML`) are achieved by passing
+SQL expression objects representing these statements along with dictionaries
+that represent parameters to be used with each statement.
+
+The ORM builds upon Core to provide a means of working with a domain object
+model mapped to a database schema. When using the ORM, SQL statements are
+constructed in mostly the same way as when using Core, however the task of DML,
+which here refers to the persistence of business objects in a database, is
+automated using a pattern called :term:`unit of work`, which translates changes
+in state against mutable objects into INSERT, UPDATE and DELETE constructs
+which are then invoked in terms of those objects. SELECT statements are also
+augmented by ORM-specific automations and object-centric querying capabilities.
+
+Whereas working with Core and the SQL Expression language presents a
+schema-centric view of the database, along with a programming paradigm that is
+oriented around immutability, the ORM builds on top of this a domain-centric
+view of the database with a programming paradigm that is more explcitly
+object-oriented and reliant upon mutability.  Since a relational database is
+itself a mutable service, the difference is that Core/SQL Expression language
+is command oriented whereas the ORM is state oriented.
+
 
 .. _doc_overview:
 
 Documentation Overview
 ======================
 
-The documentation is separated into three sections: :ref:`orm_toplevel`,
+The documentation is separated into four sections: :ref:`unified_tutorial`,
+:ref:`orm_toplevel`,
 :ref:`core_toplevel`, and :ref:`dialect_toplevel`.
 
-In :ref:`orm_toplevel`, the Object Relational Mapper is introduced and fully
-described. New users should begin with the :ref:`ormtutorial_toplevel`. If you
-want to work with higher-level SQL which is constructed automatically for you,
-as well as management of Python objects, proceed to this tutorial.
-
-In :ref:`core_toplevel`, the breadth of SQLAlchemy's SQL and database
-integration and description services are documented, the core of which is the
-SQL Expression language. The SQL Expression Language is a toolkit all its own,
-independent of the ORM package, which can be used to construct manipulable SQL
-expressions which can be programmatically constructed, modified, and executed,
-returning cursor-like result sets. In contrast to the ORM's domain-centric
-mode of usage, the expression language provides a schema-centric usage
-paradigm. New users should begin here with :ref:`sqlexpression_toplevel`.
+In :ref:`unified_tutorial`, this all-new tutorial for the 1.4/2.0 series
+of SQLAlchemy introduces the entire library holistically, starting
+from a description of Core and working more and more towards ORM-specific
+concepts.    New users, as well as users coming from :term:`1.x style`,
+who wish to work in :term:`2.0 style` should start here.
+
+In :ref:`orm_toplevel`, reference documentation for the ORM is presented; this
+section also includes the now-legacy :ref:`ormtutorial_toplevel`.
+
+In :ref:`core_toplevel`, reference documentation for everything else within
+Core is presented; section also includes the legacy :ref:`sqlexpression_toplevel`.
 SQLAlchemy engine, connection, and pooling services are also described in
 :ref:`core_toplevel`.