(Japanese | English)

Enhanced version of RDoc Fortran 90/95 parser (for GFD Dennou Club dcmodel project)

Here is a patch file to improve RDoc analysis feature for Fortran 90/95 source codes. Patched package of RDoc source is also available.

Operation verification

Operation of this package are verified with Ruby 1.8.2.

Download

The latest version (Version $Name: rdoc-f95-20060814 $)

• Patch for Ruby 1.8.4
• TGZ file of RDoc resources to which above patch applied
• Binary packages for Debian GNU/Linux

Archives of old versions

• Patch files, TGZ packages, source code trees (only JAPANESE)

Install

How to apply the patch to original Ruby package

To use the patch file, follow steps described below:

• Download ftp.ruby-lang.org/pub/ruby/ruby-1.8.4.tar.gz from Ruby Home Page.
• Unpack the archive file as

    % tar xvfz ruby-1.8.4.tar.gz
  

• Put the patch file (rdoc-f95-patch_for_ruby1.8.4) on the directory where you executed tar command, and apply the patch;

    % patch -p0 < rdoc-f95-patch_for_ruby1.8.4
  

• Install RDoc package as written in Site of the Ruby.

How to install patched RDoc package

To install RDoc package which is patched, follow steps described below:

• Download archive file rdoc-f95.tgz
• Unpack:

    % tar xvfz rdoc-f95.tgz
  

• Go into the Ruby source directory:

    % cd rdoc-f95
  

• Install the package:

    % ruby install.rb
  

If rdoc is already installed, the original rdoc will be overritten.

Use —help option to show options and the directory to which rdoc is installed:

  % ruby install.rb --help

How to use binary packages for Debian GNU/Linux

Download a debian package, and install as follows.

  % dpkg -i rdoc-f95_20060809_i386.deb

Original "rdoc" package is replaced with this "rdoc-f95" package. If you add following URL to sources.list of APT, you can install and update "rdoc-f95" package by APT commands.

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

Usage

Set environment variable PATH so as to include the directory where the execution program is installed, and RUBYLIB so as to include the directory where the libraries are installed.

Move to a directory where your Fortran 90/95 files exist, and execute the following command. HTML documents will be generated in doc directory.

  % rdoc --ignore-case --inline-source

Files ending .f90, .F90, .f95, .F95 are parsed as Fortran 90/95 programs. All Fortran 90/95 programs in subdirectories are parsed recursively.

As well as original RDoc, files ending .rb and .rbw are parsed as Ruby programs, files ending .c, .cc, .cpp, .CC, .cxx are parsed as C programs.

With —op option, directory where HTML documents are generated can be changed. —title option sets title of HTML documents. When —all option is used, private subroutines, functions etc. in Fortran 90/95 programs are shown in HTML documents (for developers). If files are specified as arguments (for example, src/*.f90), the particular files are parsed. An Example is the following.

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

For more information, see README of original RDoc.

Rules for RDoc Document

Refer parsers/parse_f95.rb which explains parsed information, way of looking at documents, the format of comment blocks in Fortran 90/95 source code. If you use "—mathml" option (see below), refer Generators::TexParser, too. For general information, see README of original RDoc .

Samples

• Code reference of data I/O library gt4f90io (only JAPANESE)
• Code reference of planetary atmospheric general circulation model DCPAM (only JAPANESE)

Differences from original RDoc

This patch is created for enhancing Fortran 90/95 parser of RDoc . Fortran 90/95 parse script parse_f95.rb is mainly modified, and other programs are also improved.

Original RDoc is developed by Dave Thomas, and now, maintained by Ryan Davis. The RDoc is available from Ruby CVS repository www.ruby-lang.org/ja/20020106.html . For more information about RDoc, see README of original RDoc .

Differences with original are as follows. Note that some differences were lost because this patch (2005/12/17 version) was already taken into original RDoc package.

Addition of —ignore-case option :	In the Fortran 90/95 Standard, upper case letters are not distinguished from lower case letters, although original RDoc produces case-dependently cross-references of Class and Methods. When this options is specified, upper cases are not distinguished from lower cases.
Cross-reference of file names :	Cross-reference of file names is available as well as modules, subroutines, and so on.
Modification of —style option :	Original rdoc can not treat relative path stylesheet. Application of this patch modifies this function.
Conversion of TeX formula into MathML :	TeX formula can be converted into MathML. MathML library for Ruby version 0.5 is needed. This library is available from Bottega of Hiraku (JAPANESE only). If you use this function, use —mathml option. See Generators::TexParser about format. *** Caution *** Documents generated with "—mathml" option are displayed correctly with Mozilla Firefox or Internet Explorer (+ MathPlayer). See MathML Software - Browsers about other browsers.

Some formats of comments in HTML document are changed because of improvement of analysis features. See parsers/parse_f95.rb for details.

Remarks in use

Enhanced version of RDoc Fortran 90/95 parser is being constructed on the premise of the uses for educations and academic researches. For those uses, the resources are permitted to use and modify without any notification. Licence of Enhanced version of RDoc Fortran 90/95 parser conforms to that of original RDoc. See README of original RDoc .

When you publish your scientific/technological works using Enhanced version of RDoc Fortran 90/95 parser, we will be very glad if you cite our resources in the following way:

  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.

Contact

Please see end of dcmodel: GFD Dennou Club Numerical Model Porject

History

2006/08/14

• Package name is changed from "rdoc-dennou" to "rdoc-f95".
• Address is changed as www.gfd-dennou.org/library/dcmodel/rdoc-f95/
• README and README.ja are modified.
• Conversion of TeX formula into MathML is enable.
• Modification of —style option.
• Main programs are added to ‘Methods’ too.
• The NAMELIST group names scattered in each file are collected on one page.
• Names of modules provided by F90 files are added to documents of the files automatically.

2006/02/24

• English version of README is created.

2006/01/18

• Comment formats for arguments of subroutines and functions are slightly modified.
  • A space is inserted below the argument described in HTML document.
• Patched package is rebulid with updated Ruby resources in CVS repository.

2005/12/28

• Patch file for ruby 1.8.4 is released.

2005/12/17

• Some bugs are fixed.
• Parsing external subroutines specified interface are improved.
• Handling of Continuation lines are improved.

2005/12/13

• Remarks and Todo are added in parsers/parse_f95.rb
• Sample is added in README
• Parsing part of public, private statements are improved.

2005/12/08

• "Remarks in use" and "Contact" are added in README .
• Address is changed as www.gfd-dennou.org/library/dcmodel/rdoc-dennou/

2005/11/28

• ":nodoc:" tag are available.
• Parsing "contains" in subroutines and functions are improved.
• Title is changed.
• Old version of the patches are placed in web page.

2005/11/17

• Improvement of analysis features, checking HTML documents which are produced by RDoc. release of preliminary version.