README.ja

Path: README.ja
Last Update: Thu Nov 16 04:18:01 JST 2006

(Japanese | English)

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

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

動作確認

このパッケージは Ruby 1.8.2 での動作を確認しています.

ダウンロード

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

過去のアーカイブ

インストール

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

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

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

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

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

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

  % tar xvfz rdoc-f95.tgz
  % cd rdoc-f95
  % 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 stable/

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 などと ファイル名を明示的に指定してください. 以下の例参照.

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

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

書法

解析される情報やドキュメントの見方, コメント部の書き方に関しては, parsers/parse_f95.rb を参照ください. —mathml オプション (下記参照) を使用する場合には, Generators::TexParser も参照ください. ただし, これらに記述されるのは 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 さんによってメンテナンスされています. オリジナルの RDoc は Ruby の CVS レポジトリ www.ruby-lang.org/ja/20020106.html より取得できます. オリジナルの RDoc に関しては RDoc オリジナルの README を参照してください.

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

—ignore-case オプションの追加 :Fortran 90/95 規格では大文字小文字の区別はありません. これに対して, オリジナルの rdoc はクラス名やメソッド名の クロスリファレンスの際に大文字小文字を区別します. このオプションを与えることにより, その区別を行わないようにします.
ファイルのクロスリファレンス :クラスやモジュール, メソッドと同様に, ファイル名に関しても クロスリファレンスを可能にしました.
—style オプションの改良 :オリジナルの rdoc では, 相対パスでスタイルシートを指定した場合, 各ドキュメントのスタイルシートへのパスが正しく設定されません. このパッチを適用することで, 正しく設定されるようになります.
TeX で書かれた数式の MathML への変換 :ひらくの工房 にて公開されている Ruby 用 MathML ライブラリのバージョン 0.6b を インストールすることで, TeX で書かれた数式を MathML の形式に変換することが可能です. この機能を有効 にするためには rdoc コマンドに —mathml オプションを 指定してください. TeX で数式を書く際の書式に関しては Generators::TexParser を参照してください.

※ 注意 ※ —mathml オプションを使用した際に作成される ドキュメントはブラウザによっては正しく表示されないことも あります. Mozilla Firefox および Internet Explorer (+ MathPlayer) では正しく表示されることを確認しています. その他のブラウザの MathML 対応に関しては, MathML 日本語情報MathML Software - Browsers などを参照してください.

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

使用上の注意

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

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

  • 引用例 (和文)
      森川 靖大, 石渡 正樹, 堀之内 武, 小高 正嗣, 林 祥介,
      数値モデリングプロジェクト dcmodel, 2006:
      RDoc Fortran 90/95 ソースコード解析機能強化版,
      http://www.gfd-dennou.org/library/dcmodel/, 地球流体電脳倶楽部.
    
  • 引用例 (英文)
      Morikawa,Y., Ishiwatari,M., Horinouchi,T., Odaka,M., Hayashi,Y.-Y.,
      dcmodel: Numerical Model Porject, 2006:
      Enhanced version of RDoc Fortran 90/95 parser,
      http://www.gfd-dennou.org/library/dcmodel/, GFD Dennou Club.
    

連絡先

数値モデリングプロジェクト dcmodel のページ末尾を参照ください.

履歴

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

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

2005/11/28

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

2005/11/17

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

[Validate]