ごくらく RDtool (基本編)

目次

はじめに

ここでは, RDtool を使って手軽に html 文章を作成する方法を紹介します.

この座学編を聞いて(比較的)損が無い人

下記の条件に当てはまる人にはおすすめ(だと思ってます)です.

キーワード:

Ruby, rd, html, tex, roff(man), ファイル生成

RD ツールってなに ???

RDtool は,

  1. RD 書式で書かれたテキストを
  2. html や roff*2, tex に変換する

ツールです.

RD とは

RD とは Ruby という言語で書かれたスクリプトファイル中にそのファイルに関する説明等を 埋め込むことを念頭に定義されたドキュメントフォーマット(書式)です.

rubyでは ruby スクリプト中の

=begin から =end

までの間に書かれた文章はコメントとみなします. そこで利用者はそのスクリプトについての さまざまなコメントを, =begin..=end 中に書くことができます.

例1:

$ less test.rb
==============================================
=begin                                
  内容    : a と b の和を表示する Ruby のプログラム
  履歴    : 2003-11-09  by daktu32        
=end
# ここから↓はプログラム.             
#!/usr/local/bin/ruby     
p a + b
...
==============================================

上記の例では, タイトルと履歴だけの短いコメントなのでこのままで一見して 内容をつかめます. ですがそのスクリプトの使い方(USAGE)や todo, 更新情報 などそのスクリプトにまつわる情報を全部ここに書き込むには文章群の構造を 表現する必要があります. 例えば見出しを工夫したり, 字下げをしたり.

RD はコメントの文書構造や URL 等の表現を統一することで, コメントの可読性を向上し, さらにその部分を抜きだして, html 等のフォーマットに変換することを目的に定義された 書式なのです.

RD の文法について簡単な解説が以下のページでなされてます. 見てみましょう.

<URL:http://yebisu.ics.es.osaka-u.ac.jp/~kawaji/rd_howto.html>

Ruby については参考文献からさまざまな Web をあげたので 興味のある方はそちらを参考にしてください.

RDtool とは

RDtool は, RD の書式で書かれたテキストファイル, もしくはテキストファイル中の 一部分を読み込んで, 同じ文書構造をもつ html ソースなど吐き出すツールです. 以下に挙げる形式に変換できます.

先程, 紹介した Ruby という言語で書かれたプログラムです.

RD & RDtool をつかってみよう!!

ここでは RDツールがどんな使い勝手なのか, 実際に皆さんの前でつかってみることにします. しばし解説に耳を傾けてください.

必要なもの

RDtool をつかうためには以下のものが必要です. 以下, rdtool の README から抜粋.

インストールについては後述の補足2でまとめますので, そちらを参照ください. 基本的に Unix 系の OS を利用している人なら使えるはずです. Windows 使いの人でも大丈夫だと思います. ちなみに僕は Windows 2000 上でつかってます. *3

実践 1 : とりあえず 変換

以下のテキストを hello.rb というファイルに保存します.

=begin

こんにちは

=end

次に, 以下のコマンドを打ちます. すると...

$ rd2 hello.rd

<?xml version="1.0" ?>
<!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml">
    <head>
    <title>hello.rd</title>
    </head>
    <body>
    <p>こんにちは</p>

    </body>
    </html>

$

というように, html のソースが標準出力にでてきました.これをファイルに保存するには お決まりの リダイレクト を使います.

$ rd2 hello.rd > hello.html
$ head hello.html

<?xml version="1.0" ?>
<!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml">
    <head>
    <title>hello.rd</title>
    </head>
    <body>
    <p>こんにちは</p>

    </body>
    </html>

こうして, めでたく rd を html に変換できましたね.

実践 2 : オプションをつけて実行しよう

見ためを変える(スタイルシート)

実践 1 で無事 RD ファイルから html ファイルを生成できました. ですが, はきだされた html はいたってシンプルで, ほとんどプレーンテキストな見ためをしています. これをかっこよくするためには, スタイルシートを生成される html にかぶせなくてはなりません. そうするためには rd2 をオプションをつけて実行します.

今, 生成する html と同じディレクトリにある sample.css という css ファイルをかませる場合 以下のコマンドを実行します.

$ rd2 hello.rd --with-css=sample.css > hello.css

--with-css= オプションで指定した css ファイルを html にかぶせます.

html のタイトルを変更する.

デフォルトでは html のタイトルは, 処理した rd ファイル名なので, かっこわるいです. タイトルを決め打ちするには --html-title= を指定します.

$ rd2 hello.rd --with-css=sample.css --with-css="タイトル" > hello.css  

その他のオプション

$ rd2 -r -rd/rd2html-lib.rb --help 

Usage: /usr/local/bin/rd2 [options] rd-file > output
global options:
    -r, --require=LIB                変換するフォーマットのライブラリを指定
    -oNAME                           出力するファイル名を指定
        --out-code=KCODE             出力する ファイル の文字コードを指定. (jis|euc|sjis)
        --output-index               Rd Method Index ファイルを (*.rmi)
    -I, --include-path=PATH          インクルードファイルのパスを指定
        --with-part=PART             フィルタの指定
        --from-rdo                   rd ファイルの変わりに rdo ファイルを読み込む
        --version                    バージョン情報を表示
        --help                       ヘルプを表示(このメッセージ)
rd2html-lib options:
        --output-rbl                 ラベルを記述したファイルを出力
        --with-css=FILE              html にかぶせる css ファイルを指定
        --html-charset=CHARSET       html のキャラコードを指定
        --html-lang=LANG             言語の指定
        --html-title=TITLE           html のタイトルを指定
        --html-link-rel=REL          add forward LINK element.("<rel>:<href>")
        --html-link-rev=REV          add reverse LINK element.("<rev>:<href>")

まとめ

以下に RD ツールに関する個人的見解をまとめます.

rdtool のいいところ

rdtool の不満なところ

というわけで, いろいろご意見はあるかと思いますが, とりあえず使ってみてください. 便利だと感じたならば, 幸いです.

ちなみに RD ツールと似たツールとして pod2html というものがあります. *4 これは Perl の埋め込みドキュメントフォーマットである POD で書かれたテキ ストファイル から html 文書を生成するツールです. Perl 使いの人で興味があ る方は参考にどうぞ.

補足1 : 応用編について

さて, rd で文章を書き慣れて来るといろいろな欲求が出て来ます. 例えば以下のような感じ.

残念ながら上記の欲求を満たす機能はデフォルトの rdtool にはありません. しかしあきらめる必要はありません. なければ自分で作ってしまえばいいのです. rdtool は ruby で書かれたプログラムですので, ruby でスクリプトをつくるのが リーズナブルでしょう.

実は, 上記の欲求を満たすツールを地球流体力学研究室 M2 の山田由貴子さんが 作りました. よって, 本日の座学編 "ごくらく RD ツール" 後編は山田由貴子さん による, RDツール応用編と題して, やまだ由さん自身がつくった rdtool の機能を 拡張するさまざまなツール群を紹介してもらいます.

後編へ

補足2 : rdtool のインストール

現在製作中...

参考文献

RD および rdtool について

RD ツール利用の具体例:

rdtool で生成した html のタイトルはデフォルトの場合, 元の .rd ファイル名がつけられます. よって hoge.rd というタイトルのサイト群は大体 rdtool で生成された html であることがわかります.

残り製作中.


*1Ruby を知ってる必要はまったくないです.
*2man のソース書式
*3ただし, Cygwin というツール経由ですが...
*4というか Ruby 用に真似したのが rdtool.