【DocUtils和訳】reStructuredText Markup仕様α0 2/2

明示的なMarkupブロック

明示的なMarkupブロックは文字ブロックです。:

• その最初の行は ".." で始め空白文字を続けます( "明示的なmarkup開始"),
• その2行目と(有るなら)後に続く行は最初の行 と対となる様にし、
• それは段下げ解除された行の前で終わります。

明示的なmarkupブロックは箇条書きリスト項目と似ています。 ".." を使った

箇条書きとして。 直ぐ後の明示的なmarkup開始行上のテキストは 本体要素の段下げで決定します。 その最大の 普通の段下げは常にブロック本体の次と後に続く行から 取除かれます。 従って、もし最初の構成が一つの行で 一致しても最初と次の構成の段下げが一致しない様ならば、 最初の構成は明示的なmarkup開始として同じ行上では 始まりません。

空行は、明示的なmarkupブロックと他の要素間に必要ですが、 曖昧でない明示的なmarkupブロック間は 任意です。

明示的なmarkupの構文は脚註、出典、リンク対象、指示(directives)、 置換定義、そしてコメントで使われます。

脚註

Doctree 要素: footnote, label.

各脚註は、明確なmarkupの開始 (".. ")、左角括弧、 脚注ラベル、右角括弧そして空白文字 で構成され、

段下げされた本体要素が続きます。 脚註には次のことが出来

ます:

• a whole 10進法の数は1以上の数字と、
• 単一の "#" (自動連番脚註 を意味する)、
• 簡単な参照名を続けた "#" (ひとつの 自動連番ラベル)、 または
• 単一の "*" (自動シンボル脚註 を意味する)で構成されます。

脚註の内容(本体要素)は連続して(最低空白文字3個で)段下げし、 左揃えしていなければなりません。 脚註内の最初の本体要素は、 概ね脚註として同じ行で始まるかもしれません.。 しかしながら、もし最初の要素が一つの行で適合し、残りの要素の 段下げが 違うなら、最初の要素は脚註ラベルの後の行上で 始まります。 別の方法では、段下げ上の 違いは見抜けません。

脚註は、文末だけでなく、文書の何処ででも、発生するかもしれません。 何処そしてどの様にそれらが処理後の出力に現れるかは、処理システムに 依存します。

ここのは手打ちの連番脚註:

.. [1] 本体要素はここに書きます。

各脚註はそれ自身の自動的にリンク対象位置を生成 します。 リンク対象名のテキストは、脚註ラベルのそれと 同じものです。 自動連番脚註 はそれらの脚註ラベルと参照名 としての数を生成します。 構造の完全解説は、 暗示的なリンク対象 をご覧下さい。

構文の構造図:

+-------+-------------------------+
| ".. " | "[" ラベル "]" 脚註     |
+-------+                         |
        | (本体要素)+             |
        +-------------------------+

自動連番脚註

ナンバー記号("#")が脚註または脚註参照の自動連番取得の為、 脚註のラベルの最初の文字として使われるかも しれません。

自動連番取得をする最初の脚註には "1"のラベルが割当てられ、 2番目には"2"のラベルが割当てられます。等々。(手打ちの 連番脚註が存在しないと仮定すれば; 下記参照 手動と自動連番脚註の混用). 自動的に "1" のラベルを 持つ脚註は暗示的なリンク対象を "1" の名前で生成します。 例え、ラベルが明示的に指定されていてもです。

