overhaul tables docs for more streamlined content

2 files changed, 210 insertions, 388 deletions

diff --git a/docs/base-css.html b/docs/base-css.html
index 084654b27..71f8da87e 100644
--- a/docs/base-css.html
+++ b/docs/base-css.html
@@ -435,150 +435,8 @@ For example, <code>section</code> should be wrapped as inline.
     <h1>Tables <small>For, you guessed it, tabular data</small></h1>
   </div>
 
-
-
-  <h2>Table markup</h2>
-
-  <table class="table table-bordered table-striped">
-    <colgroup>
-      <col class="span1">
-      <col class="span7">
-    </colgroup>
-    <thead>
-      <tr>
-        <th>Tag</th>
-        <th>Description</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr>
-        <td>
-          <code>&lt;table&gt;</code>
-        </td>
-        <td>
-          Wrapping element for displaying data in a tabular format
-        </td>
-      </tr>
-      <tr>
-        <td>
-          <code>&lt;thead&gt;</code>
-        </td>
-        <td>
-          Container element for table header rows (<code>&lt;tr&gt;</code>) to label table columns
-        </td>
-      </tr>
-      <tr>
-        <td>
-          <code>&lt;tbody&gt;</code>
-        </td>
-        <td>
-          Container element for table rows (<code>&lt;tr&gt;</code>) in the body of the table
-        </td>
-      </tr>
-      <tr>
-        <td>
-          <code>&lt;tr&gt;</code>
-        </td>
-        <td>
-          Container element for a set of table cells (<code>&lt;td&gt;</code> or <code>&lt;th&gt;</code>) that appears on a single row
-        </td>
-      </tr>
-      <tr>
-        <td>
-          <code>&lt;td&gt;</code>
-        </td>
-        <td>
-          Default table cell
-        </td>
-      </tr>
-      <tr>
-        <td>
-          <code>&lt;th&gt;</code>
-        </td>
-        <td>
-          Special table cell for column (or row, depending on scope and placement) labels<br>
-          Must be used within a <code>&lt;thead&gt;</code>
-        </td>
-      </tr>
-      <tr>
-        <td>
-          <code>&lt;caption&gt;</code>
-        </td>
-        <td>
-          Description or summary of what the table holds, especially useful for screen readers
-        </td>
-      </tr>
-    </tbody>
-  </table>
-<pre class="prettyprint linenums">
-&lt;table&gt;
-  &lt;thead&gt;
-    &lt;tr&gt;
-      &lt;th&gt;…&lt;/th&gt;
-      &lt;th&gt;…&lt;/th&gt;
-    &lt;/tr&gt;
-  &lt;/thead&gt;
-  &lt;tbody&gt;
-    &lt;tr&gt;
-      &lt;td&gt;…&lt;/td&gt;
-      &lt;td&gt;…&lt;/td&gt;
-    &lt;/tr&gt;
-  &lt;/tbody&gt;
-&lt;/table&gt;
-</pre>
-
-
-  <h2>Table options</h2>
-  <table class="table table-bordered table-striped">
-    <thead>
-      <tr>
-        <th>Name</th>
-        <th>Class</th>
-        <th>Description</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr>
-        <td>Default</td>
-        <td class="muted">None</td>
-        <td>No styles, just columns and rows</td>
-      </tr>
-      <tr>
-        <td>Basic</td>
-        <td>
-          <code>.table</code>
-        </td>
-        <td>Only horizontal lines between rows</td>
-      </tr>
-      <tr>
-        <td>Bordered</td>
-        <td>
-          <code>.table-bordered</code>
-        </td>
-        <td>Rounds corners and adds outer border</td>
-      </tr>
-      <tr>
-        <td>Zebra-stripe</td>
-        <td>
-          <code>.table-striped</code>
-        </td>
-        <td>Adds light gray background color to odd rows (1, 3, 5, etc)</td>
-      </tr>
-      <tr>
-        <td>Condensed</td>
-        <td>
-          <code>.table-condensed</code>
-        </td>
-        <td>Cuts vertical padding in half, from 8px to 4px, within all <code>td</code> and <code>th</code> elements</td>
-      </tr>
-    </tbody>
-  </table>
-
-
-  <h2>Example tables</h2>
-
-  <h3>1. Default table styles</h3>
-  <p>Tables are automatically styled with only a few borders to ensure readability and maintain structure. With 2.0, the <code>.table</code> class is required.</p>
+  <h2>Default styles</h2>
+  <p>For basic styling&mdash;light padding and only horizontal dividers&mdash;add the base class <code>.table</code> to any <code>&lt;table&gt;</code>.</p>
   <div class="bs-docs-example">
     <table class="table">
       <thead>
