reStructuredText マークアップ仕様

Author:David Goodger
Contact:docutils-develop@lists.sourceforge.net
Revision:$Revision: 7907 $
Date:$Date: 2015-08-18 11:33:55 +0000 (Tue, 18 Aug 2015) $
Copyright:

このドキュメントは、パブリック ドメインで公開されています。

注釈

この文書は詳細な技術仕様書であり、チュートリアルや入門書ではありません。これがあなたのreStructuredTextとの最初の接点であれば、まず最初に reStructuredText入門(A ReStructuredText Primer)や、早わかりreStructuredText(Quick reStructuredText)ユーザーリファレンスを読んでください。

reStructuredText は文書の構造を示すために、シンプルかつ直感的な構文を使用したプレーンテキストです。これらの構造は生のままでも加工された形態でも、同様の読みやすさです。このドキュメントが reStructuredText の(例えば、あなたがテキストファイルを読んでいるのであれば生の、HTML ドキュメントを読んでいるのであれば、加工されたドキュメントの)例そのものなのです。reStructuredText のパーサは Docutils のコンポーネントです。

シンプルで、暗黙的なマークアップはセクションの見出しや箇条書きのリスト、強調等の特殊な構造を表すために使われます。使用されるマークアップは可能な限り最小限であり、控えめです。あまり頻繁に使われない構造や、基本的なreStructuredTextの拡張構文には、より手が込んだり明示的なマークアップがあります。

reStructuredText は、とても小さいもの(例えば Python の docstring のようなインラインのプログラムドキュメントの断片)から、とても大きなもの(この文書)まで、あらゆる長さのドキュメントに適用できます。

最初のセクションでは例を使って reStructuredText のマークアップシンタックスの概要を簡単に説明します。仕様の全容は 構文詳細 セクションに記載されています。

リテラルブロック (マークアップの処理が実行されない)は、プレーンテキストのマークアップを説明するために、このドキュメント全体の例に利用されています。

構文概要

reStructuredText ドキュメントは body 要素またはブロックレベル要素によって構成されていて、セクションも構成できます。 セクション はタイトル(アンダーラインとオプションのオーバーライン)によって示されます。セクションは body 要素および/または子のセクションを含みます。body 要素はさらにリストアイテムを持つリストのように、段落や他の body 要素を順番に持つことができます。その他、段落などにはテキストと インラインマークアップ が含まれています。

