CodeReadingWiki の改善点

急いで作ったものの、既に思いついている改善点は色々ある。

- GLOBAL に -x という XHTML 出力オプションがあるのに後で気づいた。次からはこれを使おう
-複数のプロジェクトに対応していない。スキーマとしてはプロジェクト名の列を追加すればいいが HTML 側でどう情報を持たせるか？
- RecentChanges は欲しいかも。更新時の列を追加か
- MySQL のスキーマ定義でコメント列を適当に選んで MEDIUMTEXT にしたが、これは最大 1677215 文字だそうだ。明らかにこんなに要らないので次からは TEXT にしよう
- というか MySQL を使うという決断はよかったのかどうか。インストールの敷居があがっているかもしれない

CodeReadingWiki

先のエントリ [1] の最後で GNU GLOBAL が作った HTML を Wiki に取り込むアイデアについて書いた。その後実際にそのアイデアの実装をしてみたのでこれを CodeReadingWiki と名づけて公開することにした。ダウンロードは [2] からできる。

正確に言うと Wiki に取り込むのではなくて GLOBAL の HTML を Wiki 化するというほうが正しい。ソースコードの任意の行をダブルクリックすると書き込みフォームが出てきてコメントを挿入できるという感じの使い勝手になっている。大げさな視覚効果はないけれども AJAX を使っているのでページ遷移なしで編集ができる。結構便利。

以下は README.txt から。

CodeReadingWiki 説明書
======================

* 概要

CodeReadingWiki は「他人の書いたコードの読解」を目的とした Wiki エンジンです。
以下のような特徴を持っています。

- GNU GLOBAL により索引付けされた HTML を Wiki 化する
- ソースコード上の任意の場所にブラウザからコメントを挿入できる

「ひらメソッド」の「ドキュメントを書きながらボトムアップに読み進める」
という方法論を支援することを想定しています。

「ひらメソッド」については以下の URL を参照してください。
http://hira.main.jp/wiki/pukiwiki.php?2005_6_23%A5%AB%A1%BC%A5%CD%A5%EB%BA%C2%C3%CC%B2%F1%AD%A1

また CodeReadingWiki は以下の点で通常の Wiki エンジンとは異なります。

- 任意のページを新規追加することはできない
- Wiki ワードによるハイパーリンクはない
（ソース読みに必要なハイパーリンク化は GNU GLOBAL が事前にやってくれます）

* 要件

Wiki 構築時に Windows マシンで以下のソフトウェアを実行します。
インストール後実行パスを各ソフトウェアの実行ファイルのあるフォルダに通してください。

- GNU GLOBAL http://www.gnu.org/software/global/download.html
- GNU AWK http://www.vector.co.jp/soft/win95/util/se376460.html

サーバサイドで以下のソフトウェアが必要です。

- PHP
- MySQL

Wiki の閲覧・編集には以下のいずれかのブラウザが必要です。

- Mozilla FireFox 1.5
- Internet Explorer 6.0

* インストール方法

1. 使用したいソースコードを適当なフォルダに展開します。

2. コマンドプロンプトで 1. のフォルダに移動し、以下のコマンドを実行します。

gtags
htags -a

直下に HTML というフォルダが出来上がります。

3. HTML フォルダに CodeReadingWiki のアーカーブに含まれるファイルをすべてコピーします。

4. HTML フォルダに移動し、以下のコマンドを実行します。

cwriki

S フォルダの内容が S_ フォルダに退避され S フォルダは新しい内容で更新されます。

5. crwikiconf.cgi の内容を編集します。各パラメータを適宜編集してください。

- $host: ホスト名
- $user: ユーザ名
- $password: パスワード
- $db: データベース名
- $db_charcode: DBの文字コード

6. サーバサイドの MySQL で以下の SQL 文を使って remarks テーブルを作成します。

CREATE TABLE `remarks` (
`src` VARCHAR( 255 ) NOT NULL ,
`line` INT NOT NULL ,
`remark` MEDIUMTEXT NOT NULL ,
PRIMARY KEY ( `src` , `line` )
) TYPE = MYISAM ;

7. サーバ上の crwikiconf.cgi の置き場所を決めます。
可能な限り外部から見えない場所（非公開ディレクトリ）にしてください。

8. crwiki.cgi をサーバにアップロードします。
公開ディレクトリに置かざるを得ない場合は crwiki.cgi の内容が外から見えないことを確認してください。

