({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.5 and 1.9.0. -- == Tutorial A Japanese tutorial is prepared in {Auto-generation of documents of numerical models by RDoc}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/tutorial/]. English tutorial is not prepared ... (T-T) ++ == Download The latest version (Version $Name: rdoc-f95-20090109-1 $) * {Patch for Ruby 1.8.7-p72}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/rdoc-f95_ruby1.8.7-p72.patch] -- * {Patch for Ruby 1.9.0}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/rdoc-f95_ruby1.9.0.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/1.8/ruby-1.8.7-p72.tar.gz from {Ruby Home Page}[http://www.ruby-lang.org/]. * Unpack the archive file as % tar -zxvf ruby-1.8.7-p72.tar.gz * Put the patch file (rdoc-f95_ruby1.8.7-p72.patch) in the directory where you executed the tar command and apply the patch; % patch -p0 < rdoc-f95_ruby1.8.7-p72.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-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}[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 RDoc::Markup::ToXHtmlTexParser, too. For general information, see {README of original RDoc}[link:files/README_org.html] . == Samples * {Code reference of gtool5 library that is a Fortran 90/95 library for numerical models for geophysical fluid (only JAPANESE)}[http://www.gfd-dennou.org/library/gtool/gtool5/gtool5_current/doc/develop_reference/] * {Code reference of planetary atmospheric general circulation model DCPAM}[http://www.gfd-dennou.org/library/dcpam/dcpam5/dcpam5_current/doc/code_reference/xml] == 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://svn.ruby-lang.org/cgi-bin/viewvc.cgi/trunk/lib/rdoc/parser/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}[http://www.ruby-lang.org/en/news/2006/12/22/cvs-repository-moved-to-svn/]. For more information about RDoc, see {README of original RDoc}[link:files/README_org.html] or {RubyForge: rdoc Project}[http://rubyforge.org/projects/rdoc] 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 -- 0.8 is installed. This library is available from {Bottega of Hiraku (only JAPANESE)}[http://www.hinet.mydns.jp/~hiraku/]. 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}[http://www.mozilla.org/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: 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 link:../rdoc-f95-mailto.png . == References * {Yasuhiro MORIKAWA, Masaki ISHIWATARI, Takeshi HORINOUCHI, Masatsugu ODAKA, Yoshi-Yuki HAYASHI, 2007: Document generation for numerical models by RDoc. Tenki, 54, 185--190.}[http://s-ws.net/tenki/cont/54_02/co.html] (only JAPANESE) -- == Presentations ++ == 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 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.