| 原文: | reStructuredText Markup Specification (rev.7629) |
|---|---|
| 原著者: | David Goodger |
| 著者: | helloaworld.com |
| 連絡先: | http://helloaworld.com |
| Revision: | 0.0 |
| Date: | 2014/11/1 |
| Copyright: | クリエイティブコモンズ 表示-非営利-継承 |
目次
この文章は、reStructuredText Markup Specification を日本語に要約したものです。 原文が読み辛い物であった為、省略、再構成、意訳を繰り返しています。 sphinxを使い始める方用に、reStructuredTextを効率よく理解して頂く為に作成しました。
オフィシャルは、入門時は別ドキュメントの参照を勧めていますが… それだけでは、良く分からない警告やエラー、挙動を見る事になると思います。 その様な状況になった時に参照下さると役立つはずです。
また、原文の厳密な訳をされる方にも役立つはずです。
ノート
この文章は、技術的な詳細な仕様書です。導入や入門に当たっては、A ReStructuredText Primer ( 和訳 )と Quick reStructuredText ( 和訳 ) をまず見て下さい。
reStructuredTextは、シンプルで直感的な体系で ドキュメント構造を記述できる平文のファイル形式です。 この体系により、変換前後のファイルのどちらにも読みやすさが維持されます。 このドキュメントは、自身がreStructuredTextの使用例です。 reStructuredTextは、Docutilsの一部です。
まず始めに、暗黙のマークアップは章見出しやリストや強調などの構造を 指示する際に利用される。これらのマークアップは、可能な限り最小限で 簡単な構造の構文となっています。 それらに比べて利用頻度の低い構文は、複雑な構造で明確化された構文です。
reStructuredTextは 様々な長さのドキュメントに使用できます。 非常に短いもの（pythonのdocstringsのようなソースコード埋め込み型のドキュメント）から、 このドキュメントの様に大きいものまで作成できます。
省略
基本的に、このページ自身に挙げられている構文を列挙した内容です。 特に不要と考えています。以下に和訳ページがあります。
http://docutils.sphinx-users.jp/docutils/docs/ref/rst/restructuredtext.html#quick-syntax-overview
エスケープしたい部分の先頭にバックスラッシュ(\)を一つ書いて下さい。 バックスラッシュ自身を出力する場合は、二つ連ねて\\です。 通常使用ではこのレベルの理解で問題はありませんが、詳細はオフィシャルのドキュメントを参照ください。（http://docutils.sphinx-users.jp/docutils/docs/ref/rst/restructuredtext.html#escaping-mechanism）
利用例:
\=============
not section
\============
\**nonono**
単語の最後にアンダースコアを付ければ参照名になります。詳細は、明示的マークアップブロックの項目で出てきます。とりあえず本項では、最後にアンダーバーをつければ参照名になることと、いくつかの要件だけ覚えてください。
要件は下記
実例:
This is some-link. This is more-link 句読点では切れる。日本語でリンク してみる。
引用してみます。祇園精舎の鐘の声、諸行無常の響きあり [引用001] 。
| [引用001] | 梶原正昭、山下宏明 (1991). 新日本古典文学大系 44 平家物語 上 岩波書店 |
コード:
This is some-link_.
`This is
more-link`_
句読点では切れる。日本語でリンク_ してみる。
引用してみます。祇園精舎の鐘の声、諸行無常の響きあり [引用001]_ 。
.. _some-link: http://www.yahoo.co.jp/
.. _THIS IS more-LINK: http://nohost.nodomain/
.. _日本語でリンク: http://test.com/
.. [引用001] 梶原正昭、山下宏明 (1991). 新日本古典文学大系 44 平家物語 上 岩波書店
ノート
書き方は以下
===============
Section Title
===============
---------------
Section Title
---------------
Section Title
=============
文字の下、若しくは上下の”オーバーライン”の装飾でマークアップすれば良いです。 その他の要件は下記
ノート
原文では本項で、構文の各要素の階層的な構造について触れています。この部分は利用時に意識する必要は無いと思い、省いています。詳細は、The Docutils Document Tree（http://docutils.sourceforge.net/docs/ref/doctree.html）
前後に空行を配置して、四つ以上の続く-で水平の罫線を引けます。htmlの<hr>と同じです。但し、二つ以上連続することは出来ません。以下の様なものです。、
コードは以下。
文章
--------------------
文章
段落を変えたければ、二回改行してください。
ノート
空白行で段落や他のbody要素が区切られます。body要素の説明は避けます。 基本的に、段落であったり何かしらの一まとまりを構造するブロックは、区切るために前後に空行が必要 と考えてください。
実例は、以下です。
あいうえお
かきくけこ
段落をここで
変えてみます。
階層構造は
インデントを利用して
- 作れます
やり方は「* + -」などにスペースを続けてから、文字を入れてください。 インデントと、空行で区切りを行うことに注意して下さい。
コードは以下、
- あいうえお
- かきくけこ
- 段落をここで
変えてみます。
- 階層構造は
- インデントを利用して
- 作れます
列挙リストは、印のかわりに数字が振られます。以下のシーケンスを利用できます
上記に書式タイプを組み合わせて使います。推奨とされるのは3パターンです。
実際に使うときは、一行目で先頭の数字を与えてください。 後は自動列挙子に任せれば良いです。 実例は以下
- かき
- くけ
- たち
- つて
- ととと
- くけ
コードは以下
I) あいう
#) えお
#) えお
1. かき
#. くけ
a) たち
b) つて
c) ととと
#. くけ
最後の「くけ」の行は、カウンターがリセットされるようですね。 後、A. Einstein等から始まるような一行の段落はリストとして検出されるので、\でエスケープして下さい。
\A. Einstein
実例と、コードを記載します。
term(用語,項目) 2の定義は ここで行われます.
term(用語,項目) 2の定義、第二段落.
コードは以下
term 1
term(用語,項目) 1の定義は
ここで行われます.
term 2 : 分類子
term(用語,項目) 2の定義は
ここで行われます.
term(用語,項目) 2の定義、第二段落.
some_variable : unsigned long
何かしらの変数
アオスジアゲハ : アゲハチョウ科 : 昆虫綱 : 飛ぶ
都市部でも見られる、アゲハチョウの筋が青い
蝶々。
いくつかの意味合いがあります。
(a)については、ディレクティブの項目で説明しています。(b)については下記例
| Date: | 2001-08-16 |
|---|---|
| Version: | 1 |
| Authors: |
|
| 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 |
コードは下記
: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
行頭に(:)で挟まれた文字を準備すれば、フィールドを用意できます。それに、続けてフィールドの内容を指定して利用します。
(b)の用法はディレクティブ毎フィールド毎に、フィールドの指定方法が異なります。何かしらのディレクティブで、フィールドを利用する際は、しっかり仕様を確認した方が良いでしょう。
特殊な動作として、フィールドリストが文章タイトルの後ろにあれば、そのフィールドは文書の書誌情報として変換される可能性があります。以下が利用できます。
また、バージョン管理システムのキーワード置換を解釈できます。cvsやrcsやgit等々は、$keyword:expansion text$という形式へ置換を行う機能を持っています。これを、expansion textに置換する機能があります。
サンプルは以下
| -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. |
コードは以下
-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.
rstがオプションとして認識するものは、
リテラルブロックは、ソースコードやコンソール入力を示すために利用します。これを利用する場合は、まず::で構成される段落を作って、その後に任意の文字列を記入してください。
::で構成される段落の次のインデントか引用符を付与された段落は、リテラルブロックとしてマークアップされます。リテラルブロック内では、マークアップ処理がされず、通常は等幅書体となります。
また、インデントリテラルブロックという動作が取られます。::の次の文字のインデントより深い部分が、リテラルブロックとして解釈されます。::の次の文字のインデントより浅い行が出現するとインデントリテラルブロックは終了します。
ノート
sphinxを利用する場合は拡張が行われていて、デフォルトでpythonのハイライト処理が行われます。これを変更する場合は、highlightディレクティブを利用すると良いです。他にも、code-blockというディレクティブがあります。これらは、sphinxの拡張であって、docutilsの機能ではありません。
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
コード
::
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
又は以下のような書き方も
サンプル:
printf("hello world");
コード
サンプル::
printf("hello world");
インデントの変わりに、クォートを利用することも出来ます。この動作はクォートリテラルブロックと言うものです。
以下の記号をクォートとして利用できます。
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
サンプル:
>> Great idea!
>
> Why didn't I think of that?
block end!!
コード:
サンプル::
>> Great idea!
>
> Why didn't I think of that?
block end!!
Python標準ライブラリのdoctestモジュールの機能を利用して、pythonコードの簡易なテストを行います。 但し、著者の環境(python 2.7 64bit on windows 7 64bit)では動作しなかったので詳細は説明できません。 リテラルブロックの特殊なケースとして扱われていますが、doctestブロックよりは、リテラルブロックが優先されます。
コード例:
>>> print 3+5
8
sphinxがこの機能を拡張しています。参考文献としては下記が良さそうでした。
シンプルテーブルのサンプルは以下。細かい要件は省略します。要件は以下
| A | B | A and B |
|---|---|---|
| False | False | False |
| True | False | False |
| False | True | False |
| True | True | True |
コードは以下:
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
さらに込み入ったサンプルを提示します。要件は以下
サンプル
| combined | |
|---|---|
| col 1 | col 2 |
| 1 | Second column of row 1. |
| 1 | Second column of row 1. |
| 1 | Second column of row 1. |
| 2 | Second column of row 2. Second line of paragraph. |
|
|
| Row 4; column 1 will be empty. | |
コード:
===== =====
combined
------------
col 1 col 2
===== =====
1 Second column of row 1.
1 Second column of row 1.
1 Second column of row 1.
----- -----
2 Second column of row 2.
Second line of paragraph.
----- -----
.. - Second column of row 3.
- Second item in bullet
list (row 3, column 2).
\ Row 4; column 1 will be empty.
===== =====
グリッドテーブルは、アスキーアートを使ってテーブルの表現を行います。 グリッドテーブルについては、説明を省きます。複雑な表を作成しない限り、csv-tableディレクティブを利用した表現の方が、メンテナンス性及び、拡張性に富んでいます。(他にもlist-tableディレクティブがあります)
サンプル
| Header row, column 1 (header rows optional) | Header 2 | Header 3 | Header 4 |
|---|---|---|---|
| body row 1, column 1 | column 2 | column 3 | column 4 |
| body row 2 | Cells may span columns. | ||
| body row 3 | Cells may span rows. |
|
|
| body row 4 | |||
コード:
+------------------------+------------+----------+----------+
| 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. |
+------------------------+------------+---------------------+
明示的マークアップブロックは、前述のアンダースコアを利用した参照に対する定義部分のようなものです。何しか、”..”で始まるブロックです。記述方法の要件は下記
明示的マークアップの構文は、以下で利用されます。
ノート
原文では、同一の識別子名に対して参照として利用される箇所では参照名、ラベルとして使用される箇所ではラベル名と呼称されています。大体の場合で、参照名とラベル名はイコールで考えてＯＫです。アンダースコアの場所だけ注意です。
脚注の、ラベル名に以下の要件があります。
手動ナンバー型の脚注と、オートナンバー型の脚注があります。手動ナンバー型の方が優先される点にご注意ください。使われていない番号だけが、オートナンバー脚注に割り当てられます。
ヒント
参照時は、[数字]_。脚注時はアンダーバー無しで、[数字]。
サンプル
[1] is a reference to footnote 1, and [2] is a reference to footnote 2.
| [1] | This is footnote 1. |
| [2] | This is footnote 2. |
| [3] | This is footnote 3. |
[3] is a reference to footnote 3.
コード:
[#]_ 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.
複数回の参照を行う場合は、オートナンバー型ラベルを利用してください。
サンプル
初回の [4] は”[4]”のように表記されます。. さらに、 [4] のよう同じ参照を行っても”[4]”と表記されます. note のようにも参照を行えます。(an ordinary internal hyperlink reference).
| [4] | (1, 2) This is the footnote labeled “note”. |
コード:
初回の [#note]_ は"[4]"のように表記されます。.
さらに、 [#note]_ のよう同じ参照を行っても"[4]"と表記されます.
note_ のようにも参照を行えます。(an ordinary internal
hyperlink reference).
.. [#note] This is the footnote labeled "note".
オートシンボル脚注は、以下のような動作です。
サンプル
Here is a symbolic footnote reference: [*]. Here is a symbolic footnote reference: [†]. Here is a symbolic footnote reference: [‡].
| [*] | This is the footnote. |
| [†] | This is the footnote. |
| [‡] | This is the footnote. |
コード:
Here is a symbolic footnote reference: [*]_.
Here is a symbolic footnote reference: [*]_.
Here is a symbolic footnote reference: [*]_.
.. [*] This is the footnote.
.. [*] This is the footnote.
.. [*] This is the footnote.
オートシンボル脚注についての詳細は割愛します。Latin-1（ISO 8859-1）のような一般的なテキストエンコーディングではエンコードできません。utf-8の仕様が推奨です。
非数値のラベルを使用すること以外は、脚注と同じ。
サンプル
| [引用0001] | 梶原正昭、山下宏明 (1991). 新日本古典文学大系 44 平家物語 上 岩波書店 |
| [引用0002] | 新村 出 (2008). 広辞苑 第六版 岩波書店 |
| [平家物語] | 梶原正昭、山下宏明 (1991) 『新日本古典文学大系 44 平家物語 上』 岩波書店 |
コード:
- 祇園精舎の鐘の声、諸行無常の響きあり [引用0001]_ 。
- 「天上天下唯我独尊」 [引用0002]_ 。
- 祇園精舎の鐘の声、諸行無常の響きあり [平家物語]_ 。
.. [引用0001] 梶原正昭、山下宏明 (1991). 新日本古典文学大系 44 平家物語 上 岩波書店
.. [引用0002] 新村 出 (2008). 広辞苑 第六版 岩波書店
.. [平家物語] 梶原正昭、山下宏明 (1991) 『新日本古典文学大系 44 平家物語 上』 岩波書店
ヒント
脚注（=補注)は、本文上に載せるには枝葉な説明等を行うものです。引用は、他の文献から引用したことを示すもので、出典を明記するものです。
ヒント
注釈とは広義の意味を持つ言葉で、ページの下部にまとめられたものを脚注、巻末にまとめられたものを後注と呼びます。
ヒント
注記を行いたい場合は、noteディレクティブや、warningディレクティブ等々があります。
ヒント
書籍や論文としての引用や注釈の体裁については、ネットや参考書で別途調査ください。記述方法にある程度のルールはあります。
ハイパーリンクターゲットは、[]を用いません。参照名のルールについては、参照名の項目を参照してください。
ノート
参照時は文字列の後端にアンダーバー、ハイパーリンクターゲット宣言時は先頭にアンダースコアです。引用や注釈と、ルールが若干異なります。
サンプル
内部ハイパーリンクターゲットは このように リンクを晴れます。 隣接させると、連鎖します。 ここから でも同じ要素に大してリンクを張ることが出来ます。
ここにリンクが行われます。
コード:
内部ハイパーリンクターゲットは このように_ リンクを晴れます。
隣接させると、連鎖します。 ここから_ でも同じ要素に大してリンクを張ることが出来ます。
.. _このように:
.. _ここから:
ここにリンクが行われます。
外部ハイパーリンクターゲットは、内部ハイパーリンクターゲットの書式のセミコロンの後にスペースを配置し、続けてURI(相対パスでも絶対パスでも)やメールアドレスを書けば良いです。 その他要件は下記
サンプル
コード:
- python_ のHPを見てください。
- 疑問があれば、 私まで_ 連絡ください.
- 連鎖でパイソン_ をリンクします。
- `間接ハイパーリンクターゲットでパイソンのHP`_ をリンクします。
.. _連鎖でパイソン:
.. _PyThoN: http://www.python.org
.. _私まで: me@ex
ample.
com
.. _`間接ハイパーリンクターゲットでパイソンのHP`: python_
w3cの”HTML Techniques for Web Content Accessibility Guidelines 1.0”では、それぞれのリンクのターゲットを明確に識別すべきと推奨しています。ハイパーリンク参照は可能な限り詳細であるべきとの方針に従うことは面倒ですし間違いの元です。ただし、無名ハイパーリンクターゲットは、ドキュメントの保守上は好ましくないので、短期的もしくは単発のドキュメントで有用です。
以下要件です。
サンプル
コード:
- `無名のリンク`__ です。
- `無名のリンク（省略形）`__ です。
.. __: http://www.yahoo.co.jp
__ http://www.google.com
c言語だと#defineや#ifがディレクティブで、マクロに対してコマンドを発行します。 同様に.rstでコマンドを発行するときは、空白行で区切ってから”..”とスペース一文字に続けて命令の種類を伝えるために、ディレクティブ名(directiveType)と2つのコロンを記述します。具体的には下記様な文法になります。
.. directiveType:: 半角スペース後にコードブロックの文字列。
インデントされた部分は、
同一のブロックとして扱われます。
全てのディレクティブは上記の構文になりますが、ディレクティブの種類に拠ってコードブロックの中身が異なります。コードブロックの中身は、 reStruicturerdTextの仕様書を参照してください。
ディレクティブブロックには3つの要素があります。
ディレクティブオプションは、前述のフィールドリストを利用して記述する点に注意ください。 実際には以下のように利用されます。
.. directiveType:: directiveArgument
:directiveOption: someOption
:directiveOption: someOption
ディレクティブコンテンツは、空白行で区切ってから
例えば、ディレクティブコンテンツしか存在しないディレクティブの場合は以下のようになります。
.. directiveType::
ディレクティブコンテンツは、
空白行で区切ってから
ヒント
ディレクティブに関する仕様書は http://docutils.sourceforge.net/docs/ref/rst/directives.html
ヒント
一部和訳されたものはここにあります。http://docutils.sphinx-users.jp/docutils/docs/ref/rst/directives.html
ヒント
sphinxオフィシャルのドキュメントでもディレクティブに関する仕様が和訳されています。http://sphinx-users.jp/doc10/rest.html#directives
置換定義は、”.. “に続けてバーティカルバーで挟んだ置換文字列にスペースと定義ブロックが続きます。 置換文字列の先頭若しくは終端にスペースを含むことは出来ません。 定義ブロックには、”image”や”replace”のような埋め込み型のディレクティブを含むことが出来ます。 ただし、ディレクティブ名の前の”..”は不要です。
構文図:
+-------+-----------------------------------------------------+
| ".. " | "|置換文字列| ディレクティブ型:: data" |
+-------+ directive block |
| |
+-----------------------------------------------------+
利用例:
コード:
- unicodeディレクティブ |copyr2|
- replaceディレクティブ |テスト|
- リンクも出来ます |date_time|_
- 同様に無名リンク |date_time|__
.. |copyr2| unicode:: 0xA9 .. circle c
.. |テスト| replace:: AbCdE
.. |date_time| date:: %Y年%m月%d日%H時%M分%S秒
.. _date_time: http://www.nict.go.jp/JST/JST5.html
__ http://www.nict.go.jp/JST/JST5.html
外部で定義されたstyleを使用することも出来ます。
この |文字| は大きい.
.. |文字| style:: big
他にもimageディレクティブでの利用はよくあります。
サンプルコード:
|red image| は赤色です。 |yellow image| は黄色です。
.. |red image| image:: /image/red.jpg
.. |yellow image| image:: /image/yello.jpg
暗黙のハイパーリンクターゲットは、章のタイトル、脚注、引用によって生成されます。さらには外部の拡張によって生成されることがある。その他の点で、暗黙のハイパーリンクターゲットは明示されたものと同じ振る舞いをする。
明示のものと暗黙のハイパーリンクターゲットが重複して衝突することによる問題は、以下の手順で回避されています。
ターゲットリンクが除去された箇所にシステムメッセージが挿入されます。 パーサは、固有のハイパーリンクターゲットの組合わせを返さないといけません。呼び出しソフトウェア(Docutils等)は解決できないリンクを原因を添えて警告することができます。
以下の状態を満足した時、インラインマークアップ開始文字列と終端文字列が認識される。
インラインマークアップはのスタート文字列は、テキストブロックか以下の文字の前となる。
- 空白
- 右記のアスキー文字 - : / ‘ ” < ( [ {
- 右記の非アスキーの句読点 Pd (Dash), Po (Other), Pe (Close), Pf (Final quote), 若しくは Pi (Initial quote)
インラインマークアップ開始文字列は、空白以外の文字に続く
インラインマークアップ終端文字列は、空白以外の文字の前に来る
インラインマークアップ終端文字列は、テキストブロックか以下の文字に続く
- 空白
- 右記のアスキー文字 - . , : ; ! ? / \ ‘ ” ) ] } >
- 右記の非アスキーの句読点 Pd (Dash), Po (Other), Pe (Close), Pf (Final quote), 若しくは Pi (Initial quote)
‘ ” < ( [ { Pd Pi Pf出始まった場合は、対応する ‘ ” ) ] } > Pd Pi Pfで閉じられる必要がある。
インラインマークアップの終端文字列は、開始文字列と一文字以上隔たっている必要がある。
開始文字列もしくは終端文字列の前にエスケープされていないバックスラッシュがある場合は、終端文字列のインライン文字を除いて、無効なマークアップ領域となります。詳細は、エスケープの節を参照してください。
これらのルールは、90%を越えるインラインマークアップ以外で利用される”*”, “`”, “_”, “|”をエスケープ無しで使用できるようにするためのものです。以下の例では、インラインマークアップとして認識されません。
- 2*x a**b O(N**2) e**(x*y) f(x)*f(y) a|b file*.* (breaks 1)
- “*” ‘|’ (*) [*] {*} <*> ‘*’ ?*‘ ‘? ’’ ?*’ “*” ?*“ “? ”” ?*” ≫*≪ ?*? ≪*≫ ≫*≫ ?*? (breaks 5)
- __init__ __init__()
上記の例に合致しないような、エスケープが必要な文字列の場合は、インラインリテラルかリテラルブロックを利用することが最も良い選択です。
曖昧さを回避するため、インラインマークアップの区切り文字は多様な構造で利用できます。それぞれの文字に対して認識規則が定められています。
- アスタリスク: 強い強調(**)は、強調(*)の前に認識される。
- バッククォート: インラインリテラル（``で囲まれる）とインラインインターナルターゲット(_`で始まり`で終わる)は互いに独立で、ハイパーリンクの参照(`で始まり`_で終わる)とインタープリテッドテキスト(`で囲まれる)の前に認識されます。
- 先頭にアンダースコア: 脚注参照([ラベル名]_)と単純なハイパーリンク参照(名前の後に_)は互いに独立。
- バーティカルバー: 置換参照(|で囲まれる)は独立して認識される。
- 単独型ハイパーリンク(“”で囲まれる)は、最後に認識される。
バックスラッシュによってエスケープした単語内で、個別のマークアップは可能です。 (その前に、エスケープの節を見てください。) バックスラッシュのエスケープは、インラインマークアップに続く任意のテキストを許可します。
例:
- インラインマークアップ前後に半角スペースが入らない→ 強調してインラインリテラルを続け強い強調で終える。
- 半角スペースが入る→ 強調して インラインリテラルを続け 強い強調 で終える。
コード:
- インラインマークアップ前後に半角スペースが入らない→ *強調して*\ ``インラインリテラルを続け``\ **強い強調**\ で終える。
- 半角スペースが入る→ *強調して* ``インラインリテラルを続け`` **強い強調** で終える。
警告
このバックスラッシュのエスケープの利用は、非推奨です。処理前のドキュメントの可読性を悪くします。必要最小限の利用で留めてください。
一つのバッククォートで囲まれた文字列は、関連付けされる、索引とされる、リンクとされる、要約とされる、さもなければ何らかの処理が行われることを現す。
通常以下のように使われる。
:role:`解釈が行われる文字列`
`解釈が行われる文字列`:role:
上記の、前置若しくは後置の:role:によって、インタープリテッドテキストがどのように解釈されるか決まります。
ノート
後置のroleは非推奨です。
例えば以下のように利用できます。roleはコロンで囲まれて構成されます。
- 強調 はインタープリテッドテキストにstrong roleを与えてもこのように 強調 できます。
コード:
- *強調* はインタープリテッドテキストにstrong roleを与えてもこのように :strong:`強調` できます。
その他の要点は以下
- インタープリテッドテキストは、マークアップ構造の拡張を可能にする。
- 強調、強い強調、インライン文字列、ハイパーリンクの参照、などに対して、”class”や点滅など、私たちが望まないことも出来る。
- roleについては、http://docutils.sourceforge.net/docs/ref/rst/roles.html に記載があります。
- roleディレクティブで、roleを定義できます。
- 前以て定義されたroleのみ、解釈されます。
- また、アプリケーションが、特別なroleをサポートしていることもあります。
二つの連続したバッククォート(``)で囲まれた文字列は、インラインリテラルとして扱われます。
例:
- インラインリテラル の例
コード:
- ``インラインリテラル`` の例
その他の用件は以下
- インラインリテラルは2つの連続したバッククォート以外の文字列を含むことが出来ます。（前述の「インラインマークアップ認識ルール」にも記載)
- 強制改行は、保護されません。
- reStructuredTextのパーサー単体は、空白を保護して出力します。しかし、最終的な出力にまで残るかは、最終出力のフォーマッタにより決まるため、保証出来ません。
- 強制改行や、空白を保護する場合は、リテラルブロックを使うべきです。
- インラインリテラルは、コードの断片の記載に便利です。(例: [+-]?(\d+(\.\d*)?|\.\d+) )
前述の、「参照名」の章で記載している、参照名の後にアンダースコアを1つ若しくは2つ付ければハイパーリンクの参照を表現できます。
- 名前付けられたハイパーリンクの参照は、アンダースコア1つを後置→ 参照名_ 。
- 無名のハイパーリンクの参照は、アンダースコア2つを後置→ 参照名__ 。
ヒント
前述していますが、半角スペースを含んで参照名としたいときは、`で囲んでください。
以下のように、<>でURIを囲ったものを記述してください。
使用例:
コード:
こちらが `テストページ <http://www.sometest.com>`_ です。
こちらも、 `リンク先は同じ <テストページ_>`_ です。
↑のサンプルは以下と等しいです。:
こちらが `テストページ`_ です。
こちらも、 `リンク先は同じ`_ です。
`
.. _テストページ: http://www.sometest.com
.. _リンク先は同じ: テストページ_
警告
この定義方法はドキュメントの作成やメンテナンスは行い易いですが、.rstファイルの可読性が落ちます。最終出力のみが読まれる場合でない限り（例えばソースを配布しない等）、使用しないことを強く勧めます。
インラインインターナルターゲットは、「 ハイパーリンクターゲット 」記載の内部ハイパーリンクターゲットを明示的に定義できます。 “_`”と”`”で囲むと、ハイパーリンク名として定義できます。
- ここを インターナルターゲット と明示的に定義すると。
- この インターナルターゲット からジャンプを出来ます。
- 章は、暗黙的にインターナルのターゲット名を持つので、参照するだけで インラインインターナルターゲット へ飛べます。
コード:
- ここを _`インターナルターゲット` と明示的に定義すると。
- この `インターナルターゲット`_ からジャンプを出来ます。
- 章は、暗黙的にインターナルのターゲット名を持つので、参照するだけで `インラインインターナルターゲット`_ へ飛べます。
暗黙のハイパーリンクターゲット も参照してください。
“|”と”|”で挟むと、置換の参照を行えます。任意で”_”,”__”を後ろにつけることが出来ます。この場合は、アンダースコア1つが通常のリンクの参照、アンダースコア2つが無名のリンクの参照を兼ねることができます。
その他は、「 置換定義 」を参照してください。
URI ( 絶対URI若しくはeメールアドレス) は自動的にリンクが張られます。 要点は以下
- メールアドレスのみ”mailto:”を省略することが出来ます。
- URIの構造は、Official IANA Registry of URI Schemes と Retired Index of WWW Addressing Schemes を通じて知られているものに制限されます。
- URIの終端のコロンやカンマは、終端を山括弧(“>”) で閉じないと認識されません。
- アスタリスクやアンダースコア等の文字はURIに含まれます。これらの文字をマークアップ文字からエスケープさせるために、バックスラッシュを使用できます。 エスケープ も参照ください。
- reStructuredTextパーサーは、クエリやフラグメント、%エスケープシーケンス等の複雑なURI構造を認識できるはずである。
コード:
- http://www.yahoo.co.jp/ をみて下さい
- mailto:aaa@mail.somehost.com まで連絡下さい。
- aaa@mail.somehost.com まで連絡下さい。
全ての寸法は、正の浮動小数点方式の数と単位で構成される。数と単位の間には、スペースが入っている場合もある。単位は、リファレンスマニュアルで明記したところでのみサポートされる。
長さの単位は以下
- em (ems, フォントの高さ)
- ex (x-height, 文字”x”の高さ)
- px (pixels, 解像度に依存する)
- in (inches, 1インチは2.54cmです)
- cm (centimeters, センチメートル)
- mm (millimeters, ミリメートル)
- pt (points, 1pt=1/72in)
- pc (picas; 1pc=12pt)
上記のセットは、 length units in CSS (和訳は こちら ) と一致します。
“1.5em”, “20mm”, ”.5in”は全て有効な長さとしての値です。
単位を記述しない場合の数値は、ライターに依存するデフォルト値が使用されます (例: html4css1ではpx, latex2eはpt)。詳細は user doc 内のそれぞれのライターの仕様書を見て下さい。
別の値と相対的な値であることを表すパーセンテージ(“%”)は、前後関係に依存します。