reStructuredTextのUndocumentedな仕様

セクションタイトル

4文字以上の連続であること
章番号を出力する際は、間にスペースを入れる「1.1. サブセクション」
アンダーライン記号とオーバーライン記号がミスマッチ、またはオーバーライン記号のみの場合はエラーとなり出力されない。
idは全角文字部分は無視。重複の場合や空の場合は「id1」「id2」と割り振る。
「2.」の直後に「2.0.1」に相当するタイトルがある場合エラーとなる（2.1を飛ばせないということ）
セクションタイトルは暗黙的リンクを生成する。
- タイトルが重複（暗黙的リンクが重複）していても問題はないが、重複している暗黙的リンクを参照するとエラーになる。

リストブロックの抽出

リストブロック中にさらに別のブロックを入れる場合は、ブロックの手前に空行が必要。
要素中に１箇所でも空行やリスト以外のアイテムを含む場合、そのレベルとより上位のリストはすべてブロックに展開される。
- ただしアイテムの入れ子のための空行のみは無視する
次のようなリストも有効である。
```
-
    aa
-

- cc
```
この挙動は、列挙リスト、フィールドリスト、オプションリストも同様。

列挙リストの挙動

次の場合リストの終了を(2)までと見なし、(3)以降を通常文と見なす。
```
1. 項目1
2. 項目2
3. 項目3
5. 項目5
6. 項目6
```
- リストは次行をチェックする仕様であり、次行が以下のいずれかでなければならない。
  - ブランク行（空行）
  - インデントされた行
  - 全くの同型で順番も合っている列挙型
- この際、リストブロックの終わり（(2)の次行）にブランク行を入れろと警告が出る。
- (3)の後にブランク行を入れれば正常な挙動になる。
列挙の形式を混ぜることはできない
```
1. 項目1
2) 項目2
(3) 項目3
```

フィールドリスト

フールドリストの最初の行は、そのフィルード中で最小のブロックインデントと同じとみなされる。
```
:Authors: - X
    - Y
      - Z
```
```
    - X
    - Y
      - Z
```
- この仕様は「オプションリスト」同様である。

オプションリスト

ダッシュ1個"-"のときは、続く1文字[A-Za-z0-9] のみをオプションとして解釈。2文字目以降は（スペースがなくても）引数として解釈。
ダッシュ2個"-"のときは、[a-zA-Z][a-zA-Z0-9_-]* をオプションとして解釈。引数との間には、スペースまたは=1個が必要。
複数のオプションを区切る場合、", "を書く。" , "や", "はダメ。
MS-DOS形式の「/xxx」の"/"は、処理場は"--"の別表記として扱われる。
オプションの引数中に","が含まれる場合の解釈がおかしい*1
```
-c <x, y> arg include ","
```
オプションリストとして表記がおかしいものは、普通のテキストとして扱われる。

ブロックの入れ子

インデントを変えることでブロックを入れ子にできる。
以下の場合、入れ子は「aaaa」→「cccc」→「bbbb」となる。
```
aaaa
        bbbb
    cccc
```

定義リスト

単独行＋インデント行で定義リストになる。開始が複数行ではならない。

定義リスト
	定義リストdd内

２行以上の
普通の文章
	ここは引用ブロックになる。

classifierの展開がHTML違反（<dl>直下要素は<dt>/<dd>/<div>のみ）

<dt>term 4</dt>
	<span class="classifier-delimiter">:</span>
	<span class="classifier">classifier one</span>
	<span class="classifier-delimiter">:</span>
	<span class="classifier">classifier two</span>
	<dd>Definition 4.</dd>

行ブロック

空行でブロックが終了する。
入れ子は「行ブロック」のみ扱われる。
その他ブロック処理は行われない。
空白に続く行は、前行に連結したものとして扱われる。

Doctestブロック

リテラルブロック同様、\（バックスラッシュ）をそのまま出力し、シンタックスハイライトに展開する。
インデント付Doctestは、インデントなしDoctestと同じである。
```
Doctest with indent

    >>> print 'a'
    print 'b'
    print 'c'
```
Doctestよりも浅いインデントがある場合、浅いインデントを引用ブロックとして処理してから、Doctestブロックを入れ子処理する。
```
Doctest with indent

    >>> This is doctest string
  This is quiot string
```
Doctestと同じインデントで改行を含むブロック構成の場合は、全体を引用ブロックとして処理してから、Doctestブロックを入れ子処理する。
```
Doctest with indent

    >>> This is doctest string

   This is quiot string
```

テーブル

