[SQL-CVS] SQLObject/docs SQLObject.txt,1.13,1.14

[<ian...@us...>]

Update of /cvsroot/sqlobject/SQLObject/docs
In directory sc8-pr-cvs1:/tmp/cvs-serv3421

Modified Files:
	SQLObject.txt 
Log Message:
Added internal references


Index: SQLObject.txt
===================================================================
RCS file: /cvsroot/sqlobject/SQLObject/docs/SQLObject.txt,v
retrieving revision 1.13
retrieving revision 1.14
diff -C2 -d -r1.13 -r1.14
*** SQLObject.txt	28 Jun 2003 22:19:08 -0000	1.13
--- SQLObject.txt	28 Jun 2003 22:36:20 -0000	1.14
***************
*** 149,154 ****
  
  We'll develop a simple addressbook-like database.  We could create the
! tables ourselves (which I'll show later @@: link), but for now we'll
! let SQLObject do that work.  First, the class:
  
  .. raw:: html
--- 149,154 ----
  
  We'll develop a simple addressbook-like database.  We could create the
! tables ourselves, and just have SQLObject access those tables, but for
! now we'll let SQLObject do that work.  First, the class:
  
  .. raw:: html
***************
*** 169,174 ****
  different (especially the ``id`` column).  You'll notice the names
  were changed from mixedCase to underscore_separated -- this is done by
! the style object (@@: link).  There are a variety of ways to handle
! other names that are not as SQLObject expects (@@: link).
  
  The tables don't yet exist.  We'll let SQLObject create them:
--- 169,176 ----
  different (especially the ``id`` column).  You'll notice the names
  were changed from mixedCase to underscore_separated -- this is done by
! the `style object`_.  There are a variety of ways to handle
! other names that are not as SQLObject expects (see `Irregular Naming`_).
! 
! .. _`style object`: `Changing the Naming Style`_
  
  The tables don't yet exist.  We'll let SQLObject create them:
***************
*** 178,183 ****
  
  We can change the type of the various columns by using something other
! than `StringCol`, or using different arguments.  More about this @@:
! link.
  
  If you don't want to do table creation (you already have tables, or
--- 180,185 ----
  
  We can change the type of the various columns by using something other
! than `StringCol`, or using different arguments.  More about this in
! `Subclasses of Col`_.
  
  If you don't want to do table creation (you already have tables, or
***************
*** 190,195 ****
  definition, it is implied.  For MySQL databases it should be defined
  as ``INT PRIMARY KEY AUTO_INCREMENT``, in Postgres ``SERIAL PRIMARY
! KEY``, and in SQLite as ``INTEGER PRIMARY KEY``.  You can override the
! name (@@: link), but some integer primary key must exist.
  
  Using the Class
--- 192,199 ----
  definition, it is implied.  For MySQL databases it should be defined
  as ``INT PRIMARY KEY AUTO_INCREMENT``, in Postgres ``SERIAL PRIMARY
! KEY``, and in SQLite as ``INTEGER PRIMARY KEY``.  You can `override the
! name`__, but some integer primary key must exist.
! 
! __ idName_
  
  Using the Class
***************
*** 227,231 ****
  multiple threads accessing the same data (though of course across
  processes there can be no sharing of an instance).  This changes if
! you're using transactions (@@: link).
  
  To get an idea of what's happening behind the surface, I'll give the
--- 231,235 ----
  multiple threads accessing the same data (though of course across
  processes there can be no sharing of an instance).  This changes if
! you're using transactions_.
  
  To get an idea of what's happening behind the surface, I'll give the
***************
*** 352,360 ****
  you're selecting is always assumed to be included, of course.
  
  You can use the keyword arguments `orderBy` and `groupBy` to create
  ``ORDER BY`` and ``GROUP BY`` in the select statements: `orderBy`
  takes a string, which should be the *database* name of the column, or
  a column in the form ``Person.q.firstName``; `groupBy` is similar.
! Both accept lists or tuples of arguments.
  
  You can use the special class variable `_defaultOrder` to give a
--- 356,367 ----
  you're selecting is always assumed to be included, of course.
  
+ .. _orderBy:
+ 
  You can use the keyword arguments `orderBy` and `groupBy` to create
  ``ORDER BY`` and ``GROUP BY`` in the select statements: `orderBy`
  takes a string, which should be the *database* name of the column, or
  a column in the form ``Person.q.firstName``; `groupBy` is similar.
! Both accept lists or tuples of arguments.  You can use ``"-colname"``
! to specify descending order, or call ``MyClass.select().reversed()``.
  
  You can use the special class variable `_defaultOrder` to give a
***************
*** 542,546 ****
  `ForeignKey`:
      A key to another table/class.  Use like ``user =
!     ForeignKey('User')``. (@@: test)
  `EnumCol`:
      One of several string values -- give the possible strings as a
--- 549,553 ----
  `ForeignKey`:
      A key to another table/class.  Use like ``user =
!     ForeignKey('User')``.
  `EnumCol`:
      One of several string values -- give the possible strings as a
***************
*** 569,578 ****
--- 576,588 ----
      class).  You can also pass a connection object in at instance
      creation time, as described in transactions_.
