({Japanese}[link:files/README_ja.html] | English)

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

Here is a patch file to improve
RDoc[http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html]
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-20060815 $)

* {Patch for Ruby 1.8.4}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/rdoc-f95-patch_for_ruby1.8.4]

* {TGZ file of RDoc resources to which above patch applied }[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/rdoc-f95.tgz]

Archives of old versions

* {Patch files, TGZ packages, source code trees (only JAPANESE)}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/arch/SIGEN.htm]

* {Binary packages for Debian GNU/Linux}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/debian]


== Installation

You have following three ways to install.

=== A way to install by applying the patch to original Ruby package

To use the patch file, follow steps described below:

* Download
  ftp://ftp.ruby-lang.org/pub/ruby/ruby-1.8.4.tar.gz
  from {Ruby Home Page}[http://www.ruby-lang.org/].

* 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}[http://www.ruby-lang.org/].


=== A way to install by using 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

<b>If rdoc is already installed, the original rdoc will be overritten</b>.

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

  % ruby install.rb --help

=== A way to install 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 stable/

Install by APT commands.

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

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

  % apt-get install graphviz libmathml-ruby

==== *** Attention when the package is deleted ***

When you want to uninstall rdoc-f95, delete <b>rdoc1.8</b> package
as follows.

  % apt-get remove rdoc1.8

If you need the only original rdoc package, delete rdoc1.8-f95, and
reinstall rdoc1.8.

  % apt-get remove rdoc1.8-f95
  % apt-get install --reinstall rdoc1.8

Description: rdoc-f95 is a dependency package, which depends on
rdoc1.8-f95 package. And rdoc1.8-f95 replaces a part of contents of
rdoc1.8 package. Therefore, when you uninstall rdoc1.8-f95, rdoc1.8
becomes defective. To repair rdoc1.8 package, reinstalling is
needed. This reinstalling does not delete packages that depend on
rdoc.
(This packaging enables an installation and an uninstallation of
rdoc-f95 package not to influence packages that depend on
original rdoc package).


== 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 <tt>.f90</tt>, <tt>.F90</tt>, <tt>.f95</tt>, <tt>.F95</tt>
are parsed as Fortran 90/95 programs.
All Fortran 90/95 programs in subdirectories are parsed recursively.

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

With <tt>--op</tt> option,  
directory where HTML documents are generated can be changed.
<tt>--title</tt> option sets title of HTML documents.
When <tt>--all</tt> 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,
<tt>src/*.f90</tt>), 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}[link:files/README_org.html].


== Rules for RDoc Document

Refer <b>parsers/parse_f95.rb</b> 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 <b>Generators::TexParser</b>, too.
For general information, see
{README of original RDoc}[link:files/README_org.html] .

== Samples

* {Code reference of data I/O library gt4f90io (only JAPANESE)}[http://www.gfd-dennou.org/library/gtool4/gt4f90io/gt4f90io_current/doc/develop_reference/]

* {Code reference of planetary atmospheric general circulation model DCPAM (only JAPANESE)}[http://www.gfd-dennou.org/library/dcpam/dcpam3/dcpam3_current/doc/code_reference/htm]

== Differences from original RDoc

This patch is created for enhancing Fortran 90/95 parser of RDoc .
{Fortran 90/95 parse script parse_f95.rb}[http://www.ruby-lang.org/cgi-bin/cvsweb.cgi/ruby/lib/rdoc/parsers/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 http://www.ruby-lang.org/ja/20020106.html .
For more information about RDoc, 
see
{README of original RDoc}[link:files/README_org.html] .

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.

--
#<b>Enhancement of an analytical performance of Fortran 90/95 source codes</b> ::
#    See parsers/parse_f95.rb for details.

#<b>Modification of format of comment blocks</b> ::
#    See parsers/parse_f95.rb for details.
++

<b>Addition of <tt>--ignore-case</tt> option </b> ::
    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.

<b>Cross-reference of file names</b> ::
    Cross-reference of file names is available as well as
    modules, subroutines, and so on.

<b>Modification of <tt>--style</tt> option</b> ::
    Original rdoc can not treat relative path stylesheet.
    Application of this patch modifies this function.

<b>Conversion of TeX formula into MathML </b>::
    TeX formula can be converted into MathML.
    <b>MathML library for Ruby version 0.5</b> is needed.
    This library is available from {Bottega of Hiraku (JAPANESE only)}[http://www.hinet.mydns.jp/~hiraku/].
    If you use this function, use --mathml option.
    See Generators::TexParser about format.

    <b>*** Caution ***</b>
    Documents generated with "--mathml" option are displayed correctly
    with {Mozilla Firefox}[http://www.mozilla.or.jp/products/firefox/]
    or Internet Explorer
    (+ {MathPlayer}[http://www.dessci.com/en/products/mathplayer/]).
    See {MathML Software - Browsers}[http://www.w3.org/Math/Software/mathml_software_cat_browsers.html]
    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}[link:files/README_org.html] .

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}[http://www.gfd-dennou.org/library/dcmodel/index.htm.en]


== History

==== 2006/08/15

* A way to install by using binary packages for Debian GNU/Linux
  is modified.
* Bugs about parsing comments of NAMELIST is modified.

==== 2006/08/14

* Package name is changed from "rdoc-dennou" to "rdoc-f95".
* Address is changed as
  http://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 
  http://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.