グリッドテーブルは2カラム以上の開始記号と、次行の"|"があってテーブルとみなされる。最小のテーブルは以下（ただしエラーになる）。
```
+-+-+
|
```
シンプルテーブルは最後のカラムのみはみ出しても良い。
```
=== === ===
aaa bbb cccccccccc
=== === ===
```
シンプルテーブルは border の長さがすべて一致しないとエラーになる。
シンプルテーブルのボーダーは開始行を除くと「"-" と " "」のみの行、「"=" と " "」のみの行はボーダーとして扱われる。
シンプルテーブルの終わりは、3つ目の「=」ボーダーか、2つ目のボーダーの次行がブランク行の時である。
シンプルテーブルの「===/---」は、通常のカラム構成のマージン部分それぞれが、すべて埋まっているか、すべてスペースでないとエラーになる。

シンプルテーブルの変換例

=  =
adcd
----
-  -
=  =
+  1
+  2
=  =

adcd



	1
	2

脚注、引用参照（citation）

オートナンバー型脚注は、すべての脚注の中で使われていない番号を1から探索し順番に割り振る。
オートナンバー型脚注をラベル付で重複定義すると、重複した定義はすべてラベルがないものとして処理される。
オートナンバー型脚注の参照は、最初のオーナンバー脚注の宣言から順に参照する。
- ラベル付オートナンバーへの参照は、ラベルが見つからない時は、ラベルなしオートナンバーとして扱われる。
脚注番号は重複していても、脚注自体は出力される。
無効な脚注（重複した脚注を含む）への参照は、脚注ではなく存在しないリンクへの参照として扱われる。

オートナンバー型やオートシンボル型の参照で宣言が足りない時は、存在しないidへのリンクを次の形式で出力する。

