(Japanese | English)

RDoc Fortran 90/95 ソースコード解析機能強化版

RDoc - Ruby Documentation System の Fortran 90/95 ソースコード解析機能を強化するためのパッチを配布しています. パッチを適用したパッケージも配布しています.

動作確認

このパッケージは Ruby 1.8.5 および 1.9.0 での動作を確認しています.

チュートリアル

インストールに始まり, 実際に Fortran 90/95 ソースコードを作成してドキュメント化するまでのガイダンスとして, チュートリアル RDoc による数値モデルの自動ドキュメント生成 を用意しています.

ダウンロード

最新版 (バージョン $Name: rdoc-f95-20090109-1 $)

過去のアーカイブ

インストール

インストールには以下の 3 つの方法があります.

パッチファイルを利用する方法

パッチファイルを Ruby のオリジナル資源に適用する手順は以下の通りです.

まず, Ruby のホームページから ftp.ruby-lang.org/pub/ruby/1.8/ruby-1.8.7-p72.tar.gz をダウンロードしてください
上記 TGZ ファイルを展開してください.
```
  % tar -zxvf ruby-1.8.7-p72.tar.gz
```
このコマンドを実行したディレクトリに上記のパッチファイル rdoc-f95_ruby1.8.7-p72.patch を置き, 以下のコマンドでパッチを適用してください.
```
  % patch -p0 < rdoc-f95_ruby1.8.7-p72.patch
```
パッチを適用した後に, Ruby のインストール作業を行ってください. Ruby のインストール方法はオブジェクト指向スクリプト言語 Ruby のホームページを参照してください.

パッチが適用されたパッケージを利用する方法

パッチが適用された rdoc-f95.tgz パッケージを使用するには以下のようにします.

アーカイブファイル rdoc-f95.tgz をダウンロードした後に, 以下のように tar コマンドで展開後, 展開されたディレクトリに移動し, install.rb でインストールを行ってください. 既に rdoc がインストールされている場合, 上書きする可能性があります.

  % tar -zxvf rdoc-f95.tgz
  % cd rdoc-f95-XXXXXXXX
  % ruby install.rb

インストール先のディレクトリや, 変更のためのオプションに関しては, 以下のコマンドで知ることが出来ます.

  % ruby install.rb --help

Debian GNU/Linux 用バイナリパッケージを利用する方法

以下の URL を APT のソースリスト (/etc/apt/sources.list) に加えます. プロトコルとして http の代わりに ftp を用いることも可能です.

  deb http://www.gfd-dennou.org/library/cc-env/Linux/debian-dennou etch/

APT のコマンドでインストールを行ないます.

  % apt-get update
  % apt-get install rdoc-f95

このパッケージはオリジナルの rdoc パッケージのファイル群を退避した場所へ移動させるため, オリジナルの rdoc パッケージが使用できなくなります. オリジナルの rdoc パッケージを使用する場合は rdoc-f95 パッケージを削除してください. 退避されたオリジナルの rdoc パッケージのファイル群が本来の場所に復帰します.

以下の提案パッケージをインストールしておくと, diagram オプションや mathml オプション (下記参照) が使用可能になります.

  % apt-get install graphviz libmathml-ruby

RDoc の使用方法

実行プログラムがインストールされた場所を環境変数 PATH に設定し, ライブラリがインストールされた場所を環境変数 RUBYLIB に設定してください.

Fortran 90/95 ファイルが置いてあるディレクトリまで移動し, 以下のコマンドを実行してください. doc ディレクトリ以下にドキュメントが作成されます.

  % rdoc -U --ignore-case --charset euc-jp --inline-source

拡張子が .f90, .F90, .f95, .F95 であるファイルは Fortran 90/95 プログラムとして解析されます. サブディレクトリ以下の全ての Fortran 90/95 プログラムも解析されます.

なお, オリジナルの RDoc と同様, 拡張子が .rb, .rbw であるファイルは Ruby プログラムとして, 拡張子が .c, .cc, .cpp, .CC, .cxx であるファイルは C プログラムとして解析されます.

