- 追加された行はこの色です。
- 削除された行はこの色です。
* reStructuredTextリファレンス [#m4ba9945]
[[かぎマニュアルズ]] > [[記事制作方法>かぎマニュアルズ#wbdd8eaa]] >
reStructuredText にしたがって文書を書く際の約束を,
よく使うであろうものにかぎって説明します.
さらに詳しくは [[参考リンク>reStructuredTextリファレンス#la3926d0]] を参照されてください.
#contents
* 注意 [#y422bb54]
-以下の説明で,「スペース」とは半角スペースのことです.
数字や「.」,「_」,「:」などの記号も全て半角文字です.
-以下の説明で,&color(#f00){赤字}; で書いたもの
が reStructuredText の命令です.
-以下の説明で,&color(#f00){赤字}; で書いているものは,
reStructuredTextの命令です.
-以下の説明で,&color(#090){緑字}; で書いているものは,
物理のかぎプロジェクトによる拡張命令です.
-特別な理由がない限り,行の先頭にはスペースを含めないでください.
行頭のスペースは reStructuredText の命令の一つですので,
思わぬ結果を招くことになります.
* 用語 [#uc6a8ad6]
reStructuredTextではいくつか聞きなれない用語が使われています.
: ディレクティブ | ".. image:: " などの命令のこと
* 章立て [#mdb2d67d]
章立てとは,文書の構造を保つためになくてはならないものです.
最低限,「タイトル」,「節」,「小節」くらいを覚えておきましょう.
reStructuredText では,
章立てとは,文書の構造を保つためになくてはならないもので,
「見出し」によって構成されます.
reStructuredTextでは,それらのテキストにアンダーラインを引いたりすることで,
見出しであることを表現します(メールなどでも,自然にこのような表現をすることはありますね).
たとえばタイトル,セクション,サブセクション,サブサブセクション
をつかって文書を構成するには,つぎのように書きます.
==========================
タイトル
==========================
セクション 1
--------------------------
セクション
==========
サブセクション 1.1
^^^^^^^^^^^^^^^^^^^^^^^^^^
サブセクション
--------------
サブサブセクション 1.1.2
~~~~~~~~~~~~~~~~~~~~~~~~~~
サブセクション
--------------
サブセクション 1.2
^^^^^^^^^^^^^^^^^^^^^^^^^^
セクション
==========
サブサブセクション 1.1.2
~~~~~~~~~~~~~~~~~~~~~~~~~~
サブセクション
--------------
サブサブセクション
``````````````````
セクション 2
--------------------------
サブセクション 2.1
^^^^^^^^^^^^^^^^^^^^^^^^^^
サブセクション 2.2
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@author:@@
@@accept:@@
@@author: 崎間@@
@@accept: 執筆中@@
@@category: 力学@@
- [[この例の変換結果>http://hooktail.org/hooktailreST-sample/sample01.html]]
うえのソースをHTMLに変換すると,つぎのようになります.
という感じで,章立てを記述します.ご覧の通り,見出し文の下部に「----」を付けたりして,その文が見出しであることを示します.直感的にも分かりやすい表記法ですね.
#ref(sections.png,nolink)
必ずしもこの例で示した通りの記号を用いる必要はありません.
が,一つの文書において同じレベルの見出しには,
同じ記号を用いる必要があります.
さらに細かくセクション分けを加える場合は,同様に適当な見出し記号を追加します.
通常はサブセクションくらいまでで十分でしょう.
文字列の下に &color(#f00){=}; などを連続して付けることで,
その文字列が見出しであることを示します.
&color(#f00){=}; などは,見出し文字列以上の長さにしてください.つまり
上の例の最後に
セクション
===
@@author:@@
@@accept:@@
では不十分で,
という部分があります.ここに,書いた人の名前,正式公開日の日付を
セクション
===================================
@@author: 崎間@@
@@accept: 2005-01-22@@
などは問題ありません.また,アンダーラインだけでなく
などというふうに記入します.acceptの部分はいつになるか分からないので,査読に提出する際は@@accept:@@のままで構いません(@@author:@@と@@accept:@@の二つの命令は,物理のかぎプロジェクト独自の拡張です).
==========
セクション
==========
以上が,文書作成の骨組みになります.
のようにオーバーラインを引くことも可能です.
いずれの場合も,見出し部分の前に空白行が必要ですので,注意してください.
* 段落 [#q4d21bb4]
連続した行は,途中で改行が入っても一つの段落とみなされます.
** 見出し文字列を示すのに使える記号 [#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]
** 強調その1 [#g9624f41]
強調したい文字列の両側を
地の文地の文地の文 *強調したい文字列* 地の文地の文地の文
のように &color(#f00){*}; で括ると,変換後はその部分の文字列が
#ref(em.png,nolink)
と,太字になって強調されます.
このとき, &color(#f00){*}; と地の文の間には
スペースが入っている必要があるので,注意してください.
** 強調その2 [#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" ディレクティブを使い,つぎのように画像を挿入します.
と書きます. &color(#f00){.. image::}; が,そこに画像を挿入するという命令です.
.. image:: picture.png
** 画像の縦横などの詳細を含める [#ac24f783]
この例では,同一ディレクトリにある picture.png という画像ファイルが挿入されます.
さらに,詳細オプションを含めるには,つぎのようにフィールドリストを追加します.
挿入する画像について,幅や代替テキストなどの詳細を含めるには
.. image:: 画像ファイル名
.. image:: picture.jpeg
:height: 100
:width: 200
:alt: 代替テキスト
:scale: 50
:alt: alternate text
:align: right
とします.heightおよびwidthはピクセル値です.
これらのオプションは,つぎのような意味です.
: 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:: 画像ファイル名}; という命令で,
文中のターゲット部分に画像を挿入します.
** キャプション [#j9719991]
図の下にキャプション(簡単な説明文)を入れたい場合 &color(#f00){.. figure::}; を使い
.. figure:: 画像ファイル名
* 段落の強調 [#gdcd68f2]
重要な段落を強調したい場合 &color(#f00){.. important::}; 命令を使います.
たとえば
エネルギーとは,物理で良く出てくるおなじみの量です.
簡単に復習しておきますと,
キャプション
.. important::
あるモノが他のモノに対して仕事をする能力をもっているとき,
そのモノはエネルギーをもっている
と決められた量でした.「エネルギー問題」でのエネルギーも同様に,
何らかの仕事をするものです.仕事とは,たとえばテレビをつけたり,
車を動かしたり,冷暖房を運転したりするものです.
のようにしてください.キャプションの文字が少し小さくなり,
文字列の左端が画像の左端と揃えられます.
&color(#f00){.. figure::}; 行の下に空白行が入ることに気を付けてください.
の出力は
#ref(important.png,nolink)
となります.ここぞというときに用いると良いでしょう.
* 注釈 [#pdd02526]
本文から逸れる内容は注釈として記述します.注釈を加えるには
本文から逸れる内容は注釈として記述します.
注釈を加えるには &color(#f00){[*]_}; を注釈を加えたい部分に記述し,
段落をあけて &color(#f00){.. [*]}; の後ろにその内容を記述します.
注釈部分が複数行に渡る場合,先頭にスペースを入れてインデントします.
たとえば
この引っ張る力が重力 [*]_ であり,
あくまで「現在確認されている」資源がどれくらいもつかですので,
場合場合によって多少増減しています.
もう少し増えるかもしれません [*]_ .
ですが,そう遠くない将来,これらの資源が
枯渇することは避けられないでしょう.
それに,石油などは産出地域が限られていますので,
世界情勢によっては入手困難になるという問題もあります.
.. [*] 重力についての注釈
.. [*]
さらに,石油が染みこんだ砂や岩(利用するのに手間はかかる)なども,
かなりの量存在すると言われています.
これらは,オイルサンドやオイルシェールと言われます.
のように, &color(#f00){[*]_}; を注釈を加えたい部分に記述し,
&color(#f00){.. [*]}; の後ろにその内容を記述します.
注釈部分が複数行に渡る場合,先頭にスペースを入れてインデントします.
をHTMLに変換した結果は
これらの命令と地の文の間にはスペースが必要です.
注釈は &color(#f00){.. [*]}; を記述した部分に表示されます.
通常, &color(#f00){[*]_}; を書いた段落の
すぐ後に表示されるようにすると良いでしょう.
#ref(footnote.png,nolink)
複数の注釈を加えたい場合も同様で,
のようになります.
また,複数の注釈を加えたい場合も同様で,
この引っ張る力が重力 [*]_ であり,この力の法則が,万有引力 [*]_ です.
.. [*] 重力についての注釈
.. [*] 万有引力ついての注釈
のように &color(#f00){[*]_}; と &color(#f00){.. [*]}; 命令を使います.
&color(#f00){.. [*]}; 命令を書いた順番に対応づけられます.
それぞれ, &color(#f00){.. [*]}; 命令を書いた順番に対応づけられます.
これらの注釈は,PDF版ではLaTeXの \footnote 命令として処理されています.
* HTMLの命令を直接記述する場合 [#k059ab1a]
どうしても[[reStructuredText]]で用意されている形式で扱えないもの,たとえばJava AppletやFlashを記述したい場合,その命令(HTMLタグ)を直接[[reStructuredText]]のソースに記述することになります.
どうしてもreStructuredTextで用意されている形式で扱えないもの,
たとえばJava AppletやFlashを組み込む命令を記述したい場合,
HTMLタグを直接reStructuredTextのソースに記述することになります.
そのためには, &color(#f00){.. raw:: html}; という命令(rawディレクティブ)を使用します.たとえば
そのためには,&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タグとして出力されます.すなわちこの記述部分に,短い水平線が表示されます.
rawディレクティブを用いず単に <hr width=50 size=10> と書いた場合,
その文字列が(HTMLタグとしてではなく)そのまま出力されます.
ただし,この命令はJava AppletやFlashを記事に埋め込みたい場合のみに使うものであって,文字装飾やデザイン上の変更行うためのものではありません.必要最小限で利用してください.
ただし,この命令はJava AppletやFlashを記事に埋め込みたい場合のみに使うものであって,
文字装飾やデザイン上の変更を行うために用いるのはのは望ましくありません.
必要最小限で使用してください.
* 参考リンク [#la3926d0]
- [[はやわかりreStructuredText>http://www.planewave.org/translations/rst/quickref.html]]
- [[公式マニュアル(英語)>http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html]]
- [[はやわかり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:: など)の詳細
// &color(#f00){};
#br
#br
[[かぎマニュアルズ]] > [[記事制作方法>かぎマニュアルズ#wbdd8eaa]] >