Commit | Line | Data |
---|---|---|
920dae64 AT |
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> |