reStructuredText にしたがって文書を書く際の約束を, よく使うであろうものにかぎって説明します. さらに詳しくは 参考リンク を参照されてください.
reStructuredTextではいくつか聞きなれない用語が使われています.
章立てとは,文書の構造を保つためになくてはならないもので, 「見出し」によって構成されます. reStructuredTextでは,それらのテキストにアンダーラインを引いたりすることで, 見出しであることを表現します(メールなどでも,自然にこのような表現をすることはありますね).
たとえばタイトル,セクション,サブセクション,サブサブセクション をつかって文書を構成するには,つぎのように書きます.
========================== タイトル ========================== セクション ========== サブセクション -------------- サブセクション -------------- セクション ========== サブセクション -------------- サブサブセクション `````````````````` @@author: 崎間@@ @@accept: 執筆中@@ @@category: 力学@@
うえのソースをHTMLに変換すると,つぎのようになります.
文字列の下に = などを連続して付けることで, その文字列が見出しであることを示します. = などは,見出し文字列以上の長さにしてください.つまり
セクション ===
では不十分で,
セクション ===================================
などは問題ありません.また,アンダーラインだけでなく
========== セクション ==========
のようにオーバーラインを引くことも可能です.
いずれの場合も,見出し部分の前に空白行が必要ですので,注意してください.
見出しとして示すのに使える記号は
= - ` : . ' " ~ ^ _ * + #
です(他にももう少し使える記号の種類はあるのですが,上のものが推奨されています).
記号の種類と見出しのレベル(セクション,サブセクションなど)は 無関係 です. それぞれ,登場した順にタイトル,セクション,サブセクション,サブサブセクション,…… と割り振られます.
上の例の最後に
@@author: 崎間@@ @@accept: 執筆中@@ @@category: 力学@@
という部分があります.これら @@ ではじまる命令は, 物理のかぎプロジェクト用の特別なものです. 詳しくは reStructuredText拡張機能 をご覧ください.
文を表現するには,普通にテキストを書きます. 文の途中にある連続していない改行は,まったく意味を持ちません 言い換えると,文中ではどこでも改行できます.
つぎの例をみてもらうのが分かりやすいでしょう.
========================== タイトル ========================== このようにべた書きしたテキストは,普通の文として扱われます. 文の途中で は,一つだけの改行は意味を持ちません. 連続した改行は,段落の区切りになります. これは,LaTeXでの書き方と同じですね! セクション ==========
これをHTMLに変換すると
のようになります.
リスト(箇条書き)するには,
- このように - 書くと - 箇条書きされます
のように,行頭を - で書きます. この他の記号として, * と + が使えます.
リストの先頭に番号を付けたい場合,
1. このように 2. 書くと 3. 箇条書きされます
のように,先頭を 数字. と書きます (行頭にはスペースを入れないでください). ピリオド後ろにはスペースが必要です.また,
3. このように 4. 書くと 5. 箇条書きされます
のように,中途半端な番号からはじめることもできます.
定義リストとは「用語」と「その説明」をリストするものです.
用語1 ここに用語の説明を書きます 用語2 ここにその用語の説明を 書いて行きます.
のように,説明部分先頭にスペースを入れ,インデントを設けて記述します.
強調したい文字列の両側を
地の文地の文地の文 *強調したい文字列* 地の文地の文地の文
のように * で括ると,変換後はその部分の文字列が
と,太字になって強調されます. このとき, * と地の文の間には スペースが入っている必要があるので,注意してください.
さらに強調したい場合は,
地の文地の文地の文 **強調したい文字列** 地の文地の文地の文
のように,強調したい文字列を ** で括ります. すると,変換後は
というふうに太字赤色になり,少し大きいサイズで表示されます.
Java `TM`:sup:
とすると,Javaの右肩にTMが乗ります.
v `1`:sub:
とすると,vの右下に1が付きます.
文字にリンクを張りたい場合
ちなみにこういった任意定数は,初期条件に依って決まります. この例題について詳しくは, 物理のかぎしっぽ_ をご覧ください. .. _物理のかぎしっぽ: http://www12.plala.or.jp/ksp/
のように,リンクを張りたい文字列に
物理のかぎしっぽ_
と最後に「_」を付け,そのリンク先を
.. _物理のかぎしっぽ: http://www12.plala.or.jp/ksp/
とうふうに記述します. リンク先記述部分は,文書中のどこにあっても構いません. リンクを張りたい文字列と地の文との間には, スペースを入れた方が読みやすいでしょう(必ずしも入れる必要はありません).
リンクにしたい文字列が「my documents」や「式(1)」のように,空白文字(スペース)や記号「()」などを含む場合,その文字列を
`my documents`_
や
`式(1)`_
のようにバッククォート(Shiftキー + @キー)で括ります.
「式(1)」をクリックしたら,該当の数式へ飛ばすような場合など,ページ内にリンクを張りたいことがあります.それには
.. _eq1: <tex> F=G\frac{Mm}{r^2} \tag{1} </tex>
というふうに, .. _ターゲット名: に続けて数式(や文字列)を書きます. この例では「eq1」がターゲット名です. これで
<tex> F=G\frac{Mm}{r^2} \tag{1} </tex>
が変換された画像(の先頭部分)がリンクターゲットになります. このターゲットへリンクを張るには
ここで `式(1)`_ になんとか .. _式(1): #eq1
というふうに . _ターゲット1: #ターゲット2 とします. これで「ターゲット1」をクリックすると「ターゲット2」に飛びます. この例では「式(1)」という文字をクリックすると, 上で設定した数式に飛ぶようになります.
表をつくるには,
.. csv-table:: キャプション :header: "見出し1", "見出し2", "見出し3" "値1", "値2", "値3" "物理の", "かぎ", "しっぽ"
のように,カンマ区切りでデータを並べます.サンプルソースとその出力は,以下をご覧ください.
(さらに詳しく)
"image" ディレクティブを使い,つぎのように画像を挿入します.
.. image:: picture.png
この例では,同一ディレクトリにある picture.png という画像ファイルが挿入されます. さらに,詳細オプションを含めるには,つぎのようにフィールドリストを追加します.
.. image:: picture.jpeg :height: 100 :width: 200 :scale: 50 :alt: alternate text :align: right
これらのオプションは,つぎのような意味です.
図の下にキャプション(簡単な説明文)を入れたい場合 .. figure:: を使い
.. figure:: 画像ファイル名 キャプション
のようにしてください.キャプションの文字が少し小さくなり, 文字列の左端が画像の左端と揃えられます. .. figure:: 行の下に空白行が入ることに気を付けてください.
インライン(文中)に画像を含めることもできます.それには
この |imgname| という画像は,なになにです. .. |imgname| image:: 画像ファイル名
のように |ターゲット名| という命令で ターゲットを設定しておきます. この例では「imgname」がターゲット名です. そして .. |ターゲット名| image:: 画像ファイル名 という命令で, 文中のターゲット部分に画像を挿入します.
重要な段落を強調したい場合 .. important:: 命令を使います. たとえば
エネルギーとは,物理で良く出てくるおなじみの量です. 簡単に復習しておきますと, .. important:: あるモノが他のモノに対して仕事をする能力をもっているとき, そのモノはエネルギーをもっている と決められた量でした.「エネルギー問題」でのエネルギーも同様に, 何らかの仕事をするものです.仕事とは,たとえばテレビをつけたり, 車を動かしたり,冷暖房を運転したりするものです.
の出力は
となります.ここぞというときに用いると良いでしょう.
本文から逸れる内容は注釈として記述します. 注釈を加えるには [*]_ を注釈を加えたい部分に記述し, 段落をあけて .. [*] の後ろにその内容を記述します. 注釈部分が複数行に渡る場合,先頭にスペースを入れてインデントします. たとえば
あくまで「現在確認されている」資源がどれくらいもつかですので, 場合場合によって多少増減しています. もう少し増えるかもしれません [*]_ . ですが,そう遠くない将来,これらの資源が 枯渇することは避けられないでしょう. それに,石油などは産出地域が限られていますので, 世界情勢によっては入手困難になるという問題もあります. .. [*] さらに,石油が染みこんだ砂や岩(利用するのに手間はかかる)なども, かなりの量存在すると言われています. これらは,オイルサンドやオイルシェールと言われます.
をHTMLに変換した結果は
のようになります.
また,複数の注釈を加えたい場合も同様で,
この引っ張る力が重力 [*]_ であり,この力の法則が,万有引力 [*]_ です. .. [*] 重力についての注釈 .. [*] 万有引力ついての注釈
のように [*]_ と .. [*] 命令を使います. それぞれ, .. [*] 命令を書いた順番に対応づけられます.
これらの注釈は,PDF版ではLaTeXの \footnote 命令として処理されています.
どうしてもreStructuredTextで用意されている形式で扱えないもの, たとえばJava AppletやFlashを組み込む命令を記述したい場合, HTMLタグを直接reStructuredTextのソースに記述することになります.
そのためには,.. 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を記事に埋め込みたい場合のみに使うものであって, 文字装飾やデザイン上の変更を行うために用いるのはのは望ましくありません. 必要最小限で使用してください.