@@ -617,9 +475,15 @@ For example, &lt;code&gt;section&lt;/code&gt; should be wrapped as inline.
 &lt;/table&gt;
 </pre>
 
-  <h3>2. Striped table</h3>
-  <p>Get a little fancy with your tables by adding zebra-striping&mdash;just add the <code>.table-striped</code> class.</p>
-  <p class="muted"><strong>Note:</strong> Striped tables use the <code>:nth-child</code> CSS selector and is not available in IE7-IE8.</p>
+
+  <hr class="bs-docs-separator">
+
+
+  <h2>Optional classes</h2>
+  <p>Add any of the follow classes to the <code>.table</code> base class.</p>
+
+  <h3><code>.table-striped</code></h3>
+  <p>Adds zebra-striping to any table row within the <code>&lt;tbody&gt;</code> via the <code>:nth-child</code> CSS selector (not available in IE7-IE8).</p>
   <div class="bs-docs-example">
     <table class="table table-striped">
       <thead>
@@ -658,9 +522,8 @@ For example, &lt;code&gt;section&lt;/code&gt; should be wrapped as inline.
 &lt;/table&gt;
 </pre>
 
-
-  <h3>3. Bordered table</h3>
-  <p>Add borders around the entire table and rounded corners for aesthetic purposes.</p>
+  <h3><code>.table-bordered</code></h3>
+  <p>Add borders and rounded corners to the table.</p>
   <div class="bs-docs-example">
     <table class="table table-bordered">
       <thead>
@@ -703,8 +566,8 @@ For example, &lt;code&gt;section&lt;/code&gt; should be wrapped as inline.
 &lt;/table&gt;
 </pre>
 
-  <h3>4. Condensed table</h3>
-  <p>Make your tables more compact by adding the <code>.table-condensed</code> class to cut table cell padding in half (from 8px to 4px).</p>
+  <h3><code>.table-condensed</code></h3>
+  <p>Makes tables more compact by cutting cell padding in half.</p>
   <div class="bs-docs-example">
     <table class="table table-condensed">
       <thead>
@@ -743,48 +606,96 @@ For example, &lt;code&gt;section&lt;/code&gt; should be wrapped as inline.
 </pre>
 
 
-  <h3>5. Combine them all!</h3>
-  <p>Feel free to combine any of the table classes to achieve different looks by utilizing any of the available classes.</p>
-  <div class="bs-docs-example">
-    <table class="table table-striped table-bordered table-condensed">
-      <thead>
-        <tr>
-          <th></th>
-          <th colspan="2">Full name</th>
-          <th></th>
-        </tr>
-        <tr>
-          <th>#</th>
-          <th>First Name</th>
-          <th>Last Name</th>
-          <th>Username</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr>
-        <tr>
-          <td>1</td>
-          <td>Mark</td>
-          <td>Otto</td>
-          <td>@mdo</td>
-        </tr>
-        <tr>
-          <td>2</td>
-          <td>Jacob</td>
-          <td>Thornton</td>
-          <td>@fat</td>
-        </tr>
-        <tr>
-          <td>3</td>
-          <td colspan="2">Larry the Bird</td>
-          <td>@twitter</td>
-        </tr>
-      </tbody>
-    </table>
-  </div>
-<pre class="prettyprint linenums" style="margin-bottom: 18px;">
-&lt;table class="table table-striped table-bordered table-condensed"&gt;
-  ...
+  <hr class="bs-docs-separator">
+
+
+  <h2>Supported table markup</h2>
+  <p>List of supported table HTML elements and how they should be used.</p>
+  <table class="table table-bordered table-striped">
+    <colgroup>
+      <col class="span1">
+      <col class="span7">
+    </colgroup>
+    <thead>
+      <tr>
+        <th>Tag</th>
+        <th>Description</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>
+          <code>&lt;table&gt;</code>
+        </td>
+        <td>
+          Wrapping element for displaying data in a tabular format
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <code>&lt;thead&gt;</code>
+        </td>
+        <td>
+          Container element for table header rows (<code>&lt;tr&gt;</code>) to label table columns
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <code>&lt;tbody&gt;</code>
+        </td>
+        <td>
+          Container element for table rows (<code>&lt;tr&gt;</code>) in the body of the table
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <code>&lt;tr&gt;</code>
+        </td>
+        <td>
+          Container element for a set of table cells (<code>&lt;td&gt;</code> or <code>&lt;th&gt;</code>) that appears on a single row
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <code>&lt;td&gt;</code>
+        </td>
+        <td>
+          Default table cell
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <code>&lt;th&gt;</code>
+        </td>
+        <td>
+          Special table cell for column (or row, depending on scope and placement) labels<br>
+          Must be used within a <code>&lt;thead&gt;</code>
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <code>&lt;caption&gt;</code>
+        </td>
+        <td>
+          Description or summary of what the table holds, especially useful for screen readers
+        </td>
+      </tr>
+    </tbody>
+  </table>
+<pre class="prettyprint linenums">
+&lt;table&gt;
+  &lt;thead&gt;
+    &lt;tr&gt;
+      &lt;th&gt;…&lt;/th&gt;
+      &lt;th&gt;…&lt;/th&gt;
+    &lt;/tr&gt;
+  &lt;/thead&gt;
+  &lt;tbody&gt;
+    &lt;tr&gt;
+      &lt;td&gt;…&lt;/td&gt;
+      &lt;td&gt;…&lt;/td&gt;
+    &lt;/tr&gt;
+  &lt;/tbody&gt;
 &lt;/table&gt;
 </pre>
 
