updated index docs

manual/docs/Getting started - Indexes - Adding indexes.php

 <?php ?>
-You can add indexes by simple calling Doctrine_Record::option('index', $definition) where $definition is the 
-definition array. The structure of the definition array is as follows:
-<div class='sql'>
-<pre>
-[   indexName1 => [col1 => [col1-options], ... , colN => [colN-options]
-    indexName2 => ...
-    indexNameN => ]
-</pre>
-</div>
+You can add indexes by simple calling Doctrine_Record::index('indexName', $definition) where $definition is the
+definition array.
 <br \><br \>
 An example of adding a simple index to field called 'name':
 <br \><br \>
@@ -21,7 +14,7 @@ class IndexTest extends Doctrine_Record
     }
     public function setUp()
     {
-        \$this->option('index', array('myindex' => 'name'));
+        \$this->index('myindex', array('fields' => 'name');
     }
 }
 ?>");
@@ -40,7 +33,7 @@ class MultiColumnIndexTest extends Doctrine_Record
     }
     public function setUp()
     {
-        \$this->option('index', array('myindex' => array('name', 'code')));
+        \$this->index('myindex', array('fields' => array('name', 'code')));
     }
 }
 ?>");
@@ -60,10 +53,8 @@ class MultipleIndexTest extends Doctrine_Record
     }
     public function setUp()
     {
-        \$this->option('index', 
-                      array('myindex' => array('name', 'code')
-                            'ageindex' => 'age')
-                            );
+        \$this->index('myindex', array('fields' => array('name', 'code')));
+        \$this->index('ageindex', array('fields' => array('age'));
     }
 }
 ?>");

manual/docs/Getting started - Indexes - Index options.php

 <?php ?>
 Doctrine offers many index options, some of them being db-specific. Here is a full list of availible options:
 <div class='sql'>
-<pre>
-unique      => boolean(true / false)        
-        whether or not the index is unique index
+<pre>        
 
 sorting     => string('ASC' / 'DESC')      
         what kind of sorting does the index use (ascending / descending)
 
+length      => integer
+        index length (only some drivers support this)
+
 primary     => boolean(true / false)        
         whether or not the index is primary index
 
-fulltext    => boolean(true / false)        
-        whether or not the specified index is a FULLTEXT index (only availible on Mysql)
-        
-gist        => boolean(true / false)        
-        whether or not the specified index is a GiST index (only availible on Pgsql)
+type        => string('unique',         -- supported by most drivers
+                      'fulltext',       -- only availible on Mysql driver
+                      'gist',           -- only availible on Pgsql driver
+                      'gin')            -- only availible on Pgsql driver
 </pre>
 </div>
+<?php
+renderCode("<?php
+class MultipleIndexTest extends Doctrine_Record
+{
+    public function setTableDefinition() 
+    {
+        \$this->hasColumn('name', 'string');
+        \$this->hasColumn('code', 'string');
+        \$this->hasColumn('age', 'integer');
+    }
+    public function setUp()
+    {
+        \$this->index('myindex', array(
+                      'fields' => array(
+                                  'name' =>
+                                  array('sorting' => 'ASC',
+                                        'length'  => 10),
+                                  'code'),
+                      'type' => 'unique',
+                      ));
+    }
+}
+?>");
+?>

manual/docs/Getting started - Indexes - Introduction.php

-Indexes are used to find rows with specific column values quickly. 
+Indexes are used to find rows with specific column values quickly.
 Without an index, the database must begin with the first row and then read through the entire table to find the relevant rows. 
 <br \><br \>
 The larger the table, the more this consumes time. If the table has an index for the columns in question, the database 
 can quickly determine the position to seek to in the middle of the data file without having to look at all the data. 
 If a table has 1,000 rows, this is at least 100 times faster than reading rows one-by-one.
 <br \><br \>
-You should *<b>always</b>* use indexes for the fields that are used in sql where conditions.
+Indexes come with a cost as they slow down the inserts and updates. However, in general you 
+should *<b>always</b>* use indexes for the fields that are used in sql where conditions.

manual/docs/Getting started - Indexes - Special indexes.php

@@ -13,10 +13,8 @@ class Article
     }
     public function setUp() 
     {
-        \$this->option('index', 
-                        array('content' =>
-                            array('content' => 
-                                array('fulltext' => true));
+        \$this->index('content', array('fields' => 'content',
+                                       'type' => 'fulltext'));
     }
 }
 ?>");

manual/documentation.php

@@ -109,6 +109,11 @@ $menu = array('Getting started' =>
                                         'Default values',
                                         'Enum emulation',
                                         ),
+                        'Working with existing databases' => array(
+                                        'Introduction',
+                                        'Making the first import',
+                                        'Import options',
+                                        ),
 
                         'Record identifiers' => array(
                                         'Introduction',
@@ -122,6 +127,8 @@ $menu = array('Getting started' =>
                                      'Index options',
                                      'Special indexes',
                                     ),
+
+
                         ),
            'Connection management' =>
                         array(
@@ -149,6 +156,9 @@ $menu = array('Getting started' =>
                                         'Enum',
                                         'Gzip',
                         ),
+            'Foreign keys' => array(
+                            'Introduction',
+                            ),
 /**
                         'Column attributes' => array(
                                         'Introduction',