Python ドキュメントの作成

Previous: 6.8 ライブラリレベルのマークアップ Up: 6 特殊マークアップ構文 Next: 6.10 参考文献リストのマークアップ

---

6.9 表のマークアップ

表環境には汎用の三つの形式があり、できる限りこの環境を使うように してください。こうした環境は標準の LaTeX 表環境を置き換える ためのものではなく、Python ドキュメントを作成するための処理ツール で処理する際に便利なように作られています。とりわけ、この表環境で 生成した HTML は見栄えがよくなります! また、いつかドキュメントを XML 形式に変換する時にも (9 節、 ``将来の方向性'' を 参照してください)、利点があるでしょう。

各環境は \tablecols という形式の名前がついています。 cols には、表のカラム数を小文字のローマ数字で指定します。 各々の環境について、追加のマクロ\linecols が定義されて います。この場合cols は表環境のcolsに対応します。 サポートされているcols にはii、iii、iv、 v があります。どの環境も全て\tabular 環境の上に構築されて います。\longtable 環境に基づく変化形も提供されています。

標準 Python ドキュメント内の全ての表がカラム間に垂直線を 使っており、各表のマークアップでこの垂直線を指定しなければならないので 注意してください。表の外側の境界線はマークアップに使いませんが、 これは処理ツール側の役割です; ドキュメントのマークアップ時には 外側の境界線を含めてはなりません。

\longtable に基づいた表環境の変化形では、前後に余分にスペースを 入れてフォーマットを行うため、表が長すぎて、複数のページに分割したほうが 合理的な場合にのみ使ってください; 20 行よりも行数の少ない表の場合、 決して長形式の表環境を使ってマークをしないようにしてください。 ヘッダ行は、表の各ページにおける部分の先頭に繰り返し表示されます。

\begin{tableii} {colspec}{col1font}{heading1}{heading2}
\end{tableii}

LaTeX のカラム情報指定子 (column specifier) colspec を使って、 2 カラムの表を作成します。カラム情報指定子には表によって適切なカラム 分割垂直線が入るように指定を行わねばなりませんが、表の外側の垂直線は 指定してはなりません (この部分の指定はスタイルシートの問題と考えられて いるからです)。con1font パラメタは、テーブルの最初のカラムの 表示スタイルをどうするかを指定します: その結果として、最初のカラムは \col1font{column1} のようになります。 最初のカラムを特別扱いしないために、col1font を"textrm" に してもかまいません。カラムのヘッダは heading1 および heading2 からとります。

\begin{longtableii} ...
\end{longtableii}

\tableii に似ていますが、ページ境界を割って配置できるような 表を生成します。パラメタは\tableii と同じです。

\lineii {column1}{column2}

\tableii や\longtableii 環境内の単一の行を生成します。 第一カラムのテキストは\tableii 環境を始めたときに指定した col1font を適用して生成します。

\begin{tableiii} {colspec}{col1font}{heading1}{heading2}{heading3}
\end{tableiii}

\tableii 環境に似ていますが、第三カラムがあります。 第三カラムのヘッダは heading3 に指定します。

\begin{longtableiii} ...
\end{longtableiii}

\tableiii に似ていますが、ページ境界を割って配置できるような 表を生成します。パラメタは\tableiii と同じです。

\lineiii {column1}{column2}{column3}

\lineii マクロに似ていますが、第三カラムがあります。 第三カラムのテキストは column3 に指定します。

\begin{tableiv} {colspec}{col1font}{heading1}{heading2}{heading3}{heading4}
\end{tableiv}

\tableiii 環境に似ていますが、第四カラムがあります。 第四カラムのヘッダは heading4 に指定します。

\begin{longtableiv} ...
\end{longtableiv}

\tableiv に似ていますが、ページ境界を割って配置できるような 表を生成します。パラメタは\tableiv と同じです。

\lineiv {column1}{column2}{column3}{column4}

\lineiv マクロに似ていますが、第四カラムがあります。 第四カラムのテキストは column4 に指定します。

\begin{tablev} {colspec}{col1font}{heading1}{heading2}{heading3}{heading4}{heading5}
\end{tablev}

\tableiii 環境に似ていますが、第五カラムがあります。 第五カラムのヘッダは heading5 に指定します。

\begin{longtablev} ...
\end{longtablev}

\tablev に似ていますが、ページ境界を割って配置できるような 表を生成します。パラメタは\tablev と同じです。

\linev {column1}{column2}{column3}{column4}{column5}

\lineiv マクロに似ていますが、第五カラムがあります。 第五カラムのテキストは column5 に指定します。

表に似たもう一つ環境として \synopsistable があります。 この環境が生成する表は二つのカラムからなり、各行は別のマクロ定義 \modulesynopsis 中に定義されています。通常ドキュメントの作者が この環境を使うことはありませんが、\localmoduletable マクロ を使うとこの表を作成します。

ここでwarning モジュールのドキュメントにある小さな表の例を 示します; 表のマークアップ自体がかなり識別しやすく作られているので、 表セル内のマークアップは最小限にしています。 以下が表のマークアップです。

\begin{tableii}{l|l}{exception}{クラス}{説明}
\lineii{Warning}{全ての警告カテゴリの基底クラスです。
\exception{Exception} のサブクラスです。}
\lineii{UserWarning}{\function{warn()} の標準のカテゴリです。}
\lineii{DeprecationWarning}{機能の撤廃を警告するカテゴリの基底クラスです。}
\lineii{SyntaxWarning}{文法機能のあいまいさを警告するカテゴリの基底クラスです。}
\lineii{RuntimeWarning}{実行時システム機能のあいまいさを警告するカテゴリの基底クラスです。}
\lineii{FutureWarning}{変更予定のセマンティクスを警告するカテゴリの基底クラスです。}
\end{tableii}

これは以下のような表になります。

クラス名は\exception マクロを使って非明示的にマークされますが、 これは\exception が\tableii 環境のcol1font の 値として指定されているからです。最初のカラムを別のマークアップにした 表を作成するには、textrm を col1font の値に指定して、 各エントリを個別にマークしてください。

表を垂直方向に分割するために水平線を追加するには、標準のマクロ \hline を分割したい行の間に入れます:

\begin{tableii}{l|l}{constant}{言語}{対象読者}
  \lineii{APL}{マゾヒスト}
  \lineii{BASIC}{PC ハードウェア使いのプログラム初心者}
  \lineii{C}{\UNIX{} \&\ Linux カーネル開発者}
    \hline
  \lineii{Python}{誰でも!}
\end{tableii}

全ての出力形式でこの場所に水平線を引けるとは限らないので注意してください。 今読者が読んでいるドキュメントの出力形式では、上の表は以下のように なります:

---

Python ドキュメントの作成

Previous: 6.8 ライブラリレベルのマークアップ Up: 6 特殊マークアップ構文 Next: 6.10 参考文献リストのマークアップ

---