We put rdoc stuff in the RDoc module to avoid namespace clutter.

ToDo: This isn‘t universally true.

(Japanese | English)

Enhanced version of RDoc Fortran 90/95 parser

Here is a patch file to improve the RDoc 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-20070309 $)

Archives of old versions

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.ruby-lang.org/pub/ruby/ruby-1.8.5-p12.tar.gz from Ruby Home Page.
Unpack the archive file as
```
  % tar -zxvf ruby-1.8.5-p12.tar.gz
```
Put the patch file (rdoc-f95_ruby1.8.5-p12.patch) in the directory where you executed the tar command and apply the patch;
```
  % patch -p0 < rdoc-f95_ruby1.8.5-p12.patch
```
Install RDoc package as written in Site of the Ruby.

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 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.

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 .

Samples

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 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. The RDoc is available from the Ruby source code repository. See Ruby Repository Guide. For more information about RDoc, see README of original 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 is installed. This library is available from Bottega of Hiraku (JAPANESE only). 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 and Internet Explorer (+ MathPlayer). See MathML Software - Browsers 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 .

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, 2007:
  Enhanced version of RDoc Fortran 90/95 parser,
  http://www.gfd-dennou.org/library/dcmodel/, GFD Dennou Club.

Contact

To contact us, please send an email to .

History

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 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 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.

Methods

extract_sections extract_sections find_comment find_comment gets gets no_comment no_comment usage usage usage_no_exit usage_no_exit

Classes and Modules

Module RDoc::ParserFactory
Class RDoc::Alias
Class RDoc::AnonClass
Class RDoc::AnyMethod
Class RDoc::Attr
Class RDoc::C_Parser
Class RDoc::ClassModule
Class RDoc::CodeObject
Class RDoc::Constant
Class RDoc::Context
Class RDoc::Diagram
Class RDoc::Fortran95parser
Class RDoc::Include
Class RDoc::NormalClass
Class RDoc::NormalModule
Class RDoc::RDoc
Class RDoc::RDocError
Class RDoc::Require
Class RDoc::RubyParser
Class RDoc::SimpleParser
Class RDoc::SingleClass
Class RDoc::Stats
Class RDoc::Token
Class RDoc::TopLevel

Constants