<a href="#id36"><span class="problematic" id="id46"><span id="id24"></span>[#]_</span></a>
<a href="#id47"><span class="problematic" id="id48"><span id="id29"></span>[*]_</span></a>

引用参照エラーの場合は、最後の「_」を取り除いたテキストを出力する。
```
[REF_ERR]_ → [REF_ERR]
```
脚注参照や引用参照で、単なるリンク（明示的オーバーライドを含む）を参照するとPythonごと落ちる。

ラベル名 / simple reference names

最初の「#」を除いて以下の形式となる。

半角英数字と全角文字、および語中に含まれるハイフン、アンダースコア、ピリオドで構成された大文字・小文字を区別しない単語。連続した「ハイフン、アンダースコア、ピリオド」は互いに連続してはいけない。

全角文字は、Unicodeクラスの「Letter」および「Number」のみ許可される。
- 仕様書によると「simple reference names」である必要があり、全角文字が許可されるという記述は存在しない。
ラベル内にバックスラッシュ「\」がある場合無効。

Perlの正規表現で表せば以下となる。

$label =~ /^[A-Za-z0-9\p{gc:L}\p{gc:N}]+(?:[\-_\.][A-Za-z0-9\p{gc:L}\p{gc:N}]+)*$/

逆参照リンク

参照されていない脚注や引用には、逆参照リンクが付かない。*2

複数の参照元がある場合、逆参照リンクが参照数だけ付く。

<em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id3">2</a>)</em>

脚注から参照した場合は、脚注からの参照に対しては逆参照が付かない*3

リンク

リンクの本体は、そのままaタグに挿入される。
```
.. _test: footnote.html#444""
.. _ftp:  ftp://ftp.jaist.ac.jp
```
「.. _」で始まれば、リンクとしてみなされ処理される。
```
.. _malformed_error
```
脚注や引用参照のラベルを指定して直接リンクすることができる。この場合、逆参照は発生しない。
```
脚注を直接参照 1_

.. [1] footnote
```
リンクラベルを「引用参照（citation）」形式でリンクすることはできない。
リンクラベルの宣言は「::」の後にいくつスペースがあっても良いが
「:」の手前に1つのスペースは有効だが、「:」の手前に2つ以上スペースがあると無視される
- 「malformed hyperlink target」が出力され、リンクブロックが終了したとみなされる。
```
..      _有効なリンク宣言 :
.. _無効なリンク宣言  :
.. _`無効なリンク宣言 `:
```
リンクラベル中の複数の連続したスペースは1つのスペースに正規化される。
リンクラベルの宣言時、ラベル名の最後に空白を含むと無視される（上例）。
リンクラベルの宣言は、バッククオート「`」の直前や直後にスペースかあると、区切りとみなされない。
リンクラベルの宣言中にバックスラッシュ（\）を含む場合、\によるエスケープを処理した後の名前がラベルとして記録される。*4
- 「:: _tar\g\ et:」という宣言は「:: _target:」とみなされ処理される。
- 「:: _tar\get\ :」という宣言は無効である。
リンクURLは、バックスラッシュ（\）が評価される。
同じ記述が複数あっても、同じ定義（URL）ならばエラーにならない。
- 同じURLを示していても次の記述はエラーとなる。
```
.. _duplicate: https://adiary.org/
.. _duplicate:
.. _adiary: https://adiary.org/
```
エイリアス（alias）を複数行に渡って記述することができる。
```
.. _alias:
	`hyperlink
	 name`_
```
参照先が見つからないエイリアス、循環参照しているエイリアスのリンク宣言は、エラーとして出力される。
```
.. _loopX: loopX_
.. _not_found: ZZZZZZZ_
```

参照時

リンクターゲットが見つからない場合は、「`」や最後の「_」が残されたままテキストが出力される（存在しないidでリンクが生成される）。
「``」なしの形式では、バックスラッシュ（\）を含む場合、参照とみなされない（リンク処理されない）。
「``」なしの形式は、simple reference namesのみ許可される。

ラベルの重複

リンクのターゲット名と「引用参照（citation）」のラベルが同じである場合、リンクは失敗する（存在しないidでリンクが生成される）。
脚注・引用参照（citation）でリンクを参照した場合。
- それがURLである場合、実行時エラーとなり、何も出力されない。
- それが内部リンクである場合、脚注と全く同じ形式のリンクが生成される。

入れ子

リンクラベル宣言は、リストアイテム等に入れ子することができる。
```
* .. _XXX:

 あいうえお
```
```
<li>あいうえお
</li>
```

無名リンク

参照数と定義数が合わないとき、すべての無名リンクを無効とする。

埋め込みリンク

埋め込みリンクとして認識されない例（通常のリンク参照とみなされる）
- <>中に<>を含む。
- ラベルと<の間にスペースがない（スペースは複数あっても良い）。
- <>内の先頭または最後にスペースがある
- >`の間にスペースが含む
- <>の中身が空
```
- `AA < http://adiary.org>`_
- `BB<http://adiary . org>`_
- `CC <http://adiary.org >`_
- `DD <http://adiary.org> `_
- `EE <>`_
```
<>内のスペースは除去される。
- ラベル名省略時は、除去後のテキストが出力される。
```
`<http : // adiary . org>`_
→ http://adiary.org
```
埋め込みリンクの参照名が重複していても、リンク自体は出力される。

置換定義

".. |"で始まる行は置換定義とみなされ処理される。
"| |" 内の先頭および最後がスペースのものは形式エラーとなる。
"| |" の後ろにスペースがないものはエラーとなる（即改行は良い）。
"| |" 内の連続するスペースは、1つのスペースとして処理される（参照時同じ）。
エラーとなった置換定義ブロックは丸ごと出力されない。

replace |test test| !

.. |test  test| replace:: success
.. |error1|replace:: dummy
.. |error1|replace:: dummy
.. |error2| replace:: dummy
.. |error3 | replace:: dummy
.. | error4| replace:: dummy
	no output
	
	no output
  no output

重複定義した場合エラーとなるが、置換自体は成功する（最後のものが有効）。

参照時

置換とリンクの両方の参照が同時に行われた場合、置換参照に成功しないとリンクは生成されない。
置換とリンクの両方の参照が同時に行われた場合、リンク参照に成功しないと文字の置換は行われない。
```
どちらも無効 |link1|_ |link2|_

.. _link1: https://adiary.org/
.. |link2| replace:: adiary
```
replaceテキスト中で置換参照 "| |" を行うと Sphinx がクラッシュする。
replaceテキスト中で以下を行うとエラーとなる。
- インラインリンク定義 `text <http://example.com>`_
- 脚注/引用参照 [1]_ [CITE]_

インラインマークアップ

入れ子にはできない。
仕様と異なり、Unicodeカテゴリ「Po (Other Punctuation)」に属する文字でも、以下のものは区切り記号として認識しない（インラインマークアップの前後の文字として使用できない）。
```
# % & * @
```
タグの開始記号を認識してから、終了記号を認識する。
- 開始記号を先に認識し、終了記号が見つからない場合、WARNINGを出力する。
- 脚注参照[XXX]を除く。

2行にまたがるインラインタグが有効。
```
This **is
a** pen.
```
中が空であるマークアップは、マークアップ全体がエラーとなる。
仕様と異なり、認識したマークアップの開始文字がエラーとなった場合、直後の文字は境界条件（マークアップ開始記号の直前の文字に関する制限）を満たしていることになる。

記述仕様から導かれる出力実際の動作

***XX* ***XX* **XX

記述	仕様から導かれる出力	実際の動作
**XX	**XX	**<em>XX</em>

その他

文字幅を示す「East_Asian_Width」の「A (=Ambiguous)」に属するものは、すべて半角として扱う。

adiaryマニュアル