これは body 要素 の例です:

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

    Paragraphs contain text and may contain inline markup:
    *emphasis*, **strong emphasis**, `interpreted text`, ``inline
    literals``, standalone hyperlinks (http://www.python.org),
    external hyperlinks (Python_), internal cross-references
    (example_), footnote references ([1]_), citation references
    ([CIT2002]_), substitution references (|example|), and _`inline
    internal targets`.
    
    Paragraphs are separated by blank lines and are left-aligned.
    
  • 5つのリストタイプ:

    1. 箇条書きリスト:

      - This is a bullet list.
      
      - Bullets can be "*", "+", or "-".
      
    2. 列挙リスト:

      1. This is an enumerated list.
      
      2. Enumerators may be arabic numbers, letters, or roman
         numerals.
      
    3. 定義リスト:

      what
          Definition lists associate a term with a definition.
      
      how
          The term is a one-line phrase, and the definition is one
          or more paragraphs or body elements, indented relative to
          the term.
      
    4. フィールドリスト:

      :what: Field lists map field names to field bodies, like
             database records.  They are often part of an extension
             syntax.
      
      :how: The field marker is a colon, the field name, and a
            colon.
      
            The field body may contain one or more body elements,
            indented relative to the field marker.
      
    5. オプションリスト:

      -a            command-line option "a"
      -b file       options can have arguments
                    and long descriptions
      --long        options can be long also
      --input=file  long options can also have
                    arguments
      /V            DOS/VMS-style options too
      

      オプションと詳細の間は少なくともスペース2つ分なければいけません。

  • リテラルブロック:

    Literal blocks are either indented or line-prefix-quoted blocks,
    and indicated with a double-colon ("::") at the end of the
    preceding paragraph (right here -->)::
    
        if literal_block:
            text = 'is left as-is'
            spaces_and_linebreaks = 'are preserved'
            markup_processing = None
    
  • 引用ブロック:

    Block quotes consist of indented body elements:
    
        This theory, that is mine, is mine.
    
        -- Anne Elk (Miss)
    
  • Doctest ブロック:

    >>> print 'Python-specific usage examples; begun with ">>>"'
    Python-specific usage examples; begun with ">>>"
    >>> print '(cut and pasted from interactive Python sessions)'
    (cut and pasted from interactive Python sessions)
    
  • 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
      ====================  ======================
      
  • 明示的マークアップブロック はすべて明示的なブロックマーカー、ピリオド二文字とスペースで始まります:

    • 脚注:

      .. [1] A footnote contains body elements, consistently
         indented by at least 3 spaces.
      
    • 引用:

      .. [CIT2002] Just like a footnote, except the label is
         textual.
      
    • ハイパーリンクターゲット:

      .. _Python: http://www.python.org
      
      .. _example:
      
      The "_example" target above points to this paragraph.
      
    • ディレクティブ:

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

      .. |symbol here| image:: symbol.png
      
    • コメント:

      .. Comments begin with two dots and a space.  Anything may
         follow, except for the syntax of footnotes/citations,
         hyperlink targets, directives, or substitution definitions.
      

構文詳細

以下の記述は、構文構造に関連する"doctree要素"(文書ツリーの要素名; XML DTDの汎用識別子)のリストです。要素の階層の詳細については、 The Docutils Document TreeDocutils Generic DTD のXMLドキュメント型定義を参照してください。

空白文字

インデント(indentation_)にはスペースが推奨されますが、タブ文字を使うこともできます。タブはスペースに変換されます。タブストップは8桁毎です。

他の空白文字(フォームフィード [CHR(12)]、及び垂直タブ[CHR(11)])は、処理の前に単一のスペースに変換されます。

空白行

空白行は段落や他の要素を区切るために使われます。複数の連続する空白行は、(全ての空白が保持される)リテラルブロック内を除き、単一の空白行と等価です。空白行は、マークアップがインデントと組み合わせて明示的に要素を区切る場合、省略できます。文書の最初の行は前の空白行に続いているかのように、文書の最終行はその後ろに空白行が続いているかのように扱われます。

インデント

インデントは引用ブロック、定義(定義リストのアイテム)、ローカルの入れ子になったコンテンツを表す -- そして、それらを表す場合にのみ意味をもつ -- ために使います:

  • リストアイテム(内容が複数行のリストアイテム、入れ子のリストを含む複数のbody要素を含むリストアイテム)、

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

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

現在のインデントレベルよりも小さい任意のテキスト(つまり、インデントしていないテキスト又は逆インデントされたテキスト)で、現在のレベルのインデントを終了します。

すべてのインデントには意味があるので、インデントのレベルは一貫している必要があります。例えば、インデントは 引用ブロック の唯一のマークアップ指示です:

This is a top-level paragraph.

    This paragraph belongs to a first-level block quote.

    Paragraph 2 of the first-level block quote.

引用ブロック内の複数レベルのインデントは、より複雑な構造になります:

This is a top-level paragraph.

    This paragraph belongs to a first-level block quote.

        This paragraph belongs to a second-level block quote.

Another top-level paragraph.

        This paragraph belongs to a second-level block quote.

    This paragraph belongs to a first-level block quote.  The
    second-level block quote above is inside this first-level
    block quote.

段落又は他の構文が複数行のテキストで構成されている場合、行は左揃えされている必要があります:

This is a paragraph.  The lines of
this paragraph are aligned at the left.

    This paragraph has problems.  The
lines are not left-aligned.  In addition
  to potential misinterpretation, warning
    and/or error messages will be generated
  by the parser.

いくつかの構成要素はマーカーによって始まり、そのbody構造はマーカーに対して相対的にインデントしている必要があります。単純なマーカーを使った構造(箇条書きリスト列挙リスト脚注引用ハイパーリンクターゲットディレクティブ および コメント)の場合、bodyのインデントレベルは開始マーカーと同じ行から始まる、テキストの最初の行の位置によって決まります。例えば、箇条書きリストのbodyはバレットの左端を基準にして、少なくとも2列のインデントが必要です:

- This is the first line of a bullet list
  item's paragraph.  All lines must align
  relative to the first line.  [1]_

      This indented paragraph is interpreted
      as a block quote.

Because it is not sufficiently indented,
this paragraph does not belong to the list
item.

.. [1] Here's a footnote.  The second line is aligned
   with the beginning of the footnote label.  The ".."
   marker is what determines the indentation.

複雑なマーカーを使った構造(フィールドリストオプションリスト)の場合、マーカーの後の最初の行のインデントが、bodyの左端を決定します。例えば、フィールドリストは非常に長いマーカー(フィールド名を含む)を持つ場合があります:

:Hello: This field has a short field name, so aligning the field
        body with the first line is feasible.

:Number-of-African-swallows-required-to-carry-a-coconut: It would
    be very difficult to align the field body with the left edge
    of the first line.  It may even be preferable not to begin the
    body on the same line as the marker.

エスケープの仕組み

プレーンテキスト文書に利用できる 7-bit ASCII 文字セットは、普遍的に制限されています。マークアップに利用されたか否かに関わらず、それらは書かれた文書の中で複数の意味を持つことになります。そのため、マークアップ文字は時に マークアップ文字として意図されずに テキストに表示される でしょう 。まともなマークアップシステムでは、エスケープ機構がマークアップに使用される文字のデフォルトの意味を上書きする必要があります。reStructuredTextでは一般的に他のドメインでエスケープ文字として使わているバックスラッシュを使います。

任意の文字(空白文字を除いて)が続くバックスラッシュは、その文字をエスケープします。エスケープ文字は、文字そのものを表し、任意のマークアップの解釈に基づく役割を果たさなくなります。バックスラッシュは出力から削除されます。リテラルのバックスラッシュは行中に2つのバックスラッシュ(最初のバックスラッシュは、2つ目の"エスケープする"役割に解釈されるのを"エスケープ"します)で表します。

バックスラッシュでエスケープされた空白文字は文書から取り除かれます。これにより文字レベルの インラインマークアップ が可能になります。

リテラルブロックとインラインリテラル: バックスラッシュが特別な意味を持たない、2つのコンテキストがあります。これらのコンテキストでは、単一のバックスラッシュを2重にすることなく、リテラルのバックスラッシュを表します。

reStructuredTextの仕様やパーサーは、テキスト入力の表現や抽出の問題(どのように、またどのテキスト形式で実際にパーサへ 到達する のか)を扱わないことに注意して下さい。バックスラッシュと他の文字は、特定のコンテキストにおいて文字エスケープの目的を果たすことができ、また適切に対処されなければなりません。例えばPythonは文字列内で特定の文字をエスケープするのに、他でもないバックスラッシュを使います。Pythonのdoctstringでバックスラッシュを表示する最も簡単な解決策は、raw doctringを使うことです:

r"""This is a raw docstring.  Backslashes (\) are not touched."""

参照名

単純な参照名は、英数字に加えて単独で(2つが隣接していない)埋め込みのハイフン、アンダースコア、ピリオド、コロン、そしてプラス記号で構成される単一のワードです; 空白及び他の文字は許可されません。脚注のラベル(脚注脚注参照)、引用ラベル(引用引用参照)、 解釈済みテキスト ロール、およびいくつかの ハイパーリンク参照 は、この単純な参照名の構文を使用します。

句読点やフレーズ(複数のスペースで区切られた単語)の名前を使った参照名は、"フレーズ参照"と呼ばれます。フレーズ参照はバッククォートで囲み、バッククォートされたテキストを参照名として処理することによって表されます:

Want to learn about `my favorite programming language`_?

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

単純な参照名も、オプションでバッククォートを使うことができます。

参照名は、空白に対して中立であり、大文字と小文字を区別しません。内部的に参照名が解決される時:

  • 空白文字は正規化(一つ以上のスペース、水平及び垂直タブ、改行、キャリッジリターン、またはフォームフィードは単一のスペースとして解釈)され、

  • 大文字、小文字も正規化(全ての英字は小文字に変換)されます。

例えば、以下の ハイパーリンク参照 は等価です:

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

ハイパーリンク脚注 、および 引用 は参照名のために、全て同じ名前空間を共有します。引用(単純な参照名)のラベルと手動で番号付けした脚注(番号)は他のハイパーリンク名と同じデータベースに入力されます。これは(".. [1]"のように定義された)脚注が、脚注参照( [1] )で参照可能であり、またふつうのハイパーリンク参照( 1_ )で参照可能であることを意味します。もちろん参照の各タイプ(ハイパーリンク、脚注、引用)が処理され異なったレンダリングをされる場合があります。参照名の競合を避けるために、多少の注意を払うべきです。

ドキュメント構造

ドキュメント

Doc ツリー要素: document

解析されたreStructuredText文書の最上位の要素は"document"要素です。最初の構文解析を行った後、document要素は文書のタイトルや書誌要素を欠いた、 body 要素トランジション 、および セクション から構成される文書の断片の単純なコンテナです。パーサを呼び出すコードは文書の断片を、タイトルおよび場合によっては他のメタデータ要素(著者、日付など; 書誌項目 を参照してください)を持つ完全な文書に再構成するための一つ以上の任意の解析後 変換 を実行することもできます。

Specifically, there is no way to indicate a document title and subtitle explicitly in reStructuredText. [1] Instead, a lone top-level section title (see Sections_ below) can be treated as the document title. Similarly, a lone second-level section title immediately after the "document title" can become the document subtitle. The rest of the sections are then lifted up a level or two. See the DocTitle transform for details.

[1]The title configuration setting can set a document title that does not become part of the document body.

セクション

Doc ツリー要素: section, title

セクションは、タイトルテキスト下の"アンダーライン"、またはアンダーラインとタイトルの上にある同じ長さの"オーバーライン"の装飾でマークアップされたタイトルによって識別されます。アンダーライン/オーバーラインは行頭から始まり、少なくともタイトルテキストの右端まで延びる線を形成する、単一の句読点文字の繰り返しです。具体的にはアンダーライン/オーバーラインの文字は英数字を除く印刷可能な7-bit ASCII文字です [2] 。オーバーラインを使う場合、使用される長さと文字をアンダーラインと一致させる必要があります。アンダーラインのみの装飾スタイルは、同じ文字を使ったオーバーラインとアンダーラインのスタイルとは異なります。セクションタイトルのレベル数は任意ですが、出力形式によっては制限があるかも知れません(HTMLは6レベルです)。

[2]

以下は全てセクションタイトルの装飾に有効な文字です:

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

一部の文字は他の文字よりも適しています。以下が推奨されています:

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

セクションの順番は、セクションタイトルの装飾の固定した番号や順番ではなく、出現した順番に従って適用されます。最初に出現したスタイルは、最も外側のタイトル(HTMLのH1のような)になり、2番目のスタイルがサブタイトルになり、3番目のスタイルがサブサブタイトルになる、といった感じです。

以下はセクションタイトルのスタイルの例です:

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

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

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

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

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

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

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

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

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

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

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

上記の例の最初の2つのように、タイトルがアンダーラインとオーバーラインの双方を持つ場合、タイトルテキストの前後に空白を挿入して書けます。これは単に見た目上のもので、深い意味はありません。アンダーラインのみのタイトルテキストの前後に空白を挿入することはできません。

タイトルの後の空白行は省略可能です。次の、同じまたはより高いレベルのタイトルまでの全てのテキストが、セクション(またはサブセクションなど)に含まれます。

全てのセクションタイトルスタイルを使う必要も、どれか特定のセクションタイトルスタイルを使う必要もありません。しかし、文書はセクションタイトルの使い方が一貫している必要があります: 一度タイトルスタイルの階層が確立されたら、セクションはその階層に従う必要があります。

各セクションのタイトルは、自動的にそのセクションを指すハイパーリンクターゲットを生成します。ハイパーリンクターゲットのテキスト("参照名")はセクションのタイトルと同じです。詳しい説明に付いては 暗黙的ハイパーリンクターゲット を参照してください。

セクションは body 要素, トランジション, そして入れ子になったセクションを含めることができます。

トランジション

Doc ツリー要素: transition

小見出しの代わりに、段落の間に余分なスペースや花形を、文章の仕切りや主題や強調の変化を知らせるために使うことができます。

(シカゴマニュアルオブスタイル, 第14版, 1.80節)

トランジションは一般に1行から数行にまたがる、アスタリスクの行などのような花形を伴ったもしくは伴わない空白で、小説や短編作品などに見られます。トランジションは他のbody要素を区切ります。トランジションはセクションや文書の開始または終了すべきものではありませんし、また二つのトランジションが直接隣接すべきでもありません。

トランジションマーカーの構文は、4つまたはそれ以上の句読点文字の繰り返しの水平線です。これはタイトルテキストの無いセクションタイトルのアンダーライン構文と同じです。トランジションマーカーは前と後ろに空白行が必要です:

Para.

----------

Para.

セクションタイトルのアンダーラインと異なり、トランジションマーカーは階層構造を適用しませんし、トランジションマーカーの中で違いを持つこともしません。単一の一貫したスタイルを使用することが推奨されます。

処理システムは、好みの任意の方法でトランジションを出力に描画して構いません。例えばHTML出力での水平罫線(<hr>)は、分かりやすい選択でしょう。

body 要素

段落

Doc ツリー要素: paragraph

段落は、他のbody要素のマークアップを伴わない左揃えのテキストブロックで構成されます。空白行によって段落および他のbody要素と区切ります。段落は インラインマークアップ を含むことができます。

構文ダイアグラム:

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

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

箇条書きリスト

Doc ツリー要素: bullet_list, list_item

空白が後に続く "*", "+", "-", "•", "‣", または "⁃" 始まるテキストブロックは箇条書きリストアイテム(別名、"順不同"リストアイテム)です。リストアイテムの本文は、関連する箇条書きの印に合わせて左揃えでインデントする必要があります; 印の直後のテキストがインデントを決定します。例えば:

- This is the first bullet list item.  The blank line above the
  first list item is required; blank lines between list items
  (such as below this paragraph) are optional.

- This is the first paragraph in the second item in the list.

  This is the second paragraph in the second item in the list.
  The blank line above this paragraph is required.  The left edge
  of this paragraph lines up with the paragraph above, both
  indented relative to the bullet.

  - This is a sublist.  The bullet lines up with the left edge of
    the text blocks above.  A sublist is a new list so requires a
    blank line above and below.

- This is the third item of the main list.

This paragraph is not part of the list.

これは箇条書きリストの 正しくない 例です:

- This first line is fine.
A blank line is required between list items and paragraphs.
(Warning)

- The following line appears to be a new sublist, but it is not:
  - This is a paragraph continuation, not a sublist (since there's
    no blank line).  This line is also incorrectly indented.
  - Warnings may be issued by the implementation.

構文ダイアグラム:

+------+-----------------------+
| "- " | list item             |
+------| (body elements)+      |
       +-----------------------+

列挙リスト

Doc ツリー要素: enumerated_list, list_item

列挙リスト(別名、"順序"リスト)は箇条書きリストと似ていますが、印の代わりに列挙子をつかいます。列挙子は列挙シーケンスメンバーと書式で構成されています。次の列挙シーケンスが認識されます:

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

  • アルファベット大文字: A, B, C, ..., Z

  • アルファベット小文字: a, b, c, ..., z

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

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

さらに、自動列挙子"#"は、自動的にリストを列挙するために使用できます。自動列挙リストは、シーケンスを設定した明示的な列挙から初めることもできます。完全に自動の列挙リストはアラビア数字を使用し、1から始まります。(自動列挙リストはDocutils0.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")とすることを推奨します。他の開始の値も認識はされますが、出力形式によってサポートされない可能性があります。非序数1の列挙子で始まる任意のリストはレベル1 [info] システムメッセージが生成されます。

ローマ数字を使用するリストは、"I"/"i"または"II"や"XV"のようなマルチキャラクターの値で始まることが必要です。その他の任意の単一文字のローマ数字("V", "X", "L", "C", "D", "M")は、ローマ数字ではなくアルファベットの文字として解釈されます。同様に、"I"/"i" はローマ数字の1と認識されるため、アルファベットの文字を使うリストをこれらで始めることは出来ません。

列挙リストの各項目の2行目は、有効性がチェックされます。これは列挙子と全く同じテキストで始まる場合に誤ってリストアイテムとして解釈されることを防ぐためです。例えば、このテキストは通常のパラグラフとして解析されます:

A. Einstein was a really
smart dude.

しかし、段落が1行のみで構成されている場合、曖昧さを回避することが出来ません。このテキストは列挙リストのアイテムと解釈されます:

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 elements: definition_list, definition_list_item, term, classifier, definition.

定義リストの各項目には用語、省略可能な分類詞、および定義が含まれます。用語は1行の単純な単語またはフレーズです。省略可能な分類詞は用語と同じ行に" : "(スペース、コロン、スペース)に続けることが出来ます。定義は用語に関するインデントされたブロックで、複数の段落および他のbody要素を含むことができます。用語の行と定義ブロックの間には空行がありません(これによって定義リストと引用ブロックを区別します)。空白行は最初の定義リスト項目の前と、最後の定義リスト項目の後に必要ですが、間は省略可能です。例えば:

term 1
    Definition 1.

term 2
    Definition 2, paragraph 1.

    Definition 2, paragraph 2.

term 3 : classifier
    Definition 3.

term 4 : classifier one : classifier two
    Definition 4.

用語の行の中で、分類詞の区切り文字より前で解釈されたインラインマークアップは認識されます。区切り文字は任意のインラインマークアップの外に現れた場合のみ認識されます。

定義リストは以下のような例を含め、様々な使い方があります:

  • 辞書や用語集として。用語は単語そのもので、分類詞は用語の使い方(名詞、動詞、など)として使うことができ、後ろに定義が続きます。

  • プログラムの変数の説明。用語は変数名、分類詞は変数の型(文字列型、整数型、など)を示すために使用し、定義はプログラム内ので変数の使い方を説明します。この定義リストの使い方は、Pythonオブジェクトのスキーマを表現、強制するための Grouch の構文をサポートしています。

構文ダイアグラム:

+----------------------------+
| term [ " : " classifier ]* |
+--+-------------------------+--+
   | definition                 |
   | (body elements)+           |
   +----------------------------+

フィールドリスト

Doc ツリー要素: field_list, field, firld_name, field_body

フィールドリストは、ディレクティブのオプションやデータベースような何かしらの処理向けレコードの拡張構文の一部として使用されます。また、データベースのレコードに類似した2カラムのテーブルのような構造体(ラベルとデータのペア)としても使用されます。reStructuredTextアプリケーションはフィールド名を認識し、フィールドまたはフィールド本体を特定のコンテキストに変換することがあります。例については下記の 書誌項目 、 または reStructuredText ディレクティブ の"Image"と"Meta"ディレクティブを参照してください。

Field lists are mappings from field names to field bodies, modeled on RFC822 headers. A field name may consist of any characters, but colons (":") inside of field names must be escaped with a backslash. Inline markup is parsed in field names. Field names are case-insensitive when further processed or transformed. The field name, along with a single colon prefix and suffix, together form the field marker. The field marker is followed by whitespace and the field body. The field body may contain multiple body elements, indented relative to the field marker. The first line after the field name marker determines the indentation of the field body. For example:

:Date: 2001-08-16
:Version: 1
:Authors: - Me
          - Myself
          - I
:Indentation: Since the field marker may be quite long, the second
   and subsequent lines of the field body do not have to line up
   with the first line, but they must be indented relative to the
   field name marker, and they must line up with each other.
:Parameter i: integer

複数の後で構成されたフィールド名の個々の単語の解釈は、アプリケーション次第です。アプリケーションはフィールド名の構文を指定することができます。例えば、2番目以降の単語を"引数"として扱ったり、クォートされたフレーズを一つの引数として扱ったり、"mane=value"という構文をサポートさせることができます。

標準の RFC822 ヘッダは曖昧なため、この構造には使えません。後ろにコロンが付いた単語が、書かれたテキスト行の先頭にあるのが一般的です。しかしフィールドリストが先頭に必ず出現する文書(PEPやメールメッセージ)のように明確に定義されたコンテキストであれば、標準のRFC822ヘッダを使うことができます。

構文ダイアグラム (簡易版):

+--------------------+----------------------+
| ":" field name ":" | field body           |
+-------+------------+                      |
        | (body elements)+                  |
        +-----------------------------------+
書誌項目

Doc ツリー要素: docinfo, author, authors, organization, contact, version, status, date, copyright, field, topic.

フィールドリストが文書内の最初の非コメント要素(文書タイトルの後ろに、もしあれば)である場合、そのフィールドは文書の書誌情報に変換される可能性があります。この書誌情報はタイトルページや著作権ページのような、本の前付けに対応しています。

特定の登録済みフィールド名(下記参照)は、識別されて対応するDOCツリー要素へ変換され、ほとんどが"docinfo"要素の子要素になります。これらのフィールドの順番は必要ありませんが、注釈のとおり文書の構造に合わせて再配置されます。特に以下に記載のない限り、書誌要素のフィールド本体はどれも単一の段落のみを含めることができます。フィールド本体は RCS キーワード をチェックし、整形されます。認識されないフィールドはdocinfo要素内の汎用フィールドとして保持されます。

登録済み書誌フィールド名と対応するdoctree要素は以下のとおりです:

  • フィールド名 "Author": author 要素.

  • "Authors": authors.
  • "Organization": organization.
  • "Contact": contact.
  • "Address": address.
  • "Version": version.
  • "Status": status.
  • "Date": date.
  • "Copyright": copyright.
  • "Dedication": topic.
  • "Abstract": topic.

"Author" フィールドは: ";"や","で区切られた著者のリストで構成された単一の段落; または著者毎にそれぞれ単一の段落を含む箇条書きリストのどちらも含めることができます。";"は最初にチェックされるので、"Doe, Jane; Doe, John"は正しく動作します。いくつかの言語(例えば、スウェーデン語)では、"Author"と"Authors"の間に単数形/複数形の解釈の違いがないため、"Authors"のみが提供され、一人の名前の場合は"Author"と解釈されます。一人の名前にカンマが含まれている場合、明示的にセミコロンで終了します: ":Authors: Doe, Jane;"

"Address"フィールドはメールアドレスの複数行表示用です。改行や空白文字は保持されます。

"Dedication"と"Abstract"フィールドは任意のbody要素を含むことができます。許可されるのはそれぞれ一つだけです。これらはdocinfo要素直後に続く"献辞"または"要約"(もしくはそれと同様の言葉)が付いたトピック要素になります。

このフィールド名と要素名の対応は他の言語に置換できます。詳しいことは DocInfo transform の実装ドキュメントを参照してください。

Unregistered/generic fields may contain one or more paragraphs or arbitrary body elements. The field name is also used as a "classes" attribute value after being converted into a valid identifier form.

RCS キーワード

パーサによって認識される書誌情報フィールドは、通常RCS [3] キーワードかどうかをチェックされ、処理が完了します [4] 。RCSキーワードは"$キーワード$"のようにソースファイルに入力することができ、一度RCSやCVS [5] に保存されるとそれらは"$キーワード: 展開テキスト$"に展開されます。例えば、"ステータス"フィールドは"ステータス"要素に変換されます:

:Status: $keyword: expansion text $
[3]

Revision Control System。

[4]

RCS キーワード処理をOffにすることができます (未実装)。

[5]

Concurrent Versions System。CVSはRCSと同じキーワードを使います。

処理された、"ステータス"要素のテキストは単純に"展開テキスト"になります。ドル記号の区切り文字やRCSキーワード名は削除されます。

RCSキーワードの処理はフィールドリストが書誌コンテキスト(文書内の最初の非コメント構造で、もしタイトルがある場合はその後ろ)内にある場合にのみキックされます。

オプションリスト

Doc ツリー要素: option_list, option_list_item, option_group, option, option_string, option_argument, description.

オプションリストはプログラムのオプションを文書化する、コマンドラインオプションおよび説明文の2カラムのリストです。次に例を示します:

-a         Output all.
-b         Output both (this description is
           quite long).
-c arg     Output just arg.
--long     Output all day long.

-p         This option has two paragraphs in the description.
           This is the first.

           This is the second.  Blank lines may be omitted between
           options (as above) or left in (as here and below).

--very-long-option  A VMS-style option.  Note the adjustment for
                    the required two spaces.

--an-even-longer-option
           The description can also start on the next line.

-2, --two  This option has two variants.

-f FILE, --file=FILE  These two options are synonyms; both have
                      arguments.

/V         A VMS/DOS-style option.

reStructuredTextが認識するオプションにはいくつか種類があります:

  • 短いPOSIXオプションは1つのダッシュとオプション文字で構成されます。

  • 長いPOSIXオプションは2つのダッシュとオプション用語で構成されます; いくつかのシステムでは単一のダッシュを使います。

  • 古いGNUスタイルの "プラス" オプションは一つのプラス記号とオプション文字で構成されます("プラス"オプションは非推奨のため、使用すべきではありません)。

  • DOS/VMSオプションはスラッシュとオプション文字又は用語で構成されます。

DOSやWindowsソフトウェアはPOSIXスタイルとDOS/VMSスタイルの両方を使うことがあります。これらおよびその他のバリエーションが、しばしば混在して使われます。上記の名前は便宜上の都合で選んだものです。

POSIXの短いオプションと長いオプションの構文は、 GNU libc getopt_long() 関数と同様のオプションパーサを実装した、Pythonの getopt.py モジュールによってサポートされている構文に基づいていますが、いくつか制限があります。異なる形のオプションシステムがたくさんあり、reStructuredTextのオプションリストはそれらの全てをサポートはしていません。

長いPOSIXオプションやDOS/VMSのオプション用語は、コマンドラインで使用された際に、オペレーティングシステムやアプリケーションによって切り捨てられることを許可されることがありますが、reStructuredTextのオプションリストでは特別な構文でこれらを表示やサポートしたりしていません。もし該当する場合には、切り捨てに関する注釈でサポートしつつ、完全なオプション名を与えるべきです。

オプションは引数のプレースホルダを持つ場合があり、その役割や構文は説明文のテキストの中で説明されるべきです。スペースまたは等号のいずれかがオプションとオプション引数のプレースホルダの区切り文字として使用されることがあります; 短い形式のオプション("-"や"+"の接頭辞のみ)の場合は区切り文字を省略できます。オプション引数は次のいずれかの形式を取ります:

  • 英字([a-zA-Z])で始まり、続いて英字、数字、アンダースコアおよびハイフン([a-zA-Z0-9_-])で構成される

  • 開き山括弧(<)で始まり、閉じ山括弧(>)で終わる; 括弧内は山括弧を除く任意の文字が許される

一つの説明を共有する複数のオプション"シノニム"を表示することができます。それらはカンマで区切る必要があります。

オプション(複数可)と説明の間には、少なくとも2つのスペースが必要なければなりません。説明には複数のbody要素を含めることができます。オプションマーカの後の最初の行は説明の字下げを決定します。他のタイプのリストと同様に、空行は最初のオプションリストアイテムの前と最後のアイテムの後には必要ですが、オプションエントリの間は省略可能です。

構文ダイアグラム (簡易版):

+----------------------------+-------------+
| option [" " argument] "  " | description |
+-------+--------------------+             |
        | (body elements)+                 |
        +----------------------------------+

リテラルブロック

Doc ツリー要素: literal_block

二つのコロン("::")で構成される段落は、次のテキストブロック(複数可)がリテラルブロックを構成することを示します。リテラルブロックはインデントか引用符を付与(下記参照)のいずれかを必要があります。リテラルブロック内ではマークアップ処理は行われません。それらはそのまま残され、通常は等幅書体で表示されます:

This is a typical paragraph.  An indented literal block follows.

::

    for a in [5,4,3,2,1]:   # this is program code, shown as-is
        print a
    print "it's..."
    # a literal block continues until the indentation ends

This text has returned to the indentation of the first paragraph,
is outside of the literal block, and is therefore treated as an
ordinary paragraph.

"::"のみを含む段落は出力から完全に削除されます; 空の段落は残りません。

利便性のため、"::"は任意の段落の末尾で認識されます。直前に空白がある場合、両方のコロンが出力から削除されます(これは"部分最小化"の形式です)。"::"の直前にテキストがある場合、一つのコロンは出力から削除されてコロンが一つだけ残ります(つまり、"::"は":"に置き換えられます。これは"完全最小化"の形式です)。

言い換えれば、これらは全て等価です("段落"の後のコロンに注意してください):

  1. 展開された形式:

    Paragraph:
    
    ::
    
        Literal block
    
  2. 部分最小化した形式:

    Paragraph: ::
    
        Literal block
    
  3. 完全最小化した形式:

    Paragraph::
    
        Literal block
    

全ての空白(改行を含みますが、インデントリテラルブロックのための最低限のインデントは除きます)は保持されます。空行はリテラルブロックの前後に必要ですが、これらの空行はリテラルブロックには含まれません。

インデントリテラルブロック

インデントリテラルブロックは周囲のテキストに対する相対インデント(各行の先頭にある空白)によって示されます。最小のインデントはインデントリテラルブロックの各行から削除されます。リテラルブロックは隣接している必要はありません; インデントされたテキスト内のセクションの間に空行を入れるができます。リテラルブロックはインデントの終わりで終了します。

構文ダイアグラム:

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

クォートリテラルブロックはそれぞれの行が同じ英数字以外の印刷可能な7-bit ASCII文字 [6] から始まる、インデントされていない隣接したテキストのブロックです。空行はクォートリテラルブロックを終了します。引用文字は処理された文書に保存されます。

[6]

有効なクォート文字は以下のとおりです:

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

これらはセクションタイトルの修飾に有効な文字と同じであることに注意してください。

用途としては、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 |
+------------------------------+

行ブロック

Doc ツリー要素: 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     |
       +-----------------------+

引用ブロック

Doc ツリー要素: block_quote, attribution

リテラルブロックやその他のコンテンツであることを示すマークアップが前に無く、先行するテキストに対してインデントしたテキストブロックは、引用ブロックです。全てのマークアップ処理(body要素やインラインマークアップ)は引用ブロックの中で継続されます:

This is an ordinary paragraph, introducing a block quote.

    "It is my business to know things.  That is my trade."

    -- Sherlock Holmes

引用ブロックはアトリビューション("--"、"---"または本当のEMダッシュで始まり、引用ブロック内で左揃えのテキストブロック)で終わる場合があります。アトリビューションが複数行で構成されている場合は、2行目以降の行の左端は揃える必要があります。

アトリビューションで終了した場合、複数の引用ブロックを生成することができます。

インデントしていない段落。

引用ブロック 1。

—Attribution 1

引用ブロック 2。

空のコメント は先行する構成要素を引用ブロックに含まないようにするために、明示的に終了させるために利用できます:

* List item.

..

    Block quote 3.

空のコメントは引用ブロックを分けるのにも利用できます:

    Block quote 4.

..

    Block quote 5.

空行は引用ブロックの前後に必要ですが、これらの空行は引用ブロックには含まれません。

構文ダイアグラム:

+------------------------------+
| (current level of            |
| indentation)                 |
+------------------------------+
   +---------------------------+
   | block quote               |
   | (body elements)+          |
   |                           |
   | -- attribution text       |
   |    (optional)             |
   +---------------------------+

Doctest ブロック

Doc ツリー要素: doctest_block

Doctestブロックはdocstringsの中にカットアンドペーストされた、対話型Pythonセッションです。これらは例によって使用方法を示し、Python標準ライブラリの doctest モジュール を経由してエレガントかつパワフルなテスト環境を提供することを目的としています。

DoctestブロックはPython対話型インタプリタのプロンプト ">>> " で始まり、空行で終了します。Doctestブロックはリテラルブロックの特殊なケースとして扱われ、リテラルブロックの構文は不要です。両方とも存在する場合は、リテラルブロックの構文がDoctestブロック構文よりも優先されます:

This is an ordinary paragraph.

>>> print 'this is a Doctest block'
this is a Doctest block

The following is a literal block::

    >>> This is not recognized as a doctest block by
    reStructuredText.  It *will* be recognized by the doctest
    module, though!

doctestブロックは、インデントは必要ではありません。

テーブル

Doc ツリー要素: table, tgroup, colspec, thead, tbody, row, entry

ReStructuredTextはテーブルセルの輪郭を描くための二つの構文: グリッドテーブルシンプルテーブル を提供しています。

他のbody要素と同様に、空行がテーブルの前後に必要です。テーブルの左端は前のテキストブロックの左端と揃えておく必要があります; インデントされている場合、テーブルは引用ブロックの一部とみなされます。

一度分離されると、それぞれのテーブルセルは文書のミニチュアのように扱われます; セルの上下の境界線は、区切り用の空行のように機能します。それぞれのセルには0個以上のbody要素が含まれます。セルの内容は左右にマージンを含めてもよく、それらは処理前に削除されます。

グリッドテーブル

グリッドテーブルはグリッドのような"ASCIIアート"を使って完全なテーブル表現を提供します。グリッドテーブルは任意のセル内容(body要素)、および行と列の跨がりが許可します。しかしグリッドテーブルは、特に簡単なデータセットに対しては生成するための手順が煩雑になり得ます。Emacsのtable modeは、Emacsでの表の編集を簡単にしてくれるツールです。より簡単な(しかし制限のある)表現には シンプルテーブル を参照してください。

グリッドテーブルは"-"、"="、"|"、そして"+"の文字で構成された、視覚的なグリッドで描かれています。ハイフン("-")は水平線(行の区切り)に使用されます。等号("=")はオプションのヘッダ行をテーブル本体と区切るために使用されます(Emacs table mode ではサポートされていません)。縦棒("|")は垂直線(列の区切り)に使用されます。プラス記号("+")は水平線と垂直線の交点に使用されます。例えば:

+------------------------+------------+----------+----------+
| 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.    |
+------------------------+------------+---------------------+

ごくまれな、セルのテキストとの望ましくない相互作用を避けるために、グリッドテーブルに注意擦る必要があります。例えば次のテーブルの行2には列2から列4に跨るセルがあります:

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        |                                  |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

もしそのセルのテキストで縦棒が使われる場合、誤って列の区切りと位置が揃った場合に意図しない影響を及ぼす可能性があります:

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        | Use the command ``ls | more``.   |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

いくつかの解決策があります。必要なのは、セルの枠の矩形が繋がった状態を断つことです。やり方の一つは、前に余分なスペースを追加してテキストを変えることです:

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        |  Use the command ``ls | more``.  |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

もう一つの方法は、行2に余分な行を追加することです:

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        | Use the command ``ls | more``.   |
|              |                                  |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+
シンプルテーブル

シンプルテーブルは単純なデータセットのために、コンパクト且つ入力しやすいが、制限された行指向のテーブル表現を提供します。殆どのセルで任意のbody要素を表現できるものの、セルの内容は通常ひとつの段落です。シンプルテーブルでは複数行を含む(1列目を除いた全ての)行と列の跨がりを許可し、行の跨がりは許可しません。完全なテーブル表現については上述の グリッドテーブル を参照してください。

シンプルテーブルは"-"と"="の文字で構成された水平線で描かれます。等号("=")はテーブルの上部と下部の境界線、およびオプションのヘッダ行をテーブル本体と区切るために使用されます。ハイフン("-")は結合される列に下線を付けることによって一つの行で列の跨がりを示すためや、オプションで明示的・視覚的に行を区切るために使うことができます。

シンプルテーブルは各列の境界に一つ以上のスペース(2つ以上のスペースを推奨)を持つ、等号の上部境界線から始まります。跨がりに関係なく、上部の境界線は全てのテーブル列を完全に記述する必要があります。テーブル内には少なくとも2つの列がなければなりません(セクションヘッダと区別するため)。上部の境界線はヘッダ行が続く場合があり、オプションのヘッダ行の後に、再び列の境界にスペースのある'='で下線が引かれます。ヘッダ行の区切り線の下は空行にできません; これはテーブルの下部境界線と解釈されます。テーブルの下部の境界線も、列の境界にスペースのある'='の下線で構成されます。例えば、これは一つのヘッダ行と四つの行を持つ三列の真理値のテーブルです:

=====  =====  =======
  A      B    A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

'-'の下線は、隣接する列を繋ぐ列の余白を"埋める"ことによって、列の跨がりを示すために使用されます。列跨ぎの下線は完全(全ての列をカバーする必要があります)かつ出来上がった列の区切りと合わせる必要があります。列跨ぎの下線を含むテキスト行は他のテキストを含めることはできません。列跨ぎの下線は直前の1行にのみ適用されます。これはヘッダ内の列跨ぎの例です:

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

テキストの各行はセルが列を跨いで結合している場合を除いて、列の境界にスペースを含む必要があります。テキストの各行は新しい行を開始しますが、最初の列に空のセルがある場合を除きます。その場合、その行のテキストは継続行として解釈されます。このため新しい行(継続行ではない)の最初の列のセルには何かのテキストを含む必要があります; 空のセルは誤った解釈を招きます(ですが、下記のTipsを参照してください)。またこのメカニズムは、最初の列のセルを1行のテキストのみに制限します。この制限が許容されない場合はグリッドテーブルを使用してください。

ちなみに

シンプルテーブルで、最初の列にテキストを出力されずに新しい行を開始するためには、これらのうちいずれかを使います:

  • 処理された出力から省略できる、空のコメント("..") (後述のコメントを参照してください)

  • 後ろにスペースを続けたバックスラッシュ("\") (上述のエスケープの仕組みを参照してください)

'-'の下線は、列跨ぎがない場合でも視覚的に行を分けるために使うこともできます。これは特に、行が数行分の長さのある長いテーブルに有効です。

空行はシンプルテーブル内では許可されます。それらの解釈は文脈に依存します。行のの空行は無視されます。複数行で構成される行の間の空行は、セル内の段落または他のbody要素を区切ることができます。

右端の列は区切りがなく、テキストは(テーブルの境界線によって示される)テーブルの端を超えて継続することができます。しかし、境界線はテキスト全体を含めるのに十分長くしておくことをお勧めします。

次の例は、継続する行(行2は2行のテキストで、行3は4行で構成されている)、空行が区切る段落(行3、列2)、テーブルの右端を超えて延びるテキスト、処理された出力の最初の列が空の新しい行(行4)を示しています:

=====  =====
col 1  col 2
=====  =====
1      Second column of row 1.
2      Second column of row 2.
       Second line of paragraph.
3      - Second column of row 3.

       - Second item in bullet
         list (row 3, column 2).
\      Row 4; column 1 will be empty.
=====  =====

明示的マークアップブロック

明示的マークアップは以下のようなテキストブロックです:

  • 最初の行が空白の続く".."(明示的マークアップの開始)で始まり、

  • 2行目またはそれ以降の行(もしあれば)が1行目に対してインデントされていて、

  • インデントされていない行までで終わる

明示的マークアップブロックは、".."を印とした箇条書きリストに似ています。明示的マークアップ開始行の直後のテキストが、ブロック本体のインデントを決定します。 共通する最大のインデント幅は常にブロック本体である2行目とそれ以降の行から取り除かれます。そのため、もし最初の構文が1行に収まり、且つ1つめと二つ目の構文のインデントが異なる必要がある場合、1つめの構文は明示的マークアップの開始と同じ行から始めるべきではありません。

空行は明示的マークアップブロックと他の要素の間に必要ですが、明示的マークアップブロックが明白なところでは省略可能です。

明示的マークアップの構文は、脚注、引用、ハイパーリンクターゲット、ディレクティブ、置換定義、そしてコメントに使用されます。

脚注

See also: `Footnote References`_.

Doctree elements: footnote, label.

Configuration settings: footnote_references.

それぞれの脚注は、明示的マークアップの開始(".. ")と、左角括弧、脚注ラベル、右角括弧で構成され、スペース、インデントされたbody要素が続きます。脚注ラベルは:

脚注の内容(body要素)は、一貫して(少なくとも3スペースでの)インデントと左揃えされている必要があります。脚注内の最初のbody要素は、しばしば脚注ラベルと同じ行から開始します。しかし、最初の要素が1行に収まり、且つ残りの要素のインデントが異なる場合、最初の要素は脚注ラベル行の次の行から始めなければなりません。 そうでない場合、インデントの違いは検知されません。

脚注は文書の最後だけでなく、任意の場所に入れることができます。処理された出力がどこにどのように現れるかは処理系に依存します。

これは手動ナンバー型の脚注です:

.. [1] Body elements go here.

それぞれの脚注は自動的にそれ自身へのハイパーリンクターゲットを生成します。 ハイパーリンクターゲット名のテキストは、脚注ラベルのそれと同じです。 オートナンバー型脚注は脚注ラベルおよび参照名となる番号を生成します。 メカニズムの詳しい説明については暗黙的ハイパーリンクターゲットを参照してください。

構文ダイアグラム:

+-------+-------------------------+
| ".. " | "[" label "]" footnote  |
+-------+                         |
        | (body elements)+        |
        +-------------------------+
オートナンバー型脚注

ナンバー記号("#")は、脚注や脚注参照のオートナンバリングを要求するために、脚注ラベルの最初の文字として使用します。

オートナンバリング要求をした最初の脚注はラベル"1"が割り当てられ、2番目は ラベル"2"が割り当てられ、のようになります(手動ナンバリング脚注が存在しないと仮定します;手動とオートナンバー型脚注の混在は下記を参照してください)。 自動的にラベル"1"を付与された脚注は、ラベルが明示的に指定された場合と同様に、"1"という名前の暗黙的ハイパーリンクターゲットを生成します。

オートナンバリングを使いながら明示的にラベルを指定する事ができます: [#label] このラベルはオートナンバー型ラベルと呼ばれます。オートナンバ型ラベルは2つのことをします:

  • 脚注自体に対し、名前がオートナンバー型ラベル("#"は含まない)のハイパーリンクターゲットを生成します。

  • それらは、オートナンバリング脚注を脚注参照やハイパーリンク参照として複数回の参照ができるようにします。次に例を示します:

    If [#note]_ is the first footnote reference, it will show up as
    "[1]".  We can refer to it again as [#note]_ and again see
    "[1]".  We can also refer to it as note_ (an ordinary internal
    hyperlink reference).
    
    .. [#note] This is the footnote labeled "note".
    

番号付けは参照の順番ではなく、脚注の順序によって決まります。オートナンバーラベル([#]_)の無い脚注参照のため、脚注や脚注参照はお互いに同じ順序になっている必要がありますが、番号付け固定で代替する必要はありません。次に例を示します:

[#]_ is a reference to footnote 1, and [#]_ is a reference to
footnote 2.

.. [#] This is footnote 1.
.. [#] This is footnote 2.
.. [#] This is footnote 3.

[#]_ is a reference to footnote 3.

脚注がオートナンバー型の脚注参照を含む場合や、複数の参照が近接して作成されている場合には特別に注意をしなければなりません。脚注や参照はドキュメントの中に出現した順に記載されており、人がそれらを読む順番と同じである必要性はありません。

オートシンボル脚注

アスタリスク("*")は脚注と脚注参照に自動的にシンボルを付与する要求をするために、脚注のラベルに仕様されることがあります。ラベルにはアスタリスクのみである場合もあります。次に例を示します:

Here is a symbolic footnote reference: [*]_.

.. [*] This is the footnote.

変換では対応する脚注と脚注参照にラベルとしてシンボルを挿入します。参照の数は脚注の数と同じである必要があります。一つのシンボル付き脚注は複数の参照を持つことはできません。

標準のDocutilsシステムは以下のシンボルを脚注のマークとして使います [7]:

  • アスタリスク/スター("*")

  • ダガー(HTML文字参照 "&dagger;"、Unicode U+02020)

  • ダブルダガー("&Dagger;"/U+02021)

  • セクション記号("&sect;"/U+000A7)

  • 段落記号("&para;"/U+000B6)

  • ナンバー記号("#")

  • スペード組("&spades;"/U+02660)

  • ハート組("&hearts;"/U+02665)

  • ダイヤ組("&diams;"/U+02666)

  • クラブ組("&clubs;"/U+02663)

[7]

このリストはシカゴマニュアルオブスタイル, 第14版, 12.51節の中の"注記参照記号"のためのシンボル一覧にインスパイアされました。シカゴマニュアルオブスタイルでは"並行バー"("||")が段落記号の代わりに与えられています。最後の4つのシンボル(トランプの組)は、任意で追加しました。

10個以上のシンボルが必要な場合、同じ順番で2つずつ、3つずつ("**"など)というように再利用されます。

注釈

オートシンボル脚注を使う場合、出力エンコードの選択が重要です。使用される多くのシンボルは、Latin-1(ISO 8859-1)のような一般的なテキストエンコーディングではエンコードできません。出力エンコーディングにはUTF-8の使用が推奨されています。HTMLやXMLへの出力には、代わりに出力エンコーディングエラーハンドラ"xmlcharrefreplace" を使います。

手動とオートナンバー型脚注の混在

一つのドキュメントの中で手動と自動の脚注ナンバリングを一緒に使うことはできますが、意図した結果にはならないでしょう。手動ナンバリングの方が優先されます。使われていない番号だけが、オートナンバー脚注に割り当てられます。次の例はその実例になるでしょう:

[2]_ will be "2" (manually numbered),
[#]_ will be "3" (anonymous auto-numbered), and
[#label]_ will be "1" (labeled auto-numbered).

.. [2] This footnote is labeled manually, so its number is fixed.

.. [#label] This autonumber-labeled footnote will be labeled "1".
   It is the first auto-numbered footnote and no other footnote
   with label "1" exists.  The order of the footnotes is used to
   determine numbering, not the order of the footnote references.

.. [#] This footnote will be labeled "3".  It is the second
   auto-numbered footnote, but footnote label "2" is already used.
引用

See also: `Citation References`_.

Doctree element: citation

引用は、唯一 [note][GVR2001] のような非数値ラベルを使用することを除けば脚注と同じです。引用ラベルは、単純な 参照名 (半角英数字および語中に含まれるハイフン、アンダースコア、ピリオドで構成された大文字・小文字を区別しない単語; 空白は含まない)です。引用は脚注とは別に分けてレンダリングされます。次に例を示します。

Here is a citation reference: [CIT2002]_.

.. [CIT2002] This is the citation.  It's just like a footnote,
   except the label is textual.
ディレクティブ

Doc ツリー要素: depend on the directive

ディレクティブは reStructuredText のための拡張機構で、新たに基本的な構文を追加せずに (ディレクティブはローカルに追加の構文をサポートしてもよい)、新しい構造のサポートを追加する方法です。標準のディレクティブ (参照実装の reStructuredText パーサに実装、登録されている) はすべてreStructuredText ディレクティブのドキュメントに記述されていて、いつでも使うことができます。それ以外のディレクティブはドメイン固有のものであり、ドキュメントを処理する際に特別なアクションを使えるようにする必要があります。

例えば、これは画像に置換されます:

.. image:: mylogo.jpeg

図形 (キャプション付きの画像) の置換はこのようにします:

.. figure:: larch.png

   The larch.

勧告 (覚え書き、警告、など) は他の body 要素を含みます:

.. note:: This is a paragraph

   - Here is a bullet list.

ディレクティブは、ディレクティブタイプ、2つのコロン、そして空白が連なる明示的マークアップの開始 ("..") によって示されます (以下、総称して"ディレクティブマーカー" と呼びます) 。ディレクティブのタイプは、大文字と小文字を区別しない単一の語 (英数字およびハイフン、アンダースコア、プラス記号、コロンそしてピリオドです; 空白は含みません) です。2つのコロンは、以下の理由でディレクティブの後ろに使われます:

  • ディレクティブは、ディレクティブタイプ、2つのコロン、そして空白が連なる明示的マークアップの開始 ("..") によって示されます (以下、総称して"ディレクティブマーカー" と呼びます) 。ディレクティブのタイプは、大文字と小文字を区別しない単一の語 (英数字およびハイフン、アンダースコア、プラス記号、コロンそしてピリオドです; 空白は含みません) です。2つのコロンは、以下の理由でディレクティブの後ろに使われます:

  • 2つのコロンはこのような普通のテキスト・コメントとの衝突を避けることができる:

    .. Danger: modify at your own risk!
    
  • reStructuredText の実装がディレクティブを認識しない場合 (すなわち、directive-handler がインストールされていない) 、レベル3 (エラー) のシステムメッセージを生成し、ディレクティブブロック全体は (ディレクティブ自身を含みます) リテラルブロックとして含まれます。 したがって、"::" は自然な選択です。

ディレクティブブロックは、ディレクリブマーカーの後ろの何らかのテキストとそれ以降の何らかのインデントされたテキストで構成されます。ディレクティブブロックの解釈はディレクティブのコード次第です。ディレクティブブロックには3つの論理的パートが存在します。

  1. ディレクティブ引数

  2. ディレクティブオプション

  3. ディレクティブコンテンツ

個々のディレクティブはこれらのパートの任意の組み合わせを採用できます。ディレクティブの引数には、ファイルシステムパス、URL、タイトルテキスト等があります。ディレクティブオプションはフィールドリストを使って示します; フィールド名と内容はディレクティブに固有のものです。引数とオプションは、ディレクティブの最初の行または次の行から始まる隣接したブロックを形成しなければなりません; 空白行はディレクティブのコンテンツブロックの始まりを示します。引数および/またはオプションがディレクティブに採用されている場合、空白行がそれらとディレクティブのコンテンツを分離しなければなりません。"figure" ディレクティブはこれら3つのパートを採用しています:

.. figure:: larch.png
   :scale: 50

   The larch.

単純なディレクティブは、任意のコンテンツを必要としないこともあります。コンテンツブロックを採用していないディレクティブは、何かしらインデントされたテキストが続いている場合、エラーになります。引用ブロックをディレクティブの直後に続けて書く場合は、あいだに空のコメントを使います (下記のコメントを参照してください) 。

ディレクティブに応じて取られるアクションと、ディレクティブのコンテンツブロックやそれに続くテキストブロックの解釈はディレクティブに依存します。詳細についてはreStructuredText ディレクティブを参照してください。

ディレクティブは、それぞれのコンテンツに任意の処理を行うことを意図しており、元のテキストとは関係しない可能性が高いものに変換することが可能です。また、ディレクティブをプラグマとして使ったり、他の構文を試すためなどのようにパーサの振る舞いを変更するために使うこともできます。現時点でこの機能はパーサにサポートされていませんが、プラグマディレクティブに関する合理的な必要性が認められた場合には、サポートされるかも知れません。

ディレクティブは "directive" 要素を生成しません; パーサのみを構成し 、reStructuredText の外部に対して本質的には意味を持ちません。かわりにパーサは認識したディレクティブを (できる限り専用の) ドキュメント要素に変換します。未知のディレクティブはレベル3 (エラー) システムメッセージの要因になります。

構文ダイアグラム:

+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block                         |
        |                               |
        +-------------------------------+
置換定義

Doc ツリー要素: substitution_definition

置換定義は、垂直バーの続く明示的マークアップの開始 (".. ")、置換テキスト、もう一つの垂直バー、空白、そして定義ブロックで示されます。置換テキストの前後に空白は含められません。置換定義ブロックは "image" や"replace" のような埋込みのインライン互換ディレクティブを含みます。例えば:

The |biohazard| symbol must be used on containers used to
dispose of medical waste.

.. |biohazard| image:: biohazard.png

置換定義ブロックに直接的または間接的に置換参照の循環を含めると、エラーになります。

置換参照 は (マッチする置換テキストによってリンクされ) 対応する定義の加工されたコンテンツによって、インラインで置換されます。マッチは大文字と小文字を区別しますが、寛容で、マッチするものが見つからない場合は、大文字と小文字を区別しないマッチを試みます。

置換定義はブロックレベルディレクティブパワーと柔軟性が、インラインテキストによって共有することを可能にします。これはテキストの流れに詳細を含めずに、テキスト内に任意の複雑なインライン構造を含める方法で、SGML/XMLの名前付きエンティティやプログラミング言語のマクロに相当します。

置換メカニズムがなければ、誰かがアプリケーション固有の新しいインライン構造を必要とする度に、彼らは構文の変更を申請しなければならないでしょう。既存のディレクティブと組み合わせることで、任意のインライン構造を、 (おそらく新しいディレクティブを除いては) 新しい構文を必要とせずに書くことができます。

構文ダイアグラム:

+-------+-----------------------------------------------------+
| ".. " | "|" substitution text "| " directive type "::" data |
+-------+ directive block                                     |
        |                                                     |
        +-----------------------------------------------------+

以下は、置換メカニズムのユースケースのいくつかです。例示されているディレクティブのほとんどは単なる例であり、実装はされていないことに注意してください。

オブジェクト

置換参照はユニークなオブジェクト識別子で、曖昧なテキストと関連付けるために使えます。

例えば、多くの現場ではインラインの "user" ディレクティブの実装を望んでいるかも知れません:

|Michael| and |Jon| are our widget-wranglers.

.. |Michael| user:: mjones
.. |Jon|     user:: jhl

現場のニーズに応じて、これは後に検索するためにインデックスしたり、さまざまな方法 (mailto、ホームページ、プロフィールや連絡先情報のついたマウスオーバーのJavascript等) でハイパーリンクしたり、テキストの表現の加工 (インラインテキストにユーザ名を含める、テキストの横にリンク付きのアイコン画像を含める、テキストを太字や異なる色に変える等) をしたりできます。

同様のアプローチは、ユニークな識別子を持つものの、あいまいな一般名を持つオブジェクトの特定のタイプをドキュメントの中で頻繁に参照するのに使えます。 映画、アルバム、書籍、写真、判例、そして法令などがそうです。例えば:

|The Transparent Society| offers a fascinating alternate view
on privacy issues.

.. |The Transparent Society| book:: isbn=0738201448

文脈の中で、モジュールやクラス名が不明および/または解釈済みテキストが使えないような場合、クラスや関数などはもう一つの候補です:

4XSLT has the convenience method |runString|, so you don't
have to mess with DOM objects if all you want is the
transformed output.

.. |runString| function:: module=xml.xslt class=Processor
画像

画像は置換参照で一般的に使われます:

West led the |H| 3, covered by dummy's |H| Q, East's |H| K,
and trumped in hand with the |S| 2.

.. |H| image:: /images/heart.png
   :height: 11
   :width: 11
.. |S| image:: /images/spade.png
   :height: 11
   :width: 11

* |Red light| means stop.
* |Green light| means go.
* |Yellow light| means go really fast.

.. |Red light|    image:: red_light.png
.. |Green light|  image:: green_light.png
.. |Yellow light| image:: yellow_light.png

|-><-| is the official symbol of POEE_.

.. |-><-| image:: discord.png
.. _POEE: http://www.poee.org/

"画像" ディレクティブは、元から組み込まれています。

スタイル [9]

置換参照は外部に定義された表示スタイルをインラインテキストに関連付けることができます:

Even |the text in Texas| is big.

.. |the text in Texas| style:: big

スタイル名は、ある任意の出力形式の文脈で意味のある名前 (HTML 出力におけるCSS クラス名、LaTeX における LaTeX スタイルなど) で、他の出力形式 (プレーンテキストなど) では無視されます。

[9]

解釈済みテキスト構文の拡張のような、よりシンプルな構文を保証するための "スタイル" のメカニズムには十分な需要があるでしょう。 置換メカニズムは、単純なテキストのスタイリングをするには煩雑です。

テンプレート

インラインマークアップはテンプレートエンジンによる後処理のために使えます。例えば、 Zope 著者は次のように書けます:

Welcome back, |name|!

.. |name| tal:: replace user/getUserName

処理後、このZPT出力はこのような結果になります:

Welcome back,
<span tal:replace="user/getUserName">name</span>!

その後Zopeは実際のユーザとのセッション中、これを"Welcome back, David!"のように変換するでしょう。

置換テキスト

置換メカニズムはシンプルなマクロ置換として使えます。これは置換テキストが一つ以上のドキュメント全体で何度も繰り返されていて、後々変更する可能性がある場合には特に適切でしょう。簡単な例では不自然さを避けられません:

|RST|_ is a little annoying to type over and over, especially
when writing about |RST| itself, and spelling out the
bicapitalized word |RST| every time isn't really necessary for
|RST| source readability.

.. |RST| replace:: reStructuredText
.. _RST: http://docutils.sourceforge.net/rst.html

最初の、アンダースコアが後ろについている置換参照の利用に注意してください。これは対応するハイパーリンクターゲットの参照を示します。

置換は、置換テキストが他のインライン構文を使って表現できない場合や目立つほど長い場合にも適切です:

But still, that's nothing compared to a name like
|j2ee-cas|__.

.. |j2ee-cas| replace::
   the Java `TM`:super: 2 Platform, Enterprise Edition Client
   Access Services
__ http://developer.java.sun.com/developer/earlyAccess/
   j2eecas/

"replace" ディレクティブは実装されています。

コメント

Doctree 要素: コメント

明示的なマークアップ開始に続く任意のインデントがされたテキストはコメント要素をとして処理されます。コメントブロックのテキストにはそれ以上の処理はされません; コメントは単一の"テキストblog"を含みます。出力フォーマッタによっては、コメントは処理された出力から削除されることがあります。コメントの唯一の制約は、他の明示的マークアップ構文: 置換定義、ディレクティブ、脚注、引用およびハイパーリンクターゲットのいずれとも同じ構文を使わないことです。他の明示的マークアップ構文のいずれにも認識されないようにするには、行に".."だけを残します。

.. This is a comment
..
   _so: is this!
..
   [and] this!
..
   this:: too!
..
   |even| this:: !

明示的マークアップ開始の後に何もない(空白を除く)か空行にすると、"空のコメント (empty comment)"です。これは先行する構文を終了するためのもので、後続のテキストはインデント しません 。後ろにリストやなにかしらのインデントした構文を続けた引用ブロックを書くには、間にインデントしていない空コメントを挿入します。

構文ダイアグラム:

+-------+----------------------+
| ".. " | comment              |
+-------+ block                |
        |                      |
        +----------------------+

インラインマークアップ

In reStructuredText, inline markup applies to words or phrases within a text block. The same whitespace and punctuation that serves to delimit words in written text is used to delimit the inline markup syntax constructs (see the `inline markup recognition rules`_ for details). The text within inline markup may not begin or end with whitespace. Arbitrary `character-level inline markup`_ is supported although not encouraged. Inline markup cannot be nested.

インラインマークアップは9つの構文があります。構文のうち5つは、マークアップを示すために同じ開始文字列と終了文字列を用います:

構文のうちの3つは異なる開始文字列と終了文字列を用います。

独立ハイパーリンク は暗黙的に認識されるので、それ以上のマークアップは用いません。

インラインマークアップ認識ルール

インラインマークアップの開始文字列および終了文字列は、次のすべての条件が満たされている時に認識されます:

  1. インラインマークアップ開始文字列はテキストブロックを開始するか、直前が次のいずれかでなければならない

    • 空白、

    • one of the ASCII characters - : / ' " < ( [ {, or
    • a punctuation character with Unicode category Pd (Dash), Po (Other), Pi (Initial quote), Pf (Final quote), or Ps (Open).
  2. インラインマークアップ開始文字列は、直後に空白以外の文字がなければならない

  3. インラインマークアップ終了文字列は、直前に空白以外の文字がなけれなならない

  4. インラインマークアップ終了文字列はテキストブロックを終了するか、直後が次のいずれかでなければならない

    • 空白、

    • one of the ASCII characters - . , : ; ! ? \ / ' " ) ] } >, or
    • a punctuation character with Unicode category Pd (Dash), Po (Other), Pi (Initial quote), Pf (Final quote), or Pe (Close).
  5. If an inline markup start-string is immediately preceded by one of the ASCII characters ' " < ( [ { or a character with Unicode character category Ps, Pi, or Pf, it must not be followed by the corresponding closing character from ' " ) ] } > or the categories Pe, Pf, or Pi. (For quotes, corresponding characters can be any of the quotation marks in international usage.)
  6. インラインマークアップ終了文字列は、開始文字列から少なくとも1文字以上離さなければならない

  7. 開始文字列や終了文字列直前のエスケープしていないバックスラッシュは、 インラインリテラル の終了文字を除いてマークアップの認識を無効にする。前述の エスケープの仕組み を参照のこと

インラインマークアップの認識ルールは"*"、"`"、"_"および"|"のマークアップではない使い方の90%を、エスケープせずにできるようにするために考案されました。例えば、次の用語はいずれもインラインマークアップを含むものとして認識はされません:

  • 2*x a**b O(N**2) e**(x*y) f(x)*f(y) a|b file*.* (breaks 1)
  • 2 * x a ** b (* BOM32_* ` `` _ __ | (breaks 2)
  • "*" '|' (*) [*] {*} <*> ‘*’ ‚*‘ ‘*‚ ’*’ ‚*’ “*” „*“ “*„ ”*” „*” »*« ›*‹ «*» »*» ›*› (breaks 5)
  • || (breaks 6)
  • __init__ __init__()

次のインラインマークアップの例ではエスケープは不要です:

  • 2 * x *a **b *.txt (breaks 3)
  • 2*x a**b O(N**2) e**(x*y) f(x)*f(y) a*(1+2) (breaks 4)

特にコードスニペットを表す場合などは、とにかくこれらのように インラインリテラル を使うことが望ましい場合があります。判断はみなさんにおまかせします。

これらのケースでは、誤解を避けるためにリテラル引用またはエスケープが必要です:

*4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt

ほとんどのユースケースでは、 インラインリテラルリテラルブロック が最良の選択です(デフォルトでは、これは等幅フォントも選択します):

*4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt

認識順序

インラインマークアップの区切り文字は複数の構文に使われるので、あいまいさを回避するためそれぞれの文字には固有の認識順序が必要です。インラインマークアップの認識順序は次のとおりです:

文字レベルのインラインマークアップ

単語の中の個々の文字を、バックスラッシュエスケープでマークアップできます(前述の エスケープの仕組み を参照)。バックスラッシュエスケープは任意のテキストをインラインマークアップの直後に続けることができます:

Python ``list``\s use square bracket syntax.

バックスラッシュは処理されたドキュメントには現れません。単語"list"はインラインリテラルのテキストとして、文字"s"はその直後に通常の文字として表示され、間にスペースはありません。

任意のテキストはバックスラッシュエスケープされた空白を使って、インラインマークアップの直前に付けることもできます。

Possible in *re*\ ``Structured``\ *Text*, though not encouraged.

処理されたドキュメントには、"re"、"Structured"、"Text"を区切っているバックスラッシュと空白は現れません。

ご用心

文字レベルのインラインマークアップのためのバックスラッシュエスケープは推奨されません。そのような使い方は醜く、処理前のドキュメントの可読性を下げます。この機能は控えめに、本当に必要な場合にだけ使ってください。

強調

Doctree 要素: emphasis

開始文字列 = 終了文字列 = "*"

1つのアスタリスク文字で囲まれたテキストは強調されます。

This is *emphasized text*.

強調されたテキストは通常、斜体で表示されます。

強い強調

Doctree 要素: strong

開始文字列 = 終了文字列 = "**"

2つのアスタリクス文字で囲まれたテキストは強く強調されます。

This is **strong text**.

強く強調されたテキストは通常、太字で表示されます。

解釈済みテキスト

Doctree 要素: 明示的または暗黙的なロールや処理に依存する

開始文字列 = 終了文字列 = "`"

解釈済みテキストは、関連付け、索引付け、リンク、サマリまたはその他の処理をされているテキストですが、テキストそのものは通常、そのまま残されています。解釈済みテキストはバッククオート文字1つで囲まれます:

This is `interpreted text`.

解釈済みテキストの"ロール"は、テキストがどのように解釈されたかによります。ロールは暗黙的に推測されてもよい(上記では"デフォルトロール"が使われている)ですし、ロールマーカを使って明示的に示すこともできます。ロールマーカはコロン、ロール名、もう一つのコロンで構成されます。ロール名は英数字と内部に独立したハイフン、アンダースコア、プラス記号、コロン、ピリオドで構成されます; 空白や他の文字は使えません。ロールマーカは解釈済みテキストの前後どちらか読みやすい方に付けます; どちらにするかは作者次第です。

:role:`interpreted text`

`interpreted text`:role:

解釈済みテキストは、利用可能なインライン記述的マークアップ構文の拡張ができます。 強調強い強調インラインリテラルハイパーリンク参照 に対して、"title reference"、"index entry"、"acronym"、"class"、"red"、"blinking"、あるいは私達が望むものをなんでも追加できます。予め決まったロールだけが認識され、未知のロールはエラーを生成します。標準ロールのコアセットは、基準となるパーサに実装されています; 個別の説明については reStructuredTextの解釈済みテキストロール を参照してください。さらに、アプリケーションは特殊なロールのサポートもできます。

インラインリテラル

Doctree 要素: literal

開始文字列 = 終了文字列 = "``"

バッククオート2つでか囲まれたテキストは、インラインリテラルとして扱われます。

This text is an example of ``inline literals``.

インラインリテラルは(前述の認識規則に従い)終了文字列のコンテキストである隣り合ったバッククオートを除いて、任意の文字を含めることができます。インラインリテラルの中では(バックスラッシュエスケープを含め)マークアップの解釈は行われません。

インラインリテラル内の改行は保持され ません 。reStructuredTextのパーサは、それ自身の出力で空白の連続を保持しますが、最終的に処理されたドキュメントの表現は出力フォーマッタに依存するため、空白の保持は保証できません。改行やその他の空白の保持が重要な場合は、 リテラルブロック を使う必要があります。

インラインリテラルは短いコードスニペットに便利です。例えば:

The regular expression ``[+-]?(\d+(\.\d*)?|\.\d+)`` matches
floating-point numbers (without exponents).

インライン内部ターゲット

Doc ツリー要素: target

開始文字列 = "_`"、終了文字列 = "`"

インライン内部ターゲットは明示的な 内部ハイパーリンクターゲット に相当しますが、テキストが連続している中に現れます。構文はアンダースコアとバッククオートで始まり、ハイパーリンク名かフレーズが続き、バッククオートで終わります。インライン内部ターゲットは匿名ではありません。

例えば、次の段落は"Norwegian Blue"と名付けられたハイパーリンクターゲットを含んでいます:

Oh yes, the _`Norwegian Blue`.  What's, um, what's wrong with it?

重複した参照名の解決については、 暗黙的ハイパーリンクターゲット を参照してください。

脚注参照

See also: Footnotes_

Doctree element: footnote_reference.

Configuration settings: footnote_references, trim_footnote_reference_space.

開始文字列 = "["、終了文字列 = "]_"

それぞれの脚注参照は、末尾にアンダースコアのある角括弧で括られたラベルで構成されます。脚注ラベルは次のうちの1つです:

例:

Please RTFM [1]_.

.. [1] Read The Fine Manual

`Inline markup recognition rules`_ may require whitespace in front of the footnote reference. To remove the whitespace from the output, use an escaped whitespace character (see `Escaping Mechanism`_) or set the trim_footnote_reference_space configuration setting. Leading whitespace is removed by default, if the footnote_references setting is "superscript".

引用参照

See also: Citations_

Doctree element: citation_reference.

開始文字列 = "["、終了文字列 = "]_"

それぞれの引用参照は、末尾にアンダースコアのある角括弧で括られたラベルで構成されます。引用ラベルは単純な 参照名 (大文字小文字を区別しない単一の単語で、英数字および内部にハイフン、アンダースコアおよびピリオドで構成されます; 空白は含みません)です。

例:

Here is a citation reference: [CIT2002]_.

置換参照

Doctree 要素: substitution_reference、reference

開始文字列 = "|"、終了文字列 = "|"(オプションで "_"または"__"が末尾に付く)

垂直バーは置換参照テキストを括るために使います。置換参照は、末尾に"_"(名前付き)や"__"(無名)を付与することで、ハイパーリンク参照にもなります; 置換テキストは、名前付きの場合には参照テキストとして使われます。

処理システムは置換参照を対応する 置換定義 ("対応"の定義を参照)の処理された内容と置き換えます。置換定義は、インライン互換要素を生成します。

例:

This is a simple |substitution reference|.  It will be replaced by
the processing system.

This is a combination |substitution and hyperlink reference|_.  In
addition to being replaced, the replacement text or element will
refer to the "substitution and hyperlink reference" target.

単位

(New in Docutils 0.3.10.)

All measures consist of a positive floating point number in standard (non-scientific) notation and a unit, possibly separated by one or more spaces.

Units are only supported where explicitly mentioned in the reference manuals.

長さの単位

The following length units are supported by the reStructuredText parser:

  • em (ems, the height of the element's font)
  • ex (x-height, the height of the letter "x")
  • px (pixels, relative to the canvas resolution)
  • 長さの単位

  • cm (centimeters; 1cm=10mm)
  • mm (millimeters)
  • pt (points; 1pt=1/72in)
  • pc (picas; 1pc=12pt)

This set corresponds to the length units in CSS.

(List and explanations taken from http://www.htmlhelp.com/reference/css/units.html#length.)

The following are all valid length values: "1.5em", "20 mm", ".5in".

Length values without unit are completed with a writer-dependent default (e.g. px with html4css1, pt with latex2e). See the writer specific documentation in the user doc for details.

パーセンテージの単位

Percentage values have a percent sign ("%") as unit. Percentage values are relative to other values, depending on the context in which they occur.

エラーハンドリング

Doctree element: system_message, problematic.

Markup errors are handled according to the specification in PEP 258.