+ 
  `_table`:
      The database name of the table for this class.  If you don't give
      a name, then the standard ``MixedCase`` to ``mixed_case``
      translation is performed.
+ 
  `_joins`:
      A list of `Join` objects.  This is covered below.
+ 
  `_cacheValues`:
      If set to ``False`` then values for attributes from the database
***************
*** 582,591 ****
      then this is probably the way to do so.  You should also use
      it with transactions_ (it is not implied).
  `_idName`:
      The name of the primary key column (default ``id``).
  `_style`:
      A style object -- this object allows you to use other algorithms
      for translating between Python attribute and class names, and the
!     database's column and table names. (@@: link)
  
  Relationships Between Classes/Tables
--- 592,608 ----
      then this is probably the way to do so.  You should also use
      it with transactions_ (it is not implied).
+ 
+ .. _idName:
+ 
  `_idName`:
      The name of the primary key column (default ``id``).
+ 
  `_style`:
      A style object -- this object allows you to use other algorithms
      for translating between Python attribute and class names, and the
!     database's column and table names.  See `Changing the Naming
!     Style`_ for more.
! 
! .. Relationships_:
  
  Relationships Between Classes/Tables
***************
*** 611,619 ****
      points to this table, then you'd use ``joinColumn="ProductNo"``.
  `orderBy`:
!     Like the `orderBy` argument to `select()` (@@: link), you can specify
      the order that the joined objects should be returned in.  `_defaultOrder`
      will be used if not specified; ``None`` forces unordered results.
  `joinMethodName`:
!     When adding joins dynamically (using the class method `addJoin` @@: link),
      you can give the name of the accessor for the join.  It can also be
      created automatically, and is normally implied (i.e., ``addresses = 
--- 628,636 ----
      points to this table, then you'd use ``joinColumn="ProductNo"``.
  `orderBy`:
!     Like the `orderBy`_ argument to `select()`, you can specify
      the order that the joined objects should be returned in.  `_defaultOrder`
      will be used if not specified; ``None`` forces unordered results.
  `joinMethodName`:
!     When adding joins dynamically (using the class method `addJoin`_),
      you can give the name of the accessor for the join.  It can also be
      created automatically, and is normally implied (i.e., ``addresses = 
***************
*** 634,641 ****
      The name of the intermediate table which references both classes.
  `addRemoveName`:
!     In the user/role example (@@: link), the methods `addRole(role)` and 
      `removeRole(role)` are created.  The ``Role`` portion of these
      method names can be changed by giving a string value here.
  
  An example schema that requires the use of `joinColumn`, `otherColumn`,
  and `intermediateTable`::
--- 651,660 ----
      The name of the intermediate table which references both classes.
  `addRemoveName`:
!     In the `user/role example`__, the methods `addRole(role)` and 
      `removeRole(role)` are created.  The ``Role`` portion of these
      method names can be changed by giving a string value here.
  
+ __ `Many-to-Many Relationships`_
+ 
  An example schema that requires the use of `joinColumn`, `otherColumn`,
  and `intermediateTable`::
***************
*** 726,730 ****
      This is a reference to another table.  You typically need to
      only give the name of the foreign class that is referenced.
!     `ForeignKey` implies an ``INT`` column.  (@@: link)
  
  Creating and Dropping Tables
--- 745,749 ----
      This is a reference to another table.  You typically need to
      only give the name of the foreign class that is referenced.
!     `ForeignKey` implies an ``INT`` column.
  
  Creating and Dropping Tables
***************
*** 785,792 ****
  ``MyClass.delColumn("username")``).
  
! You can also add Joins (@@: link), like 
  ``MyClass.addJoin(MultipleJoin("MyOtherClass"))``, and remove joins with
  `delJoin`.  `delJoin` does not take strings, you have to get the join
  object out of the `_joins` attribute.
  
  Legacy Database Schemas
--- 804,815 ----
  ``MyClass.delColumn("username")``).
  
! .. _addJoin:
! 
! You can also add Joins__, like 
  ``MyClass.addJoin(MultipleJoin("MyOtherClass"))``, and remove joins with
  `delJoin`.  `delJoin` does not take strings, you have to get the join
  object out of the `_joins` attribute.
+ 
+ __ Relationships_:
  
  Legacy Database Schemas