revised section on quoting, semanticized headings and table of content lists

5 files changed, 94 insertions, 70 deletions

diff --git a/doc/build/components/formatting.myt b/doc/build/components/formatting.myt
index 52928f539..53575bf13 100644
--- a/doc/build/components/formatting.myt
+++ b/doc/build/components/formatting.myt
@@ -6,6 +6,33 @@
 </%global>
 
 
+<%method printtoc>
+<%args> 
+    root
+    includefile
+    current = None
+    full = False
+    children = True
+</%args>
+
+% header = False
+<ul class="toc_list">
+% for i in root.children:
+
+%   if i.header:
+%       if header:
+    </ul>
+%
+%   header = True
+    <h3><% i.header %></h3>
+    <ul class="toc_list">
+%
+    <& printtocelement, item=i, includefile = includefile, bold = (i == current and includefile), full = full, children=children &>
+%
+
+</ul>
+</%method>
+
 <%def printtocelement>
 <%doc>prints a TOCElement as a table of contents item and prints its immediate child items</%doc>
     <%args>
@@ -16,16 +43,14 @@
         children = True
     </%args>
 
-    <div class="toclink">
-        <A style="<% bold and "font-weight:bold;" or "" %>" href="<% item.get_link(includefile, anchor = (not includefile)) %>"><% item.description %></a>
-    </div>
+        <li><A style="<% bold and "font-weight:bold;" or "" %>" href="<% item.get_link(includefile, anchor = (not includefile)) %>"><% item.description %></a></li>
     
 % if children:  
-    <div class="toclinkcontainer">
+    <ul class="small_toc_list">
 %   for i in item.children:
         <& printsmtocelem, item=i, includefile = includefile, children=full &>
 %
-    </div>
+    </ul>
 %
 </%def>
 
@@ -35,48 +60,18 @@
         includefile
         children = False
     </%args>    
-    <div class="toclinkcontainer">
-    
-    <div class="smalltoclink">
-    <A href="<% item.get_link(includefile) %>"><% item.description %></a>
-    </div>
+    <li><A href="<% item.get_link(includefile) %>"><% item.description %></a></li>
 
 % if children:
+    <ul class="small_toc_list">
 %   for i in item.children:
         <& printsmtocelem, item = i, includefile = includefile &>
 %
+    </ul>
 %
-    </div>
 
 </%def>
 
-<%method printtoc>
-<%args> 
-    root
-    includefile
-    current = None
-    full = False
-    children = True
-</%args>
-
-% header = False
-% for i in root.children:
-
-%   if i.header:
-%       if header:
-    </div>
-%
-%   header = True
-    <b><% i.header %></b><br/>
-    <div class="tocsection">
-%
-    <& printtocelement, item=i, includefile = includefile, bold = (i == current and includefile), full = full, children=children &>
-%
-
-%   if header:
-    </div>
-%
-</%method>
 
 
 <%method printitem>
@@ -99,7 +94,7 @@
 <div class="subsection" style="margin-left:<% repr(10 + indentlevel * 10) %>px;">
 
 % if not omitheader:
-    <span class="sectionheadertext"><% item.description %></span>
+    <h3><% item.description %></h3>
 %
     <div class="sectiontext">
 
diff --git a/doc/build/components/printsection.myt b/doc/build/components/printsection.myt
index 006b89055..cd5a26ff3 100644
--- a/doc/build/components/printsection.myt
+++ b/doc/build/components/printsection.myt
@@ -128,7 +128,7 @@ Next: <& formatting.myt:itemlink, item=item.next, includefile=ispaged &>
 	<& topnavcontrol, **ARGS &>
 
 	<a name="table_of_contents"></a>
-	<span class="docheadertext">Table of Contents</span>
+	<h2>Table of Contents</h2>
 	&nbsp;&nbsp;
 	<a href="#full_index">(view full table)</a>
 	<br/><br/>
@@ -142,7 +142,7 @@ Next: <& formatting.myt:itemlink, item=item.next, includefile=ispaged &>
 
 	<div class="maintoc">
 	<a name="full_index"></a>
-	<span class="docheadertext">Table of Contents: Full</span>
+	<h2>Table of Contents: Full</h2>
 	&nbsp;&nbsp;
 	<a href="#table_of_contents">(view brief table)</a>
 	<br/><br/>
diff --git a/doc/build/components/section_wrapper.myt b/doc/build/components/section_wrapper.myt
index 8ed91f5ec..b4e7c524e 100644
--- a/doc/build/components/section_wrapper.myt
+++ b/doc/build/components/section_wrapper.myt
@@ -29,7 +29,7 @@
 
 <div class="docheader">
 
-<div class="docheadertext" ><% title %></div>
+<h1><% title %></h1>
 % if version is not None:
 <div class="">Version: <% version %>   Last Updated: <% time.strftime('%x %X', time.localtime(last_updated)) %></div>
 %
diff --git a/doc/build/content/metadata.txt b/doc/build/content/metadata.txt
index 171b39594..a52cd4133 100644
--- a/doc/build/content/metadata.txt
+++ b/doc/build/content/metadata.txt
@@ -233,24 +233,39 @@ Within the `MetaData` collection, this table will be identified by the combinati
 
 #### Enabling Table / Column Quoting {@name=quoting}
 
