({Japanese}[link:files/README_ja.html] | English)
= Enhanced version of RDoc Fortran 90/95 parser
Here is a patch file to improve
the RDoc[http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html]
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.2.
== Download
The latest version (Version $Name: rdoc-f95-20061116 $)
* {Patch for Ruby 1.8.5}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/rdoc-f95_ruby1.8.5.patch]
* {TGZ file of patched RDoc resources}[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 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:
* Download
ftp://ftp.ruby-lang.org/pub/ruby/ruby-1.8.5.tar.gz
from {Ruby Home Page}[http://www.ruby-lang.org/].
* Unpack the archive file as
% tar -zxvf ruby-1.8.5.tar.gz
* Put the patch file (rdoc-f95_ruby1.8.5.patch)
in the directory where you executed the tar command
and apply the patch;
% patch -p0 < rdoc-f95_ruby1.8.5.patch
* Install RDoc package as written in
{Site of the Ruby}[http://www.ruby-lang.org/].
=== 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
* 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 stable/
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 are specified as arguments (for example,
src/*.f90), the particular files are parsed.
An Example is the following.
% rdoc -U --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 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 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 has been created for enhancing the Fortran 90/95 parser of RDoc .
{The 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.
The original RDoc has been developed by Dave Thomas and is now
maintained by Ryan Davis. 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 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.
--
#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 format
with --mathml option,
if MathML library for Ruby version 0.6b is installed.
This library is available from {Bottega of Hiraku (JAPANESE only)}[http://www.hinet.mydns.jp/~hiraku/].
See Generators::TexParser 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}[http://www.mozilla.or.jp/products/firefox/]
and 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]
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}[link:files/README_org.html] .
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:
Morikawa,Y., Ishiwatari,M., Horinouchi,T., Odaka,M., Hayashi,Y.-Y.,
dcmodel: Numerical Model Project, 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 Project}[http://www.gfd-dennou.org/library/dcmodel/index.htm.en]
== History
==== 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
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.