diff --git a/docs/templates/pages/base-css.mustache b/docs/templates/pages/base-css.mustache
index ee95ac755..5910d66ba 100644
--- a/docs/templates/pages/base-css.mustache
+++ b/docs/templates/pages/base-css.mustache
@@ -366,150 +366,8 @@
     <h1>{{_i}}Tables <small>For, you guessed it, tabular data</small>{{/i}}</h1>
   </div>
 
-
-
-  <h2>{{_i}}Table markup{{/i}}</h2>
-
-  <table class="table table-bordered table-striped">
-    <colgroup>
-      <col class="span1">
-      <col class="span7">
-    </colgroup>
-    <thead>
-      <tr>
-        <th>{{_i}}Tag{{/i}}</th>
-        <th>{{_i}}Description{{/i}}</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr>
-        <td>
-          <code>&lt;table&gt;</code>
-        </td>
-        <td>
-          {{_i}}Wrapping element for displaying data in a tabular format{{/i}}
-        </td>
-      </tr>
-      <tr>
-        <td>
-          <code>&lt;thead&gt;</code>
-        </td>
-        <td>
-          {{_i}}Container element for table header rows (<code>&lt;tr&gt;</code>) to label table columns{{/i}}
-        </td>
-      </tr>
-      <tr>
-        <td>
-          <code>&lt;tbody&gt;</code>
-        </td>
-        <td>
-          {{_i}}Container element for table rows (<code>&lt;tr&gt;</code>) in the body of the table{{/i}}
-        </td>
-      </tr>
-      <tr>
-        <td>
-          <code>&lt;tr&gt;</code>
-        </td>
-        <td>
-          {{_i}}Container element for a set of table cells (<code>&lt;td&gt;</code> or <code>&lt;th&gt;</code>) that appears on a single row{{/i}}
-        </td>
-      </tr>
-      <tr>
-        <td>
-          <code>&lt;td&gt;</code>
-        </td>
-        <td>
-          {{_i}}Default table cell{{/i}}
-        </td>
-      </tr>
-      <tr>
-        <td>
-          <code>&lt;th&gt;</code>
-        </td>
-        <td>
-          {{_i}}Special table cell for column (or row, depending on scope and placement) labels{{/i}}<br>
-          {{_i}}Must be used within a <code>&lt;thead&gt;</code>{{/i}}
-        </td>
-      </tr>
-      <tr>
-        <td>
-          <code>&lt;caption&gt;</code>
-        </td>
-        <td>
-          {{_i}}Description or summary of what the table holds, especially useful for screen readers{{/i}}
-        </td>
-      </tr>
-    </tbody>
-  </table>
-<pre class="prettyprint linenums">
-&lt;table&gt;
-  &lt;thead&gt;
-    &lt;tr&gt;
-      &lt;th&gt;…&lt;/th&gt;
-      &lt;th&gt;…&lt;/th&gt;
-    &lt;/tr&gt;
-  &lt;/thead&gt;
-  &lt;tbody&gt;
-    &lt;tr&gt;
-      &lt;td&gt;…&lt;/td&gt;
-      &lt;td&gt;…&lt;/td&gt;
-    &lt;/tr&gt;
-  &lt;/tbody&gt;
-&lt;/table&gt;
-</pre>
-
-
-  <h2>{{_i}}Table options{{/i}}</h2>
-  <table class="table table-bordered table-striped">
-    <thead>
-      <tr>
-        <th>{{_i}}Name{{/i}}</th>
-        <th>{{_i}}Class{{/i}}</th>
-        <th>{{_i}}Description{{/i}}</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr>
-        <td>{{_i}}Default{{/i}}</td>
-        <td class="muted">{{_i}}None{{/i}}</td>
-        <td>{{_i}}No styles, just columns and rows{{/i}}</td>
-      </tr>
-      <tr>
-        <td>{{_i}}Basic{{/i}}</td>
-        <td>
-          <code>.table</code>
-        </td>
-        <td>{{_i}}Only horizontal lines between rows{{/i}}</td>
-      </tr>
-      <tr>
-        <td>{{_i}}Bordered{{/i}}</td>
-        <td>
-          <code>.table-bordered</code>
-        </td>
-        <td>{{_i}}Rounds corners and adds outer border{{/i}}</td>
-      </tr>
-      <tr>
-        <td>{{_i}}Zebra-stripe{{/i}}</td>
-        <td>
-          <code>.table-striped</code>
-        </td>
-        <td>{{_i}}Adds light gray background color to odd rows (1, 3, 5, etc){{/i}}</td>
-      </tr>
-      <tr>
-        <td>{{_i}}Condensed{{/i}}</td>
-        <td>
-          <code>.table-condensed</code>
-        </td>
-        <td>{{_i}}Cuts vertical padding in half, from 8px to 4px, within all <code>td</code> and <code>th</code> elements{{/i}}</td>
-      </tr>
-    </tbody>
-  </table>
-
-
-  <h2>{{_i}}Example tables{{/i}}</h2>
-
-  <h3>1. {{_i}}Default table styles{{/i}}</h3>
-  <p>{{_i}}Tables are automatically styled with only a few borders to ensure readability and maintain structure. With 2.0, the <code>.table</code> class is required.{{/i}}</p>
+  <h2>{{_i}}Default styles{{/i}}</h2>
+  <p>{{_i}}For basic styling&mdash;light padding and only horizontal dividers&mdash;add the base class <code>.table</code> to any <code>&lt;table&gt;</code>.{{/i}}</p>
   <div class="bs-docs-example">
     <table class="table">
       <thead>
