reStructuredTextのUndocumentedな仕様

セクションタイトル

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

リストブロックの抽出

  • リストブロック中にさらに別のブロックを入れる場合は、ブロックの手前に空行が必要。
  • 要素中に1箇所でも空行やリスト以外のアイテムを含む場合、そのレベルとより上位のリストはすべて<p>ブロックに展開される。
    • ただしアイテムの入れ子のための空行のみは無視する
  • 次のようなリストも有効である。
    -
        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 ","
    
  • オプションリストとして表記がおかしいものは、普通のテキストとして扱われる。

*1 : 仕様では< >内には何を書いても良いので、バグと思われる

ブロックの入れ子

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

定義リスト

  • 単独行+インデント行で定義リストになる。開始が複数行ではならない。
    定義リスト
    	定義リストdd内
    
    2行以上の
    普通の文章
    	ここは引用ブロックになる。
    
  • 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

*2 : 1つだけの場合そもそも付かない模様。

*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><p id="xxx">あいうえお</p>
    </li>
    

無名リンク

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

埋め込みリンク

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

*4 : footnoteや引用参照の宣言や、リンクの参照では途中に「\」を含むと期待した動作をしない。

置換定義

  • ".. |"で始まる行は置換定義とみなされ処理される。
  • "| |" 内の先頭および最後がスペースのものは形式エラーとなる。
  • "| |" の後ろにスペースがないものはエラーとなる(即改行は良い)。
  • "| |" 内の連続するスペースは、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***<em>XX</em>

その他

  • 文字幅を示す「East_Asian_Width」の「A (=Ambiguous)」に属するものは、すべて半角として扱う。
OK キャンセル 確認 その他