* reStructuredTextリファレンス [#m4ba9945]
[[かぎマニュアルズ]] > [[記事制作方法>かぎマニュアルズ#wbdd8eaa]] >
reStructuredText にしたがって文書を書く際の約束を，
よく使うであろうものにかぎって説明します．
さらに詳しくは [[参考リンク>reStructuredTextリファレンス#la3926d0]] を参照されてください．
#contents
* 注意 [#y422bb54]
-以下の説明で，「スペース」とは半角スペースのことです．
数字や「.」，「_」，「:」などの記号も全て半角文字です．
-以下の説明で，&color(#f00){赤字}; で書いているものは，
reStructuredTextの命令です．
-以下の説明で，&color(#090){緑字}; で書いているものは，
物理のかぎプロジェクトによる拡張命令です．
-特別な理由がない限り，行の先頭にはスペースを含めないでください．
行頭のスペースは reStructuredText の命令の一つですので，
思わぬ結果を招くことになります．
* 用語 [#uc6a8ad6]
reStructuredTextではいくつか聞きなれない用語が使われています．
: ディレクティブ | ".. image:: " などの命令のこと
* 章立て [#mdb2d67d]
章立てとは，文書の構造を保つためになくてはならないもので，
「見出し」によって構成されます．
reStructuredTextでは，それらのテキストにアンダーラインを引いたりすることで，
見出しであることを表現します（メールなどでも，自然にこのような表現をすることはありますね）．
たとえばタイトル，セクション，サブセクション，サブサブセクション
をつかって文書を構成するには，つぎのように書きます．
==========================
タイトル
==========================
セクション
==========
サブセクション
--------------
サブセクション
--------------
セクション
==========
サブセクション
--------------
サブサブセクション
``````````````````
@@author: 崎間@@
@@accept: 執筆中@@
@@category: 力学@@
うえのソースをHTMLに変換すると，つぎのようになります．
#ref(sections.png,nolink)
文字列の下に &color(#f00){=}; などを連続して付けることで，
その文字列が見出しであることを示します．
&color(#f00){=}; などは，見出し文字列以上の長さにしてください．つまり
セクション
===
では不十分で，
セクション
===================================
などは問題ありません．また，アンダーラインだけでなく
==========
セクション
==========
のようにオーバーラインを引くことも可能です．
いずれの場合も，見出し部分の前に空白行が必要ですので，注意してください．
** 見出し文字列を示すのに使える記号 [#xe79c702]
見出しとして示すのに使える記号は
= - ` : . ' " ~ ^ _ * + #
です（他にももう少し使える記号の種類はあるのですが，上のものが推奨されています）．
** 見出しのレベル [#w5098f76]
記号の種類と見出しのレベル（セクション，サブセクションなど）は ''無関係'' です．
それぞれ，登場した順にタイトル，セクション，サブセクション，サブサブセクション，……
と割り振られます．
** @@の命令 [#me3fe291]
上の例の最後に
@@author: 崎間@@
@@accept: 執筆中@@
@@category: 力学@@
という部分があります．これら &color(#090){@@}; ではじまる命令は，
物理のかぎプロジェクト用の特別なものです．
詳しくは [[reStructuredText拡張機能]] をご覧ください．
* 文と段落 [#q4d21bb4]
文を表現するには，普通にテキストを書きます．
文の途中にある連続していない改行は，まったく意味を持ちません
文の途中にある連続していない改行は，まったく意味を持ちません．
言い換えると，文中ではどこでも改行できます．
つぎの例をみてもらうのが分かりやすいでしょう．
==========================
タイトル
==========================
このようにべた書きしたテキストは，普通の文として扱われます．
文の途中で
は，一つだけの改行は意味を持ちません．
連続した改行は，段落の区切りになります．
これは，LaTeXでの書き方と同じですね！
セクション
==========
これをHTMLに変換すると
#ref(para1.png,nolink)
のようになります．
* リスト [#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:: キャプション
:header: "見出し1", "見出し2", "見出し3"
"値1", "値2", "値3"
"物理の", "かぎ", "しっぽ"
のように，カンマ区切りでデータを並べます．サンプルソースとその出力は，以下をご覧ください．
#ref(table.txt)
- [[table.txtの変換結果>http://hooktail.maxwell.jp/kagi/cb490047835e67bda983ccf5e364d9e2.html]]
（[[さらに詳しく>http://docutils.sourceforge.net/docs/ref/rst/directives.html#id3]]）
* 画像 [#m9859d81]
** image [#q71207a4]
"image" ディレクティブを使い，つぎのように画像を挿入します．
.. image:: picture.png
この例では，同一ディレクトリにある picture.png という画像ファイルが挿入されます．
さらに，詳細オプションを含めるには，つぎのようにフィールドリストを追加します．
.. image:: picture.jpeg
:height: 100
:width: 200
:scale: 50
:alt: alternate text
:align: right
これらのオプションは，つぎのような意味です．
: alt | 代替テキスト．画像についての短い説明を書きます．画像を表示できないブラウザでは，代替テキストが表示されます．また，音声ブラウザでも代替テキストが読み上げられるので，できるだけ書いておいた方がいいです．
: height | 半角数字で整数を記入して，画像の高さをピクセルで指定します．"scale" オプションを指定していると，これらはまとめて処理されます．例えば "height" が "200" で "scale" が "50" なら，"scale" が指定されていない場合の "100" と等価です．
: width | 半角数字で整数を記入して，画像の幅をピクセルで指定します．"scale" との関係は "height" と同様です．
: scale | 半角数字で整数を記入して，画像にスケーリング要素をもたせます（"%" 記号は要りません）．scale オプションを省略した場合は "100"（フルサイズ）として扱われます．"height" もしくは "widht" オプションが与えられていない場合，"scale" は特定できません．
: align | "top", "middle", "bottom", "left", "center", or "right" を指定します．画像のアラインメントを指定できます（が，ちょっと表示がずれるかもしれません）．
: target | URLか参照名（name_ など）を指定し，画像にハイパーリンクを張ります．
: class | class属性を指定します．
** figure [#e3d24358]
** キャプション [#j9719991]
図の下にキャプション（簡単な説明文）を入れたい場合 &color(#f00){.. figure::}; を使い
.. figure:: 画像ファイル名
キャプション
のようにしてください．キャプションの文字が少し小さくなり，
文字列の左端が画像の左端と揃えられます．
&color(#f00){.. figure::}; 行の下に空白行が入ることに気を付けてください．
** インライン画像 [#x2bf301c]
インライン（文中）に画像を含めることもできます．それには
この |imgname| という画像は，なになにです．
.. |imgname| image:: 画像ファイル名
のように &color(#f00){|ターゲット名|}; という命令で
ターゲットを設定しておきます．
この例では「imgname」がターゲット名です．
そして &color(#f00){.. |ターゲット名| image:: 画像ファイル名}; という命令で，
文中のターゲット部分に画像を挿入します．
* 段落の強調 [#gdcd68f2]
重要な段落を強調したい場合 &color(#f00){.. important::}; 命令を使います．
たとえば
エネルギーとは，物理で良く出てくるおなじみの量です．
簡単に復習しておきますと，
.. important::
あるモノが他のモノに対して仕事をする能力をもっているとき，
そのモノはエネルギーをもっている
と決められた量でした．「エネルギー問題」でのエネルギーも同様に，
何らかの仕事をするものです．仕事とは，たとえばテレビをつけたり，
車を動かしたり，冷暖房を運転したりするものです．
の出力は
#ref(important.png,nolink)
となります．ここぞというときに用いると良いでしょう．
* 注釈 [#pdd02526]
本文から逸れる内容は注釈として記述します．
注釈を加えるには &color(#f00){[*]_}; を注釈を加えたい部分に記述し，
段落をあけて &color(#f00){.. [*]}; の後ろにその内容を記述します．
注釈部分が複数行に渡る場合，先頭にスペースを入れてインデントします．
たとえば
あくまで「現在確認されている」資源がどれくらいもつかですので，
場合場合によって多少増減しています．
もう少し増えるかもしれません [*]_ ．
ですが，そう遠くない将来，これらの資源が
枯渇することは避けられないでしょう．
それに，石油などは産出地域が限られていますので，
世界情勢によっては入手困難になるという問題もあります．
.. [*]
さらに，石油が染みこんだ砂や岩（利用するのに手間はかかる）なども，
かなりの量存在すると言われています．
これらは，オイルサンドやオイルシェールと言われます．
をHTMLに変換した結果は
#ref(footnote.png,nolink)
のようになります．
また，複数の注釈を加えたい場合も同様で，
この引っ張る力が重力 [*]_ であり，この力の法則が，万有引力 [*]_ です．
.. [*] 重力についての注釈
.. [*] 万有引力ついての注釈
のように &color(#f00){[*]_}; と &color(#f00){.. [*]}; 命令を使います．
それぞれ， &color(#f00){.. [*]}; 命令を書いた順番に対応づけられます．
これらの注釈は，PDF版ではLaTeXの \footnote 命令として処理されています．
* 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> と書いた場合，
その文字列が（HTMLタグとしてではなく）そのまま出力されます．
ただし，この命令はJava AppletやFlashを記事に埋め込みたい場合のみに使うものであって，
文字装飾やデザイン上の変更を行うために用いるのはのは望ましくありません．
必要最小限で使用してください．
* 参考リンク [#la3926d0]
- [[はやわかりreStructuredText:http://www.planewave.org/translations/rst/quickref.html]] Quick reStructuredTextの日本語訳
- [[A ReStructuredText Primer:http://docutils.sourceforge.net/docs/user/rst/quickstart.html]] 大雑把な解説
- [[Quick reStructuredText:http://docutils.sourceforge.net/docs/user/rst/quickref.html]] リファレンス
- [[reStructuredText Markup Specification:http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html]] もっとも詳しい（けど長い）
- [[reStructuredText Directives:http://docutils.sourceforge.net/docs/ref/rst/directives.html]] ディレクティブ（.. image:: など）の詳細
#br
#br
[[かぎマニュアルズ]] > [[記事制作方法>かぎマニュアルズ#wbdd8eaa]] >
reStructuredTextリファレンス の変更点
