(Japanese | {English}[link:files/README.html])
= RDoc Fortran 90/95 ソースコード解析機能強化版
{RDoc - Ruby Documentation System}[http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html]
の Fortran 90/95 ソースコード解析機能を強化するためのパッチを
配布しています. パッチを適用したパッケージも配布しています.
== 動作確認
このパッケージは Ruby 1.8.5 および 1.9.0 での動作を確認しています.
== チュートリアル
インストールに始まり,
実際に Fortran 90/95 ソースコードを作成して
ドキュメント化するまでのガイダンスとして,
チュートリアル
{RDoc による数値モデルの自動ドキュメント生成}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/tutorial/]
を用意しています.
== ダウンロード
最新版 (バージョン $Name: rdoc-f95-20090109 $)
* {Ruby 1.8.7-p72 用のパッチ}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/rdoc-f95_ruby1.8.7-p72.patch]
--
* {Ruby 1.9.0 用のパッチ}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/rdoc-f95_ruby1.9.0.patch]
++
* {rdoc-f95 tar.gz パッケージ (Ruby 1.8.7-p72 の rdoc の部分を取り出し, 上記パッチを適用して tar ボールにしたもの)}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/rdoc-f95.tgz]
過去のアーカイブ
* {パッチ ・ TGZ パッケージ ・ ソースツリーのリスト}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/arch/SIGEN.htm]
* {Debian GNU/Linux 用バイナリパッケージ}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/debian]
== インストール
インストールには以下の 3 つの方法があります.
=== パッチファイルを利用する方法
パッチファイルを Ruby のオリジナル資源に適用する手順は
以下の通りです.
* まず, {Ruby のホームページ}[http://www.ruby-lang.org/] から
ftp://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 のホームページ}[http://www.ruby-lang.org/]
を参照してください.
=== パッチが適用されたパッケージを利用する方法
パッチが適用された 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}[link:files/README_org.html]
を参照ください.
== 書法
解析される情報やドキュメントの見方, コメント部の書き方に関しては,
parsers/parse_f95.rb を参照ください. --mathml オプション (下記参照)
を使用する場合には, RDoc::Markup::ToXHtmlTexParser も参照ください.
ただし, これらに記述されるのは Fortran 90/95 などに特有な部分なので,
一般的な部分に関しては
{RDoc オリジナルの README}[link:files/README_org.html]
を参照ください.
大林さんによる日本語訳が http://www.kmc.gr.jp/~ohai/rdoc.ja.html にあります.
== サンプル
* {地球流体数値モデルのための Fortran 90/95 ライブラリ gtool5 のコードリファレンス}[http://www.gfd-dennou.org/library/gtool/gtool5/gtool5_current/doc/develop_reference/]
* {惑星大気大循環モデル dcpam5 のコードリファレンス}[http://www.gfd-dennou.org/library/dcpam/dcpam5/dcpam5_current/doc/code_reference/xml]
== オリジナルの RDoc との違い
ここで配布するパッチは, RDoc の Fortran 90/95 ソースコードの
解析能力を大幅に向上させ, Fortran 90/95 プログラムから
自動生成されるドキュメントの情報量を充実させます.
主に改良されているのは, 元々の RDoc に付属される
{Fortran 90/95 解析プログラム parse_f95.rb}[http://svn.ruby-lang.org/cgi-bin/viewvc.cgi/trunk/lib/rdoc/parsers/parse_f95.rb]
ですが, 他のいくつかのプログラムにも改良を施しています.
オリジナルの RDoc は Dave Thomas さんによって開発され,
現在では Ryan Davis さんによってメンテナンスされています.
オリジナルの RDoc は Ruby のソースコードレポジトリ
より取得できます.
{Ruby レポジトリガイド}[http://www.ruby-lang.org/ja/documentation/repository-guide] を参照してください.
オリジナルの RDoc に関しては
{RDoc オリジナルの README}[link:files/README_org.html]
を参照してください.
オリジナルからの変更点の主なものは以下の通りです.
なお, 既にこのパッチ (2005/12/17 バージョン) は
Ruby 本家のソースコードレポジトリへとフィードバックされているので,
一部は既に「オリジナルとの変更点」
ではなくなっていることに注意してください.
--ignore-case オプションの追加 ::
Fortran 90/95 規格では大文字小文字の区別はありません.
これに対して, オリジナルの RDoc はクラス名やメソッド名の
クロスリファレンスの際に大文字小文字を区別します.
このオプションを与えることにより,
その区別を行わないようにします.
ファイルのクロスリファレンス ::
クラスやモジュール, メソッドと同様に, ファイル名に関しても
クロスリファレンスを可能にしました.
--style オプションの改良 ::
オリジナルの RDoc では, 相対パスでスタイルシートを指定した場合,
各ドキュメントのスタイルシートへのパスが正しく設定されません.
このパッチを適用することで, 正しく設定されるようになります.
TeX で書かれた数式の MathML への変換 ::
{ひらくの工房}[http://www.hinet.mydns.jp/~hiraku/]
にて公開されている
Ruby 用 MathML ライブラリのバージョン 0.6b 〜 0.8 を
インストールすることで, TeX で書かれた数式を
MathML の形式に変換することが可能です. この機能を有効
にするためには rdoc コマンドに --mathml オプションを
指定してください.
TeX で数式を書く際の書式に関しては
RDoc::Markup::ToXHtmlTexParser を参照してください.
※ 注意 ※ --mathml オプションを使用した際に作成される
ドキュメントはブラウザによっては正しく表示されないことも
あります.
{Mozilla Firefox}[http://www.mozilla.org/products/firefox/]
および Internet Explorer
(+ {MathPlayer}[http://www.dessci.com/en/products/mathplayer/])
では正しく表示されることを確認しています.
その他のブラウザの MathML 対応に関しては,
{MathML 日本語情報}[http://washitake.com/MathML/]
や {MathML Software - Browsers}[http://www.w3.org/Math/Software/mathml_software_cat_browsers.html]
などを参照してください.
--
# 以降は Fortran とは関係の無い改変
#
#Ruby ライブラリ IRB::SLex の読み込みについて ::
# Ruby 1.8.2 でも動作するよう, 最新の parse_rb.rb を1つ以前の
# バージョンに戻しています.
#
#
#拡張子cxxも C パーサで解釈 ::
# これは全く Fortran 90/95 とは関係ありません.
# この拡張子 cxx は c++ ファイルから
# SWIG[http://swig.shibu.jp/] によって作成されるファイルの拡張子です.
++
解析能力が向上されたのに伴い, ドキュメントに反映されるコメントの書法の
多少変更されています.
parsers/parse_f95.rb を参照してください.
== 使用上の注意
RDoc Fortran 90/95 ソースコード解析機能強化版のパッチもしくはパッケージ
(以下, 本パッチもしくはパッケージ)は,
研究・教育の場で用いられることを前提としております. 教育現場においては自由に使用・改変していただいて結構です.
ライセンス規定は本家 RDoc に準拠します.
{RDoc オリジナルの README}[link:files/README_org.html]
を参照ください.
本パッチもしくはパッケージを利用して得られた科学技術的成果を
論文や 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.
== 連絡先
コメントや意見, 質問などは link:../rdoc-f95-mailto.png までお寄せください.
== 参考文献
* {森川靖大, 石渡正樹, 堀之内武, 小高正嗣, 林祥介, 2007:
RDoc を用いた数値モデルのドキュメント生成. 天気, 54, 185--190.}[http://s-ws.net/tenki/cont/54_02/co.html]
== 発表資料
* 森川靖大, 石渡正樹, 堀之内武, 小高正嗣, 林祥介,
「RDoc を用いた数値モデルのドキュメント生成」,
日本気象学会 2006 年度春季大会,
つくば国際会議場, 2006 年 5 月 24 日 (講演番号 D401).
{講演予稿}[http://www.gfd-dennou.org/arch/prepri/2006/metsoc.spr/rdoc-dennou/yokou/pub/rdoc-dennou_2006_metsoc-spr_ver0.8.pdf],
{発表資料 (HTML)}[http://www.gfd-dennou.org/arch/prepri/2006/metsoc.spr/rdoc-dennou/presen/pub/]
{発表資料 (PDF)}[http://www.gfd-dennou.org/arch/prepri/2006/metsoc.spr/rdoc-dennou/presen/pub/metsoc-spr2006_rdoc-dennou_ver1.4.pdf].
* 森川靖大, 石渡正樹, 堀之内武, 小高正嗣, 林祥介,
「RDoc を用いた Fortran90/95 プログラムのドキュメント生成」,
地球惑星科学連合 2006 年大会,
幕張メッセ国際会議場, 2006 年 5 月 14 日 (講演番号 J157-016).
{講演予稿}[http://www.gfd-dennou.org/arch/prepri/2006/goudou/rdoc-dennou/yokou/pub/J157-016.pdf],
{発表資料 (HTML)}[http://www.gfd-dennou.org/arch/prepri/2006/goudou/rdoc-dennou/presen/pub/],
{発表資料 (PDF)}[http://www.gfd-dennou.org/arch/prepri/2006/goudou/rdoc-dennou/presen/pub/jpgu_rdoc-dennou_ver1.4.pdf].
* 森川靖大, 石渡正樹, 堀之内武, 小高正嗣, 林祥介,
「RDoc を用いた Fortran90/95 プログラムのドキュメント生成」,
2005 年 STEL 研究小集会,
宇宙地球系情報科学研究会, 愛媛大学総合情報メディアセンター,
2005 年 12 月 15 日.
{発表資料}[http://www.gfd-dennou.org/arch/prepri/2005/stel-gi/rdoc-dennou/pub/]
== 履歴
==== 2009/01/09
* パッチファイルを Ruby バージョン 1.8.7-p72 に対応.
* サンプルのリンク先を更新.
==== 2008/03/16
* チュートリアル
{RDoc による数値モデルの自動ドキュメント生成}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/tutorial/]
を作成.
==== 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 に変更.
* 公開アドレスを
http://www.gfd-dennou.org/library/dcmodel/rdoc-dennou/ から
http://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
* 「使用上の注意」, 「連絡先」を追加.
* 公開アドレスを
http://www.gfd-dennou.org/library/dcmodel/doc/rdoc-dennou/ から
http://www.gfd-dennou.org/library/dcmodel/rdoc-dennou/ へ変更.
(過去の URL もしばらく残しておきます).
==== 2005/11/28
* ":nodoc:" の指定を可能にする.
* サブルーチンや関数内の "contains" 文の処理方法を修正する.
* 表題を変更する.
* 過去のバージョンを公開する.
==== 2005/11/17
* 一通り欲しい機能が揃い, ドキュメントのチェックも行ったので,
タグをつけて公開する.