misc. > reStructuredText Markup Specification日本語訳

reStructuredText Markup Specification日本語訳

Date
2008-02-24
Revision
5511
Translator

Jiro Kita (info@ktjdragon.com)

Original Document

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

Note

この文書は、詳細な技術的特徴を示したものであり、チュートリアルや入門書では無い。これがあなたにとっての最初のreStructureTextの文書であるならば、A ReStructuredText PrimerQuick reStructuredText user referenceをまず読んでほしい。

Tip

訳注: どちらの文書も瀬戸山春輝氏によって、それぞれReStructuredText 入門はやわかり reStructuredTextとして和訳されている。

reStructuredTextは文書の構造を記述するための、シンプルかつ直感的な構成のプレーンテキストである。これらの構成は、加工前、加工後のいずれの形態でも等しく容易に読むことができる。この文書はそれ自身がreStructuredTextの一例である(あなたがテキストファイルを直接読んでいるならばそれはパーサによって処理されてないものである。また、例えばHTML文書を読んでいるならばそれは処理された後のものである)。reStructuredTextのパーサは、Docutilsの構成要素である。

特別な構成、例えばセクション見出し、ブレットリスト、強調表現を示すためにシンプルかつ暗黙のマークアップが使用される。使用されるマークアップは、最小かつ可能な限り控えめなものとなっている。使用頻度の低い構成や、基本的なreStructionText文法の拡張においては、複雑であったり明示的であるようなマークアップが使用されうる。

reStructuredTextは、とても小さいもの(例えばPythonのdocstringsのような、インラインプログラムにおける文書の断片)からとても大きなもの(この文書)に至るまで、文書の大きさにかかわらず使用可能である。

最初のセクションは、一例としてreStructuredTextマークアップの文法の基本的な構成を示すものである。全ての特徴は詳細な文法セクションに含まれる。

この文書中においては、(マークアップがあっても処理されない)リテラルブロックは、プレーンテキストのマークアップを例示するために使用されている。



基本的な構成

reStructuredTextドキュメントは、ボディすなわちブロックレベル要素にて形成され、また、セクションにて構造化可能である。セクションは、表題スタイル(アンダーライン。オーバーラインを追加することも可能)を用いて示される。セクションは、ボディ要素および/又はサブセクションを含む。一部のボディ要素は、(リストがリスト項目を有するように)さらなる要素を含み、そしてこれも、段落や他のボディ要素を含むことができる。他のもの、例えば段落は、テキストとインラインマークアップ要素のみを含む。