DOT_DOC_FILENAME	=	".document"	Name of the dotfile that contains the description of files to be processed in the current directory
KNOWN_CLASSES	=	{ "rb_cObject" => "Object", "rb_cArray" => "Array", "rb_cBignum" => "Bignum", "rb_cClass" => "Class", "rb_cDir" => "Dir", "rb_cData" => "Data", "rb_cFalseClass" => "FalseClass", "rb_cFile" => "File", "rb_cFixnum" => "Fixnum", "rb_cFloat" => "Float", "rb_cHash" => "Hash", "rb_cInteger" => "Integer", "rb_cIO" => "IO", "rb_cModule" => "Module", "rb_cNilClass" => "NilClass", "rb_cNumeric" => "Numeric", "rb_cProc" => "Proc", "rb_cRange" => "Range", "rb_cRegexp" => "Regexp", "rb_cString" => "String", "rb_cSymbol" => "Symbol", "rb_cThread" => "Thread", "rb_cTime" => "Time", "rb_cTrueClass" => "TrueClass", "rb_cStruct" => "Struct", "rb_eException" => "Exception", "rb_eStandardError" => "StandardError", "rb_eSystemExit" => "SystemExit", "rb_eInterrupt" => "Interrupt", "rb_eSignal" => "Signal", "rb_eFatal" => "Fatal", "rb_eArgError" => "ArgError", "rb_eEOFError" => "EOFError", "rb_eIndexError" => "IndexError", "rb_eRangeError" => "RangeError", "rb_eIOError" => "IOError", "rb_eRuntimeError" => "RuntimeError", "rb_eSecurityError" => "SecurityError", "rb_eSystemCallError" => "SystemCallError", "rb_eTypeError" => "TypeError", "rb_eZeroDivError" => "ZeroDivError", "rb_eNotImpError" => "NotImpError", "rb_eNoMemError" => "NoMemError", "rb_eFloatDomainError" => "FloatDomainError", "rb_eScriptError" => "ScriptError", "rb_eNameError" => "NameError", "rb_eSyntaxError" => "SyntaxError", "rb_eLoadError" => "LoadError", "rb_mKernel" => "Kernel", "rb_mComparable" => "Comparable", "rb_mEnumerable" => "Enumerable", "rb_mPrecision" => "Precision", "rb_mErrno" => "Errno", "rb_mFileTest" => "FileTest", "rb_mGC" => "GC", "rb_mMath" => "Math", "rb_mProcess" => "Process"
GENERAL_MODIFIERS	=	[ 'nodoc' ].freeze
CLASS_MODIFIERS	=	GENERAL_MODIFIERS
ATTR_MODIFIERS	=	GENERAL_MODIFIERS
CONSTANT_MODIFIERS	=	GENERAL_MODIFIERS
METHOD_MODIFIERS	=	GENERAL_MODIFIERS + [ 'arg', 'args', 'yield', 'yields', 'notnew', 'not-new', 'not_new', 'doc' ]
DOT_DOC_FILENAME	=	".document"	Name of the dotfile that contains the description of files to be processed in the current directory

Public Class methods

extract_sections(flow, sections)

Given an array of flow items and an array of section names, extract those sections from the flow which have headings corresponding to a section name in the list. Return them in the order of names in the sections array.

[Source]

     # File usage.rb, line 165
165:   def RDoc.extract_sections(flow, sections)
166:     result = []
167:     sections.each do |name|
168:       name = name.downcase
169:       copy_upto_level = nil
170: 
171:       flow.each do |item|
172:         case item
173:         when SM::Flow::H
174:           if copy_upto_level && item.level >= copy_upto_level
175:             copy_upto_level = nil
176:           else
177:             if item.text.downcase == name
178:               result << item
179:               copy_upto_level = item.level
180:             end
181:           end
182:         else
183:           if copy_upto_level
184:             result << item
185:           end
186:         end
187:       end
188:     end
189:     if result.empty?
190:       puts "Note to developer: requested section(s) [#{sections.join(', ')}] " +
191:            "not found"
192:       result = flow
193:     end
194:     result
195:   end

extract_sections(flow, sections)

[Source]

     # File doc-tmp/rdoc/usage.rb, line 165
165:   def RDoc.extract_sections(flow, sections)
166:     result = []
167:     sections.each do |name|
168:       name = name.downcase
169:       copy_upto_level = nil
170: 
171:       flow.each do |item|
172:         case item
173:         when SM::Flow::H
174:           if copy_upto_level && item.level >= copy_upto_level
175:             copy_upto_level = nil
176:           else
177:             if item.text.downcase == name
178:               result << item
179:               copy_upto_level = item.level
180:             end
181:           end
182:         else
183:           if copy_upto_level
184:             result << item
185:           end
186:         end
187:       end
188:     end
189:     if result.empty?
190:       puts "Note to developer: requested section(s) [#{sections.join(', ')}] " +
191:            "not found"
192:       result = flow
193:     end
194:     result
195:   end

find_comment(file)

[Source]

     # File usage.rb, line 141
141:   def RDoc.find_comment(file)
142:     catch(:exit) do
143:       # skip leading blank lines
144:       0 while (line = gets(file)) && (line =~ /^\s*$/)
145: 
146:       comment = []
147:       while line && line =~ /^\s*#/
148:         comment << line
149:         line = gets(file)
150:       end
151: 
152:       0 while line && (line = gets(file))
153:       return no_comment if comment.empty?
154:       return comment.join
155:     end
156:   end

find_comment(file)

[Source]

     # File doc-tmp/rdoc/usage.rb, line 141
141:   def RDoc.find_comment(file)
142:     catch(:exit) do
143:       # skip leading blank lines
144:       0 while (line = gets(file)) && (line =~ /^\s*$/)
145: 
146:       comment = []
147:       while line && line =~ /^\s*#/
148:         comment << line
149:         line = gets(file)
150:       end
151: 
152:       0 while line && (line = gets(file))
153:       return no_comment if comment.empty?
154:       return comment.join
155:     end
156:   end

gets(file)

Find the first comment in the file (that isn‘t a shebang line) If the file doesn‘t start with a comment, report the fact and return empty string

[Source]

     # File usage.rb, line 133
133:   def RDoc.gets(file)
134:     if (line = file.gets) && (line =~ /^#!/) # shebang
135:       throw :exit, find_comment(file)
136:     else
137:       line
138:     end
139:   end

gets(file)

Find the first comment in the file (that isn‘t a shebang line) If the file doesn‘t start with a comment, report the fact and return empty string

[Source]

     # File doc-tmp/rdoc/usage.rb, line 133
133:   def RDoc.gets(file)
134:     if (line = file.gets) && (line =~ /^#!/) # shebang
135:       throw :exit, find_comment(file)
136:     else
137:       line
138:     end
139:   end

no_comment()

Report the fact that no doc comment count be found

[Source]

     # File usage.rb, line 199
199:   def RDoc.no_comment
200:     $stderr.puts "No usage information available for this program"
201:     ""
202:   end

no_comment()

Report the fact that no doc comment count be found

[Source]

     # File doc-tmp/rdoc/usage.rb, line 199
199:   def RDoc.no_comment
200:     $stderr.puts "No usage information available for this program"
201:     ""
202:   end

usage(*args)

Display usage information from the comment at the top of the file. String arguments identify specific sections of the comment to display. An optional integer first argument specifies the exit status (defaults to 0)

[Source]

    # File doc-tmp/rdoc/usage.rb, line 81
81:   def RDoc.usage(*args)
82:     exit_code = 0
83: 
84:     if args.size > 0
85:       status = args[0]
86:       if status.respond_to?(:to_int)
87:         exit_code = status.to_int
88:         args.shift
89:       end
90:     end
91: 
92:     # display the usage and exit with the given code
93:     usage_no_exit(*args)
94:     exit(exit_code)
95:   end

usage(*args)

[Source]

    # File usage.rb, line 81
81:   def RDoc.usage(*args)
82:     exit_code = 0
83: 
84:     if args.size > 0
85:       status = args[0]
86:       if status.respond_to?(:to_int)
87:         exit_code = status.to_int
88:         args.shift
89:       end
90:     end
91: 
92:     # display the usage and exit with the given code
93:     usage_no_exit(*args)
94:     exit(exit_code)
95:   end

usage_no_exit(*args)

Display usage

[Source]

     # File usage.rb, line 98
 98:   def RDoc.usage_no_exit(*args)
 99:     main_program_file, = caller[-1].split(/:\d+/, 2)
100:     comment = File.open(main_program_file) do |file|
101:       find_comment(file)
102:     end
103: 
104:     comment = comment.gsub(/^\s*#/, '')
105: 
106:     markup = SM::SimpleMarkup.new
107:     flow_convertor = SM::ToFlow.new
108:     
109:     flow = markup.convert(comment, flow_convertor)
110: 
111:     format = "plain"
112: 
113:     unless args.empty?
114:       flow = extract_sections(flow, args)
115:     end
116: 
117:     options = RI::Options.instance
118:     if args = ENV["RI"]
119:       options.parse(args.split)
120:     end
121:     formatter = options.formatter.new(options, "")
122:     formatter.display_flow(flow)
123:   end

usage_no_exit(*args)

Display usage

[Source]

     # File doc-tmp/rdoc/usage.rb, line 98
 98:   def RDoc.usage_no_exit(*args)
 99:     main_program_file, = caller[-1].split(/:\d+/, 2)
100:     comment = File.open(main_program_file) do |file|
101:       find_comment(file)
102:     end
103: 
104:     comment = comment.gsub(/^\s*#/, '')
105: 
106:     markup = SM::SimpleMarkup.new
107:     flow_convertor = SM::ToFlow.new
108:     
109:     flow = markup.convert(comment, flow_convertor)
110: 
111:     format = "plain"
112: 
113:     unless args.empty?
114:       flow = extract_sections(flow, args)
115:     end
116: 
117:     options = RI::Options.instance
118:     if args = ENV["RI"]
119:       options.parse(args.split)
120:     end
121:     formatter = options.formatter.new(options, "")
122:     formatter.display_flow(flow)
123:   end