({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-20060814 $)
* {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]
* {Binary packages for Debian GNU/Linux}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/debian]
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]
== Install
=== How to apply 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/].
=== 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}[link:files/README_org.html].
== 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}[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.
--
#Enhancement of an analytical performance of Fortran 90/95 source codes ::
# See parsers/parse_f95.rb for details.
#Modification of format of comment blocks ::
# See parsers/parse_f95.rb for details.
++
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)}[http://www.hinet.mydns.jp/~hiraku/].
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}[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/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.