rbdoc.txt is rbdoc source.

rbdoc

usage
ruby rbdoc.rb foo.txt > foo.html



はじめに

これを作ったそもそもの原因は Ruby/Xlib のドキュメントを直接 HTML で書くのに嫌気がさしたことなんだ。

例えば， 
    new(x, y, width, height) : Rect rect
      新しい四角形を作る。


と書いたら， 
  <dt><a name="new"><h3>new(x, y, width, height) : Rect
  rect</h3></a>
  <dd> 新しい四角形を作る。


に変換してほしいんだ。あなたもそう思うよね ?



特長

書きやすい
source となる plain text は，妙な記号でマークアップする必要がないシンプルなもの。
読みやすい
plain text は当然として，生成される HTML も読みやすくインデントされる (rbdoc の source はお世辞にも読みやすいとは言えないけど ) 。また， lynx でもそれなりの表示を期待できる。
使いやすい
rbdoc は rbdoc.rb のみで構成されている。
速い
rbdoc のパーサは行指向であり単純である。

制約

実は rbdoc は作法に厳しい。言い換えると，融通が利かないんだ。困ったもんだね。

文字コード
Shift_JIS じゃないといけない。これは HTML の charset 指定を固定しているために起こる弊害である。でも，このあたりの改良は簡単にできるはずだ。
メソッド名
きっかり 4 カラム目から書く。 2 カラム目には '*' を付ける。これで rbdoc はメソッド名と認識する。 ( 逃げ道もある。 method 参照 )
インデント
インデントは 2 行を 1 組として扱う。 2 行とは，定義の行と意味の行のこと。これは，かなり痛い制約である。しかし，この制約のおかげでまとまりのある文章を書けるのだ，とは言えないだろうか ( 説得力のない言い訳ともいう ) 。

使いかた



コメント

# で始まる行はコメントである。 rbdoc はこの行の記述に関知しない。



空行

rbdoc でいう空行は，改行で始まる行である。空白文字を含んではいけない。



title, author, mailto

title: で始まる行はタイトル指定である。このあと改行までの文字列が記録される。

author: で始まる行は著者名指定。

mailto: で始まる行は連絡先指定。



lang

%lang= で始まる行はタイトル指定である。 en もしくは jp と指定することができる。また， lang 指定は途中で変更できる。

しかし，もはや lang 指定は重要でなくなった。通常は無指定でよい。

将来的には，言語ごとの出力をサポートするようになるだろう。そのときにまたここの記述も改変しよう。



セクション

行頭に 1.1. などと書くと，それはセクションになる。 1. はレベル 1 ， 1.1.1. はレベル 3 となる。



段落

上記以外の始まり方をする行は段落の始まりである。



インデント

rbdoc のインデントにはスペースのみ使える。タブは使えない。

4 カラムインデントして， 2 カラム目に * を付けた行はメソッド定義とみなす。

4 の倍数カラムインデントした行は定義部とみなす。定義部の後には意味部がくる。意味部は定義部よりも 2 だけ深いインデントを持つ。では，奇数カラムなら？そのときは -1 した位置と同じ深さになる。

前の行と同じ深さだけインデントした行は，前の行に継続する。



ハイフネーション

lang に jp を指定した場合，継続は前後の空白を全て消去する形で行うので，英単語が連続する場合は問題になる。そんなときはハイフン '-' を末尾に付ければよい。 rbdoc は，末尾のハイフンをスペースに変換してくれる。

lang に en を指定した場合は， jp の場合とは全く逆の動作になる。すなわち，継続はスペースを挟む形で行われ，これを抑制するために末尾のハイフンを用いる。つまり，一般的なハイフネーションを行うわけである。

lang が無指定の場合は，継続する文字列の末尾と先頭にある文字を調べ，両方とも 2 byte 文字であるときには空白を入れずにそのまま連結し，それ以外は空白を入れる。ハイフネーションは en の場合と同様に行う。このモードが最も使いやすいと思われるので，結論としては「 lang は指定しなくてよい」と言える。なあんだ。



修飾

書式
%<act>:<src>%
<act> に指定できる文字
e, c, v, s, html, href, mref, method, nil

e
eval src
c
記号。 code tag で src を囲む。
v
変数。 var tag で src を囲む。
s
強調。 strong tag で src を囲む。
html
HTML を そのまま 埋め込む。
href
リンクを張る。 src は foo.html! ふう のように ! をデリミタとして後ろにラベルを記述できる。この場合，ラベルは ふう となる。ラベル指定を省略すると，リンク先 URL がそのままラベルとなる。
mref
メソッドへのリンクを張る。 src には Xlib::XOR , Array.new , File#open のように指定できる。なお， equal? は equal_p ， chop! は chop_bang ，というように rbdoc は 末尾の '?', '!' を適切に修正する。

method

メソッド名専用の機能。 mref に対応するアンカー名を作成する。 4 カラムインデントして， 2 カラム目に * を付けた行は自動的に %method:<src>% で囲まれる。最初の '(' or '{' or ' ' までをメソッド名とみなす。

しかしながら，メソッド名が頻繁に出てくる文書 ( 拡張ライブラリのドキュメントとか ) の場合には，いちいち '*' を付けるのは面倒である。そんな時には %method_switch=true を指定してほしい。そうすれば '*' を付けることの意味は逆転する。すなわち， '*' を付けないとメソッド名，付けると通常の定義部と rbdoc は認識してくれる。

なお，ここでの '*' は HTML 上では表示されない。
nil
何もしない。なぜ何もしないものが必要なのかと言えば埋め込みドキュメントを任意のレベルで使いたいという要望に答えるためである。まあ初めは気にしなくていい。

src に '%' を使いたいときは代わりに '%%' を置いてほしい。



埋め込みドキュメント

書式 
%<act>:
  <src>
   ...
%
<act> に指定できる文字
r, html, ruby, c, e, item, enum

いくつかの方法で plain text そのままの形で表示するような HTML を生成できる。

r
pre tag で src を囲む。
html
HTML を そのまま 埋め込む。
ruby
r の応用。 Ruby スクリプトを表示するのに使う。
c
r の応用。 C プログラムを表示するのに使う。
e
eval src
item
記号付き箇条書。インデントをつけると階層構造になる。
enum
番号付き箇条書。インデントをつけると階層構造になる。

src に '%' を使いたいときはそのまま '%' でよい。ただし，行頭の % は終端を表すので， %% とする必要がある。

ruby の例を挙げる。 
%ruby:
def html_encode(src)
  src.gsub! /</, '&lt;'
  src.gsub! />/, '&gt;'
  src.gsub! /&/, '&amp;'
end
%


def html_encode(src)
  src.gsub! /</, '&lt;'
  src.gsub! />/, '&gt;'
  src.gsub! /&/, '&amp;'
end
html の例を挙げる。 
%html:
  &amp;
  <i>let's enjoy rbdoc!</i>
%


& let's enjoy rbdoc!

コンセプト

rbdoc を作成するにあたって前提においたことを挙げる。
  1. 1 path
  2. source 1 line で意味解析できる
  3. rbdoc-tag は nest できない
  4. CSS を活用する
  5. HTML で pre tag になる rbdoc-tag は here-document にする
author: Kazuhiro Yoshida