構造

まずはじめに、"Structured Text" （構造化されたテキスト）という呼び方には、 いくぶん不適切なところがあると指摘しておきます。実際には、首尾一貫したパターンを使う "Relaxed Text" （形式ばらないテキスト）とでも呼ぶべきものです。そのパターンを HTML コンバータで変換することで、WEB ブラウザで扱えるような「非常に構造化された テキスト」が生成されるのです。

最も分かり易くて基本的なパターンは、 パラグラフ（段落） (quickref) です。 （1つ以上の）空行で区分されたテキストのひとかたまりが、パラグラフとなります。 パラグラフは等しいインデントでなければなりません。つまり、パラグラフの 各行は左側が揃っていなければならないということです。また、インデントされた パラグラフは、引用のパラグラフに変換されます。 たとえば、

これはパラグラフです。とても
短いですね。

   このパラグラフは、インデントされたテキストで、
   通常、他のテキストの引用として扱われます。

これもパラグラフです。

結果は、

これはパラグラフです。とても 短いですね。

このパラグラフは、インデントされたテキストで、 通常、他のテキストの引用として扱われます。

これもパラグラフです。

テキストの装飾

(quickref)

パラグラフやその他のテキストでは、 斜体 としたい部分を "*斜体*" という形式で、 太字 としたい部分を "**太字**" という形式で マークアップします。

固定スペースで表示させたい場合は、"``2重バッククォート``" を使います。 2重バッククォートの内部では、文字装飾は行われません。 ですから、アスタリスク "*" などはそのままになります。

「特殊」文字をテキスト中で使いたい場合も、reStructuredText はスマートにできており、 問題はありません。たとえば、アスタリスク * を上手く扱いたい場合を例に取ります。 *アスタリスクに挟まれた* テキストを斜体に したくない ときには、 "\*" (quickref) と言うようにバックスラッシュ（日本語環境では円記号）を 前に置くか、2重バッククォートで以下のように囲むかして、 そのアスタリスクが特殊ではないことを示します。

``\*``

リスト

リストには、 番号付き 、 箇条書き 、 定義 の3種類があります。 すべてのリストは、パラグラフの左側を、リストの要素の最初の行とあわせることで、 複数パラグラフやサブリストを扱うことができます。

リストは、新しいパラグラフの始まりとなります。すなわち、空行の後にリストを書く 必要があります。

番号付き リスト (数、文字もしくはローマ数字、 quickref)

行を、ピリオド "." か閉じ括弧 ")" を付けた、もしくは括弧で囲んだ "( )" 数字か文字で始めます。以下の形式のすべてが認識されます。

1. 数字

A. 大文字の英字
   複数行も書けます。

   複数のパラグラフも！

a. 小文字の英字

   3. 違う番号から始まるサブリスト
   4. 番号が適切な順番になっているか確認してください。

I. 大文字のローマ数字

i. 小文字のローマ数字

(1) 数字

1) 数字

変換結果はこの通り(注意。ブラウザによっては、これらすべての形式の 番号付きリストがサポートされていない場合もあります。ですので、 上のように指定した効果が完全には表示されていないかも知れません）。

1. 数字

1. 大文字の英字 複数行も書けます。

   複数のパラグラフも！

1. 小文字の英字
   3. 違う番号から始まるサブリスト
   4. 番号が適切な順番になっているか確認してください。

1. 大文字のローマ数字

1. 小文字のローマ数字

1. 数字

1. 数字

箇条書き リスト (quickref)

番号つきリストと似ていますが、行を "-" または "+", "*" の行頭記号で 始めます。

* 行頭記号 "*"

  - 行頭記号 "-"

    + サブリスト

  - 複数アイテム

変換結果はこの通り。

• 行頭記号 "*"
  • 行頭記号 "-"
    • サブリスト
  • 複数アイテム

定義 リスト (quickref)

上の２つとは違って、定義リストは用語とその定義からなります。定義リストの様式は、

何を
  定義リストは用語と定義を関連付けます。

*どのように*
  用語は1行に収まるフレーズです。定義は、１つもしくは複数のパラグラフや
  その他の要素からなり、用語よりも深くインデントします。
  用語と定義との間に空行を入れてはいけません。

変換結果はこうなります。

何を

定義リストは用語と定義を関連付けます。

どのように

用語は1行に収まるフレーズです。定義は、１つもしくは複数のパラグラフや その他の要素からなり、用語よりも深くインデントします。 用語と定義との間に空行を入れてはいけません。

フォーマット済みテキスト

(quickref)

（コードのサンプルなど）フォーマット済みで、文字装飾を行ないたくないテキストを 扱う場合は、その直前のパラグラフを "::" で終えてください。フォーマット済みの ブロックは、インデントがそのフォーマット済みブロックの直前のパラグラフと同じに なったところで終わります。例を示しましょう。:

サンプル::

    空白文字や空行やすべてのマークアップ（たとえば *これ* や \これ)は
    そのままとなります。
  インデントレベルを下げました。
  (少しだけですが)