以下にボディ要素の例を示す。

  • 段落(及びインラインマークアップ):

    段落はテキストを含み、以下のインラインマークアップを含んでもよい。
    すなわち、 *強調* 、 **強い強調** 、 `インタープリテッドテキスト` 、 ``インライン
    リテラル`` 、スタンドアロンのハイパーリンク(http://www.python.org)、
    外部ハイパーリンク(Python_)、内部の相互参照(example_)、脚注参照
    ([1]_)、引用参照([CIT2002]_)、代理参照(|example|)、及び _`インライン
    内部ターゲット` である。
    
    段落は空白行によって区画されており、左詰めで記述される。
  • 5種類のリスト

    1. ブレットリスト

      - これはブレットリストです。
      - リストの先頭の記号として、"*"、"+"または"-"が使用可能です。
    2. 番号つきリスト

      1. これは番号つきリストです。
      
      2. 番号は、アラビア数字、アルファベット又はローマ数字が使用可能です。
    3. 定義リスト

      what
          定義リストとは、用語とその定義を結び付けたものです。
      
      how
          用語は一行のフレーズです。また、定義は1つ以上の段落又はボディ要素
          であって用語に対して字下げされています。
    4. フィールドリスト

      :what: フィールドリストはフィールド名をフィールド本体に(データベース
             レコードのように)関連付けます。これらは文法の拡張に多用されます。
      
      :how:  フィールドのマーカはコロン、フィールド名、そしてコロンです。
      
             フィールドは1以上のボディ要素を含みます。これは、フィールドのマーカ
             に対して字下げされています。
    5. オプションリストはコマンドラインオプションの一覧を示すときに使用されます。:

      -a            "a"というコマンドラインオプションです。
      -b file       オプションは引数や長い
                    説明を伴うことができます。
      --long        短縮化されていないオプションも可能です。
      --input=file  短縮化されていないオプションも、引数を伴うことができます。
      /V            DOSやVMSスタイルのオプションも可能です。

      オプションと説明との間には2つ以上の空白が必要です。

  • リテラルブロック:

    リテラルブロックは、字下げされるか、行頭に引用符が入ったブロックであり、
    直前の段落の末尾にコロン2つ("::")を付けることによって示されます。
    (つまりこの右にあるもの→)::
    
      if literal_block:
          text = 'is left as-is'
          spaces_and_linebreaks = 'are preserved'
          markup_processing = None
  • 引用ブロック:

    引用ブロックは、字下げされたボディ要素から構成されます。
    
      This theory, that is mine, is mine.
    
      -- Anne Elk (Miss)
  • Doctestブロック:

    >>> print 'Python特有の表記法で、">>>"が行頭につきます'
    Python特有の表記法で、">>>"が行頭につきます
    >>> print '(動的なPythonセッションからカット&ペーストされます)'
    (動的なPythonセッションからカット&ペーストされます)
  • 2種類のテーブル表記法:

    1. 罫線つきテーブル 完全なものだが複雑で冗長:

      +------------------------+------------+----------+
      | Header row, column 1   | Header 2   | Header 3 |
      +========================+============+==========+
      | body row 1, column 1   | column 2   | column 3 |
      +------------------------+------------+----------+
      | body row 2             | Cells may span        |
      +------------------------+-----------------------+
    2. シンプルなテーブル 書きやすく簡潔、ただし制約あり:

      ====================  ==========  ==========
      Header row, column 1  Header 2    Header 3
      ====================  ==========  ==========
      body row 1, column 1  column 2    column 3
      body row 2            Cells may span columns
      ====================  ======================
  • 明示的マークアップブロックは必ず明示的ブロックマーカである2つのピリオドと空白が行頭に付く。

    • 脚注:

      .. [1] 脚注は、3文字以上字下げされた
         ボディ要素を含みます。
    • 引用:

      .. [CIT2002] 脚注とほとんど同じですが、ラベルが文字列となっています。
    • ハイパーリンクターゲット:

      .. _Python: http://www.python.org
      
      .. _example:
      
      上の"_example" ターゲットは、この段落を示す。
    • ディレクティブ:

      .. image:: mylogo.png
    • 置換の定義:

      .. |シンボルはここ| image:: symbol.png
    • コメント:

      .. コメントは2つのピリオドと空白から始まる。その後には何を書いてもよい
         ただし、脚注、引用、ハイパーリンクターゲット、ディレクティブ、置換の
         定義を除く。

詳細な文法

下記のものは、文法の構造に対応した「doctree要素」(文書ツリー要素の名称、つまりXML DTDの一般識別子)の一覧を示したものである。要素の階層構造の詳細については、The Docutils Document TreeおよびDocutils Generic DTDのXML文書型定義を参照のこと。

ホワイトスペース

字下げの為に空白を使用することが推奨されているが、タブも使用可能である。タブは空白に置換される。タブ間隔は8文字である。

他のホワイトスペース文字(フォームフィード[chr(12)]及び垂直タブ[chr(13)])は、前処理で空白に変換される。

空白行

空白行は、段落や他の要素を区画するために使用される。連続する複数の空白行は一行の空白行と等価であるが、(全てのホワイトスペースが保持される)リテラルブロックにおいてはそうはならない。字下げを伴うマークアップによって要素の区画が明確になされるような場合は、空白行を省略してもよい。文書の最初の行は空白行が手前にあるものとして扱われ、また、文書の最終行はその直後に空白行があるものとして扱われる。

字下げ

字下げは、引用ブロック、(定義リストアイテム内での)定義、そして以下の入れ子状にまとめられた内容を示す際に使用されるものであり、そのためだけに使用される。

  • リストアイテムの内容(複数のリストアイテムや、リストアイテム中の(入れ子状のリストを含む)複数のボディ要素)

  • リテラルブロックの内容

  • 明示的なマークアップブロックの内容

現在の字下げレベルよりも上位レベルのテキスト(つまり、字下げされていないテキストや「字上げ」されたもの)は、現在の字下げレベルの末端を意味する。

全ての字下げには意味があるので、字下げのレベルは矛盾なく設定されなければならない。例えば、字下げは、引用ブロックを示す唯一のマークアップ指示子である。

これは最上位の段落です。

  この段落は第1レベルの引用ブロックに属します。

  第1レベルの引用ブロックの第2段落です。

引用段落内で複数段の字下げレベルを用いることによって、より複雑な構造を表現できる。

これは最上位の段落です。

  この段落は第1レベルの引用ブロックに属します。

    この段落は第2レベルの引用ブロックに属します。

これも最上位の段落です。

    この段落は第2レベルの引用ブロックに属します。

  この段落は第1レベルの引用ブロックに属します。
  上の第2レベルの引用ブロックは、この第1レベルの
  引用ブロックの中に配置されます。

段落などの構造が複数行に亙るのであれば、それらの行は左揃えでなければならない。

これは段落です。この段落の
行は左揃えされています。

   この段落は正しくありません。
 行が左揃えになっていません。
  文が間違って解釈される可能
    性があり、また、警告及び/又は
   エラーメッセージがパーサによって
  生成されるはずです。

一部の構造はマーカで始まり、その構造のボディはマーカに対して字下げされていなければならない。シンプルなマーカ(ブレットリスト番号つきリストハイパーリンクターゲットディレクティブ及びコメント)を用いる場合は、そのボディの字下げのレベルはそのテキストの最初の行、つまりマーカがある行によって決まる。例えば、ブレットリストのボディは、リスト記号から少なくとも二文字分字下げされなければならない。

- これはブレットリストの項目の段落の最初の
  段落です。全ての行は1行目と左揃えになって
  いなければいけません。 [1]_

    この字下げされた段落は引用ブロックとして
    解釈されます。

この段落はちゃんと字下げされていので、
リストの項目にはなりません。

.. [1] これは脚注です。脚注の2行目は
   脚注の最初の行と左揃えにします。".."
   というマーカから字下げされます。

複雑なマーカを用いる構造(フィールドリストオプションリストのような様々なテキストがマーカに含まれるもの)の場合は、マーカの後の最初の行の字下げがボディの左端となる。

:こんにちは: このフィールドはフィールド名が短いので、
           無理無くフィールドボディを一行目に揃える
           ことができます。

:何匹のアフリカツバメでヤシの実を運んだんだ?: この場合、
    一行目の左端にフィールドボディを揃えるのはとても
    難しいです。マーカのある行からボディを開始しないケース
    が望ましいこともあります。

Note

(訳注)上の2段落目の例は、原文では"Number-of-African-swallows-required-to-carry-a-coconut"となっています。これはモンティ・パイソン・アンド・ホーリー・グレイルが元ネタなので、それっぽく訳しています。

エスケープ機構

7ビットアスキーコードは広く使われているプレーンテキスト用の文字セットだが、これを好き勝手に使える訳ではない。マークアップに使われる文字はなんであれ、既存の文法においても色々な意味で使われている。それ故に、時々マークアップ用の文字を、マークアップとして字下げせずに文章中で使いたくなる時もあるだろう。実用性重視のマークアップ機構には、マークアップに使用される文字の意味を無効にするためのエスケープ機構が必要だ。reStructuredTextは、他の色々なテキストと同様、バックスラッシュをエスケープ文字として使用している。

バックスラッシュは、その後に続く一文字(ホワイトスペース文字)をエスケープする。エスケープされた文字は、その文字そのものとして扱われ、マークアップとして解釈されないようになる。(パーサによって処理された後の)出力にはバックスラッシュは含まれない。バックスラッシュを出力したい時は、バックスラッシュを二文字並べればよい(最初のバックスラッシュが二文字目を「エスケープ」し、これが「エスケープ」文字として解釈されないようにする)。

バックスラッシュでエスケープされたホワイトスペースは文書から除去される。これによって、文字レベルでのインラインマークアップが可能となる。

Tip

(訳注)これは日本語を含むマルチバイト文字を含む語をインラインマークアップしたい時に有用である。つまり、"\ "でマークアップを囲むことによって、ハイパーリンクターゲット文字の強調の前後に空白を出力させないようにすることができる。

リテラルブロックとインラインリテラル内ではバックスラッシュが意味をなさない。この場合、バックスラッシュを2つ重ねなくても、一文字のバックスラッシュを出力することができる。

reStructuredTextの仕様やパーサは、入力されるテキストをどのように表現するか、またはどのように抽出するか(どうやって、またどのような形式のテキストをパーサに送るか)を定めるものではない、という点に留意されたい。バックスラッシュや他の文字が、ある状況下では文字エスケープ用途に使用され、適切に処理されるだろう。例えば、パイソンではバックスラッシュは特定の文字をエスケープする際に使用されるが、他の文字をエスケープしない。Pythonのdocstrings中にバックスラッシュがあった場合、下記の例のようにたいていは処理せずにそのまま使用される。

r"""このdocstringは処理されません。バックスラッシュ(\)はそのまま残ります"""

参照名

シンプルな参照名は、英数文字と単独の(2文字以上連続しない)ハイフン、アンダースコア、ピリオド、コロン及びプラス記号から構成され、ホワイトスペースや他の文字を含まない単語である。脚注ラベル(脚注及び脚注参照)、引用ラベル(引用及び引用参照)、インタプリテッドテキスト、及び一部のハイパーリンク参照は、シンプルな文法の参照名を使用する。

句読点を含む参照名やフレーズの参照名(スペースで区切られた2語以上のもの)は、「フレーズ参照」と呼ばれる。以下のように、フレーズ参照はバッククォートでフレーズを囲むことによって記述され、参照名として扱われる。

`my favorite programming language`_ について知りたくはないかい?

.. _my favorite programming language: http://www.python.org

また、シンプルな参照名をバッククォートで囲んでもよい。

参照名はホワイトスペースや大文字小文字を厳密に扱わない。参照名は内部的には以下のように処理される。

  • ホワイトスペースは標準化される(空白、水平または垂直タブ、改行、キャリッジリターン、フォームフィードは1つであってもそれ以上であっても空白一つであると解釈される)

  • 大文字小文字は標準化される(全てのアルファベットは小文字に変換される)

例えば、下記のハイパーリンクターゲットはどれも同じ意味である。

- `A HYPERLINK`_
- `a    hyperlink`_
- `A
  Hyperlink`_

ハイパーリンク脚注、及び引用はすべて参照名のネームスペースを共有する。引用のラベル(シンプルな参照名)と、手動で番号が付与された脚注(数字)は、他のハイパーリンク名とともに同一のデータベースに入力される。これは、(".. [1]"として定義される)脚注は、脚注参照([1]_)から参照されるとともに、通常のハイパーリンク参照(1_)からも参照される。無論、各タイプの参照(ハイパーリンク、脚注、引用)を別々に処理してレンダリングすることもある。参照名のコンフリクトを避けるべくある程度考慮はするべきである。

文書構造

文書 ``

Doctree要素: 文書

解釈されたreStructuredText文書における最上位の要素は、「文書」要素である。最初の解釈を行った後、文書要素は、ボディ要素区切り及びセクションからなる文書の断片(文書の表題や他の書誌要素を含まない)のためのシンプルなコンテナとなる。パーサを呼び出すコードは、選択的な解釈後の後処理として1以上の変形処理を実行し、表題と必要に応じて他のメタデータ要素(著者、日付など。書誌フィールド参照のこと)を加えて文書を完成させることができる。

実のところ、reStructuredTextに表題や副題を明示する方法は無い。その代わり、一つしかない最上位レベルのセクション見出し(後述のセクションを参照のこと)は、表題として解釈されうる。同様に、「表題」の直後にある一つしかない第2レベルのセクション見出しが、副題であると解釈されうる。それ以降のセクションは1または2レベル格上げされる。詳細は、DocTitle transform`_を参照のこと。

セクション

Doctree要素: セクション、 見出し

セクションはその見出しによって識別され、その見出しのテキストの下を「アンダーライン」で装飾するか、アンダーラインとそれに対応するタイトルの上の「オーバーライン」で装飾することによってマークアップされる。アンダーラインやオーバーラインは、句読点文字を左端から繰り返し入力して線状にしたものであり、少なくとも見出しテキストの右端より長く伸びている。なお、アンダーライン及びオーバーライン用の文字としては、出力可能な7ビットのアスキー文字のうち、英数文字を除いた全てが使用可能である1。オーバーラインを使用する場合は、その長さと文字はアンダーラインと同じものでなければならない。アンダーラインのみの装飾スタイルは、同じ文字を使用しているオーバーラインとアンダーラインのスタイルとは異なるものとして解釈される。セクション見出しのレベルの深さに制限はないが、出力フォーマットの方に制約があるかもしれない(HTMLの見出しは6レベルである)。

1

以下の文字は全てセクション見出しの装飾に問題なく使用可能である。

! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~

一部の文字は他のものよりも適切であり、以下の文字が推奨される。

= - ` : . ' " ~ ^ _ * + #

セクション見出しの数や序列は装飾スタイルに応じて固定されている訳ではなく、序列は登場順に割り当てられる。最初に登場するスタイルは(HTMLにおけるH1のような)最上位の見出しであり、その次に登場するスタイルは副見出しであり、三番目に登場するものは副々見出しであり、以下同様である。

セクション見出しの一例を以下に示す。

===============
 Section Title
===============

---------------
 Section Title
---------------

Section Title
=============

Section Title
-------------

Section Title
`````````````

Section Title
'''''''''''''

Section Title
.............

Section Title
~~~~~~~~~~~~~

Section Title
*************

Section Title
+++++++++++++

Section Title
^^^^^^^^^^^^^

見出しがアンダーラインとオーバーラインの双方を伴う場合、上の2例のように、見出しのテキストをマージン付きで書くことができる。これは見た目の問題に過ぎず、特に意味のあるものではない。通常は、アンダーラインのみの見出しテキストにマージンをつけることは出来ない

見出しの後に空白行を入れることができる。この見出しから同じまたはより上位の見出しまでの間にあるテキストのブロックは、一つのセクション(またはサブセクションなど)に含まれる。

全てのセクション見出しのスタイルを使用する必要は無く、また、特定のセクション見出しのスタイルを使用する必要も無い。ただし、文書はセクション見出しを矛盾無く使用する必要がある。つまり、見出しのスタイルの上下関係が一度決まったら、セクションはこの上下関係に従って設定されなければならない。

セクション見出しの各々は、そのセクションを指すハイパーリンクターゲットを自動的に生成する。ハイパーリンクターゲット(つまり「参照名」)のテキストはセクション見出しのテキストと同じである。暗黙のハイパーリンクターゲットも参照のこと。

セクションは、ボディ要素区切り及び下位のセクションを含むことができる。

区切り

Doctree要素: 区切り

小見出しを使用する代わりに段落間に空白や装飾を入れ、テキストの区切りとしたり、主題の変更や強調を示すことができる。

(The Chicago Manual of Style, 14th edition, section 1.80)

区切りは小説や短いフィクションでは、1行以上の空白(アスタリスクの列のような装飾を伴うこともある)を区切りとして使用することが多い。区切りは他のボディ要素とは異なる特徴を有する。区切りはセクションや文書の先頭又は末尾に配置されるべきでは無く、また、2つの区切りを隣同士で配置すべきではない。

区切りのマーカは、4字以上の句読点文字からなる水平線として記述される。この記法は、(見出しテキストが無いという点以外では)アンダーラインによるセクション見出しの記法と同じである。以下のように、区切りのマーカの前後には空白行を入れなければならない。

段落

----------

段落

セクション見出しのアンダーラインとは異なり、区切り用のマーカには上下関係は無く、区切りのマーカの違いはいかなる意味をもなさない。とはいえ、同じスタイルで統一することが望ましい。

処理系は、嗜好に応じてどのような形で区切りを出力してもよい。例えば、HTML出力の場合は水平線(<hr>)の使用が妥当な選択だろう。

ボディ要素

段落

Doctree要素: 段落

段落は、他のボディ要素を示すマークアップが付与されていない、左揃えのテキストのブロックである。空白行は段落を他の段落やボディ要素と区別する。段落はインラインマークアップを含んでいてもよい。

段落の書き方を以下に図示する。

+------------------------------+
| paragraph                    |
|                              |
+------------------------------+

+------------------------------+
| paragraph                    |
|                              |
+------------------------------+
ブレットリスト

Doctree要素: ブレットリスト、 リストアイテム

"*"、 "+"、 "-"、 "•"、 "‣"または "⁃"とその次のホワイトスペースに続いて記述されるテキストブロックはブレットリストアイテム(別名:「番号無し」リストアイテム)である。リストアイテムのボディは左揃え且つブレットに対して字下げされていなければならない。つまり、ブレットの直後のテキストの字下げレベルがリストアイテムの字下げレベルとなる。以下に一例を示す。

- これは最初のリストアイテムです。最初のリストアイテムの上には空白行を入れな
  ければいけません。また、リストアイテム同士の間の空白行(この段落の下にあるよ
  うなもの)は無くても構いません。

- これはリストの二番目のアイテムの第一段落です。

  これはリストの二番目のアイテムの第二段落です。この段落の上に空白行を入れな
  ければいけません。この段落の左端は上の段落と揃えられており、共にブレット
  から字下げされています。

  - これはサブリストです。ブレットは上のテキストブロックの左端に揃えられます。
    サブリストは新しいリストなので、そのリストアイテムの上下には空白行を入れる
    必要があります。

- これはメインのリストの三番目のリストアイテムです。

これは、リストに含まれない段落です。

間違った形式のブレットリストの一例を以下に示す。

- この第一行目は間違っていません。
リストアイテムと(リストに属さない)段落との間には空白行が必要です。(警告)

- この次の行からサブリストが始まります。しかし、以下の点でダメです。
  - これは上の段落の続きであって、サブリストではありません(間に空白行が入って
    いません)。加えて、字下げの仕方が間違っています。
  - ここを処理する際に警告が示されるでしょう。

ブレットリストの書き方を以下に示す。

+------+-----------------------+
| "- " | list item             |
+------| (body elements)+      |
       +-----------------------+
番号つきリスト

Doctree要素: 番号つきリスト、 リストアイテム

番号つきリスト(別名: 「順番」リスト)は、ブレットリストとほとんど同じであるが、ブレットの代わりに番号を使用する。番号は、番号づけシーケンス部と、書式記号から構成され、その後にホワイトスペースを入れる。下記の番号づけシーケンスが使用可能である。

  • アラビア数字: 1, 2, 3, ... (上限無し).

  • ローマンアルファベット(大文字): A, B, C, ..., Z.

  • ローマンアルファベット: a, b, c, ..., z.

  • ローマ数字(大文字): I, II, III, IV, ..., MMMMCMXCIX (4999).

  • ローマ数字(小文字): i, ii, iii, iv, ..., mmmmcmxcix (4999).

また、オート番号である"#"を用いることによって、番号を自動的に割り振ることができる。自動的に番号が割り振られたリストは、最初のアイテムに明示的な(訳注:つまり"#"ではなく数字やアルファベットを使用する)番号を使用して、番号付けシーケンスを設定することもできる。どのような。完全に自動化された(訳注:つまり、最初のアイテムから"#"を使用した)リストは、アラビア数字を番号とし、最初のアイテムの番号は1である。(自動的に番号が割り振られるリストは、Docutils 0.3.8にて最初に実装された)

リストの書式としては以下のものが使用可能である。

  • 番号文字の後ろにピリオドをつけたもの: "1.", "A.", "a.", "I.", "i.".

  • 番号文字をカッコで囲んだもの: "(1)", "(A)", "(a)", "(I)", "(i)".

  • 番号文字の後ろに右カッコをつけたもの: "1)", "A)", "a)", "I)", "i)".

番号つきリストの解釈において、以下のような場合は必ず新しいリストが生成される。

  • リスト中に、異なる番号文字や書式が現れた場合。(例えば、"1."の後に"(a)"があれば、それぞれが別個のリストとなる)

  • 番号が順番に並んでいない場合。(例えば、"1."の後に"3."があれば、それぞれ別個のリストとなる)

最初のリストアイテムの番号は、1番目を指すもの("1"、"A"、"a"、"I"または"i")であることが推奨される。最初の番号の値として使用しても認識はされるが、出力フォーマットにおいてサポートされるとは限らない。level-1[info]システムのメッセージは、1番を指す文字で始まらないいかなるリストも生成可能である。

ローマ数字を使用するリストの最初のアイテムの番号は、"I"か"i"、あるいは"II"や"XV"のような複数文字からなる値でなければならない。他の一文字のローマ数字("V"、"X"、"L"、"C"、"D"、"M")は、ローマ数字ではなくアルファベットの文字として処理される。同様に、アルファベットを使用するリストにおいては、"I"や"i"はローマ数字として処理されるため、これらの文字を最初のアイテムの番号として使用することは出来ない。

番号つきリストの各リストアイテムの二行目が正しく書かれているかどうかのチェックが行われる。これは、番号として使用されうる文字で始まる通常の段落が間違ってリストアイテムとして解釈されないようにするためである。例えば、下記のテキストは通常の段落として解釈される。

A. Einstein was a really
smart dude.

しかしながら、そのような段落が一行のみである場合は、誤って解釈される可能性を排除できない。下記のテキストは、番号つきリストのリストアイテムとして解釈される。

A. Einstein was a really smart dude.

番号として使用されうる文字列("A."、"1."、"(b)"、"I)"など)で始まる一行の段落を記述する場合は、最初の文字をエスケープしてその行が通常の段落として解釈されるようにする。

\A. Einstein was a really smart dude.

入れ子状の番号つきリストを以下に示す。

1. Item 1 initial text.

   a) Item 1a.
   b) Item 1b.

2. a) Item 2a.
   b) Item 2b.

番号つきリストの書き方を以下に図示する。

+-------+----------------------+
| "1. " | list item            |
+-------| (body elements)+     |
        +----------------------+
定義リスト

Doctree要素: 定義リスト、 定義リストアイテム、 用語見出し、 分類子、 定義内容

定義リストアイテムの各々には、用語見出し、分類子(オプション)および定義内容が含まれる。 用語見出しは一行のシンプルな単語またはフレーズである。オプションである分類子は用語見出しに続いて同じ行に記述され、そのそれぞれはインラインの" : "(空白、コロン、空白)の後に記述される。定義内容は用語見出しに対して字下げされたブロックであり、複数の段落や他のボディ要素を含むことができる。用語見出しの行と定義内容のブロックを入れられない(これによって、定義リストと引用ブロックとを区別することができる)。最初の定義リストアイテムの前と、最後の定義リストアイテムの後には空白行を入れる必要がある。また、定義リストアイテム間に空白行を入れてもよい。以下に例を示す。

用語1
    定義1。

用語2
    定義2の第一段落。

    定義2の第二段落。

用語3 : 分類子
    定義3。

用語4 : 分類子1 : 分類子2
    定義4。

用語見出しの行のインラインマークアップは、分類子の区切り文字(" : ")が認識される前においては解釈される。区切り文字は、インラインマークアップの外にある場合に認識される(訳注: つまり、区切り文字がマークアップされている場合は、区切り文字として認識されない)。

定義リストは様々なケースで使用される。以下に例を示す。

  • 辞書や用語集的な用法。用語見出しに単語を記述し、分類子は例えばその語の種類(名詞や動詞など)を示すために使用される。そして、その後に定義内容を記述する。

  • プログラムの変数を説明する。用語見出しは変数の名称であり、分類子は例えばその変数の種類(文字列、整数など)を示すために使用される。そして、定義内容にはそのプログラム中の変数の用途を記述する。定義リストにおけるこの用法を、Pythonのオブジェクト・スキーマを記述しかつ実行するシステムであるGrouchの分類子の記述法は採用している。(訳注: 2008年3月時点では上記のリンクはデッドリンクとなっている。ただし、Grouchのソースのファイルリストにはアクセス可能)

定義リストの書き方を以下に図示する。

+----------------------------+
| term [ " : " classifier ]* |
+--+-------------------------+--+
   | definition                 |
   | (body elements)+           |
   +----------------------------+
フィールドリスト

Doctree要素: フィールドリスト、 フィールド、 フィールド名、 フィールドボディ

フィールドリストは、ディレクティブのオプションやデータベース風のレコードのような、更なる処理が予定される拡張書式の一部として使用される。これらはまた、データベースのレコード(ラベルとデータの組み合わせ)に似た、2列のテーブル状の構造を使用する。reStructuredTextを使用するアプリケーションはフィールド名を認識し、フィールドまたはフィールドボディを所定のコンテキストに変換する。一例については、後述の書誌フィールドや、reStructuredText Directivesにおける"image"および"meta"ディレクティブを参照のこと。

フィールドリストは、RFC822のヘッダを参考にして、フィールド名にフィールドボディを関連付けたものである。フィールド名を構成する文字は何を使ってもよいが、フィールド名の中ではコロン(":")はバックスラッシュでエスケープしなければならない。インラインマークアップはフィールド名中でも有効である。後工程においてはフィールド名は大文字小文字を区別せずに処理または変換される。フィールド名はその前後にコロンが記入されており、これらはフィールドマーカを形成する。フィールドマーカの後ろにはホワイトスペースとフィールドボディが記述される。フィールドボディは、フィールドマーカから字下げされた複数のボディ要素であってもよい。フィールドボディの字下げの文字数は、フィールド名のマーカの次の行で決まる。以下に例を示す。

:Date: 2001-08-16
:Version: 1
:Authors: - Me
          - Myself
          - I
:インデンティケーション: フィールドマーカがとても長いので、
   フィールドボディの二行目以降は一行目とは揃えられては
   いないが、フィールドマーカに対して字下げされており、
   かつ二行目以降は左揃えとなっている。
:Parameter i: integer

複数の単語からなるフィールド名中の個々の単語は、アプリケーションによって処理される。アプリケーションによってはフィールド名の特定の書式を使用する。例えば、二語目以降を「引数」として扱い、引用符でくくられたフレーズを一つの引数として扱い、"name=value"形式への直接のサポートを追加する。

RFC822規格のヘッダは一義ではないため、このような構造に対して使用することはできない。行の一番左の単語の後にコロンが付く構造は、通常のテキストでもよく見られる。但し、フィールドリストが文書の先頭に必ず現れる(PEPや電子メール・メッセージ)ような、十分に定義されたコンテキストにおいては、RFC822規格のヘッダを使うことができる。

簡略化されたフィールドリストの書き方を以下に図示する。

+--------------------+----------------------+
| ":" field name ":" | field body           |
+-------+------------+                      |
        | (body elements)+                  |
        +-----------------------------------+
書誌フィールド

Doctree要素: docinfo, author, authors, organization, contact, version, status, date, copyright, field, topic.

フィールドリストが文書中の最初の(文書の表題の直後(表題が一つのみの場合に限る))コメントではない要素である時は、そのフィールドは文書の書誌データに変換される。この書誌データは、書籍序文、例えばタイトルや著作権のページに対応する。

特定の登録されたフィールド名(後述)は認識されて対応するdoctree要素に変換されうる。そして、そのほとんどは「docinfo」要素の子要素となる。このようなフィールドにおいては、(要素が記述される)順序に決まりは無く、前述のように、文書構造に適合するように順番の入れ替えがなされる可能性がある。下記の例外を除いては、書誌的要素のフィールドボディは一つの段落のみを含むことができる。フィールドボディはRCSキーワードをチェックされ、次いでこのキーワードは削除される。未登録のフィールドは市消去されず、docinfo要素中の汎用フィールドになる。

The registered bibliographic field names and their corresponding doctree elements are as follows: 登録されている書誌フィールド名及び対応するdoctree要素を以下に示す。

  • "Author": 著者

  • "Authors": 著者(複数)

  • "Organization": 組織

  • "Contact": 連絡先

  • "Address": アドレス

  • "Version": バージョン

  • "Status": 状態

  • "Date": 日付

  • "Copyright": 著作権

  • "Dedication": トピック

  • "Abstract": トピック

「Authors」フィールドは、著者のリストがセミコロンかカンマで区切られた一つの段落か、ブレットリストであってその要素の各々が一人の著者に対応する単一の段落となっているもののいずれかである。セミコロンが先にチェックされるので、「Doe, Jane; Doe, John」は(「Jane Doe」と「John Doe」として)きちんと処理される。特定の言語(例えばスウェーデン語)では、「Author」と「Authors」を単数/複数で区別しない、そのため、「Authors」フィールドのみが使用され、著者が単数の場合は「Author」として処理される。一つの名前であってそこにカンマが含まれる場合は、それが一つの名前であることを明確にするため、末尾にセミコロンを加える。すなわち、":Authors: Doe Jane;"とする。

「Address」フィールドには、複数行に亙ってメールのアドレスを記載することができる。空白行やホワイトスペースはそのまま保持される。

「Dedication」及び「Abstract」フィールドには、任意の複数のポディ要素を含むことができる。この2つのうちのどちらか一方のみ使用可能である。これらは「Dedication」または「Abstract」のタイトル(または他の言語による等価な語)を伴うトピック要素となり、docinfo要素の直後に配置される。

このフィールド名と要素の組み合わせは、他の言語に置き換えることができる。詳細はDocInfo transformの組み込みのための文書を参照せよ。

登録されていない/汎用のフィールドは、段落または任意のボディ要素を一つまたはそれ以上含むことができる。

RCSキーワード

パーサによって認識される書誌フィールドに対しては、通常、RCS2キーワードのチェックが行われ、次いでキーワードは削除される3。RCSキーワードはソースファイルに"$keyword$"という形で入力され、一旦RCSまたはCVS4に記憶され、その時これらは"$keyword: expansion text $"に書き換えられる。例えば、"Status"フィールドは以下のように"status"要素に変換される。

:Status: $keyword: expansion text $
2

Revision Control System.

3

RCS keyword processing can be turned off (unimplemented).

4

Concurrent Versions System. CVS uses the same keywords as RCS.

"status"要素のテキストが処理されると、これは単なる"expansion text"となる。$マークの区切り文字や頭にあるRCSきキーワードは削除される。

RCSキーワードの処理は、フィールドリストが書誌的コンテキストである(文書において、文書タイトルの後にある最初の非コメント構造(文書タイトルが一つのみである場合に限る))場合においてのみ実行される。

オプションリスト

Doctree要素: option_list, option_list_item, option_group, option, option_string, option_argument, description.

オプションリストは、コマンドラインオプションとその説明からなる2列のリストであり、プログラムのオプションを説明するためのものである。以下に例を示す。

-a         全て出力する。
-b         両方を出力する(この説明は
           とても長い).
-c arg     argのみを出力する。
--long     全日分を出力する。

-p         このオプションの説明は2段落に亙っている。
           これが最初の段落である。

           これが2番目の段落である。 空白行は上記のようにオプション間
           では無くてもよく、ここや下記のようにあってもよい。

--very-long-option  VMSタイプのオプション。オプションと説明文の間
                    には2つ以上の空白が必要である。

--an-even-longer-option
           次の行から説明文を書きはじめてもよい。

-2, --two  2つの引数を持つオプション

-f FILE, --file=FILE  この2つのオプションは同じ意味を持つ。どちらの
                      オプションにも属性値がつく。

/V         VMS/DOSタイプのオプション。

reStructuredTextは複数の種類のオプションを認識することができる。

  • ダッシュと一文字のオプションから構成されるPOSIXタイプのオプション。

  • 2つのダッシュとオプション・ワードから構成されるPOSIXタイプの長いオプション。 システムによってはダッシュは一つである。

  • プラス記号と一文字のオプション文字から構成される古いGNUタイプの"plus"オプション ("plus"オプションは現在では反対されており、使用すべきではない)

  • スラッシュ記号と一文字のオプション文字または一つのオプション/ワードから構成されるDOS/VMSタイプのオプション

POSIXタイプのオプションとDOS/VMSタイプのオプションの双方がDOS用又はWindows用のソフトで使用されるという点に注意すること。これらのもの及びその別体が、時々ごっちゃになって使用されている。上記の名称は便宜的に採用したものである。

ショートタイプ又はロングタイプのPOSIXオプションの文法はPythonのgetopt.pyモジュールにてサポートされているものに基づいており、これは、GNU libc getopt_long() 関数のものに似ているが一部制約のあるオプションパーサを採用している。オプションシステムには別体がたくさんあり、reStructuredTextのオプションリストでこれら全てがサポートされているわけでは無い。

OSやアプリケーションによっては、コマンドラインで使用するときのロングタイプのPOSIXやDOS/VMSオプションの単語を短縮することができるようになっているが、reStructuredTextのオプションリストは、いかなる特別な文法においてもこれを指示することもサポートもすることはない。オプションワードは全て説明され、短縮形が使用可能であるならばそれについての注釈でサポートされるべきである。

オプションの後には引数プレースホルダが付くことがあり、その役割や文法はオプションリストの説明部分で説明されるべきである。空白やイコール記号がオプションと引数プレースホルダとの間の区切文字として使用される場合があり、また、("-"や"+"のみをプレフィックスとする)短いオプションにおいては区切文字を用いない場合がある。オプションの引数は下記の2つの形式のどちらかが使用される。

  • 文字([a-zA-Z])で始まり、 英数文字やアンダースコア、ハイフンで構成される([a-zA-Z0-9_-])。

  • 開き山括弧(<)で始まり、閉じ山括弧(>)で終わるもの。その間には山括弧以外のあらゆる文字を記入可能である。

同義の複数のオプションを並べることにより、その説明を共有することができる。これらはカンマと空白文字で区切られていなければならない。

オプションとその説明との間には少なくとも空白を二文字入れなければならない。説明文は複数のボディ要素を有していてもよい。説明文の字下げレベルはオプションマーカの次の行の字下げによって決まる。最初のリストアイテムの前及び最後のアイテムの後には空白行を入れる必要があるが、一方オプションエントリ同士の間には空白を入れても入れなくてもよい。

簡略化されたオプションリストの書き方を以下に図示する。

+----------------------------+-------------+
| option [" " argument] "  " | description |
+-------+--------------------+             |
        | (body elements)+                 |
        +----------------------------------+
リテラルブロック

Doctree要素: literal_block.

2つのコロン("::")から構成される段落は、その後のテキストブロックがリテラルブロックであることを意味する。リテラルブロックは字下げされるか、引用符(後述)を伴うものでなければならない。リテラルブロックの中ではマークアップ処理は行われない。リテラルブロックは加工されずにそのまま表示され、大抵の場合はモノスペースフォントでレンダリングされる。

これは通常の段落です。その後には、字下げされたリテラルブロックがあります。

::

    for a in [5,4,3,2,1]:   # this is program codeであり、整形されません
        print a
    print "it's..."
    # リテラルブロックは字下げされていない行が現れるまで続きます

このテキストの字下げレベルは最初の段落と同じであるので、リテラルブロックとはならず、
通常の段落として処理されます。

"::"のみの段落は完全に取り除かれ、、アウトプットに空の段落が残ることはない。

その方が便利であるため、"::"は各段落の最後のもののみが(リテラルブロックを定めるものとして)認識される。 "::"の前にホワイトスペースを伴う場合、コロンは2つともアウトプットには残らない (これは、『一部簡略化された』形式である)。 テキストの直後に(ホワイトスペースを置かずに)"::"を記述した場合は、コロンが一つ削除され、アウトプットにはコロンは一つのみ表示される(すなわち、"::"は":"に置き換わる。これは、『完全に簡略化された』形式である)。

例を挙げると、以下の3つは等価である("段落"の後ろにあるコロンに注目のこと)。

  1. 非簡略の形式:

    段落:
    
    ::
    
        リテラルブロック
  2. 一部簡略化された形式:

    段落: ::
    
        リテラルブロック
  3. 完全に簡略化された形式:

    段落::
    
        リテラルブロック

全てのホワイトスペース(改行を含む。 また、字下げリテラルブロックの各行の字下げのうち、 最小のものの文字数分のホワイトスペースは含まれない)はそのまま残される。 リテラルブロックの前後には空白行を入れる必要があるが、これらの空白行は、 リテラルブロックの一部分とはならない。

字下げリテラルブロック

字下げリテラルブロックは、前後のテキストに対する字下げ(各行がホワイトスペースで始まる)によって定められる。 字下げリテラルブロックの各行の字下げのうち最小のものの文字数分のホワイトスペースは取り除かれる。 リテラルブロックは、連続している必要はない。 つまり、字下げされたテキストのセクション間に空白行があってもよい。 リテラルブロックの範囲は、字下げを伴う行までである。

字下げリテラルブロックの書き方を以下に図示する。

+------------------------------+
| paragraph                    |
| (ends with "::")             |
+------------------------------+
   +---------------------------+
   | indented literal block    |
   +---------------------------+
クウォーテッドリテラルブロック

クウォーテッドリテラルブロックは、字下げされていない連続したテキストのブロックであり、 各行が同一の7ビットASCII非英数記号 5 で始まるものである。 空白行により、クウォーテッドリテラルブロックは終了する。 引用符は、処理後の文書にも残される。

5

以下の文字はすべて引用符として使用される

! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~

これらは、セクションのタイトルを装飾するための文字と同じである。

例えば、Haskellによる文芸的プログラミングや電子メールでの引用は、 クウォーテッドリテラルブロックとして使用可能である。

John Doe wrote::

>> Great idea!
>
> Why didn't I think of that?

You just did!  ;-)

クウォーテッドリテラルブロックの書き方を以下に図示する。

+------------------------------+
| paragraph                    |
| (ends with "::")             |
+------------------------------+
+------------------------------+
| ">" per-line-quoted          |
| ">" contiguous literal block |
+------------------------------+
行ブロック

Doctree要素: line_block, line. (Docutils 0.3.5より)

行ブロックは、アドレスブロックや韻文(詩、歌詞等)、それに装飾の無いリストといった、 行の構造が明確であるようなものの記述に有用である。 行ブロックは、先頭が垂直バー("|")となる行の集合である。 行の前にある垂直バーの各々が新しい行を意味するので、改行は改行として処理される。 行頭の字下げは、ネスト構造として処理される。 また、インラインマークアップが使用可能である。 (行ブロックの一行目に続く)継続行は、長い行の一部となる。 これらの行においては、垂直バーの位置にスペース一文字を入れる。 継続行の左端は字下げされていなければならないが、その上の行のテキストと揃える必要は無い。 空白行をもって行ブロックは終了する。

継続行の例を以下に示す。

| Lend us a couple of bob till Thursday.
| I'm absolutely skint.
| But I'm expecting a postal order and I can pay you back
  as soon as it comes.
| Love, Ewan.

各行の字下げによって定められるネスト構造の行ブロックの例を以下に示す。

Take it away, Eric the Orchestra Leader!

    | A one, two, a one two three four
    |
    | Half a bee, philosophically,
    |     must, *ipso facto*, half not be.
    | But half the bee has got to be,
    |     *vis a vis* its entity.  D'you see?
    |
    | But can a bee be said to be
    |     or not to be an entire bee,
    |         when half the bee is not a bee,
    |             due to some ancient injury?
    |
    | Singing...

行ブロックの書き方を以下に図示する。

+------+-----------------------+
| "| " | line                  |
+------| continuation line     |
       +-----------------------+
引用ブロック
Doctestブロック
テーブル
罫線つきテーブル
シンプルなテーブル
明示的マークアップブロック
脚注
自動的に番号が振られる脚注
自動的に引用記号が振られる脚注
番号の自動割り当てと手動割り当ての混在
引用
ハイパーリンクターゲット
匿名ハイパーリンク
ディレクティブ
置換の定義
コメント

暗黙のハイパーリンクターゲット

インラインマークアップ

文字レベルのインラインマークアップ
強調
強い強調
インタプリテッドテキスト
インラインリテラル
ハイパーリンク参照
埋め込みURI
インライン内部ターゲット
脚注参照
引用参照
置換参照
スタンドアロン・ハイパーリンク

単位

長さの単位
相対的な単位

エラー処理


コメント(0)

コメントを投稿する際はここをクリック

Note

本サイトのハイパーリンクの一部は、オリジナルのサイトが閉鎖してしまったため"Internet archive Wayback Machine"へのリンクとなっています。そのようなリンクにはアイコン[archive]を付与しています。

本サイトはCookieを使用しています。本サイトにおけるCookieは以下の三種類のみであり、Cookieの内容に基づいてサイトの表示を変更する以外の用途には用いておりません。