-Many table, schema, or column names require quoting to be enabled.  Reasons for this include names that are the same as a database reserved word, or for identifiers that use MixedCase, where the database would normally "fold" the case convention into lower or uppercase (such as Postgres).  SQLAlchemy currently has no internal logic to automatically determine when quoting should be used; so its off unless explicitly enabled for a particular column or table.  Turning on quoting for a column or table identifier is performed manually by the `quote=True` flag on `Column` or `Table`, as well as the `quote_schema=True` flag for `Table`. 
+Feature Status: [Alpha Implementation][alpha_implementation] 
+
+Many table, schema, or column names require quoting to be enabled.  Reasons for this include names that are the same as a database reserved word, or for identifiers that use MixedCase, where the database would normally "fold" the case convention into lower or uppercase (such as Postgres).  SQLAlchemy as of version 0.2.8 will attempt to automatically determine when quoting should be used.  It will determine a value for every identifier name called `case_sensitive`, which defaults to `False` if the identifer name uses no uppercase letters, or `True` otherwise.  This flag may be explicitly set on any schema item as well (schema items include `Table`, `Column`, `MetaData`, `Sequence`, etc.) to override this default setting, where objects will inherit the setting from an enclosing object if not explicitly overridden.
+
+When `case_sensitive` is `True`, the dialect will do what it has to in order for the database to recognize the casing.  For Postgres and Oracle, this means using quoted identifiers.
+
+Identifiers that match known SQL reserved words (such as "asc", "union", etc.) will also be quoted according to the dialect's quoting convention regardless of the `case_sensitive` setting.
+
+To force quoting for an identifier, set the "quote=True" flag on `Column` or `Table`, as well as the `quote_schema=True` flag for `Table`. 
 
     {python}
     table2 = Table('WorstCase2', metadata,
-        # desc is a reserved word so quote this column
-        Column('desc', Integer, quote=True, primary_key=True),
+        # desc is a reserved word, which will be quoted.
+        Column('desc', Integer, primary_key=True),
 
-        # MixedCase uses a mixed case convention, so quote this column
-        Column('MixedCase', Integer, quote=True),
+        # if using a reserved word which SQLAlchemy doesn't know about,
+        # specify quote=True
+        Column('some_reserved_word', Integer, quote=True, primary_key=True),
+
+        # MixedCase uses a mixed case convention. 
+        # it will be automatically quoted since it is case sensitive
+        Column('MixedCase', Integer),
 
         # Union is both a reserved word and mixed case
-        Column('Union', Integer, quote=True),
+        Column('Union', Integer),
 
         # normal_column doesnt require quoting
-        Column('normal_column', String(30)),
-        
-        # the table name uses mixed case, so turn on quoting for the table ident
-        quote=True)
+        Column('normal_column', String(30)))
+
+    # to use tables where case_sensitive is False by default regardless
+    # of idenfifier casings, set "case_sensitive" to false at any level
+    # (or true to force case sensitive for lowercase identifiers as well)
+    lowercase_metadata = MetaData(case_sensitive=False)
 
 #### Other Options {@name=options}
 
diff --git a/doc/docs.css b/doc/docs.css
index c86b6ded2..753612557 100644
--- a/doc/docs.css
+++ b/doc/docs.css
@@ -120,9 +120,25 @@ pre {
 	margin: 0px 0px 0px 0px;
 }
 
-.docheadertext {
+h1, .docheadertext {
        font-size: 16px;
        font-weight: bold;
+       padding: 0px;
+       margin: 0px;
+}
+
+h2 {
+    font-size: 16px;
+    font-weight: bold;
+    display: inline;
+    padding: 0px;
+    margin: 0px;
+}
+
+h3, .sectionheadertext {
+	font-weight: bold;
+	font-size: 16px;
+	display: inline;
 }
 
 .docheader {
@@ -139,10 +155,6 @@ pre {
 	padding: 20px 0px 0px 0px;
 }
 
-.sectionheadertext {
-	font-weight: bold;
-	font-size: 16px;
-}
 
 .sectiontext {
 	font-size: 12px;
@@ -156,24 +168,26 @@ pre {
 	margin: 0px 0px 10px 0px;
 }
 
-.toclinkcontainer {
-	padding:0px 0px 0px 8px;
-	/*border:1px solid;*/
+.toc_list {
+    padding:0px;
+	margin: 0px;
+    }
+.toc_list li {
+	font-size: 12px;
+	list-style-type: none;
+    padding:0px 0px 3px 8px;
+	margin: 0px;
 }
-
-.tocsection {
-	padding:2px 2px 2px 8px;
+.small_toc_list {
+    padding: 0px 0px 0px 8px;
+}
+.small_toc_list li {
+	font-size: 11px;
+	list-style-type: none;
 }
-
 .toclink {
 	font-size: 12px;
 	padding:0px 0px 3px 8px;
-	/*border:1px solid;*/
-}
-
-.smalltoclink {
-	font-size: 11px;
-	padding:0px 0px 3px 0px;
 }
 
 .docstring {