@@ -548,9 +406,15 @@
 &lt;/table&gt;
 </pre>
 
-  <h3>2. {{_i}}Striped table{{/i}}</h3>
-  <p>{{_i}}Get a little fancy with your tables by adding zebra-striping&mdash;just add the <code>.table-striped</code> class.{{/i}}</p>
-  <p class="muted">{{_i}}<strong>Note:</strong> Striped tables use the <code>:nth-child</code> CSS selector and is not available in IE7-IE8.{{/i}}</p>
+
+  <hr class="bs-docs-separator">
+
+
+  <h2>{{_i}}Optional classes{{/i}}</h2>
+  <p>{{_i}}Add any of the follow classes to the <code>.table</code> base class.{{/i}}</p>
+
+  <h3><code>{{_i}}.table-striped{{/i}}</code></h3>
+  <p>{{_i}}Adds zebra-striping to any table row within the <code>&lt;tbody&gt;</code> via the <code>:nth-child</code> CSS selector (not available in IE7-IE8).{{/i}}</p>
   <div class="bs-docs-example">
     <table class="table table-striped">
       <thead>
@@ -589,9 +453,8 @@
 &lt;/table&gt;
 </pre>
 
-
-  <h3>3. {{_i}}Bordered table{{/i}}</h3>
-  <p>{{_i}}Add borders around the entire table and rounded corners for aesthetic purposes.{{/i}}</p>
+  <h3><code>{{_i}}.table-bordered{{/i}}</code></h3>
+  <p>{{_i}}Add borders and rounded corners to the table.{{/i}}</p>
   <div class="bs-docs-example">
     <table class="table table-bordered">
       <thead>
@@ -634,8 +497,8 @@
 &lt;/table&gt;
 </pre>
 
