Gauche:scm2texi
koguro(2007/02/03 04:39:06 PST): GaucheFest:19thで作ったドキュメント作成支援のためのスクリプトです。
scm2texiとは
Gaucheのソースコードから、関数やクラスなどの定義を調べてtexinfo形式のドキュメントのひな形を作成するスクリプトです。以下のような機能を持ちます。
- 英語と日本語の両方のドキュメントが混在できるtexinfoを生成します(Gaucheのドキュメントで使われているextractスクリプトを使い、おのおのの言語のドキュメントを分離します)。
- 関数、マクロ、クラス、メソッド、変数、定数、モジュールの定義を調べてドキュメントのテンプレート(@defun 〜みたいなもの)を作成します。ただし、定義を見落とすこともあるので、足りないものは自分で追加してください。
- let-keywords*やlet-optionals*を調べて、引数の記述に&keywordや&optionalを含めることができます(ただし、判定ロジックがいい加減なので間違えることもあります)。
- export があれば、そこにあるシンボルのみドキュメント化されます。
- Makefile.inも自動生成されます。ただしconfigureは自分で作る必要があります。
なお、以下のような機能はありません。
- Javadocのようなソースコード中のコメントからのドキュメント生成(scm2texiではコメントは一切無視します)。ソースコードとドキュメントは構成や記述内容がずれるところがあるので、私は一体化しない方がよいと思うのですがどうでしょう。
勢いに任せてライブラリを書いてみたものの、公開する段になってドキュメントに何を書けばいいのか迷ってしまったり、texinfoの構文をよく間違えたりするような人向けです(私はよく@deffnと@defunを間違えたりします)。
インストール方法
scm2texi-1.0.tgzをダウンロードして、gauche-package install --install-as=root scm2texi-1.0.tgz を実行してください。
使い方
以下のコマンドを実行します。ちなみにファイル名は複数指定でき、1ファイル1ノードでドキュメントが作られます。
% gosh scm2texi [ソースコードのファイル名] ...
コマンドを実行すると、いくつか質問をしてきたのち、texinfoドキュメントなどを生成します。
% gosh scm2texi mymodule.scm Output directory: doc <-ドキュメント出力先のディレクトリ名 Title: mymodule <- ドキュメントの英語タイトル Description []: Very useful library <- 何のドキュメントかの英語での説明 Info filename prefix: mymodule <- ファイル名のプレフィックス (この例だとmymodule-ref.texiが作られます) タイトル [mymodule]: mymodule <- ドキュメントの日本語タイトル 説明 [Very useful library]: すごく便利なライブラリ <- 何のドキュメントかの日本語での説明 Author: Alyssa P. Hacker <- 作者名 Mail address []: xxx@xxx.xxx <- メールアドレス(@authorに入ります) mymodule-ref.texi is generated.
あとは適宜内容を書き換えてください。