構造

初めに一言いわせてください。たぶん"Structured Text"は名前の付け方が少し間違っています。ある一貫したパターンを使う"Relaxed Text"がよりふさわしいでしょう。webブラウザで見られる"Very Structured Text"を出力するHTMLコンバータをつかって、これらのパターンを解釈します。

認識されるもっとも基本的なパターンは 段落 (quickref)です。それは空行(一行で充分です)によって区分されるテキストの集まりです。段落は同じ字下げでなければなりません -- すなわち、左端を揃えなければなりません。字下げを始めた段落は、結果として字下げされた引用段落となります。例えば:

これは段落です。とても
短いです。

   この段落は字下げされたテキストブロックに
   なるでしょう。通常は他のテキストを引用する
   ために使われます。

これは別の段落です。

は、このような結果になります:

これは段落です。とても 短いです。

この段落は字下げされたテキストブロックに なるでしょう。通常は他のテキストを引用する ために使われます。

これは別の段落です。

テキストスタイル (Text Styles)

(quickref)

段落と他のテキスト本体の内部で、さらにテキストに印を付けられます。 italics には "*italics*" を使い、 bold には "**bold**" を使います。

固定幅のリテラルに見えるものが欲しい場合は、 "``double back-quotes``" を使ってください。二重逆引用符の内部では、それ以上変更しません -- したがって、アスタリスク "*" などもそのまま残ります。

"特別な"文字の一つをテキストで使いたいと思った場合、一般的にはOKです -- reStructuredTextはかなり賢いのです。例えば、この * アスタリスクは実に巧妙に扱われます。実際にイタリック体にされ ない *アスタリスクに囲まれた* テキストが欲しいなら、そのときはアスタリスクが特殊でないことを指示しなければなりません。そうするには、"\*" (quickref)のようにバックスラッシュをその直前に置くか、もしくは下のように二重逆引用符で囲みます(インラインリテラル)。:

``\*``

リスト

項目のリストは主に三種類の形式があります: 番号 、 記号 および 定義 。すべてのリストで、あなたが望むだけ、段落の左側もしくはリスト項目におけるテキストの第一行目がどれも揃っている限り、たくさんの段落、サブリストなどを持つことができます。

リストでは常に新しい段落から始まらなければなりません -- すなわち、空行の次になければなりません。

番号 リスト(数、文字あるいはローマ数字; quickref)

ピリオド "." 、右括弧 ")" が後ろに続く、もしくは括弧 "( )" で囲まれた数や文字で(どれでもあなたのお好みで)ラインオフ???を始めてください。次のような形式がすべて認識されます:

1. 数

A. 大文字
   それは複数行にわたります

   二つの段落とその他すべても含めて!

a. 小文字

   3. 異なる数で始まるサブリストを含んでいます
   4. しかし、その数が正しい順番になっていることを確認してください!

I. 大文字のローマ数字

i. 小文字のローマ数字

(1) 再び、数

1) さらに、もう一度

結果はこのようになります(注意: 異なる番号リスト形式は、必ずしもすべてのウェブブラウザがサポートしているとは限りません。したがって、ここで完全な効果を得ることができないかもしれません):

1. 数

1. 大文字 それは複数行にわたります

   二つの段落とその他すべても含めて!

1. 小文字

   3. 異なる数で始まるサブリストを含んでいます
   4. しかし、その数が正しい順番になっていることを確認してください!

1. 大文字のローマ数字

1. 小文字のローマ数字

1. 再び、数

1. さらに、もう一度

記号 リスト (quickref)

番号リストと同じように、中点文字で行を始めてください - "-" 、 "+" もしくは "*" のいずれか:

* "*" 使った中点

  - "-"を使ったサブリスト

    + さらにもう一つのサブリスト

  - もう一つの項目

結果は:

• "*"を使った中点
  • "-"を使ったサブリスト
    • さらにもう一つのサブリスト
  • もう一つの項目

定義 リスト (quickref)

他の二つと違い、定義リストは項目とその項目の定義からなります。定義リストのフォーマットは:

what
  定義リストは定義と項目を関連づけます。

*how*
  項目は一行の句で、定義は項目より字下げした一つ以上の段落もしくは本文要素です。項目と定義の間に空行を入れることはできません。

結果は:

what

定義リストは定義と項目を関連づけます。

how

項目は一行の句で、定義は項目より字下げした一つ以上の段落もしくは本文要素です。項目と定義の間に空行を入れることはできません。

プリフォーマット (コードサンプル)

(quickref)

