KtJ Dragon

グリッドテーブル

グリッドテーブルは、 - 、 = 、| 、 + の4種類の記号で罫線を記述するものである。 - は横罫線、 | は盾罫線、 +　は横罫線と縦罫線の交差部に用いる。 = はヘッダと表本体とを区切るための横罫線として使用する。例えば、

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

は、html5変換では以下のように置き換えられる。

HTMLソースは以下の通り。

<table>
  <colgroup>
    <col style="width: 43%" />
    <col style="width: 21%" />
    <col style="width: 18%" />
    <col style="width: 18%" />
  </colgroup>
  <thead>
    <tr>
      <th class="head"><p>Header row, column 1
        (header rows optional)</p></th>
      <th class="head"><p>Header 2</p></th>
      <th class="head"><p>Header 3</p></th>
      <th class="head"><p>Header 4</p></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><p>body row 1, column 1</p></td>
      <td><p>column 2</p></td>
      <td><p>column 3</p></td>
      <td><p>column 4</p></td>
    </tr>
    <tr>
      <td><p>body row 2</p></td>
      <td colspan="3"><p>Cells may span columns.</p></td>
    </tr>
    <tr>
      <td><p>body row 3</p></td>
      <td rowspan="2"><p>Cells may
        span rows.</p></td>
      <td colspan="2" rowspan="2">
        <ul class="simple">
          <li><p>Table cells</p></li>
          <li><p>contain</p></li>
          <li><p>body elements.</p></li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><p>body row 4</p></td>
    </tr>
  </tbody>
</table>

複数の列にまたがるセルを記述する際、そのセル内のテキストに | が含まれる場合は、その | の真上及び真下が縦罫線となると、セル内の | が縦罫線として解釈されてしまう。そのため、セル内の | の水平方向位置が縦罫線と重ならないようにスペースで調整するか、そのセルを複数行で記述してセル内の | の上下のどちらかが縦罫線とならないようにする。

シンプルテーブル

シンプルテーブルはグリッドテーブルよりも簡素な記述方法で、基本的に横罫線 = 、 - しか使用しない。殆どの場合は = のみ使用する。 - は、2行以上あるヘッダ部分の最下段以外の行において複数の列にまたがるセルを作成するときのみに使用する。列区切りは空白である。

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

という記述はhtml5変換では以下のように置き換えられる。

HTMLソースは以下の通り。

<table>
  <colgroup>
    <col style="width: 31%" />
    <col style="width: 31%" />
    <col style="width: 38%" />
  </colgroup>
  <thead>
    <tr>
      <th class="head" colspan="2"><p>Inputs</p></th>
      <th class="head"><p>Output</p></th>
    </tr>
    <tr>
      <th class="head"><p>A</p></th>
      <th class="head"><p>B</p></th>
      <th class="head"><p>A or B</p></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><p>False</p></td>
      <td><p>False</p></td>
      <td><p>False</p></td>
    </tr>
    <tr>
      <td><p>True</p></td>
      <td><p>False</p></td>
      <td><p>True</p></td>
    </tr>
    <tr>
      <td><p>False</p></td>
      <td><p>True</p></td>
      <td><p>True</p></td>
    </tr>
    <tr>
      <td><p>True</p></td>
      <td><p>True</p></td>
      <td><p>True</p></td>
    </tr>
  </tbody>
</table>

学術分野で使われるタイプの表を作成する際に有用な表記方法である。より複雑な表を作成したい時はグリッドテーブルや後述のリストテーブルを使うことになる。

ディレクティブでの記述

グリッドテーブル、シンプルテーブル共にディレクティブで記述可能である。ディレクティブで記述する場合、キャプションや各列の幅、表全体の幅、テーブルの表示位置を設定可能である。書式は以下の通りでオプションは省略可。他のディレクティブと同様、classとnameも指定可能。

.. table:: キャプション
   :align: 表の表示位置。left, center, rightのいずれかを指定
   :widths: 各セルの幅(文字数)。auto, grid, 又はカンマ区切りの数字を指定する
   :width: 表全体の幅。cssで使用されている単位か、親要素に対するパーセンテージを指定する

   三文字字下げして表を記述

CSVテーブル

このCSVテーブルとリストテーブルはディレクティブのみで記述される。書式は以下の通り。他のディレクティブと同様、classとnameも指定可能。

.. csv-table:: キャプション
   :widths: 各セルの幅(文字数)。auto又はカンマ区切りの数字を指定する
   :width: 表全体の幅。cssで使用されている単位か、親要素に対するパーセンテージを指定する
   :header-rows: 列見出しとして使用する行を数字で指定。デフォルトは0(見出し無し)
   :stub-columns: 行見出しと使用する列を数字で指定。デフォルトは0(見出し無し)
   :header: 列見出しをCSV行として記述。header-rowsで指定された行よりも前に表示される。
   :file: CSVデータのローカルファイルシステム上のパス
   :url: CSVデータのURL
   :encoding: file又はurlで指定されたCSVデータのテキストエンコーディング。デフォルトはreSTのエンコーディング
   :delim: 各セルの区切り文字。デフォルトはカンマ
   :quote: 引用符の指定。デフォルトはダブルクォーテーション
   :keepspace: このオプションが指定されると区切り文字の直後の空白を無視しない
   :escape: 区切り文字や引用符を文字として扱う場合のエスケープ文字を指定する。デフォルトではこれらの文字を2回繰り返す
   :align: 表の表示位置。left, center, rightのいずれかを指定

   三文字字下げしてCSVデータを記述

リストテーブル

リストテーブルは、以下のようにブレットリストのような形で表を定義する。列見出しを使いたい時はCSVテーブルかリストテーブルを使用する。

.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

これをhtml5に変換すると以下のようになる。

htmlソースは以下の通り。

<table class="colwidths-given">
  <caption>Frozen Delights!</caption>
  <colgroup>
    <col style="width: 27%" />
    <col style="width: 18%" />
    <col style="width: 55%" />
  </colgroup>
  <thead>
    <tr>
      <th class="head"><p>Treat</p></th>
      <th class="head"><p>Quantity</p></th>
      <th class="head"><p>Description</p></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><p>Albatross</p></td>
      <td><p>2.99</p></td>
      <td><p>On a stick!</p></td>
    </tr>
    <tr>
      <td><p>Crunchy Frog</p></td>
      <td><p>1.49</p></td>
      <td><p>If we took the bones out, it wouldn't be
        crunchy, now would it?</p></td>
    </tr>
    <tr>
      <td><p>Gannet Ripple</p></td>
      <td><p>1.99</p></td>
      <td><p>On a stick!</p></td>
    </tr>
  </tbody>
</table>

オプションとして、 widths 、 width 、 header-rows 、 stub-columns 、 align 、 class 、 name を指定可能。使い方はCSVテーブルと同じ。