README

Path: README
Last Update: Fri Jan 09 20:41:56 +0900 2009

(Japanese | English)

Enhanced version of RDoc Fortran 90/95 parser

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

Operation verification

Operation of the package has been verified with Ruby 1.8.5 and 1.9.0.

Download

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

Archives of old versions

Installation

You have the following three ways for installation.

Installation by applying the patch to original Ruby package

To use the patch file, follow the steps described below:

Installation by using patched RDoc package

To install the patched RDoc package, follow the steps described below:

  • Download archive file rdoc-f95.tgz
  • Unpack: 
      % tar -zxvf rdoc-f95.tgz
  • Go into the Ruby source directory: 
      % cd rdoc-f95-XXXXXXXX
  • 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

Installation by using binary packages for Debian GNU/Linux

Add following URL to sources.list of APT (/etc/apt/sources.list). You can use "ftp" protocol instead of "http". 

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

Install by APT commands. 

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

This "rdoc-f95" package disables original "rdoc" package because "rdoc-f95" moves files of "rdoc" to diverted location. If you want to use original "rdoc" package, please remove "rdoc-f95". Then files of original "rdoc" package will be returned to proper location.

Following suggested packages enable you to use "diagram" and "mathml" options (see below). 

  % apt-get install graphviz libmathml-ruby

Usage

Set the environment variable PATH to include the directory where the execution program is installed, and RUBYLIB 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 -U --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.

Just as in the original RDoc, files ending with .rb and .rbw are parsed as Ruby programs and files ending with .c, .cc, .cpp, .CC, .cxx are parsed as C programs.

With the option —op, the 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 or directories are specified as arguments (for example, "src/*.f90" or "test/"), the particular files are parsed. In the following example, files with suffix ".f90" in a directory "src/" and files in a directory "test/" are parsed. 

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

Alternatively, you can parse only a part of files by creating a ".document" file and writing names of the files and the directories to the file.

For more information, see README of original RDoc.

Rules for RDoc Document

Refer to 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 to RDoc::Markup::ToXHtmlTexParser, too. For general information, see README of original RDoc .

Samples

Differences from original RDoc

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

The original RDoc has been developed by Dave Thomas and is now maintained by Ryan Davis and Eric Hodel, etc. . The RDoc is available from the Ruby source code repository. See Ruby Repository Guide. For more information about RDoc, see README of original RDoc or RubyForge: rdoc Project

Differences to the original one are given below. Note that some differences were lost because this patch (2005/12/17 version) has been already included into the 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 format with —mathml option, if MathML library for Ruby version 0.6b — 0.8 is installed. This library is available from Bottega of Hiraku (only JAPANESE). See RDoc::Markup::ToXHtmlTexParser about format.

*** Caution *** Documents generated with "—mathml" option are not displayed correctly according to browser and/or its setting. We have been confirmed that documents generated with "—mathml" option are displayed correctly with Mozilla Firefox and Internet Explorer (+ MathPlayer). See MathML Software - Browsers for other browsers.

Some formats of comments in HTML document are changed to improve the analysis features. See parsers/parse_f95.rb for details.

Remarks on usage

The enhanced version of the RDoc Fortran 90/95 parser has been constructed on the premise of educational and academic usages only. For these uses, usage and modification of the resources withiout notification to the authors is permitted. Licence of the 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 the enhanced version of RDoc Fortran 90/95 parser, we will be very glad if you cite our resources in the following way: 

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

Contact

To contact us, please send an email to .

References

History

2009/01/09

  • Ruby version of a patch file is updated to 1.8.7-p72.
  • "Samples" are updated.

2008/03/16

  • Tutorial is created (only JAPANESE)

2008/03/08

  • Ruby version 1.9.0 is supported.
  • MathML library for Ruby version 0.8 is supported.
  • References and presentations are added to README. An example of citation is changed.

2007/03/09

  • A bug that RiWriter can not operate in Ruby 1.8 is fixed.

2007/02/27

  • README and README.ja are modified due to movement of Ruby source code Repository from CVS to SVN.

2007/01/12

  • A bug that Fortran 90/95 source code like "FUNCTION Get_Platform() RESULT(platform)" is converted to "Get_Platform( platform ) result(platform)" is fixed. (by the advice from Hani Andreas Ibrahim).

2007/01/09

  • Generators::TexParser is modified.

2007/01/05

  • Contact address is changed.
  • Ruby version of a patch file is updated to 1.8.5-p12.
  • Document "Usage of newcommand and newenvironment" is added in Generators::TexParser.
  • Document "Cross-reference of defined operators and defined assignments" is added in parsers/parse_f95.rb.
  • Document "The sequence of displayed entities" in parsers/parse_f95.rb is modified.
  • A bug that ’—ignore-case’ option is invalid partly is fixed.

2006/12/15

  • Ruby version of a patch file is updated to 1.8.5-p2

2006/12/13

  • The sequence of displayed entities can be ordered manually by the comment like "!:doc-priority 100:".

2006/11/20

  • Description about ".docuemnt" file is added.
  • Some subprograms which have different names in one interface block are parsed correctly.
  • Import updates of RDoc in original Ruby CVS.

2006/11/16

  • Generators::TexParser is modified/
    • A way to write equations across multiple lines is described in document.
    • The format of CVS keywords, that is "$ID: … $" or "$LOG: … $ etc. is ignored.
  • All methods added to "code_object.rb" for "parse_f95.rb" are moved to "parse_f95.rb". Therefore "parse_f95.rb" works alone in Ruby 1.8.5 .

2006/11/14

  • Ruby version of a patch file is updated to 1.8.5
  • Patch filename is changed.
  • Debian GNU/Linux binary packages are modified.
  • XHTML version of documents is changed from "XHTML 1.0 Transitional" to "XHTML 1.1 plus MathML 2.0".
  • Interpreter of continuous lines is modified.
  • Import updates of RDoc in original Ruby CVS.
  • English is corrected with comments of Dr. Geiger (Institute for Plasma Physics)
  • File names beginning "../" are parsed correctly.
  • A version of MathML library for Ruby is changed from 0.5 to 0.6b.
  • Syntax error with MathML library for Ruby is avoided.

2006/08/15

  • Description about installation with binary packages for Debian GNU/Linux is modified.
  • Bugs about parsing comments of NAMELIST is modified.

2006/08/14

  • Package name is changed as "rdoc-f95" from "rdoc-dennou".
  • 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

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.

[Validate]