プリフォーマットされた、絶対に変更されないテキストのかたまりを含めるためには、直前の段落を"::"で終えてください。テキストがプリフォーマットされたブロックの前の段落と同じ字下げレベルに戻ったとき、プリフォーマットされたブロックが終わります。例えば:

例::

    空白、改行、空行、および(*これ* や \これ のような)全種類のマークアップが
      リテラルブロックによって保存されます。
  ここを見てください、字下げレベルを下げています
  (しかし、十分な大きさではありません)

これ以上のサンプルはありません

結果は:

例:

  空白、改行、空行、および(*これ* や \これ のような)全種類のマークアップが
    リテラルブロックによって保存されます。
ここを見てください、字下げレベルを下げています
(しかし、十分な大きさではありません)

これ以上のサンプルはありません

もし段落が"::"だけから構成される場合は、そのとき出力から取り除かれることに注意してください:

::

    これはプリフォーマットされたテキストです。そして、
    直前の "::" 段落は取り除かれます

結果は:

これはプリフォーマットされたテキストです。そして、
直前の "::" 段落は取り除かれます

セクション

(quickref)

もっと長いテキストを複数のセクションに分割するには、 セクションヘッダ を使います。これらは装飾付きの一行のテキスト(一つ以上の単語)です: 装飾には、ダッシュ"-----"、等号"======"、波形符号"~~~~~~"、もしくは好ましく感じる非英数字``= - ` : ' " ~ ^ _ * + # < >``のいずれかを用いたアンダーラインのみ、もしくはオーバーラインとオーバーライン(訳注: アンダーラインの間違いか?)を共に使います。アンダーラインのみの装飾は、同じ文字を使うオーバーラインとアンダーラインの装飾とは違います。アンダーライン/オーバーラインは少なくともタイトルテキストと同じ長さでなければならない。同じ装飾形式でマークされたすべてのセクションが同じレベルと判断されるため、一貫性を保ってください:

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

第1.1節 タイトル
----------------

第1.1.1節 タイトル
~~~~~~~~~~~~~~~~~~

第1.2節 タイトル
----------------

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

この結果は、簡略化したpseudo-XMLで示された次のような構造となります。:

<section>
    <title>
        第1章 タイトル
    <section>
        <title>
            第1.1節 タイトル
        <section>
            <title>
                第1.1.1節 タイトル
    <section>
        <title>
            第1.2節 タイトル
<section>
    <title>
        第2章 タイトル

(Pseudo-XMLはネスティングのために字下げを使っており、終了タグがありません。他の例のように、実際の処理結果を示すことはできません。セクションはブロッククオートの内部に存在できないからです。具体的な例としては、このドキュメントのソーステキストの構造と処理結果を比較してください。)

セクションヘッダは、その名前を使うリンクターゲットとして利用できることに注目してください。 リスト の見出しへリンクするには、 "リスト_" と書きます。 テキストスタイル (Text Styles) のように見出しの中に空白がある場合、見出し"`テキストスタイル (Text Styles)`_"をクオートする必要があります。

ドキュメントのタイトルを示すために、ドキュメントの先頭で独自の装飾形式を使ってください。ドキュメントのサブタイトルを示すために、ドキュメントのタイトルのすぐ後に別の独自の装飾形式を使ってください。例えば:

======================
 ドキュメントタイトル
======================
--------------
 サブタイトル
--------------

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

...

"ドキュメントタイトル"と"セクションタイトル"両方が等号記号を使っていても、ベ別個の無関係な形式であることに注意してください。美しさのために、(アンダーラインだけではなく)オーバーラインとアンダーラインのタイトルのテキストが挿入されてもよい。

画像

(quickref)

ドキュメントに画像を入れるために、``image`` 命令 を使います。例えば:

.. image:: images/biohazard.png

結果は:

images/biohazard.png 部分はドキュメントに表示したい画像のファイル名を示します。載せる画像(フォーマット、大きさなど)に制限はありません。画像がHTMLに表示され、追加情報を与えたい場合、次のようにできます:

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

さらに情報を得るには、完全なimage命令の ドキュメント を参照してください。

次は何ですか?

この入門書はreStructuredTextのもっとも一般的な特徴を紹介していますが、探求すべきものはもっとたくさんあります。 速習reStructuredText ユーザリファレンスは次に進むには良いところです。完全な詳細について知りたい場合は、 reStructuredTextマークアップ仕様書 が進むべきところです ¹ 。

疑問があるユーザやDocutilsやreStructuredTextについて助けが必要なユーザは Docutils-Usersメーリングリスト へ メッセージをポストしてください 。 Docutilsプロジェクトウェブサイト にはさらに情報があります。