({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 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 === 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 rdoc1.8 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 .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/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.