*reStructuredText [#h8ab1cc6]
[[かぎマニュアルズ]] > [[記事制作方法>かぎマニュアルズ#wbdd8eaa]]
[[reStructuredText]] とは，テキストを書く際の約束ごとのようなものです．実体はテキストファイルです．メモ帳でも簡単に作成できます．普通のテキストファイルとちょっと違うのは，構造化情報を持たせることができる，という点です．
物理のかぎプロジェクトでは，この [[reStructuredText]] に基づいたテキストを記述し，記事を制作します．そのために，ある程度の仕組みと書式を覚えていただく必要があります．といっても，普通に記事を書く分にはそれほど難しくありませんので，このページや [[物理のかぎ記事チュートリアル]] を参照しながら，気軽に取り組んで行って下さい♪
----
#contents
* どうやってつくるのか [#u8f065c3]
メモ帳などの普通のテキストエディタで，普通に保存すればいいです．拡張子は気にしなくてかまいませんが，テキストファイルですから「.txt」としておけば良いでしょう（普通は勝手にそうなりますね）．重要なのは書き方です．
そしてその，[[reStructuredText]] という約束に基づいたテキストファイルを，たとえばHTMLに変換すると，その約束に基づいた構造が保たれたまま変換されます．変換には [[rst2hooktail>http://hooktail.maxwell.jp/rst2hooktail/index.html]] をお使いください．ただしこれは，TeX数式処理やHTMLの表示スタイルなど，物理のかぎプロジェクトぽ用にカスタマイズが施されています（文書構造そのものは [[reStructuredText]] に基づいています）．
** 構造化とは [#u13600d6]
「Structured Text」とは「構造化されたテキスト」の意味ですが，厳密な構造ではなく，自由度の高い，ある一定のパターンを含んでいるというべきでしょうか．そのパターンを解析するコンバータで変換することで，XHTMLやLaTeXフォーマットのような厳密な構造を出力できます．要するに気の利いたテキストファイルです．
* リファレンス [#g98c211a]
[[reStructuredText]] にしたがって文書を書く際の約束を，
よく使うであろうものにかぎって説明します．
さらに詳しくは [[はやわかりreStructuredText>http://www.planewave.org/translations/rst/quickref.html]] や [[公式マニュアル>http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html]]
（残念ながら英語ですが，最も情報量が多いです）を参照されてください．
** 注意 [#y422bb54]
-以下の説明で，「スペース」とは半角スペースのことです．
数字や「.」，「_」，「:」などの記号も全て半角文字です．
-以下の説明で，&color(#f00){赤字}; で書いたもの
が [[reStructuredText]] の命令です．
-特別な理由がない限り，行の先頭にはスペースを含めないでください．
行頭のスペースは [[reStructuredText]] の命令の一つですので，
思わぬ結果を招くことになります．
** 章立て [#mdb2d67d]
章立てとは，文書の構造を保つためになくてはならないものです．
最低限，「タイトル」，「節」，「小節」くらいを覚えておきましょう．
[[reStructuredText]]では，
==========================
タイトル
==========================
セクション 1
--------------------------
サブセクション 1.1
^^^^^^^^^^^^^^^^^^^^^^^^^^
サブサブセクション 1.1.2
~~~~~~~~~~~~~~~~~~~~~~~~~~
サブセクション 1.2
^^^^^^^^^^^^^^^^^^^^^^^^^^
サブサブセクション 1.1.2
~~~~~~~~~~~~~~~~~~~~~~~~~~
セクション 2
--------------------------
サブセクション 2.1
^^^^^^^^^^^^^^^^^^^^^^^^^^
サブセクション 2.2
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@author:@@
@@accept:@@
- [[この例の変換結果>http://hooktail.org/hooktailreST-sample/sample01.html]]
という感じで，章立てを記述します．ご覧の通り，見出し文の下部に「----」を付けたりして，その文が見出しであることを示します．直感的にも分かりやすい表記法ですね．
必ずしもこの例で示した通りの記号を用いる必要はありません．
が，一つの文書において同じレベルの見出しには，
同じ記号を用いる必要があります．
さらに細かくセクション分けを加える場合は，同様に適当な見出し記号を追加します．
通常はサブセクションくらいまでで十分でしょう．
上の例の最後に
@@author:@@
@@accept:@@
という部分があります．ここに，書いた人の名前，正式公開日の日付を
@@author: 崎間@@
@@accept: 2005-01-22@@
などというふうに記入します．acceptの部分はいつになるか分からないので，査読に提出する際は@@accept:@@のままで構いません（@@author:@@と@@accept:@@の二つの命令は，物理のかぎプロジェクト独自の拡張です）．
以上が，文書作成の骨組みになります．
**段落 [#q4d21bb4]
連続した行は，途中で改行が入っても一つの段落とみなされます．
という感じで，章立てを記述します．
ご覧の通り，見出し文の下部に「----」を付けたりして，
その文が見出しであることを示します．
は一つの段落として，途中に改行を含めず表示されます．
という感じで，章立てを記述します．
ご覧の通り，見出し文の下部に「----」を付けたりして，
その文が見出しであることを示します．
のように，途中で空行が入ると，その上と下は違う段落として表示されます．
**リスト [#z21242cc]
リスト（箇条書き）するには，
- このように
- 書くと
- 箇条書きされます
のように，行頭を &color(#f00){-}; で書きます．
この他の記号として， &color(#f00){*}; と &color(#f00){+}; が使えます．
***番号付きリスト [#z83cd06a]
リストの先頭に番号を付けたい場合，
1. このように
2. 書くと
3. 箇条書きされます
のように，先頭を &color(#f00){数字.}; と書きます
（行頭にはスペースを入れないでください）．
ピリオド後ろにはスペースが必要です．また，
3. このように
4. 書くと
5. 箇条書きされます
のように，中途半端な番号からはじめることもできます．
***定義リスト [#d4db8a0e]
定義リストとは「用語」と「その説明」をリストするものです．
用語1
ここに用語の説明を書きます
用語2
ここにその用語の説明を
書いて行きます．
のように，説明部分先頭にスペースを入れ，インデントを設けて記述します．
** 文字装飾 [#rd506246]
*** 強調その１ [#g9624f41]
強調したい文字列の両側を
地の文地の文地の文 *強調したい文字列* 地の文地の文地の文
のように &color(#f00){*}; で括ると，変換後はその部分の文字列が
#ref(em.png,nolink)
と，太字になって強調されます．
このとき， &color(#f00){*}; と地の文の間には
スペースが入っている必要があるので，注意してください．
*** 強調その２ [#h880a2da]
さらに強調したい場合は，
地の文地の文地の文 **強調したい文字列** 地の文地の文地の文
のように，強調したい文字列を &color(#f00){**}; で括ります．
すると，変換後は
#ref(strong.png,nolink)
というふうに太字赤色になり，少し大きいサイズで表示されます．
*** 上付き文字 [#m7198313]
Java `TM`:sup:
とすると，Javaの右肩にTMが乗ります．
*** 下付き文字 [#dbb18719]
v `1`:sub:
とすると，vの右下に1が付きます．
**リンク [#nc527202]
文字にリンクを張りたい場合
ちなみにこういった任意定数は，初期条件に依って決まります．
この例題について詳しくは， 物理のかぎしっぽ_ をご覧ください．
.. _物理のかぎしっぽ: http://www12.plala.or.jp/ksp/
のように，リンクを張りたい文字列に
物理のかぎしっぽ_
と最後に「_」を付け，そのリンク先を
.. _物理のかぎしっぽ: http://www12.plala.or.jp/ksp/
とうふうに記述します．
リンク先記述部分は，文書中のどこにあっても構いません．
リンクを張りたい文字列と地の文との間には，
スペースを入れた方が読みやすいでしょう（必ずしも入れる必要はありません）．
***空白を含む文字列へのリンク [#f7ce6493]
リンクにしたい文字列が「my documents」や「式(1)」のように，空白文字（スペース）や記号「（）」などを含む場合，その文字列を
`my documents`_
や
`式(1)`_
のようにバッククォート（Shiftキー + @キー）で括ります．
***ページ内の相互参照 [#hc6adeae]
「式(1)」をクリックしたら，該当の数式へ飛ばすような場合など，ページ内にリンクを張りたいことがあります．それには
.. _eq1:
<tex>
F=G\frac{Mm}{r^2} \tag{1}
</tex>
というふうに， &color(#f00){.. _ターゲット名:};
に続けて数式（や文字列）を書きます．
この例では「eq1」がターゲット名です．
これで
<tex>
F=G\frac{Mm}{r^2} \tag{1}
</tex>
が変換された画像（の先頭部分）がリンクターゲットになります．
このターゲットへリンクを張るには
ここで `式(1)`_ になんとか
.. _式(1): #eq1
というふうに &color(#f00){. _ターゲット1: #ターゲット2}; とします．
これで「ターゲット1」をクリックすると「ターゲット2」に飛びます．
この例では「式(1)」という文字をクリックすると，
上で設定した数式に飛ぶようになります．
**表組み [#p6727763]
表をつくるには，
.. csv-table:: Frozen Delights!
:header: "Treat", "Quantity", "Description"
:widths: 15, 10, 30
"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
crunchy, now would it?"
"Gannet Ripple", 1.99, "On a stick!"
のように，カンマ区切りでデータを並べます．（[[さらに詳しく>http://docutils.sourceforge.net/docs/ref/rst/directives.html#id3]]）
**画像 [#m9859d81]
文書に画像を挿入するには，挿入したい場所に
.. image:: 画像ファイル名
と書きます． &color(#f00){.. image::}; が，そこに画像を挿入するという命令です．
***画像の縦横などの詳細を含める [#ac24f783]
挿入する画像について，幅や代替テキストなどの詳細を含めるには
.. image:: 画像ファイル名
:height: 100
:width: 200
:alt: 代替テキスト
とします．heightおよびwidthはピクセル値です．
*** インライン画像 [#x2bf301c]
インライン（文中）に画像を含めることもできます．それには
この |imgname| という画像は，なになにです．
.. |imgname| image:: 画像ファイル名
のように &color(#f00){|ターゲット名|}; という命令で
ターゲットを設定しておきます．
この例では「imgname」がターゲット名です．
そして &color(#f00){.. |ターゲット名| image:: 画像ファイル名}; という命令で，
文中のターゲット部分に画像を挿入します．
*** キャプション [#j9719991]
図の下にキャプション（簡単な説明文）を入れたい場合 &color(#f00){.. figure::}; を使い
.. figure:: 画像ファイル名
キャプション
のようにしてください．キャプションの文字が少し小さくなり，
文字列の左端が画像の左端と揃えられます．
&color(#f00){.. figure::}; 行の下に空白行が入ることに気を付けてください．
** 注釈 [#pdd02526]
本文から逸れる内容は注釈として記述します．注釈を加えるには
この引っ張る力が重力 [*]_ であり，
.. [*] 重力についての注釈
のように， &color(#f00){[*]_}; を注釈を加えたい部分に記述し，
&color(#f00){.. [*]}; の後ろにその内容を記述します．
注釈部分が複数行に渡る場合，先頭にスペースを入れてインデントします．
これらの命令と地の文の間にはスペースが必要です．
注釈は &color(#f00){.. [*]}; を記述した部分に表示されます．
通常， &color(#f00){[*]_}; を書いた段落の
すぐ後に表示されるようにすると良いでしょう．
複数の注釈を加えたい場合も同様で，
この引っ張る力が重力 [*]_ であり，この力の法則が，万有引力 [*]_ です．
.. [*] 重力についての注釈
.. [*] 万有引力ついての注釈
のように &color(#f00){[*]_}; と &color(#f00){.. [*]}; 命令を使います．
&color(#f00){.. [*]}; 命令を書いた順番に対応づけられます．
** HTMLの命令を直接記述する [#k059ab1a]
どうしても[[reStructuredText]]で用意されている形式で扱えないもの，たとえばJava AppletやFlashを記述したい場合，その命令（HTMLタグ）を直接[[reStructuredText]]のソースに記述することになります．
そのためには， &color(#f00){.. raw:: html}; という命令（rawディレクティブ）を使用します．たとえば
.. raw:: html
<hr width=50 size=10>
のように書いた場合，
<hr width=50 size=10>
がHTMLタグとして記述されます．すなわちこの記述部分に，短い水平線が表示されます（rawディレクティブを用いず単に <hr width=50 size=10> と書いた場合，その文字列がそのまま出力されます）．
ただし，この命令はJava AppletやFlashを記事に埋め込みたい場合のみに使うものであって，文字装飾やデザイン上の変更行うためのものではありません．必要最小限で利用してください．
// &color(#f00){};
[[かぎマニュアルズ]] > [[記事制作方法>かぎマニュアルズ#wbdd8eaa]]
reStructuredText のバックアップソース(No.33)
