clmemo@aka: RD の目次を作る rd-hindex2.rb |RD|Ruby|

2005-07-12

RD の目次を作る rd-hindex2.rb |RD|Ruby|

Ruby には RD という簡易マークアップ言語があって、 RDtool で HTML へと変換できる。RD の特微はシンプルな構造。いいかえれば、可読性の高いドキュメント。例えば、ドキュメントのヘッダーは次のように書く。

= ヘッダー 1

== ヘッダー 2

=== ヘッダー 3

==== ヘッダー 4

+ ヘッダー 5

++ ヘッダー 6

読み易いし、書き易い。HTML のタグ打ちに嫌気がさして文章に注力したい人は是非使ってみて欲しい一品。詳しくは、RD フリークを自認する「るびきち」氏が「Ruby を 256 倍使うための本魔道編」で一冊かけて説明しているので、そちらを参考されたし。

使い易い RD なのだけど、いくつか制限がある。その一つが、デフォールトで目次 (Table of contents) 作成に対応していないこと。そこで、 rd-hindex2.rb の紹介。RD ドキュメントから、ヘッダー部分を取り出して ul 要素を使った目次を作成してくれる。

$ rd-hindex2.rb foo.rd > foo.toc.rd

目次を入れたい所に include で toc ファイルを埋め込むだけ。

<<< foo.toc.rd

次の Makefile は、 GNU Arch の説明を書いた時に使ったもの。よければ、 SRC = gnu-arch の部分を適当に変えてお使い下さい。

RD2 = rd2
RD2HTML = $(RD2) --require=rd/rd2html-lib --html-lang=ja
RDHINDEX = rd-hindex2.rb --base-level=1
SRC = gnu-arch
CSS = $(SRC).css

all: html

html: $(SRC).html

$(SRC).html: $(SRC).rd $(SRC).hindex.rd
 $(RD2HTML) --html-title="Rendez-vous GNU Arch" --with-css=$(CSS) $< > $@
$(SRC).hindex.rd: $(SRC).rd
 $(RDHINDEX) $< > $@

rd-hindex2.rb のオプション

上の Makefile で、 --base-level というオプションが見える。実は、rd-hindex2.rb はレベル 2 (HTML でいう所の h2 要素) 以下のヘッダーの目次を作る。つまり、レベル 1 (h1 要素) のヘッダーは目次に含まれない。普通の人なら、レベル 1 のヘッダーはドキュメントの題名を入れるだろうから、この仕様は納得できるものだ。ただ、愚かなことに、gnu-arch.rd はそういう事を考えずに文章を書いてしまったので、レベル 1 のヘッダーも目次に含めて欲しかった。 --base-level はそんな人のためのオプション。このオプションで指定した数字より小さなレベルの目次が作られる。

ドキュメントによっては、第 6 レベルのヘッダーまで書く人もいるでしょう。でも、深いレベルの目次は欲しくない。せいぜい、レベル 3 程度に留めて欲しい、という人もいるかと思う。そんな人には --max-depth オプション。このオプションで指定した数字より大きなレベルの目次が作られる。