-  <h3>4. {{_i}}Condensed table{{/i}}</h3>
-  <p>{{_i}}Make your tables more compact by adding the <code>.table-condensed</code> class to cut table cell padding in half (from 8px to 4px).{{/i}}</p>
+  <h3><code>{{_i}}.table-condensed{{/i}}</code></h3>
+  <p>{{_i}}Makes tables more compact by cutting cell padding in half.{{/i}}</p>
   <div class="bs-docs-example">
     <table class="table table-condensed">
       <thead>
@@ -674,48 +537,96 @@
 </pre>
 
 
-  <h3>5. {{_i}}Combine them all!{{/i}}</h3>
-  <p>{{_i}}Feel free to combine any of the table classes to achieve different looks by utilizing any of the available classes.{{/i}}</p>
-  <div class="bs-docs-example">
-    <table class="table table-striped table-bordered table-condensed">
-      <thead>
-        <tr>
-          <th></th>
-          <th colspan="2">{{_i}}Full name{{/i}}</th>
-          <th></th>
-        </tr>
-        <tr>
-          <th>#</th>
-          <th>{{_i}}First Name{{/i}}</th>
-          <th>{{_i}}Last Name{{/i}}</th>
-          <th>{{_i}}Username{{/i}}</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr>
-        <tr>
-          <td>1</td>
-          <td>Mark</td>
-          <td>Otto</td>
-          <td>@mdo</td>
-        </tr>
-        <tr>
-          <td>2</td>
-          <td>Jacob</td>
-          <td>Thornton</td>
-          <td>@fat</td>
-        </tr>
-        <tr>
-          <td>3</td>
-          <td colspan="2">Larry the Bird</td>
-          <td>@twitter</td>
-        </tr>
-      </tbody>
-    </table>
-  </div>{{! /example }}
-<pre class="prettyprint linenums" style="margin-bottom: 18px;">
-&lt;table class="table table-striped table-bordered table-condensed"&gt;
-  ...
+  <hr class="bs-docs-separator">
+
+
+  <h2>{{_i}}Supported table markup{{/i}}</h2>
+  <p>{{_i}}List of supported table HTML elements and how they should be used.{{/i}}</p>
+  <table class="table table-bordered table-striped">
+    <colgroup>
+      <col class="span1">
+      <col class="span7">
+    </colgroup>
+    <thead>
+      <tr>
+        <th>{{_i}}Tag{{/i}}</th>
+        <th>{{_i}}Description{{/i}}</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>
+          <code>&lt;table&gt;</code>
+        </td>
+        <td>
+          {{_i}}Wrapping element for displaying data in a tabular format{{/i}}
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <code>&lt;thead&gt;</code>
+        </td>
+        <td>
+          {{_i}}Container element for table header rows (<code>&lt;tr&gt;</code>) to label table columns{{/i}}
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <code>&lt;tbody&gt;</code>
+        </td>
+        <td>
+          {{_i}}Container element for table rows (<code>&lt;tr&gt;</code>) in the body of the table{{/i}}
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <code>&lt;tr&gt;</code>
+        </td>
+        <td>
+          {{_i}}Container element for a set of table cells (<code>&lt;td&gt;</code> or <code>&lt;th&gt;</code>) that appears on a single row{{/i}}
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <code>&lt;td&gt;</code>
+        </td>
+        <td>
+          {{_i}}Default table cell{{/i}}
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <code>&lt;th&gt;</code>
+        </td>
+        <td>
+          {{_i}}Special table cell for column (or row, depending on scope and placement) labels{{/i}}<br>
+          {{_i}}Must be used within a <code>&lt;thead&gt;</code>{{/i}}
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <code>&lt;caption&gt;</code>
+        </td>
+        <td>
+          {{_i}}Description or summary of what the table holds, especially useful for screen readers{{/i}}
+        </td>
+      </tr>
+    </tbody>
+  </table>
+<pre class="prettyprint linenums">
+&lt;table&gt;
+  &lt;thead&gt;
+    &lt;tr&gt;
+      &lt;th&gt;…&lt;/th&gt;
+      &lt;th&gt;…&lt;/th&gt;
+    &lt;/tr&gt;
+  &lt;/thead&gt;
+  &lt;tbody&gt;
+    &lt;tr&gt;
+      &lt;td&gt;…&lt;/td&gt;
+      &lt;td&gt;…&lt;/td&gt;
+    &lt;/tr&gt;
+  &lt;/tbody&gt;
 &lt;/table&gt;
 </pre>