プログラミング言語/Ruby

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では<a>タグの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"のようにしてください。

参考


*1 dRubyを基幹にし、RDをWiki文法として使うWikiクローン
*2 RDLikeStyleというWiki文法が選択できる
*3 RDベースのWiki文法
*4 Web日記システム。RDで日記を書くプラグインあり
*5 BitChannelベースに作られたシステム
*6 全角なのはPukiwiki対策。本来はもちろん半角