脚註は自動連番要求と同時に明示的にラベルを指定するかもしれません。 : [#ラベル]?. これらのラベルは 自動連番ラベル と呼ばれます。 自動連番ラベルは2つのことをします:

• 脚註それ自身上で、 名前が自動連番ラベルである リンク対象を生成します。("#" を含みません)。
• それらは、脚註参照またはリンク参照として、自動的に

連番脚註に一度以上参照されることを可能にします。 例えば

、:

もし [#note]_ が最初の脚註参照ならば、"[1]" として表示するで
しょう。   [#note]_ として参照出来ます。それでは、それは再度ご覧
下さい "[1]" 。  同様にそれは note_ (一つの普通の内部リンク参照)
として参照出来ます。

.. [#note] これは "note" とラベルされた脚註です。

番号付けは、参照順でなく、脚注の並びで 決定されます。 自動連番ラベル([#]?_)を伴なわない脚註参照の為に、 脚註と脚注参照は、同じ相対的な順番の中になければ なりません。 でも交互に横並びにする必要はありません。 例 えば:

[#]_ は脚註 1 の参照ですし、  [#]_ は脚註 2 の
参照です。

.. [#] これは脚註1です。
.. [#] これは脚註2です。
.. [#] これは脚註3です。

[#]_ は脚註3の参照です。

もし、脚註それ自身が自動連番脚註の参照を含んだり、 複数の参照が近接近で作られているなら、特別な注意を 払わなければなりません。 脚註と参照は順番に注意です。 それらは、文書内で衝突しますし、必ずしも同じ順番で それを読んでくれるとは限りません。

自動シンボル脚註

1つのアスタリスク("*")が、脚註と脚註参照用の自動的な シンボル生成用に脚註ラベルに使われるかもしれません。 アスタリスクは ラベル内の唯一の文字かもしれません。 例えば:

ここは、シンボル脚註の参照です: [*]_.

.. [*] これは脚註です。

変換では符合する脚註と脚註参照内のラベルとしてのシンボルを 挿入するでしょう。 参照の数は脚註の数と等しく なければなりません。 一つのシンボル脚註は複数の参照を持つことが 出来ません。

標準の Docutils 脚註のマーク用にシステムは次のシンボルを使 います。 [5]:

• アスタリスク/星 ("*")
• 短剣符 (HTML 文字エンティティ "†", Unicode U+02020)
• 2重短剣符 ("‡"/U+02021)
• セクションマーク ("§"/U+000A7)
• パラグラフまたは段落記号 ("¶"/U+000B6)
• ナンバー記号 ("#")
• スペード ("♠"/U+02660)
• ハート ("♥"/U+02665)
• ダイア ("♦"/U+02666)
• クラブ(三つ葉) ("♣"/U+02663)

[6]	このリストは The Chicago Manual of Style 14版 12.51節の "NoteReference? Marks" 用のシンボルリストに触発 されました。 "平行" ("||")はCMoS?では段落の代わりに与え られます。 最後の4つのシンボル(トランプ)は独断的に追加され ました。

もし、10以上のシンボルが必要ならば、同じものが連続して 再度使われ、2重ね3重ね以降同様になります。("**" etc.).

注意!

自動シンボル脚註を使うとき、その出力符号化は 重要です。 使われるシンボルの多くは、Latin-1(ISO 8859-1) の様にある一般的な文字符号化で符号化出来ません。 出力 符号化ではUTF-8利用を推奨します。 HTMLとXMLの出力の為の代替手段は "xmlcharrefreplace"

出力符号化 error handler を使うことです。

手動と自動連番脚註の混用

手動と自動による脚註の番号付けは単一の文書内で共に 使えます。とはいえ、結果は期待通りではないかもしれません。 手動に よる番号付けが優先されます。 使われていない脚註番号のみが自動連番 脚註に割当られます。 次の例示は説明に役立つ でしょう。:

[2]_ は "2" となります(手動による番号付け)、
[#]_ は "3" となります(匿名自動番号付け)、と
[#label]_ は "1" となります(自動番号付けでラベルされる)。

.. [2] この脚註は手動でラベルされ、その番号は固定されます。

.. [#label] この自動連番ラベル脚註は "1" でラベルされるでしょう。
   それは最初の自動連番脚註で、かつ "1" をラベルとする他の
   脚註がありません。  脚註の順番は番号付けの決定が利用され、
   脚註参照の順番ではありません。

.. [#] この脚註は "3" とラベルされるでしょう。  それは２番目の
   自動連番脚註ですが、脚註ラベル "2" は既に使われています。

出典

出典は [note]? や [GVR2001]? の様な数でないラベルのみを 使うことを除いて、脚註と瓜二つです。 出典の ラベルは単純な 参照名 (大文字小文字区別のな単語は 英数字 プラス 内側のハイフン、アンダースコアーそれにピリオドで 構成され、空白文字は無しです)。 出典は、脚註とは違って、 隔離してレンダリング表示されるかもしれませんし。 例えば:

ここは出典参照です: [CIT2002]_ 。

.. [CIT2002] これは出典です。  脚註に似ています。
   但しラベルが文字ということを除く。

リンク対象

Doctree 要素: target.

これらは、以下で定義の 暗示的なリンク対象 と区別する為に、

明示的なリンク対象 とも呼ばれるものです。

リンク対象は、文書の内か外かの位置を識別します。 その文書は リンク参照 でリンクされているかもしれません。

リンク対象は名前があったり匿名だったりします。 名前のあるリンク対象は 明示的なmarkup開始(".. ")、アンダースコアー、参照名(後付けの アンダースコアーは不要)、コロン、空白文字そして、 リンクブロック:

.. _hyperlink-name: link-block

参照名は空白文字中立で大文字小文字区別なしです。 詳細 と事例は 参照名 をご覧下さい。

匿名リンク対象は明示的なmarkup開始(".. ")、2つの アンダースコアー、1つのコロン、空白文字そしてリンク ブロックで構成され、ここに参照名はありません。:

.. __: anonymous-hyperlink-target-link-block

匿名リンク用の代替構文は、 2つのアンダースコアー、 空白文字そしてリンクブロックで構成されています。:

__ anonymous-hyperlink-target-link-block

下記参照 匿名リンク 。

リンク対象には次の３タイプがあります: 内部、 外部そして 間接。

1. 内部リンク対象 は空のリンクブロックを持ちます。. それらは、 文書内の他の場所の1つにつなぐリンクを可能にする 端点を提供します。 内部リンク対象は続く対象の 要素を指し示します。 例えば:

   内部リンク上でのクリックは、下記の `対象`_につれて行くで
   しょう。
   
   .. _`対象`:
   
   上記のリンク対象はこの段落を指示します。
   

   内部リンク対象は "つながれる" ことになります。 隣接する複数の 内部リンク対象は全て、同じ要素を指し示します。:

   .. _`対象1`:
   .. _`対象2`:
   
   
   "対象1" と "対象2" の対象は同義語です。 それらは共に、
   この段落を指示します。
   

   要素が "指し示す" のが外部リンク対象(そのリンクブロック内に URLを伴なう、下記参照 #2)なら、 外部リンク対象からのURLは 内部リンク対象に伝播されます。 それらは同じURIを全て、指し示します。 それらは複製する必要は ありません。 例えば、次のリンク対象3つ全てが同じ URIを参照します:

   .. _`Python DOC-SIG メーリングリスト保管庫`:
   .. _archive:
   .. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/
   

   内部リンク対象からの行内は利用出来ます。参照 `行内内部対象`_。

2. 外部リンク対象 はリンクブロック内のURIまたはEメール アドレスを絶対または相対で持つことが出来ます。 例えば、次の入力を 試してみて下さい:

   See the Python_ home page for info.
   
   `Write to me`_ with your questions.
   
   .. _Python: http://www.python.org
   .. _Write to me: [e-mail]
   

   HTML中の処理後、リンクは次の様に伝達されるかもしれません:

   See the <a href="http://www.python.org">Python</a> home page
   for info.
   
   
   <a href="mailto:[e-mail]">Write to me</a> with your
   questions.
   

   外部リンクのURIは、明示的なmarkup開始と対象名の様に、 同じ行で始まることもあります。または、それは、空行の 介在なしに、近くに続く段下げされたテキストブロック内で 始めるかもしれません。 リンクブロックに複数行があるなら、それらは 連結されます。 空白文字は取除かれます(空白文字は 行を包む為に放置することを許可されます。). 次の外部 リンク対象は等価です:

   .. _one-liner: http://docutils.sourceforge.net/rst.html
   
   .. _starts-on-this-line: http://
      docutils.sourceforge.net/rst.html
   
   .. _entirely-below:
      http://docutils.
      sourceforge.net/rst.html
   

   外部リンク対象のURIが、その最後の文字として1つのアンダー スコアーを含むなら、それは、間接リンク対象に 対する誤りを回避する為、エスケープされなければなりません。:

   この link_ は、``underscore_`` で呼ばれるファイルを参照します。
   
   .. _link: underscore\_
   
   

   リンク参照内に直接URIを含むことが可能です (とはいえ、通常推奨しません)。 下記参照 埋め込みURI 。

3. 間接リンク対象 はそのリンクブロック内にリンク参照 を持ちます。 次の事例では、対象 "one" は間接的に何やら 対象 "two"を参照し、対象 "two" は、内部 リンク対象の対象 "three"を参照しています。 事実上、 3つの参照全ては同じものを参照します:

   .. _one: two_
   .. _two: three_
   .. _three:
   

   ちょうど、 リンク参照 文書内の何処ぞの様に、 語句参照がリンクブロックに使われるなら、バッククゥォートで 括らなければなりません。 外部リンク対象 での様に、明示的な markup開始として間接リンク対象のリンクブロック同じ行上、または 次の行で始まるかもしりません。 それもまた複数行に 分かれるかもしれない場合には、 標準化の前に空白文字で

   行をつなぎ合わされます。

   例えば、次の間接リンク対象は 等価です:

   .. _one-liner: `A HYPERLINK`_
   .. _entirely-below:
      `a    hyperlink`_
   .. _split: `A
      Hyperlink`_
   

参照名がコロン等を含むならば、どちらかです:

• 語句はバッククゥォートで括らなければなりません:

  .. _`FAQTS: Computers: Programming: Languages: Python`:
     http://python.faqts.com/
  

• またはコロンはリンク対象でバックスラッシュ回避しなければなりません:

  
  .. _Chapter One\: "Tadpole Days":
  
  It's not easy being green...
  

参照名の繰返しの解決には 下部の`暗示的な リンク対象`_ を ご覧下さい。

構文の構造図:

+-------+----------------------+
| ".. " | "_" 名前 ":" リンク  |
+-------+ ブロック             |
        |                      |
        +----------------------+

匿名リンク

あの World Wide Web コンソーシアム は、その Webコンテンツのための HTML技法アクセシビリティ ガイドライン で推奨していて、それで、著者は "各リンクの対象で明瞭に確認す" べきです。リンク参照は可能な 限り詳細であるべきですが、その対象内の冗長なリンク名の複製は 煩わしくエラーしやすいものです。. 匿名リンクは 便利に冗長なリンク参照を可能にする為に設計されましたし、 自動連番脚註 に似ています。 それらは、特に 短いとか 単発の文書で有用です。 しかしながら、この機能は乱用され易く、 読み辛い平文 そして/または維持不能な文書を もたらすことになります。 警告がアドバイスされています。

匿名の リンク参照 は1つアンダースコアーの代わりに2つで 指示されます:

参照 `the web site of my favorite programming language`__.

匿名対象は ".. __:" で始めます。参照名は必要も許容も されません:

.. __: http://www.python.org

便利な代替手段として、匿名対象は "__" のみで開始 します:

__ http://www.python.org

参照の参照名はその対象への参照に一致して使われないかも しれません。 代わりに、文書内の匿名リンク参照と対象の順番は 重要です: 最初の匿名 参照は最初の匿名対象にリンクするでしょう。 文書内の 匿名リンク参照の数は匿名対象の数と 一致しなければ なりません。 可読性のためには、対象は参照の近くに 置くことを推奨します。 匿名参照を含んでいるテキスト編集時 には、注意を払って下さい。追加、削除そして再配置には 対象の符合する順番に注意が必要です。

指示

Doctree 要素: depend on the directive.

指示(Directives)はreStructuredText用の1つの拡張構造で、新たな構成を 新しい第1位の構文を追加することなく、追加サポートするの方法です。 (指示は局所的に追加の構文をサポートします)。 全ての標準指示 (それらは実装され、reStructuredText構文解析の文献に 登録されています。)は、`reStructuredTextの指示`_ の 文書中に記述され、いつも利用可能です。 いかなる他の指示も 分野特定であり、それらを文書処理時に利用可能にする為に特別な 動きを必要とするかもしれません。

例えば、これが1つの 画像 を置く方法です:

.. image:: mylogo.jpeg

図表 (説明文付きのグラフィック) はこの様に置きます [原文校正01]_:

.. figure:: larch.png

   カラマツ。

勧告 (note, caution, 等、)は他の本体要素を含みます。:

.. note:: これは1つの段落です

   - これは箇条書きのリストです。

指示は1つの明示的なmarkup開始 (".. ")により意味付けされ、指示タイプが 続けられます。2つのコロンと空白文字(一緒にして "指示目印(directive marker)"と呼ばれます)。 指示タイプは大文字小文字区別なしの単語 (英数字プラス内側のハイフン、アンダースコアーそれにピリオド。 空白文字は不可)。 2つのコロンは、これらの理由で指示の後に 使われます:

• 2つのコロンは独特で、普通のテキストで使うことがありそうにありません。

• 2つのコロンは、普通のコメントテストの様なものとの衝突を回避します:

  .. Danger: あなたの棄権負担で修正して下さい!
  

• reStructuredTextの実装は、指示を認識しない(言い換えれば、

その指示の処理がインストールされていない)なら、レベル-3の

(エラー)システムメッセージが生成され、その搭載指示ブロック (その指示それ自身を含む)はリテラルブロックとして含まれ ます。 従って "::" は自然な選択です。.

指示ブロックは指示の目印の後の指示の最初の行上のいくつかの 文字といくつかの後に続く段下げされたテキストで構成されて います。 指示ブロックの解釈は指示のコード 次第です。 指示ブロックへの3つの論理的な部分があります:

1. 指示の引数。
2. 指示のオプション
3. 指示の内容

個別の指示は、それらの部分の組合せを使うことが出来ます。 指示の引数は、ファイルシステムパス、題名の文字等であることが出来ます。 指示オプションは 領域リスト を使って示されます。その 領域名とコンテンツは 指示の仕様です。 引数とオプションは、指示の最初 または次の行で始まる連続しているブロックを形成 しなければなりません。 空行は指示内容ブロックの開始を 示します。 どちらの引数と/またはオプションは 、指示により使われます。 空行はそれらを指示コンテンツから隔離しなければなりません。 "図表" 指示は全ての3つの部分を使います:

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

   カラマツ。

簡素な指示は何らの内容も必要とはしません。 兎に角、内容ブロックを 使わない指示に段下げテキストが続いているなら、 それはエラーです。 ブロック引用が指示に直ぐ続くなら、 空のコメントの中割りを使って下さい(下記参照 コメント ).

指示内容ブロックまたは後に来るテキストブロック内のテキストの 指示と解釈への応答の術中に嵌る操作 は指示依存です。 詳しくは reStructuredTextの指示 をご覧下さい。

指示はそれらの内容の任意の処理としっくりします。 それは可能な限りオリジナルのテキストとは無関係なものに変換されることが 出来ます。 それは、代替の構文で試してみる様に、構文解析の振舞いを 修正する為、pragmasとして使用される為の指示にとって 可能であるかも しれません。[訳註意味不明01]?_ この機能性の為の構文解析のサポートは 今のところありません。 pragma指示の正当な必要性が見付けられるなら、 それらはサポートされるかもしれません。

指示は "指示" 要素を生成しません。; それらは 構文解析構造 だけですし、reStructuredTextの外側に固有の 意味を持ちません。 代わりに、構文解析は認識された指示を (可能な限り専門化した)文書要素に変換するでしょう。 未知の 指示はトリガーレベル3(エラー)のシステムメッセージを招くでしょう。

構文の構造図:

+-------+-------------------------------+
| ".. " | 指示タイプ "::" 指示          |
+-------+ ブロック                      |
        |                               |
        +-------------------------------+

代入定義

Doctree 要素: substitution_definition.

代入定義は明示的なmarkup開始(".. ")により示され、 縦棒、 代入文字、もう一つの縦棒、空白文字、定義ブロックが 続きます。 代入テキストは 空白文字で開始し終了します。 代入定義ブロックは、 "画像" または "置換え" の様な、埋め込みの行内-互換指示を (".. " を前に付けず)含みます。 例えば:

The |biohazard| シンボルは、医療廃棄物を処分する為に
使われる廃棄物容器上で使われなければなりません。

.. |biohazard| image:: biohazard.png

それは直接的または間接的に循環代入参照を含むことによる 代入定義ブロックのエラーです。

代入参照 は処理後の符合定義の内容 (一致している 代入テキストによりリンクされたリンクされた)により行内に 置換えられます。 一致は大文字小文字区分がありますが、寛容です。 的確な一致が見つからないなら、大文字小文字区別なし比較が試みられます。

代入定義は、行内テキストに共有されるブロックレベルの 指示 の力強さとしなやかさを可能にします。 それらがテキストの 流れから詳細を保つ間に、任意に 複雑な行内構造 を テキスト内に含む方法です。 それらは、エンティティまたは プログラム言語マクロという名のSGML/XMLの同等物です。

代替構造なしに、いつもだれかがアプリ特定の新しい行内 構造を望みます。, 彼らは構文変更の為、嘆願しなければ ならないでしょう。 存在する指示構文の組合せで、 any 行内構造は新しい構文(極力、新しい指示を除く)なしにコード化 出来ます。

構文の構造図:

+-------+-----------------------------------------------------+
| ".. " | "|" 代入テキスト "| " 指示タイプ "::" データ        |
+-------+ 指示ブロック                                        |
        |                                                     |
        +-----------------------------------------------------+

次に代入構造の利用事例をいくつかを挙げます。 どうか、 ご注意下さい。表示された埋め込み指示のほとんどは例示に過ぎず、 実装されている訳ではありません。

オブジェクト

代入参照は曖昧なテキストを固有のオブジェクト識別子.と 結合しがちかもしれません。

例えば、多くのサイトでは行内 "user" 指示を実装したいと 願うかもしれません:

|Michael| と |Jon| は我らが widgetカウボーイです。

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

サイトの必要次第で、これは、後で検索する文書の索引に、 様々な方法(メール先、ホームページ、プロファイルと連絡先 情報付きのマウスオーバーJavascript等)で行内テキストに リンクすることに、またはテキストの体裁のカスタマイズ(行内 テキストにユーザ名を含める、文の次のリンク付きアイコンイメージを 含める、太字や別の色にする等)に使われる かもしれません。

同じアプローチは、固有であっても曖昧な一般名の識別子を付きで 頻繁に特殊なオブジェクトの型に参照する文書で 使うことが出来ます。 映画、アルバム、書籍、写真、, 判例そして 法律が可能です。 例えば:

|The Transparent Society| (透明な社会)はプライバシーの課題面の
興味深い相互的視点を提示しています。

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

文脈内のモジュールまたはクラス名が不明確かつ/または 解釈テキストが使われないクラスと関数は、別の 可能性です:

4XSLT には便利なメソッド |runString| があります。それで、
DOMオブジェクトにちょっかいを出す必要はありません。
もし、あなたが欲しい全てが変換後の出力ならです。

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

画像

画像は代入参照の一般的な利用です:

西は |H| 3 を最初に出し、 ダミーの |H| Q により隠し、
西は  |H| K、で手札は |S| 2 だ。

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

* |Red light| は止まれを意味します。
* |Green light| は進めを意味します。
* |Yellow light| は本気で速く進めを意味します。

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

|-><-| は POEE_ の公式シンボルです。

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

"画像" 指示は実装されています。

スタイル [6]

代入参照は行内を外部で定義された体裁のスタイルと 関連付ける為に使われることがあります:

Even |the text in Texas| is big. (テキサス内の文字さえも大きい)

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

そのスタイル名は特殊な出力書式の文脈内で意味深長かもしれませんし、 (HTML出力用のCSSクラス名、LaTeX?用のLaTeX? スタイル名等)、 また、他の出力書式(平文の様に)では無視されるかも しれません。

[7]?	これらは、解釈されたテキスト 役割 構文への to 拡張の様により簡素な構文を認可する為に、 "スタイル" 構造用に 充分に 必要かもしれません。 代入構造は シンプルなテキストのスタイル化には扱いにくい。

テンプレート

行内markupはテンプレートエンジンによる後処理の為、使われるかも しれません。 例えば、Zope_ 著者は書かれるかもしれない:

お帰りなさい、 |name|!

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

処理後、このZPT出力が生じるでしょう:

お帰りなさい、
<span tal:replace="user/getUserName">name</span>!

Zopeは、次に、これをセッション中の実在のユーザを付けて、 "お帰りなさい、David!" の類に変換するでしょう。

テキストの置換え

代入構造はシンプルなマクロ代入の為に使われるかも しれません。 これは、テキストの置換えが１以上の文書全体に わたって多数回繰返されるときに、適しているかもしれません。 殊にもし、それが後で変更が必要なら。 短い例は 不自然な不可避可能性:

|RST|_ は何度もタイプしていると、少しうっとうしい。殊に
|RST| それ自身につして書いていて、大文字付きの
単語 |RST| を毎回略さずに書くことは、 |RST| ソースの
可読性にとり実際には、必要ありません。

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

代入参照を最初の利用内の後付けのアンダースコアーに注意 して下さい. これは、リンク対象の符合への 参照を示します。

代入もまた、置換えテキストが インライン構成を使って描く ことが出来ないか、押し付けがましく長いときに適して います:

しかし依然、 |j2ee-cas|__ の様な名前と比較するものでは
ありません。

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

The "置換え" 指示は実装されています。

コメント

Doctree 要素: comment.

任意の段下げテキストは明示的なmarkup開始に続き、コメント要素として 処理されるかもしれません。 これ以上の処理はコメントブロックの テキスト上でなされません。コメントは単一の "テキストBLOB" を含みます。 出力フォーマッタ次第で、コメントは処理後の出力から 取除かれます。 コメント上の制限は、それらが他の 明示的なmarkup構成の何れとも同じ構文を使わないことだけです: 代入定義、指示、脚註、出典または リンク対象。 他の明示的なmarkup構成の何れも認識されないことを 確実にする為に、それ自体の行上の ".." を取除いで下さい。:

.. これはコメントです
..
   _so: はこれです!
..
   [and] これ!
..
   これ:: も!
..
   これ |さえも|:: !

1つの明示的なmarkup開始に続き1つの空行と他には何も 要りません(空白文字は別として)。 "empty comment". それは、 先行する構成を終了する働きをし、続く段下げされたテキストを 壊しません。 リストまたは何か段下げされた構成に続くブロック引用を 持つには、段下げ解除された空のコメントの中割りを挿入して下さい。

構文の構造図:

+-------+----------------------+
| ".. " | コメント             |
+-------+ ブロック             |
        |                      |
        +----------------------+