9. 7. で決めた場所に基づいて crwiki.php の require '../crwikiconf.cgi'; を書き換えます。

10. HTML フォルダ以下の crwikiconf.cgi 以外を丸ごとサーバにアップロードします。

* Wiki の使い方

- アップロードした index.html から各ソースファイルをブラウズすることができます。
- S ディレクトリの下のファイル（ソースコード実体）は編集が可能です。
- コメントを挿入したい行をダブルクリックするとその下にフォームが現れます。
- コメントを入力し、再度該当行をダブルクリックするとコメントが反映されます。

* 移植性について

事前のクライアント上作業は現在 Windows マシンを前提としていますが、
crwiki.bat を移植することにより他の環境でも実行できるようになるでしょう。

* 既知の問題点

Internet Explorer を使う場合、挿入したコメントに対するスタイル指定が効きません。

[1] http://blog.so-net.ne.jp/rainyday/2006-10-01
[2] http://tcl.s27.xrea.com/crwiki-0.1.zip

2007-01-07追記: SourceForge.jp にプロジェクトを作りました。次回以降のリリースは下記の場所で行います。
http://sourceforge.jp/projects/crwiki/

ひらメソッド＋GNU GLOBAL

「ひらメソッド」 [1] というソースコードを読むコツみたいなものがあることを知った。

巨大なソースをトップダウンで追うと頭に入らず挫折してしまうのでボトムアップで理解していきましょうという趣旨。なるほどなあと思った。

それに Wiki を使う―個々の関数に対応するページを作って理解したことを書いていく―というのがこのメソッドのメソッドたる部分だと思う。でもこの方法だったら Wiki にいちいちソースをコピーしてハイパーリンクを手で作っていくのではなくて、GNU GLOBAL で生成した HTML をローカルで編集しながらコメントを書いていく方が手軽なように思える。

Netscape が Mozilla Firefox に「進化」する過程で切り捨てられた機能に Netscape Composer がある。Netscape Communicator 4.x で GNU GLOBAL の HTML をブラウズして、何か書き込みたくなったらメニューからページの編集を選べばその場で WYSIWYG のエディタが立ち上がる。ぴったりじゃないか。

Wiki を使う方法に比べて短所があるとしたら共同作業には向かないということだろうか。逆にソース読みを一人でやるのだとしたら特に欠点はなく、ハイパーリンクの生成を GLOBAL が自動でやってくれることによる労力節約が圧倒的だと思う。

発展的な方法として GLOBAL が生成したHTML化ソースとそのリンク付けを何らかの方法で Wiki に取り込んでしまうというのもあるかもしれない（勿論そういうことをするプログラムを書く必要がある）。

[1] http://hira.main.jp/wiki/pukiwiki.php?2005_6_23%A5%AB%A1%BC%A5%CD%A5%EB%BA%C2%C3%CC%B2%F1%AD%A1

GNU GLOBAL

GNU GLOBAL [1] というツールを使ってみた。
昔からあるようだし、いまさら便利がっているほうが恥ずかしいのかもしれないけどこれは素晴らしい。

何をしてくれるかというと、C や C++ なんかのソースを総ざらいして関数やマクロなどがどこで使用されているかという情報をハイパーテキスト化してくれる。他人のソースを読むときとか、自分のソースをリファクタリングしたりするときにかなり重宝しそう。例えばある関数を改変したいときにどこでその関数が使われているかという影響範囲がすぐに一覧で分かる。それに出力が HTML なのでかなり直感的にブラウズできる。他人の書いたソースをつらつらと眺めるのに便利な感じだ。

使い方はインストールして、ソースツリーの置かれたディレクトリで

gtags
htags -sa

と打つ。これで HTML というディレクトリができるので ./HTML/index.html をブラウザで開けばよい。
s というオプションをつけるとあらゆるシンボルをハイパーリンク化するので HTML がかなりくどくなるのだけど、これをつけないと関数が抽出されていない場合があったのでつけることにした（どういう結果が正しいものなのかマニュアルからはいまいちわからない）。

[ この記事を投稿しかけたあとで、ちょっと思い直して、他にも同じようなツールがあるようだし、実は Visual Studio みたいな IDE でも呼び出し元をたどる機能があったりするので、それらを調べて比較してからにしようと思ったのだけど、やっぱり HTML 化という機能の便利さが突出しているのがわかったので安心して褒めることにした ]

[1] http://www.tamacom.com/global-j.html