doc ディレクトリ以外に出力したい場合は, —op オプションをつけてください. タイトルは —title オプションで変更できます. また, デフォルトでは Fortran 90/95 の private 属性のサブルーチンや関数などはドキュメントに出力されませんが, —all オプションをつけることで, 全てがドキュメントに出力されます. —charsetオプションは, ドキュメントに反映されるコメントに日本語など 2 バイト文字が含まれる場合に用います. コメントの文字コードに合わせ, euc-jp, Shift_JIS, iso-2022-jp などを指定してください.

一部のファイルのみをドキュメント化したい場合は, 引数に src/*.f90 などとファイル名やディレクトリ名を明示的に指定してください. 以下の例では, "src/" 以下のディレクトリに存在する拡張子 ".f90" のファイルと, "test" ディレクトリ以下のファイルがドキュメント化されます.

  % rdoc -U --ignore-case --charset euc-jp --inline-source  \
         --op rdoc --title "RDoc documentations" src/*.f90 test/

この方法以外にも, ".document" ファイルを作成し, その中にファイル名やディレクトリ名を記述しておくことでドキュメント化するファイルを限定することが出来ます.

詳しいことは RDoc オリジナルの README を参照ください.

書法

解析される情報やドキュメントの見方, コメント部の書き方に関しては, parsers/parse_f95.rb を参照ください. —mathml オプション (下記参照) を使用する場合には, RDoc::Markup::ToXHtmlTexParser も参照ください. ただし, これらに記述されるのは Fortran 90/95 などに特有な部分なので, 一般的な部分に関しては RDoc オリジナルの README を参照ください. 大林さんによる日本語訳が www.kmc.gr.jp/~ohai/rdoc.ja.html にあります.

サンプル

オリジナルの RDoc との違い

ここで配布するパッチは, RDoc の Fortran 90/95 ソースコードの解析能力を大幅に向上させ, Fortran 90/95 プログラムから自動生成されるドキュメントの情報量を充実させます. 主に改良されているのは, 元々の RDoc に付属される Fortran 90/95 解析プログラム parse_f95.rb ですが, 他のいくつかのプログラムにも改良を施しています.

オリジナルの RDoc は Dave Thomas 氏によって開発され, 現在では Ryan Davis 氏, Eric Hodel 氏らによってメンテナンスされています. オリジナルの RDoc は Ruby のソースコードレポジトリより取得できます. Ruby レポジトリガイドを参照してください. オリジナルの RDoc に関しては RDoc オリジナルの README を参照してください.

オリジナルからの変更点の主なものは以下の通りです. なお, 既にこのパッチ (2005/12/17 バージョン) は Ruby 本家のソースコードレポジトリへとフィードバックされているので, 一部は既に「オリジナルとの変更点」ではなくなっていることに注意してください.

`—ignore-case` オプションの追加 :	Fortran 90/95 規格では大文字小文字の区別はありません. これに対して, オリジナルの RDoc はクラス名やメソッド名のクロスリファレンスの際に大文字小文字を区別します. このオプションを与えることにより, その区別を行わないようにします.
ファイルのクロスリファレンス :	クラスやモジュール, メソッドと同様に, ファイル名に関してもクロスリファレンスを可能にしました.
`—style` オプションの改良 :	オリジナルの RDoc では, 相対パスでスタイルシートを指定した場合, 各ドキュメントのスタイルシートへのパスが正しく設定されません. このパッチを適用することで, 正しく設定されるようになります.
TeX で書かれた数式の MathML への変換 :	ひらくの工房にて公開されている Ruby 用 MathML ライブラリのバージョン 0.6b ～ 0.8 をインストールすることで, TeX で書かれた数式を MathML の形式に変換することが可能です. この機能を有効にするためには rdoc コマンドに —mathml オプションを指定してください. TeX で数式を書く際の書式に関しては RDoc::Markup::ToXHtmlTexParser を参照してください. ※ 注意 ※ —mathml オプションを使用した際に作成されるドキュメントはブラウザによっては正しく表示されないこともあります. Mozilla Firefox および Internet Explorer (+ MathPlayer) では正しく表示されることを確認しています. その他のブラウザの MathML 対応に関しては, MathML 日本語情報や MathML Software - Browsers などを参照してください.

解析能力が向上されたのに伴い, ドキュメントに反映されるコメントの書法の多少変更されています. parsers/parse_f95.rb を参照してください.

使用上の注意

RDoc Fortran 90/95 ソースコード解析機能強化版のパッチもしくはパッケージ (以下, 本パッチもしくはパッケージ)は, 研究・教育の場で用いられることを前提としております. 教育現場においては自由に使用・改変していただいて結構です. ライセンス規定は本家 RDoc に準拠します. RDoc オリジナルの README を参照ください.

本パッチもしくはパッケージを利用して得られた科学技術的成果を論文や Web 等にて発表する際には, その旨を記し, リファレンスに挙げて頂きますようお願いします.

引用例 (和文)

  地球流体電脳倶楽部 dcmodel プロジェクト, 2008:
  http://www.gfd-dennou.org/library/dcmodel/, 地球流体電脳倶楽部.

引用例 (英文)

  GFD Dennou Club dcmodel project, 2008:
  http://www.gfd-dennou.org/library/dcmodel/, GFD Dennou Club.

連絡先

コメントや意見, 質問などはまでお寄せください.

参考文献

森川靖大, 石渡正樹, 堀之内武, 小高正嗣, 林祥介, 2007: RDoc を用いた数値モデルのドキュメント生成. 天気, 54, 185--190.

発表資料

森川靖大, 石渡正樹, 堀之内武, 小高正嗣, 林祥介, 「RDoc を用いた数値モデルのドキュメント生成」, 日本気象学会 2006 年度春季大会, つくば国際会議場, 2006 年 5 月 24 日 (講演番号 D401). 講演予稿, 発表資料 (HTML) 発表資料 (PDF).
森川靖大, 石渡正樹, 堀之内武, 小高正嗣, 林祥介, 「RDoc を用いた Fortran90/95 プログラムのドキュメント生成」, 地球惑星科学連合 2006 年大会, 幕張メッセ国際会議場, 2006 年 5 月 14 日 (講演番号 J157-016). 講演予稿, 発表資料 (HTML), 発表資料 (PDF).
森川靖大, 石渡正樹, 堀之内武, 小高正嗣, 林祥介, 「RDoc を用いた Fortran90/95 プログラムのドキュメント生成」, 2005 年 STEL 研究小集会, 宇宙地球系情報科学研究会, 愛媛大学総合情報メディアセンター, 2005 年 12 月 15 日. 発表資料

履歴

2009/01/09

パッチファイルを Ruby バージョン 1.8.7-p72 に対応.
サンプルのリンク先を更新.

2008/03/16

チュートリアル RDoc による数値モデルの自動ドキュメント生成 を作成.

2008/03/08

Ruby バージョン 1.9.0 に対応.
Ruby 用 MathML ライブラリバージョン 0.8 に対応.
README に参考文献と発表資料を追加. 引用例の変更.

2007/03/09

RiWriter が Ruby 1.8 で動作しないバグを修正.

2007/02/27

Ruby ソースコードレポジトリが CVS から SVN に変更されたことに伴い README, README.ja を修正.

2007/01/12

"FUNCTION Get_Platform() RESULT(platform)" のような Fortran 90/95 ソースコードが "Get_Platform( platform ) result(platform)" のように表示されてしまうバグの修正 (Hani Andreas Ibrahim 氏による報告より).

2007/01/09

Generators::TexParser の修正.

2007/01/05

連絡先アドレスを変更.
パッチファイルを Ruby バージョン 1.8.5-p12 に対応.
Generators::TexParser に解説「newcommand, newenvironment の使用方法」を追加.
parsers/parse_f95.rb に解説「利用者定義演算子, 利用者定義代入のクロスリファレンス」を追加.
parsers/parse_f95.rb の解説「言語要素の表示順序」を修正
クロスリファレンス時に一部 ’—ignore-case’ オプションが効かない問題を修正.

2006/12/15

パッチファイルを Ruby バージョン 1.8.5-p2 に対応.

2006/12/13

"!:doc-priority 100:" といったコメントの記述により, 表示される言語要素の順番を明示的に変更可能にする.

2006/11/20

".document" ファイルについて追記.
一つの interface ブロック内に記述される異なる名前の複数の副プログラムを正しく解析できるよう修正.
Ruby 本家の CVS の更新内容を移植.

2006/11/16

Generators::TexParser の改良.
- 解説文書に, 数式を複数行で表示する場合の例を追記.
- "$ID: … $" や "$LOG: … $ といった, CVS のキーワードとして用いられている書き方は数式として扱わない.
parse_f95.rb のために code_object.rb に追加した全てのメソッドを parse_f95.rb へ移動した. これにより, parse_f95.rb 単体を Ruby 1.8.5 に組み込んで使用することが可能となった.

2006/11/14

パッチファイルを Ruby バージョン 1.8.5 に対応.
パッチのファイル名を変更.
Debian GNU/Linux のバイナリパッケージの作成方法を修正.
生成されるドキュメントの XHTML のバージョンを XHTML 1.0 Transitional から XHTML 1.1 plus MathML 2.0 へ変更.
Fortran 90/95 パーサにおいて, 継続行の処理方法を修正.
Ruby 本家の CVS の更新内容を移植.
Institute for Plasma Physics の Giger 氏のコメントを受けて英語を修正
"../" で始まるファイル名をパースできないバグを修正.
使用する Ruby 用 MathML ライブラリのバージョンを 0.5 から 0.6a へ.
Ruby 用 MathML ライブラリを使用する際, エラーが生じても警告を発して動作を継続するよう修正.

2006/08/15

Debian GNU/Linux 用バイナリパッケージのインストール方法を改定.
NAMELIST のコメントを取得するプログラムのバグを修正.

2006/08/14

パッケージ名を rdoc-dennou から rdoc-f95 に変更.
公開アドレスを www.gfd-dennou.org/library/dcmodel/rdoc-dennou/ から www.gfd-dennou.org/library/dcmodel/rdoc-f95/ へ変更. (過去の URL もしばらく残しておきます).
README, README.ja の修正.
TeX で書かれた数式を MathML への変換する機能を追加.
style オプションの改良.
主プログラムも ‘Methods’ の欄に追加.
各ファイルに点在している NAMELIST 変数群を自動的に一箇所に集約して表示するよう改良.
F90 ファイルが提供するモジュール群の名前を, 自動的にファイルのドキュメントに追記するよう改良.

2006/02/24

英語版 README の作成
README.ja の修正.

2006/01/18

サブルーチン, 関数の引数の情報をコメントとして出力する際の書式を少しだけ修正.
- 引数情報をコメントに出力する際, 引数の後ろに空白を挿入した. これにより, メソッドの並び替えを行う際 (メソッドはメソッド名, 引数, コメントの順に大きさを比較し, 並べる順序を決める), "args" が "args(:)" よりも前に来るようになる.
本家 Ruby の CVS レポジトリ内の更新を受け, 最新版をこちらのパッケージ版にも移植.

2005/12/28

ruby 1.8.4 のリリースに伴い, パッチを 1.8.4 用に変更.

2005/12/17

同名の手続き同士で公開・非公開属性を誤って設定してしまうバグを修正.
以下のバグを修正
- program, module, subroutine, function の end 文は必ず end program, end module, end subroutine, end function のように記述しないと, 書法を正しく解析出来ない.
- program ～ end program 文の, 最初と最後の program という文字を省略した場合, program 文の内部で定義されるものは全て public だと認識される.
- ";" の文字をコメント内でも改行に変換してしまう
!— ～ !++ によるコメント削除の指定の際に, "!" よりも前に空白を含んでよいように修正.
interface 文で指定される外部手続きの解析を修正.
継続行の扱いを修正.

2005/12/13

parsers/parse_f95.rb に注意事項と Todo を追加.
「サンプル」を追加.
public, private 文を解析する部分のバグを修正.

2005/12/08

「使用上の注意」, 「連絡先」を追加.
公開アドレスを www.gfd-dennou.org/library/dcmodel/doc/rdoc-dennou/ から www.gfd-dennou.org/library/dcmodel/rdoc-dennou/ へ変更. (過去の URL もしばらく残しておきます).

2005/11/28

":nodoc:" の指定を可能にする.
サブルーチンや関数内の "contains" 文の処理方法を修正する.
表題を変更する.
過去のバージョンを公開する.

2005/11/17

一通り欲しい機能が揃い, ドキュメントのチェックも行ったので, タグをつけて公開する.

README.ja