RD#
RDとはRuby Documentationの略です。
ソースコードに埋め込む形式としてはRDocのほうが主流になりがちですが、 RWiki*1や VikiWiki*2、 BitChannel*3や tDiary*4、 新リファレンスマニュアル*5など、 用いられているものはたくさんあります。
書く場所#
=begin
...
=endという複数行コメントがRubyにはありますが、PerlにおけるRODのような 感じでそこに埋め込むことを考えられていましたが、 前述の通りRDocにその役目は譲りつつありますし、 RDtoolは=beginや=end行を補完してくれたりします。
書式#
基本的に、Inlineを除く書式は先頭の文字(HeadChar)で決まり、 要素の連なりはインデントによって判別されます。
- TextBlock
- 通常のテキスト段落。
空白以外から始まる行の連なり。
Example:
こんにちは。
わたしは、
VIPからきますた。- Verdatim
- 整形済みテキスト。
インデントがそれまでより深い行の連続。 インデントが同じ行の連続がひとつのVerdatimとして扱われる。 Verdatim内ではInlineは解釈されない。
Example:
ここはインデント深くないのでTextBlock。
ここも。
ここからVerdatim。
改行などもそのまま反映される。
ここもまだVerdatim。
前より深いので。
前より浅くなったが、まだまだVerdatim。
インデントが戻ったので、ここは普通のTextBlock。- Comment
- コメント。
`#‘で始まる行がコメント行とされる。 Rubyと使う文字が一緒だが、Rubyとは違って行の途中からの コメントはない。
- HeadLine
- 見出し。
六段階の見出しが書ける。 内容がLabelとなる(Labelについては後述)。
Example:
= HeadLine-1
== HeadLine-2
=== HeadLine-3
==== HeadLine-4
+ HeadLine-5
++ HeadLine-6- Include
- 別ファイルの取り込み。
RDを取り込む方法と、変換するのフォーマットを取り込む方法とがある。
Example:
#RDを取り込む
<<< anothoer_file.rd
#変換フォーマットに従って取り込む(HTMLならexternal_file.htmlを)
<<< external_file- ItemList
- 箇条書き。
`*‘から始まる行は箇条書きの項目(Item)になり、 Itemの連続で箇条書きリストになります。
Example1:
* これが
* リスト
* ですItemにはTextBlockから始まる各要素の連なりが置けます。 そのTextBlockの始まりがインデントの基準とされます。
Example2:
* つまり、Verdatimを書くには
インデント基準より深くすればぉk
なのでこれはVerdatim。
ここからはTextBlock。
* 二つ目のItem。
* 要素を入れ子に、ということは、
* とうぜんリスト自体も含められるわけで。
*ただしHeadLineやIncludeは無理だよーん- EnumList
- 番号付き箇条書き。
`(1)‘のようなHeadCharによって作られるItemの連なり。 ただ、番号自体は無視されます:-)
Example:
(1)ここはItemListと同じでTextBlock。
|基準はここなので、
これはVerdatim。
(2)ItemListと同じでよいのですが、`*'一文字のItemListのノリで
入れ子を書こうとして、
(3)全然入れ子になっていないというミスが多いので注意。
ここは(1)、(2)とは違うEnumListにされます。- DescList
- 定義や説明の記述。
Term部とDescription部からなる。 Term部は`:‘から始まる行で、Description部はTerm部を基準とした インデント基準に沿った要素の連なり。 Term部の内容はLabelになる。 Term部にはTextBlockが置かれ、そのTextBlockの開始位置がインデント 基準となる。
Example:
:Term部
Description部。ここがDescription部の基準を決める。
その基準より深いのでこれはVerdatim。
: 深いTerm部
「深」の前が基準なのでここはDescription部にされない- MethodList
- メソッド説明専用のDescList。
DescListの要領だが、Term部は`—‘から始まる。
Example:
--- HogeClass#piyo(arg1, arg2){...}
何かをするメソッド。
とにかく何かを返す。Term部はRubyっぽくパースされてマークアップされる。 DescListと同様、Term部の内容がLabelになるが、 ちゃんとメソッド名のHogeClass#piyoだけが使われる。
- Inline
- 文中要素の総称。
（（強調））のように「丸カッコ *6 二つ+記号」からなる開き・閉じカッコ によって、文中を装飾する要素です。
Inline#
以下の各Inline表記で全角になっている記号は、Pukiwiki文法との 衝突を避けるためです。本来はもちろん半角です。
- （（*強調*））
- 内容を強調要素としてマークアップします。
- （（<リンク>））
- URLによるリンクやReferenceを指定します。
ややこしいので別枠で説明。
- （（-脚注-））
- 内容を、その位置に対しての脚注として扱います。
- （（{コード}））
- 内容をコード要素としてマークアップします。
- （（%キータイプ%））
- 内容をキータイプ要素としてマークアップします。
- （（｜変数｜））
- 内容を変数要素としてマークアップします。
- （（:インデックス要素:））
- 内容をインデックス要素として扱います。
例えばHTMLではタグのid属性とname属性が付加されます。
- （（'Inlineのエスケープ'））
- この中にInlineを入れ子にしても、
Inlineとしてパースせずそのまま表記する。
Inlineリンク#
URLは
((<URL:http://www.google.co.jp>))のように記述します。この「URL:」が大事です。
Referenceは、Labelの指定によるドキュメント内リンクです。
Example:
= HeadLine1
Inlineを使う。((<HeadLine1>))で先頭にリンク。HeadLineやDescListで説明したように、Labelになりうる場所には こうして簡単にリンクを晴れます。
この要素は<リンク>と表記されるが、
((<Text|リンク>))とすることで、表記をTextにすることができます。
Text内で|'や/‘をエスケープするにはタブルクォーテーションで
“Text"のようにしてください。