| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="doc.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="doc.html" title='Documenting Python' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='last' href='about.html' title='About this document...' /> |
| 10 | <link rel='help' href='about.html' title='About this document...' /> |
| 11 | <link rel="next" href="references.html" /> |
| 12 | <link rel="prev" href="library-markup.html" /> |
| 13 | <link rel="parent" href="special-constructs.html" /> |
| 14 | <link rel="next" href="references.html" /> |
| 15 | <meta name='aesop' content='information' /> |
| 16 | <title>6.9 Table Markup </title> |
| 17 | </head> |
| 18 | <body> |
| 19 | <DIV CLASS="navigation"> |
| 20 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 21 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 22 | <tr> |
| 23 | <td class='online-navigation'><a rel="prev" title="6.8 Library-level Markup" |
| 24 | href="library-markup.html"><img src='../icons/previous.png' |
| 25 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 26 | <td class='online-navigation'><a rel="parent" title="6 Special Markup Constructs" |
| 27 | href="special-constructs.html"><img src='../icons/up.png' |
| 28 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 29 | <td class='online-navigation'><a rel="next" title="6.10 Reference List Markup" |
| 30 | href="references.html"><img src='../icons/next.png' |
| 31 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 32 | <td align="center" width="100%">Documenting Python</td> |
| 33 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 34 | href="contents.html"><img src='../icons/contents.png' |
| 35 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 36 | <td class='online-navigation'><img src='../icons/blank.png' |
| 37 | border='0' height='32' alt='' width='32' /></td> |
| 38 | <td class='online-navigation'><img src='../icons/blank.png' |
| 39 | border='0' height='32' alt='' width='32' /></td> |
| 40 | </tr></table> |
| 41 | <div class='online-navigation'> |
| 42 | <b class="navlabel">Previous:</b> |
| 43 | <a class="sectref" rel="prev" href="library-markup.html">6.8 Library-level Markup</A> |
| 44 | <b class="navlabel">Up:</b> |
| 45 | <a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A> |
| 46 | <b class="navlabel">Next:</b> |
| 47 | <a class="sectref" rel="next" href="references.html">6.10 Reference List Markup</A> |
| 48 | </div> |
| 49 | <hr /></div> |
| 50 | </DIV> |
| 51 | <!--End of Navigation Panel--> |
| 52 | |
| 53 | <H2><A NAME="SECTION000790000000000000000"></A><A NAME="table-markup"></A> |
| 54 | <BR> |
| 55 | 6.9 Table Markup |
| 56 | </H2> |
| 57 | |
| 58 | <P> |
| 59 | There are three general-purpose table environments defined which |
| 60 | should be used whenever possible. These environments are defined |
| 61 | to provide tables of specific widths and some convenience for |
| 62 | formatting. These environments are not meant to be general |
| 63 | replacements for the standard <span class="LaTeX">LaTeX</span> table environments, but can |
| 64 | be used for an advantage when the documents are processed using |
| 65 | the tools for Python documentation processing. In particular, the |
| 66 | generated HTML looks good! There is also an advantage for the |
| 67 | eventual conversion of the documentation to XML (see section |
| 68 | <A href="futures.html#futures">9</A>, ``Future Directions''). |
| 69 | |
| 70 | <P> |
| 71 | Each environment is named <tt class='environment'>\table<var>cols</var></tt>, where <var>cols</var> |
| 72 | is the number of columns in the table specified in lower-case |
| 73 | Roman numerals. Within each of these environments, an additional |
| 74 | macro, <tt class='macro'>\line<var>cols</var></tt>, is defined, where <var>cols</var> |
| 75 | matches the <var>cols</var> value of the corresponding table |
| 76 | environment. These are supported for <var>cols</var> values of |
| 77 | <code>ii</code>, <code>iii</code>, and <code>iv</code>. These environments are all |
| 78 | built on top of the <tt class='environment'>\tabular</tt> environment. Variants based on |
| 79 | the <tt class='environment'>\longtable</tt> environment are also provided. |
| 80 | |
| 81 | <P> |
| 82 | Note that all tables in the standard Python documentation use |
| 83 | vertical lines between columns, and this must be specified in the |
| 84 | markup for each table. A general border around the outside of the |
| 85 | table is not used, but would be the responsibility of the |
| 86 | processor; the document markup should not include an exterior |
| 87 | border. |
| 88 | |
| 89 | <P> |
| 90 | The <tt class='environment'>\longtable</tt>-based variants of the table environments are |
| 91 | formatted with extra space before and after, so should only be |
| 92 | used on tables which are long enough that splitting over multiple |
| 93 | pages is reasonable; tables with fewer than twenty rows should |
| 94 | never by marked using the long flavors of the table environments. |
| 95 | The header row is repeated across the top of each part of the |
| 96 | table. |
| 97 | |
| 98 | <P> |
| 99 | |
| 100 | <dl class='envdesc'> |
| 101 | <dt><tt>\begin{<b class='environment'>tableii</b>}</tt> |
| 102 | <tt>{</tt><var>colspec</var><tt>}</tt><tt>{</tt><var>col1font</var><tt>}</tt><tt>{</tt><var>heading1</var><tt>}</tt><tt>{</tt><var>heading2</var><tt>}</tt> |
| 103 | <br /><tt>\end{<b class='environment'>tableii</b>}</tt></dt> |
| 104 | <dd> |
| 105 | Create a two-column table using the <span class="LaTeX">LaTeX</span> column specifier |
| 106 | <var>colspec</var>. The column specifier should indicate vertical |
| 107 | bars between columns as appropriate for the specific table, but |
| 108 | should not specify vertical bars on the outside of the table |
| 109 | (that is considered a stylesheet issue). The <var>col1font</var> |
| 110 | parameter is used as a stylistic treatment of the first column |
| 111 | of the table: the first column is presented as |
| 112 | <code>\<var>col1font</var>{column1}</code>. To avoid treating the first |
| 113 | column specially, <var>col1font</var> may be "<tt class="samp">textrm</tt>". The |
| 114 | column headings are taken from the values <var>heading1</var> and |
| 115 | <var>heading2</var>. |
| 116 | </dd></dl> |
| 117 | |
| 118 | <P> |
| 119 | |
| 120 | <dl class='envdesc'> |
| 121 | <dt><tt>\begin{<b class='environment'>longtableii</b>}</tt> |
| 122 | ... |
| 123 | <br /><tt>\end{<b class='environment'>longtableii</b>}</tt></dt> |
| 124 | <dd> |
| 125 | Like <tt class='environment'>\tableii</tt>, but produces a table which may be broken |
| 126 | across page boundaries. The parameters are the same as for |
| 127 | <tt class='environment'>\tableii</tt>. |
| 128 | </dd></dl> |
| 129 | |
| 130 | <P> |
| 131 | |
| 132 | <dl class='macrodesc'> |
| 133 | <dt><b><tt class='macro'>\lineii</tt></b> |
| 134 | <tt>{</tt><var>column1</var><tt>}</tt><tt>{</tt><var>column2</var><tt>}</tt></dt> |
| 135 | <dd> |
| 136 | Create a single table row within a <tt class='environment'>\tableii</tt> or |
| 137 | <tt class='environment'>\longtableii</tt> environment. |
| 138 | The text for the first column will be generated by applying the |
| 139 | macro named by the <var>col1font</var> value when the <tt class='environment'>\tableii</tt> |
| 140 | was opened. |
| 141 | </dd></dl> |
| 142 | |
| 143 | <P> |
| 144 | |
| 145 | <dl class='envdesc'> |
| 146 | <dt><tt>\begin{<b class='environment'>tableiii</b>}</tt> |
| 147 | <tt>{</tt><var>colspec</var><tt>}</tt><tt>{</tt><var>col1font</var><tt>}</tt><tt>{</tt><var>heading1</var><tt>}</tt><tt>{</tt><var>heading2</var><tt>}</tt><tt>{</tt><var>heading3</var><tt>}</tt> |
| 148 | <br /><tt>\end{<b class='environment'>tableiii</b>}</tt></dt> |
| 149 | <dd> |
| 150 | Like the <tt class='environment'>\tableii</tt> environment, but with a third column. |
| 151 | The heading for the third column is given by <var>heading3</var>. |
| 152 | </dd></dl> |
| 153 | |
| 154 | <P> |
| 155 | |
| 156 | <dl class='envdesc'> |
| 157 | <dt><tt>\begin{<b class='environment'>longtableiii</b>}</tt> |
| 158 | ... |
| 159 | <br /><tt>\end{<b class='environment'>longtableiii</b>}</tt></dt> |
| 160 | <dd> |
| 161 | Like <tt class='environment'>\tableiii</tt>, but produces a table which may be broken |
| 162 | across page boundaries. The parameters are the same as for |
| 163 | <tt class='environment'>\tableiii</tt>. |
| 164 | </dd></dl> |
| 165 | |
| 166 | <P> |
| 167 | |
| 168 | <dl class='macrodesc'> |
| 169 | <dt><b><tt class='macro'>\lineiii</tt></b> |
| 170 | <tt>{</tt><var>column1</var><tt>}</tt><tt>{</tt><var>column2</var><tt>}</tt><tt>{</tt><var>column3</var><tt>}</tt></dt> |
| 171 | <dd> |
| 172 | Like the <tt class='macro'>\lineii</tt> macro, but with a third column. The |
| 173 | text for the third column is given by <var>column3</var>. |
| 174 | </dd></dl> |
| 175 | |
| 176 | <P> |
| 177 | |
| 178 | <dl class='envdesc'> |
| 179 | <dt><tt>\begin{<b class='environment'>tableiv</b>}</tt> |
| 180 | <tt>{</tt><var>colspec</var><tt>}</tt><tt>{</tt><var>col1font</var><tt>}</tt><tt>{</tt><var>heading1</var><tt>}</tt><tt>{</tt><var>heading2</var><tt>}</tt><tt>{</tt><var>heading3</var><tt>}</tt><tt>{</tt><var>heading4</var><tt>}</tt> |
| 181 | <br /><tt>\end{<b class='environment'>tableiv</b>}</tt></dt> |
| 182 | <dd> |
| 183 | Like the <tt class='environment'>\tableiii</tt> environment, but with a fourth column. |
| 184 | The heading for the fourth column is given by <var>heading4</var>. |
| 185 | </dd></dl> |
| 186 | |
| 187 | <P> |
| 188 | |
| 189 | <dl class='envdesc'> |
| 190 | <dt><tt>\begin{<b class='environment'>longtableiv</b>}</tt> |
| 191 | ... |
| 192 | <br /><tt>\end{<b class='environment'>longtableiv</b>}</tt></dt> |
| 193 | <dd> |
| 194 | Like <tt class='environment'>\tableiv</tt>, but produces a table which may be broken |
| 195 | across page boundaries. The parameters are the same as for |
| 196 | <tt class='environment'>\tableiv</tt>. |
| 197 | </dd></dl> |
| 198 | |
| 199 | <P> |
| 200 | |
| 201 | <dl class='macrodesc'> |
| 202 | <dt><b><tt class='macro'>\lineiv</tt></b> |
| 203 | <tt>{</tt><var>column1</var><tt>}</tt><tt>{</tt><var>column2</var><tt>}</tt><tt>{</tt><var>column3</var><tt>}</tt><tt>{</tt><var>column4</var><tt>}</tt></dt> |
| 204 | <dd> |
| 205 | Like the <tt class='macro'>\lineiii</tt> macro, but with a fourth column. The |
| 206 | text for the fourth column is given by <var>column4</var>. |
| 207 | </dd></dl> |
| 208 | |
| 209 | <P> |
| 210 | |
| 211 | <dl class='envdesc'> |
| 212 | <dt><tt>\begin{<b class='environment'>tablev</b>}</tt> |
| 213 | <tt>{</tt><var>colspec</var><tt>}</tt><tt>{</tt><var>col1font</var><tt>}</tt><tt>{</tt><var>heading1</var><tt>}</tt><tt>{</tt><var>heading2</var><tt>}</tt><tt>{</tt><var>heading3</var><tt>}</tt><tt>{</tt><var>heading4</var><tt>}</tt><tt>{</tt><var>heading5</var><tt>}</tt> |
| 214 | <br /><tt>\end{<b class='environment'>tablev</b>}</tt></dt> |
| 215 | <dd> |
| 216 | Like the <tt class='environment'>\tableiv</tt> environment, but with a fifth column. |
| 217 | The heading for the fifth column is given by <var>heading5</var>. |
| 218 | </dd></dl> |
| 219 | |
| 220 | <P> |
| 221 | |
| 222 | <dl class='envdesc'> |
| 223 | <dt><tt>\begin{<b class='environment'>longtablev</b>}</tt> |
| 224 | ... |
| 225 | <br /><tt>\end{<b class='environment'>longtablev</b>}</tt></dt> |
| 226 | <dd> |
| 227 | Like <tt class='environment'>\tablev</tt>, but produces a table which may be broken |
| 228 | across page boundaries. The parameters are the same as for |
| 229 | <tt class='environment'>\tablev</tt>. |
| 230 | </dd></dl> |
| 231 | |
| 232 | <P> |
| 233 | |
| 234 | <dl class='macrodesc'> |
| 235 | <dt><b><tt class='macro'>\linev</tt></b> |
| 236 | <tt>{</tt><var>column1</var><tt>}</tt><tt>{</tt><var>column2</var><tt>}</tt><tt>{</tt><var>column3</var><tt>}</tt><tt>{</tt><var>column4</var><tt>}</tt><tt>{</tt><var>column5</var><tt>}</tt></dt> |
| 237 | <dd> |
| 238 | Like the <tt class='macro'>\lineiv</tt> macro, but with a fifth column. The |
| 239 | text for the fifth column is given by <var>column5</var>. |
| 240 | </dd></dl> |
| 241 | |
| 242 | <P> |
| 243 | An additional table-like environment is <tt class='environment'>\synopsistable</tt>. The |
| 244 | table generated by this environment contains two columns, and each |
| 245 | row is defined by an alternate definition of |
| 246 | <tt class='macro'>\modulesynopsis</tt>. This environment is not normally used by |
| 247 | authors, but is created by the <tt class='macro'>\localmoduletable</tt> macro. |
| 248 | |
| 249 | <P> |
| 250 | Here is a small example of a table given in the documentation for |
| 251 | the <tt class="module">warnings</tt> module; markup inside the table cells is |
| 252 | minimal so the markup for the table itself is readily discernable. |
| 253 | Here is the markup for the table: |
| 254 | |
| 255 | <P> |
| 256 | <div class="verbatim"><pre> |
| 257 | \begin{tableii}{l|l}{exception}{Class}{Description} |
| 258 | \lineii{Warning} |
| 259 | {This is the base class of all warning category classes. It |
| 260 | is a subclass of \exception{Exception}.} |
| 261 | \lineii{UserWarning} |
| 262 | {The default category for \function{warn()}.} |
| 263 | \lineii{DeprecationWarning} |
| 264 | {Base category for warnings about deprecated features.} |
| 265 | \lineii{SyntaxWarning} |
| 266 | {Base category for warnings about dubious syntactic |
| 267 | features.} |
| 268 | \lineii{RuntimeWarning} |
| 269 | {Base category for warnings about dubious runtime features.} |
| 270 | \lineii{FutureWarning} |
| 271 | {Base category for warnings about constructs that will change |
| 272 | semantically in the future.} |
| 273 | \end{tableii} |
| 274 | </pre></div> |
| 275 | |
| 276 | <P> |
| 277 | Here is the resulting table: |
| 278 | |
| 279 | <P> |
| 280 | <div class="center"><table class="realtable"> |
| 281 | <thead> |
| 282 | <tr> |
| 283 | <th class="left" >Class</th> |
| 284 | <th class="left" >Description</th> |
| 285 | </tr> |
| 286 | </thead> |
| 287 | <tbody> |
| 288 | <tr><td class="left" valign="baseline"><tt class="constant">Warning</tt></td> |
| 289 | <td class="left" >This is the base class of all warning category classes. It |
| 290 | is a subclass of <tt class="exception">Exception</tt>.</td></tr> |
| 291 | <tr><td class="left" valign="baseline"><tt class="constant">UserWarning</tt></td> |
| 292 | <td class="left" >The default category for <tt class="function">warn()</tt>.</td></tr> |
| 293 | <tr><td class="left" valign="baseline"><tt class="constant">DeprecationWarning</tt></td> |
| 294 | <td class="left" >Base category for warnings about deprecated features.</td></tr> |
| 295 | <tr><td class="left" valign="baseline"><tt class="constant">SyntaxWarning</tt></td> |
| 296 | <td class="left" >Base category for warnings about dubious syntactic |
| 297 | features.</td></tr> |
| 298 | <tr><td class="left" valign="baseline"><tt class="constant">RuntimeWarning</tt></td> |
| 299 | <td class="left" >Base category for warnings about dubious runtime features.</td></tr></tbody> |
| 300 | </table></div> |
| 301 | |
| 302 | <P> |
| 303 | Note that the class names are implicitly marked using the |
| 304 | <tt class='macro'>\exception</tt> macro, since that is given as the <var>col1font</var> |
| 305 | value for the <tt class='environment'>\tableii</tt> environment. To create a table using |
| 306 | different markup for the first column, use <code>textrm</code> for the |
| 307 | <var>col1font</var> value and mark each entry individually. |
| 308 | |
| 309 | <P> |
| 310 | To add a horizontal line between vertical sections of a table, use |
| 311 | the standard <tt class='macro'>\hline</tt> macro between the rows which should be |
| 312 | separated: |
| 313 | |
| 314 | <P> |
| 315 | <div class="verbatim"><pre> |
| 316 | \begin{tableii}{l|l}{constant}{Language}{Audience} |
| 317 | \lineii{APL}{Masochists.} |
| 318 | \lineii{BASIC}{First-time programmers on PC hardware.} |
| 319 | \lineii{C}{\UNIX{} \&\ Linux kernel developers.} |
| 320 | \hline |
| 321 | \lineii{Python}{Everyone!} |
| 322 | \end{tableii} |
| 323 | </pre></div> |
| 324 | |
| 325 | <P> |
| 326 | Note that not all presentation formats are capable of displaying a |
| 327 | horizontal rule in this position. This is how the table looks in |
| 328 | the format you're reading now: |
| 329 | |
| 330 | <P> |
| 331 | <div class="center"><table class="realtable"> |
| 332 | <thead> |
| 333 | <tr> |
| 334 | <th class="left" >Language</th> |
| 335 | <th class="left" >Audience</th> |
| 336 | </tr> |
| 337 | </thead> |
| 338 | <tbody> |
| 339 | <tr><td class="left" valign="baseline"><tt class="constant">APL</tt></td> |
| 340 | <td class="left" >Masochists.</td></tr> |
| 341 | <tr><td class="left" valign="baseline"><tt class="constant">C</tt></td> |
| 342 | <td class="left" ><span class="Unix">Unix</span> & Linux kernel developers.</td></tr> |
| 343 | <tr><td class="left" valign="baseline"><tt class="constant">JavaScript</tt></td> |
| 344 | <td class="left" >Web developers.</td></tr> |
| 345 | |
| 346 | <tr><td class="left" valign="baseline"><tt class="constant">Python</tt></td> |
| 347 | <td class="left" >Everyone!</td></tr></tbody> |
| 348 | </table></div> |
| 349 | |
| 350 | <P> |
| 351 | |
| 352 | <DIV CLASS="navigation"> |
| 353 | <div class='online-navigation'> |
| 354 | <p></p><hr /> |
| 355 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 356 | <tr> |
| 357 | <td class='online-navigation'><a rel="prev" title="6.8 Library-level Markup" |
| 358 | href="library-markup.html"><img src='../icons/previous.png' |
| 359 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 360 | <td class='online-navigation'><a rel="parent" title="6 Special Markup Constructs" |
| 361 | href="special-constructs.html"><img src='../icons/up.png' |
| 362 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 363 | <td class='online-navigation'><a rel="next" title="6.10 Reference List Markup" |
| 364 | href="references.html"><img src='../icons/next.png' |
| 365 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 366 | <td align="center" width="100%">Documenting Python</td> |
| 367 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 368 | href="contents.html"><img src='../icons/contents.png' |
| 369 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 370 | <td class='online-navigation'><img src='../icons/blank.png' |
| 371 | border='0' height='32' alt='' width='32' /></td> |
| 372 | <td class='online-navigation'><img src='../icons/blank.png' |
| 373 | border='0' height='32' alt='' width='32' /></td> |
| 374 | </tr></table> |
| 375 | <div class='online-navigation'> |
| 376 | <b class="navlabel">Previous:</b> |
| 377 | <a class="sectref" rel="prev" href="library-markup.html">6.8 Library-level Markup</A> |
| 378 | <b class="navlabel">Up:</b> |
| 379 | <a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A> |
| 380 | <b class="navlabel">Next:</b> |
| 381 | <a class="sectref" rel="next" href="references.html">6.10 Reference List Markup</A> |
| 382 | </div> |
| 383 | </div> |
| 384 | <hr /> |
| 385 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 386 | </DIV> |
| 387 | <!--End of Navigation Panel--> |
| 388 | <ADDRESS> |
| 389 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 390 | </ADDRESS> |
| 391 | </BODY> |
| 392 | </HTML> |