サンプル終わり

変換結果を示します。

サンプル:

  空白文字や空行やすべてのマークアップ（たとえば *これ* や \これ)は
  そのままとなります。
インデントレベルを下げました。
(少しだけですが)

サンプル終わり

"::" だけのパラグラフは、出力からは削除されます。:

::

    フォーマット済みテキストです。
    直前の "::" だけのパラグラフは削除されます。

変換結果はこの通り。

フォーマット済みテキストです。
直前の "::" だけのパラグラフは削除されます。

セクション

(quickref)

長い文章をセクション（章など）に別けるには、 セクションヘッダ を使います。 セクションヘッダとは、1行のテキストを、アンダーラインで、またはアンダーラインと オーバーラインで装飾したものです。ラインには、ダッシュ "-----" や 等号 "======" 、チルダ "~~~~~~" などの非アルファベットの文字 = - ` : ' " ~ ^ _ * + # < > を使用します。同じ文字を使用していても、 アンダーラインのみのものと、アンダーラインとオーバーライン両方を使ったものは 区別されます。アンダーラインやオーバーラインは、少なくともタイトルと同じ長さに してください。同じスタイルで装飾されたすべてのセクションは、同じレベルだと みなされますので、首尾一貫性を保つようにしてください。

第1章 タイトル
==============

セクション 1.1 タイトル
-----------------------

サブセクション 1.1.1 タイトル
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

セクション 1.2 タイトル
-----------------------

第2章 タイトル
==============

変換結果は、擬似 XML で表すと以下のようになります。

<section>
    <title>
        第1章 タイトル
    <section>
        <title>
            セクション 1.1 タイトル
        <section>
            <title>
                サブセクション 1.1.1 タイトル
    <section>
        <title>
            セクション 1.2 タイトル
<section>
    <title>
        第2章 タイトル

（この擬似 XML は、ネストをインデントで表し、終了タグがありません。セクションは 引用のブロック中に置けないため、他の例と異なり、実際の変換結果を示すことが できませんでした。具体的な例としては、この文書自体のソーステキストと変換結果とを 比較してみてください。）

セクションヘッダは、その名前をリンクのターゲットとして使用できます。リスト_ ヘッダにリンクしたい場合は、"リスト_"と書きます。ヘッダが、 ReStructuredText 入門 の様にスペースを含む場合は、 "`ReStructuredText 入門`_" とクオートする必要があります。

==============
 文書タイトル
==============
--------------
 サブタイトル
--------------

セクションのタイトル
====================

...

画像

(quickref)

文書に画像を挿入するには、 image ディレクティブ を使います。 たとえば、

.. image:: images/biohazard.png

変換結果は、

images/biohazard.png の部分が、ドキュメントで表示させたい画像のファイル名 です。イメージについて（形式やサイズなどの）制限はありません。画像が HTML で 表示される場合、追加の情報を付け加えることもできます。

.. image:: images/biohazard.png
   :height: 100
   :width: 200
   :scale: 50
   :alt: alternate text

詳しい情報は、 画像ディレクティブの解説 を参照してください。

その他は?

この文書では、入門として、reStructuredText の最も一般的な機能について紹介 しました。しかし、reStructuredText には、もっと多くの機能があります。この文書の 次には、ユーザリファレンスである Quick reStructuredText を参照すると 良いでしょう。完全な詳細を知るには、 reStructuredText Markup Specification を参照してください。

Docutils および reStructuredText について質問があったり、援助が必要な場合は、 Docutils-Users mailing list に、 メールを出して みてください。 Docutils project web site にも、情報が掲載されています。