6.9 Table Markup

##
6.9 Table Markup

There are three general-purpose table environments defined which should be used whenever possible. These environments are defined to provide tables of specific widths and some convenience for formatting. These environments are not meant to be general replacements for the standard LaTeX table environments, but can be used for an advantage when the documents are processed using the tools for Python documentation processing. In particular, the generated HTML looks good! There is also an advantage for the eventual conversion of the documentation to XML (see section 8, ``Future Directions'').

Each environment is named `\tablecols`, where cols is the number of columns in the table specified in lower-case Roman numerals. Within each of these environments, an additional macro, `\linecols`, is defined, where cols matches the cols value of the corresponding table environment. These are supported for cols values of `ii`, `iii`, and `iv`. These environments are all built on top of the `\tabular` environment. Variants based on the `\longtable` environment are also provided.

Note that all tables in the standard Python documentation use vertical lines between columns, and this must be specified in the markup for each table. A general border around the outside of the table is not used, but would be the responsibility of the processor; the document markup should not include an exterior border.

The `\longtable`-based variants of the table environments are formatted with extra space before and after, so should only be used on tables which are long enough that splitting over multiple pages is reasonable; tables with fewer than twenty rows should never by marked using the long flavors of the table environments. The header row is repeated across the top of each part of the table.

`\begin{tableii}` `{`colspec`}``{`col1font`}``{`heading1`}``{`heading2`}`
`\end{tableii}`
  Create a two-column table using the LaTeX column specifier colspec. The column specifier should indicate vertical bars between columns as appropriate for the specific table, but should not specify vertical bars on the outside of the table (that is considered a stylesheet issue). The col1font parameter is used as a stylistic treatment of the first column of the table: the first column is presented as `\col1font{column1}`. To avoid treating the first column specially, col1font may be "`textrm`". The column headings are taken from the values heading1 and heading2.

`\begin{longtableii}` ...
`\end{longtableii}`
  Like `\tableii`, but produces a table which may be broken across page boundaries. The parameters are the same as for `\tableii`.

`\lineii` `{`column1`}``{`column2`}`
  Create a single table row within a `\tableii` or `\longtableii` environment. The text for the first column will be generated by applying the macro named by the col1font value when the `\tableii` was opened.

`\begin{tableiii}` `{`colspec`}``{`col1font`}``{`heading1`}``{`heading2`}``{`heading3`}`
`\end{tableiii}`
  Like the `\tableii` environment, but with a third column. The heading for the third column is given by heading3.

`\begin{longtableiii}` ...
`\end{longtableiii}`
  Like `\tableiii`, but produces a table which may be broken across page boundaries. The parameters are the same as for `\tableiii`.

`\lineiii` `{`column1`}``{`column2`}``{`column3`}`
  Like the `\lineii` macro, but with a third column. The text for the third column is given by column3.

`\begin{tableiv}` `{`colspec`}``{`col1font`}``{`heading1`}``{`heading2`}``{`heading3`}``{`heading4`}`
`\end{tableiv}`
  Like the `\tableiii` environment, but with a fourth column. The heading for the fourth column is given by heading4.

`\begin{longtableiv}` ...
`\end{longtableiv}`
  Like `\tableiv`, but produces a table which may be broken across page boundaries. The parameters are the same as for `\tableiv`.

`\lineiv` `{`column1`}``{`column2`}``{`column3`}``{`column4`}`
  Like the `\lineiii` macro, but with a fourth column. The text for the fourth column is given by column4.

`\begin{tablev}` `{`colspec`}``{`col1font`}``{`heading1`}``{`heading2`}``{`heading3`}``{`heading4`}``{`heading5`}`
`\end{tablev}`
  Like the `\tableiv` environment, but with a fifth column. The heading for the fifth column is given by heading5.

`\begin{longtablev}` ...
`\end{longtablev}`
  Like `\tablev`, but produces a table which may be broken across page boundaries. The parameters are the same as for `\tablev`.

`\linev` `{`column1`}``{`column2`}``{`column3`}``{`column4`}``{`column5`}`
  Like the `\lineiv` macro, but with a fifth column. The text for the fifth column is given by column5.

An additional table-like environment is `\synopsistable`. The table generated by this environment contains two columns, and each row is defined by an alternate definition of `\modulesynopsis`. This environment is not normally used by authors, but is created by the `\localmoduletable` macro.

Here is a small example of a table given in the documentation for the `warnings` module; markup inside the table cells is minimal so the markup for the table itself is readily discernable. Here is the markup for the table:

    \begin{tableii}{l|l}{exception}{Class}{Description}
      \lineii{Warning}
             {This is the base class of all warning category classes.  It
              is a subclass of \exception{Exception}.}
      \lineii{UserWarning}
             {The default category for \function{warn()}.}
      \lineii{DeprecationWarning}
             {Base category for warnings about deprecated features.}
      \lineii{SyntaxWarning}
             {Base category for warnings about dubious syntactic
              features.}
      \lineii{RuntimeWarning}
             {Base category for warnings about dubious runtime features.}
      \lineii{FutureWarning}
             {Base category for warnings about constructs that will change
             semantically in the future.}
    \end{tableii}

Here is the resulting table:

Class | Description
--- | ---
`Warning` | This is the base class of all warning category classes. It is a subclass of `Exception`.
`UserWarning` | The default category for `warn()`.
`DeprecationWarning` | Base category for warnings about deprecated features.
`SyntaxWarning` | Base category for warnings about dubious syntactic features.
`RuntimeWarning` | Base category for warnings about dubious runtime features.

Note that the class names are implicitly marked using the `\exception` macro, since that is given as the col1font value for the `\tableii` environment. To create a table using different markup for the first column, use `textrm` for the col1font value and mark each entry individually.

To add a horizontal line between vertical sections of a table, use the standard `\hline` macro between the rows which should be separated:

    \begin{tableii}{l|l}{constant}{Language}{Audience}
      \lineii{APL}{Masochists.}
      \lineii{BASIC}{First-time programmers on PC hardware.}
      \lineii{C}{\UNIX{} \&\ Linux kernel developers.}
        \hline
      \lineii{Python}{Everyone!}
    \end{tableii}

Note that not all presentation formats are capable of displaying a horizontal rule in this position. This is how the table looks in the format you're reading now:

Language | Audience
--- | ---
`APL` | Masochists.
`C` | Unix & Linux kernel developers.
`JavaScript` | Web developers.
`Python` | Everyone!