title: rbdoc -- Ruby document writer
author: Kazuhiro Yoshida
mailto: moriq.kazuhiro@nifty.ne.jp
  %href:rbdoc.txt% is rbdoc source.
1.rbdoc

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

1.1. はじめに

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

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

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

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

1.1. 特長

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

1.1. 制約

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

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

1.1. 使いかた

    1.1.1. コメント

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

    1.1.1. 空行

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

    1.1.1.title, author, mailto

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

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

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

    1.1.1.lang

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

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

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

    1.1.1. セクション

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

    1.1.1. 段落

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

    1.1.1. インデント

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

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

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

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

    1.1.1. ハイフネーション

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

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

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

    1.1.1. 修飾

        書式
          %c:%%<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 を %html:<u> そのまま </u>% 埋め込む。
        href
          リンクを張る。 src は %c:foo.html! ふう % のように
          %c:!% をデリミタとして後ろにラベルを記述できる。この場
          合，ラベルは %c: ふう % となる。ラベル指定を省略すると
          ，リンク先 URL がそのままラベルとなる。
        mref
          メソッドへのリンクを張る。 src には %c: Xlib::XOR %,
          %c: Array.new %, %c: File#open % のように指定できる。な
          お， %c: equal? % は %c: equal_p % ， %c: chop! % は
          %c: chop_bang % ，というように rbdoc は 末尾の %c:'?',
          '!'% を適切に修正する。
        %method:method%
          メソッド名専用の機能。 mref に対応するアンカー名を作成
          する。 4 カラムインデントして， 2 カラム目に %c:*% を付
          けた行は自動的に %c:%%method:<src>%%% で囲まれる。最初
          の %c:'(' or '{' or ' '% までをメソッド名とみなす。

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

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

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

    1.1.1. 埋め込みドキュメント

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

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

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

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

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

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

%html:
  &amp;
  <i>let's enjoy rbdoc!</i>
%

1.1. コンセプト

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