Duckbill

= これは何? =


 * Executable Documentation Systemです. 解析スクリプトをノートの中に埋め込み、このノートそのものを実行することができます.
 * 例えばhello2.txtからコマンド１つでhello2.htmlが作られます.
 * ノートを書く際に使うマークアップ言語は何でも構いません.

= インストール =

Ubuntu Linux 10.04 LTS (Lucid Lynx)にて動作確認

以下の3つで動作する
 * http://rgm2.lab.nig.ac.jp/Repository2/duckbill/Bundle-DuckBill-0.92.tar.gz
 * http://rgm2.lab.nig.ac.jp/Repository2/duckbill/DuckBill-0.92.tar.gz
 * http://rgm2.lab.nig.ac.jp/Repository2/duckbill/scripts.tar.gz

= 使い方 =

Hello world
(1) 以下のようなテキストファイル (hello.txt) を作成する.
 * Hello world


 * Rのプログラムを実行.

%begin{file}[run(R)]{foo.R} png(filename="split.png", width=480, height=480)

require(stats); require(graphics) n <- 10; nn <- 100 g <- factor(round(n * runif(n * nn))) x <- rnorm(n * nn) + sqrt(as.numeric(g)) xg <- split(x, g) boxplot(xg, col = "lavender", notch = TRUE, varwidth = TRUE)

dev.off %end{file}


 * 1) file{foo.R}

Rプログラムの実行結果
 * 1) file{%STDOUT%}
 * 2) img{split.png}


 * perlのプログラムを実行

%begin{file}[run(perl)]{foo.pl} print STDOUT "1+2+3+.. = infinity\n"; print STDERR "1+2+3+.. = -1/12\n"; %end{file}


 * 1) file{foo.pl}

perlプログラムの実行結果

STDOUT
 * 1) file{%STDOUT%}

STDERR STDERRを捕捉すると、実行中にエラーが出ているのがリアルタイムに分からなくなってしまうので、 捕捉しない仕様になりました.
 * 1) file{%STDERR%}


 * bashのスクリプトを実行

%begin{file}[run(bash)]{foo.sh} tree -a %end{file}


 * 1) file{foo.sh}

実行結果
 * 1) file{%STDOUT%}

(2) このファイルを以下のコマンドにより処理する. bill -e hello.txt

以下のことが行われる.
 * 1) hello.txt中の%begin{file} ... %end{file}で囲まれた部分がファイルに書き出される.
 * 2) 書き出されたファイルが指定されたプログラムで実行される.
 * 3) 実行の際に標準出力に出されたメッセージなどは、.helloディレクトリの下に保存される.
 * 4) hello.txt中から%begin{}..%end{}などのコマンドが取り除かれたファイルがhello.wikiとして保存される.
 * 5) hello.wikiはogawiki.plxによりhello.htmlに変換される.

ノートを書くためのマークアップ言語はここではpukiwikiに似たスタンドアロンのwikiを使っているが、実際には何を使っても構わない. LaTeX、HTML、他のスタンドアロンwikiなどに差し替えることが可能. (その際はbillスクリプトをちょっと書き変えて下さい. ）

(3) 実行の結果、hello.html というファイルが作られる.

実行制御
スクリプトなどの実行制御にはMakeが使われることが多いが、処理ステップ数が多くなってくると、依存関係をmakefileで管理するのが面倒になってくる. そこで以下のような単純な方法で実行制御を行っている. もともとノートの中にスクリプトが埋め込まれるという代物なので、依存関係についての注意が必要ならば、注意書きを残しておけば済むことであると考える.

bill -e hello.txtの-eは、hello.txt中のすべてのコマンドを実行せよ、という意味である.
 * -eをつけなければ、一切のスクリプトの実行を行わず、hello.txt => hello.wiki => hello.htmlの変換だけを行う.
 * -exec=グループ名 と指定すると、文書中の特定のグループだけを実行する.
 * -exec=グループ1,グループ3 などと複数のグループを指定することも出来る.

%group{グループ名}というコマンドを文書中の行頭に挿入することで、スクリプト実行グループを定義する. 次の%group{}コマンドに出会うかファイルが終わるまでが一つのグループである. %group{g1} グループg1の文書 %group{g2} グループg2の文書

例えばhello2.txtを bill -exec=g1,g3 hello2.txt と実行すると結果はhello2.htmlとなる.

実行にかかった時間は自動的に記録され、Last updateのところをクリックすると、過去の計測結果の一覧が表示される. (下図）



ファイルへの書き出し
%begin{file}{filename}

書き出されるファイルの中身

%end{file}

スクリプトの実行
%begin{file}[run(プログラム名)]{filename}

スクリプトの中身

%end{file}

内容をそのまま表示
%begin{verbatim}

ノートに書き出したい内容

%end{verbatim}

例えばDuckbillのコマンドをそのままノートに書きたいときは以下の様にする. %begin{verbatim} %begin{file}[run(R)]{test.R} print("hello") %end{file} %end{verbatim}

ogawikiリファレンスマニュアル

 * pukiwiki風
 * HTMLタグを直接入力すると、そのまま出力されます.

章 * chapter ** section *** subsection

ファイルの読み込み=>表示
 * 1) file{ファイル名}
 * 2) img{画像ファイル名}

詳細を隠す/表示する 細かい話
 * 1) begin_detail
 * 1) end_detail

LaTeXで数式 y=x^2-2x+1
 * 1) begin_math
 * 1) end_math
 * LaTeXを直接呼び出しますので、LaTeX 2eがインストールされている必要があります.
 * AMS-LaTeXを自動的に呼んでますのでAMS-LaTeXのコマンドが使えます.

= 拡張の方法 =

実行できる言語の種類を増やす
Duckbillから実行できるスクリプト言語の種類を増やしたければ、

(1) DuckBill.pm中の以下の部分を探して、適当に書き換える.


 * 左辺は%begin{file}[run(dot)]{filename.dot}のように呼び出すときのrunの引数文字列.
 * 右辺は実際に呼び出されるプログラムの名前である.

(2) 必要ならば、呼び出しスクリプト(batch_R.plxなどに相当するスクリプト)を書く.

呼び出しスクリプトは、perlのように、単に perl ファイル名 で実行されるように、呼び出し方を調整しているだけである. （だからperlやbashは呼び出しスクリプトが要らない. )