reStructuredText互換性情報

慎重に互換性を調べながら実装したので忠実に再現されていると思いますが、バグがありましたらご連絡ください。

非互換の仕様

  • リスト要素にブロックが存在するとき、その要素のみ<p>タグが出現する。
    • Sphinxでは、並列要素および親要素すべてが<p>タグにより段落処理される。
  • 脚注は書いた場所ではなく、セクションの終わりに出力される。
  • 複数の参照元がある脚注/引用でも、ラベル自体にリンクを生成する。
  • 脚注/引用参照は明示的リンクを生成する(オーバーライドできない)。
  • 脚注/引用参照でリンクラベルを参照した際はエラーを出力する。
  • 無名リンクの参照数と定義数が一致しないとき、一致する分だけリンクを出力する。
  • 同じラベルのリンク宣言が複数ある時、同じURLを示していてもエラーとなる。
  • 埋め込みリンクで定義した参照名が重複した場合、エラーとなりリンクを出力しない。
  • 置換定義の中で許可されないインラインタグ(脚注参照等)がある場合も、置換定義を有効とする。
  • 無効なエイリアスまたは循環参照しているリンク定義も、本文には何も出力しない。*1

その他、使用タグはHTML5準拠で適当に変換してあります。

*1 : エイリアスは参照時評価

ディレクティブの非互換

  • ファイル参照時、アルバム内のファイル以外は参照できない(image::等)。
  • 「note:」や「WARNING:」等のタイトルを翻訳せず英字のまま出力する。
  • image:: リンクtargetが見つからず、altもないとき、空文字ではなくファイル名に対してエラーを出力する。
  • code:: 未知の言語を指定してもエラーにならない。
  • math:: 引数があっても式番号を出力しない。*2
  • csv-table::
    • delim, quote, escape に使用できるのは1byte文字のみ。
    • delim, quote, escape のいずれかに同じ文字を指定した場合エラーとする。*3
    • urlオプションは無視される。
  • contents::
    • backlinks 非対応*4
    • 出力すべき内容がない時でも、空のdivやタイトルが出力される。
  • sectnum:: 存在する場所以降にのみ影響する。
  • raw:: htmlのみ対応。urlオプションは無視される。

*2 : 本家のmathディレクティブで、引数に数式を書くと挙動が不可解なので止めたほうが良い

*3 : 本家では同じ文字を指定してもエラーにはならない。

*4 : 指定は可能だが、backlinkは生成されない

roleの非互換

  • code:: 未知の言語(language)を指定してもエラーにならない。
  • :pep: :rfc: の省略形roleを使っても、リンク文字を<strong>に入れない。
  • :raw: オプションにformat指定がエラーになっても、エラー結果を本文に出力する。*5

*5 : 本家では本文には何も出力しない。

何も処理しないディレクティブ

オプション等はチェックされるが、出力に影響しない。

  • header
  • footer
  • meta
  • title

非対応ディレクティブ

使用するとエラーになる。

  • line-block
  • list-table
  • target-notes
  • include
  • class

fileオプション

  • imageディレクティブや、その他ディレクティブでのfileオプションは、アルバム内の参照のみ許可しています。
  • ファイルパスを files/ で始めると、アルバム内の参照と解釈し置換します。
  • アルバムの外のファイルを参照することは(../path/ や /path/ 等を使用しても)できません。
OK キャンセル 確認 その他