rdoc-f95 0.0.1

data/History.txt

@@ -0,0 +1,4 @@
+== 0.0.1 2009-01-08
+
+* 1 major enhancement:
+  * Initial release

data/Manifest.txt

@@ -0,0 +1,79 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+lib/rdoc-f95.rb
+script/console
+script/destroy
+script/generate
+test/test_helper.rb
+test/test_rdoc-f95.rb
+bin/rdoc-f95
+lib/rdoc-f95/code_objects.rb
+lib/rdoc-f95/diagram.rb
+lib/rdoc-f95/dot.rb
+lib/rdoc-f95/generator
+lib/rdoc-f95/generator/chm.rb
+lib/rdoc-f95/generator/html.rb
+lib/rdoc-f95/generator/ri.rb
+lib/rdoc-f95/generator/xhtml.rb
+lib/rdoc-f95/generator/xml.rb
+lib/rdoc-f95/generator/chm
+lib/rdoc-f95/generator/chm/chm.rb
+lib/rdoc-f95/generator/html
+lib/rdoc-f95/generator/html/hefss.rb
+lib/rdoc-f95/generator/html/html.rb
+lib/rdoc-f95/generator/html/kilmer.rb
+lib/rdoc-f95/generator/html/one_page_html.rb
+lib/rdoc-f95/generator/xhtml
+lib/rdoc-f95/generator/xhtml/ctop.xsl
+lib/rdoc-f95/generator/xhtml/mathml.xsl
+lib/rdoc-f95/generator/xhtml/pmathml.xsl
+lib/rdoc-f95/generator/xhtml/pmathmlcss.xsl
+lib/rdoc-f95/generator/xhtml/xhtml.rb
+lib/rdoc-f95/generator/xml
+lib/rdoc-f95/generator/xml/rdf.rb
+lib/rdoc-f95/generator/xml/xml.rb
+lib/rdoc-f95/generator.rb
+lib/rdoc-f95/install.rb
+lib/rdoc-f95/markup
+lib/rdoc-f95/markup/formatter.rb
+lib/rdoc-f95/markup/fragments.rb
+lib/rdoc-f95/markup/inline.rb
+lib/rdoc-f95/markup/install.rb
+lib/rdoc-f95/markup/lines.rb
+lib/rdoc-f95/markup/mathml_wrapper.rb
+lib/rdoc-f95/markup/preprocess.rb
+lib/rdoc-f95/markup/to_flow.rb
+lib/rdoc-f95/markup/to_html.rb
+lib/rdoc-f95/markup/to_html_crossref.rb
+lib/rdoc-f95/markup/to_latex.rb
+lib/rdoc-f95/markup/to_test.rb
+lib/rdoc-f95/markup/to_xhtml_texparser.rb
+lib/rdoc-f95/markup/sample
+lib/rdoc-f95/markup/sample/rdoc2latex.rb
+lib/rdoc-f95/markup/sample/sample.rb
+lib/rdoc-f95/markup.rb
+lib/rdoc-f95/options.rb
+lib/rdoc-f95/parsers
+lib/rdoc-f95/parsers/parse_c.rb
+lib/rdoc-f95/parsers/parse_f95.rb
+lib/rdoc-f95/parsers/parse_rb.rb
+lib/rdoc-f95/parsers/parse_simple.rb
+lib/rdoc-f95/parsers/parserfactory.rb
+lib/rdoc-f95/ri
+lib/rdoc-f95/ri/cache.rb
+lib/rdoc-f95/ri/descriptions.rb
+lib/rdoc-f95/ri/display.rb
+lib/rdoc-f95/ri/driver.rb
+lib/rdoc-f95/ri/formatter.rb
+lib/rdoc-f95/ri/paths.rb
+lib/rdoc-f95/ri/reader.rb
+lib/rdoc-f95/ri/util.rb
+lib/rdoc-f95/ri/writer.rb
+lib/rdoc-f95/ri.rb
+lib/rdoc-f95/stats.rb
+lib/rdoc-f95/template.rb
+lib/rdoc-f95/tokenstream.rb
+lib/rdoc-f95/usage.rb

data/PostInstall.txt

@@ -0,0 +1,7 @@
+
+For more information on rdoc-f95, see http://rdoc-f95.rubyforge.org
+
+NOTE: Change this information in PostInstall.txt 
+You can also delete it if you don't want it.
+
+

data/README.rdoc

@@ -0,0 +1,147 @@
+= rdoc-f95: Enhanced version of RDoc Fortran 90/95 parser
+
+* Project Page: http://rubyforge.org/projects/rdoc/
+* Documentation: http://rdoc-f95.rubyforge.org/
+
+== INSTALLATION
+
+    % sudo gem install rdoc-f95
+
+== 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-f95 -U --ignore-case --inline-source
+
+Files ending <tt>.f90</tt>, <tt>.F90</tt>, <tt>.f95</tt>, <tt>.F95</tt>
+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 <tt>.rb</tt> and <tt>.rbw</tt>
+are parsed as Ruby programs and files ending with <tt>.c</tt>, <tt>.cc</tt>,
+<tt>.cpp</tt>, <tt>.CC</tt>, <tt>.cxx</tt> are parsed as C programs.
+
+With the option <tt>--op</tt>,  
+the directory where HTML documents are generated can be changed.
+<tt>--title</tt> option sets title of HTML documents.
+When <tt>--all</tt> 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,
+"<tt>src/*.f90</tt>" or "<tt>test/</tt>"), the particular files
+are parsed.
+In the following example, files with suffix "<tt>.f90</tt>" in a
+directory "<tt>src/</tt>" and files in a directory "<tt>test/</tt>"
+are parsed.
+
+  % rdoc-f95 -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
+"<tt>.document</tt>" file and writing names of the files and the
+directories to the file.
+
+For more information, 
+see http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html
+
+
+== RULES for RDocF95 Document
+
+Refer to {parse_f95.rb}[link:files/lib/rdoc-f95/parsers/parse_f95_rb.html] 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 <b>RDoc::Markup::ToXHtmlTexParser</b>, too.
+For general information, see
+http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.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}[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
+http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html
+or
+{RubyForge: rdoc Project}[http://rubyforge.org/projects/rdoc]
+
+Differences to the original one are given below.
+
+--
+#<b>Enhancement of an analytical performance of Fortran 90/95 source codes</b> ::
+#    See lib/rdoc-f95/parsers/parse_f95.rb for details.
+
+#<b>Modification of format of comment blocks</b> ::
+#    See lib/rdoc-f95/parsers/parse_f95.rb for details.
+++
+
+<b>Addition of <tt>--ignore-case</tt> option </b> ::
+    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.
+
+<b>Cross-reference of file names</b> ::
+    Cross-reference of file names is available as well as
+    modules, subroutines, and so on.
+
+<b>Modification of <tt>--style</tt> option</b> ::
+    Original RDoc can not treat relative path stylesheet.
+    Application of this patch modifies this function.
+
+<b>Conversion of TeX formula into MathML</b>::
+    TeX formula can be converted into MathML format
+    with --mathml option, 
+    if <b>MathML library for Ruby version 0.6b -- 0.8</b> is installed.
+    This library is available from {Bottega of Hiraku (only JAPANESE)}[http://www.hinet.mydns.jp/~hiraku/].
+    See <b>RDoc::Markup::ToXHtmlTexParser</b> about format.
+
+    <b>*** Caution ***</b>
+    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 {parse_f95.rb}[link:files/lib/rdoc-f95/parsers/parse_f95_rb.html]
+
+== LICENSE
+
+Licence of the enhanced version of RDoc Fortran 90/95 parser 
+conforms to that of original RDoc.
+see http://rdoc.rubyforge.org/
+
+
+== HISTORY
+
+=== 0.0.1
+
+* Initial release 
+

data/Rakefile

@@ -0,0 +1,28 @@
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/rdoc-f95'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('rdoc-f95', RDocF95::VERSION) do |p|
+  p.developer('FIXME full name', 'morikawa@gfd-dennou.org')
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
+  p.rubyforge_name       = p.name # TODO this is default value
+  # p.extra_deps         = [
+  #   ['activesupport','>= 2.0.2'],
+  # ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+  
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# task :default => [:spec, :features]

data/bin/rdoc-f95

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+#
+#  RDoc: Documentation tool for source code
+#        (see lib/rdoc/rdoc.rb for more information)
+#
+#  Copyright (c) 2003 Dave Thomas
+#  Released under the same terms as Ruby
+#
+#  $Revision: 1.2 $
+
+## Transitional Hack ####
+#
+#  RDoc was initially distributed independently, and installed
+#  itself into <prefix>/lib/ruby/site_ruby/<ver>/rdoc...
+#
+#  Now that RDoc is part of the distribution, it's installed into
+#  <prefix>/lib/ruby/<ver>, which unfortunately appears later in the
+#  search path. This means that if you have previously installed RDoc,
+#  and then install from ruby-lang, you'll pick up the old one by
+#  default. This hack checks for the condition, and readjusts the
+#  search path if necessary.
+
+#def adjust_for_existing_rdoc(path)
+#  
+#  $stderr.puts %{
+#  It seems as if you have a previously-installed RDoc in
+#  the directory #{path}.
+#
+#  Because this is now out-of-date, you might want to consider
+#  removing the directories:
+#
+#    #{File.join(path, "rdoc")}
+#
+#  and
+#
+#    #{File.join(path, "markup")}
+#
+#  }
+#
+#  # Move all the site_ruby directories to the end
+#  p $:
+#  $:.replace($:.partition {|path| /site_ruby/ !~ path}.flatten)
+#  p $:
+#end
+#
+# $:.each do |path|
+#  if /site_ruby/ =~ path 
+#    rdoc_path = File.join(path, 'rdoc', 'rdoc.rb')
+#    if File.exists?(rdoc_path)
+#      adjust_for_existing_rdoc(path)
+#      break
+#    end
+#  end
+#end
+
+## End of Transitional Hack ##
+
+
+require 'rdoc-f95'
+
+begin
+  r = RDocF95::RDocF95.new
+  r.document ARGV
+rescue Interrupt
+  $stderr.puts
+  $stderr.puts "Interrupted"
+rescue RDocF95::Error => e
+  $stderr.puts e.message
+  exit 1
+end

data/lib/rdoc-f95.rb

@@ -0,0 +1,306 @@
+# See README.
+#
+ 
+
+require 'rdoc-f95/parsers/parse_rb.rb'
+require 'rdoc-f95/parsers/parse_c.rb'
+require 'rdoc-f95/parsers/parse_f95.rb'
+require 'rdoc-f95/parsers/parse_simple.rb'
+
+require 'rdoc-f95/stats'
+require 'rdoc-f95/options'
+
+require 'rdoc-f95/diagram'
+
+require 'find'
+require 'fileutils'
+require 'time'
+
+module RDocF95
+
+  ##
+  # RDoc version you are using
+
+  VERSION = '0.0.1'
+
+  ##
+  # Exception thrown by any rdoc error.
+
+  class Error < RuntimeError; end
+
+  RDocError = Error # :nodoc:
+
+  DOT_DOC_FILENAME = ".document"
+
+  GENERAL_MODIFIERS = %w[nodoc].freeze
+
+  CLASS_MODIFIERS = GENERAL_MODIFIERS
+
+  ATTR_MODIFIERS  = GENERAL_MODIFIERS
+
+  CONSTANT_MODIFIERS = GENERAL_MODIFIERS
+
+  METHOD_MODIFIERS = GENERAL_MODIFIERS +
+    %w[arg args yield yields notnew not-new not_new doc]
+
+  ##
+  # Encapsulate the production of rdoc documentation. Basically
+  # you can use this as you would invoke rdoc from the command
+  # line:
+  #
+  #    rdoc = RDocF95::RDoc.new
+  #    rdoc.document(args)
+  #
+  # where _args_ is an array of strings, each corresponding to
+  # an argument you'd give rdoc on the command line. See rdoc/rdoc.rb
+  # for details.
+
+  class RDocF95
+
+    Generator = Struct.new(:file_name, :class_name, :key)
+
+    ##
+    # This is the list of output generator that we support
+
+    GENERATORS = {}
+
+    $LOAD_PATH.collect do |d|
+      File.expand_path d
+    end.find_all do |d|
+      File.directory? "#{d}/rdoc-f95/generator"
+    end.each do |dir|
+      Dir.entries("#{dir}/rdoc-f95/generator").each do |gen|
+        next unless /(\w+)\.rb$/ =~ gen
+        type = $1
+        unless GENERATORS.has_key? type
+          GENERATORS[type] = Generator.new("rdoc-f95/generator/#{gen}",
+                                           "#{type.upcase}".intern,
+                                           type)
+        end
+      end
+    end
+
+    def initialize
+      @stats = Stats.new
+    end
+
+    ##
+    # Report an error message and exit
+
+    def error(msg)
+      raise ::RDocF95::Error, msg
+    end
+
+    ##
+    # Create an output dir if it doesn't exist. If it does exist, but doesn't
+    # contain the flag file <tt>created.rid</tt> then we refuse to use it, as
+    # we may clobber some manually generated documentation
+
+    def setup_output_dir(op_dir, force)
+      flag_file = output_flag_file(op_dir)
+      if File.exist?(op_dir)
+        unless File.directory?(op_dir)
+          error "'#{op_dir}' exists, and is not a directory"
+        end
+        begin
+          created = File.read(flag_file)
+        rescue SystemCallError
+          error "\nDirectory #{op_dir} already exists, but it looks like it\n" +
+            "isn't an RDoc directory. Because RDoc doesn't want to risk\n" +
+            "destroying any of your existing files, you'll need to\n" +
+            "specify a different output directory name (using the\n" +
+            "--op <dir> option).\n\n"
+        else
+          last = (Time.parse(created) unless force rescue nil)
+        end
+      else
+        FileUtils.mkdir_p(op_dir)
+      end
+      last
+    end
+
+    ##
+    # Update the flag file in an output directory.
+
+    def update_output_dir(op_dir, time)
+      File.open(output_flag_file(op_dir), "w") {|f| f.puts time.rfc2822 }
+    end
+
+    ##
+    # Return the path name of the flag file in an output directory.
+
+    def output_flag_file(op_dir)
+      File.join(op_dir, "created.rid")
+    end
+
+    ##
+    # The .document file contains a list of file and directory name patterns,
+    # representing candidates for documentation. It may also contain comments
+    # (starting with '#')
+
+    def parse_dot_doc_file(in_dir, filename, options)
+      # read and strip comments
+      patterns = File.read(filename).gsub(/#.*/, '')
+
+      result = []
+
+      patterns.split.each do |patt|
+        candidates = Dir.glob(File.join(in_dir, patt))
+        result.concat(normalized_file_list(options,  candidates))
+      end
+      result
+    end
+
+    ##
+    # Given a list of files and directories, create a list of all the Ruby
+    # files they contain.
+    #
+    # If +force_doc+ is true we always add the given files, if false, only
+    # add files that we guarantee we can parse.  It is true when looking at
+    # files given on the command line, false when recursing through
+    # subdirectories.
+    #
+    # The effect of this is that if you want a file with a non-standard
+    # extension parsed, you must name it explicity.
+
+    def normalized_file_list(options, relative_files, force_doc = false,
+                             exclude_pattern = nil)
+      file_list = []
+
+      relative_files.each do |rel_file_name|
+        next if exclude_pattern && exclude_pattern =~ rel_file_name
+        stat = File.stat(rel_file_name)
+        case type = stat.ftype
+        when "file"
+          next if @last_created and stat.mtime < @last_created
+          file_list << rel_file_name.sub(/^\.\//, '') if force_doc || ParserFactory.can_parse(rel_file_name)
+        when "directory"
+          next if rel_file_name == "CVS" || rel_file_name == ".svn"
+          dot_doc = File.join(rel_file_name, DOT_DOC_FILENAME)
+          if File.file?(dot_doc)
+            file_list.concat(parse_dot_doc_file(rel_file_name, dot_doc, options))
+          else
+            file_list.concat(list_files_in_directory(rel_file_name, options))
+          end
+        else
+          raise RDocF95::Error, "I can't deal with a #{type} #{rel_file_name}"
+        end
+      end
+
+      file_list
+    end
+
+    ##
+    # Return a list of the files to be processed in a directory. We know that
+    # this directory doesn't have a .document file, so we're looking for real
+    # files. However we may well contain subdirectories which must be tested
+    # for .document files.
+
+    def list_files_in_directory(dir, options)
+      files = Dir.glob File.join(dir, "*")
+
+      normalized_file_list options, files, false, options.exclude
+    end
+
+    ##
+    # Parse each file on the command line, recursively entering directories.
+
+    def parse_files(options)
+      files = options.files
+      files = ["."] if files.empty?
+
+      file_list = normalized_file_list(options, files, true)
+
+      return [] if file_list.empty?
+
+      file_info = []
+      width = file_list.map { |name| name.length }.max + 1
+
+      file_list.each do |fn|
+        $stderr.printf("\n%*s: ", width, fn) unless options.quiet
+
+        content = if RUBY_VERSION >= '1.9' then
+                    File.open(fn, "r:ascii-8bit") { |f| f.read }
+                  else
+                    File.read fn
+                  end
+
+        if /coding:\s*(\S+)/ =~ content[/\A(?:.*\n){0,2}/]
+          if enc = Encoding.find($1)
+            content.force_encoding(enc)
+          end
+        end
+
+        top_level = TopLevel.new(fn)
+        parser = ParserFactory.parser_for(top_level, fn, content, options, @stats)
+        file_info << parser.scan
+        @stats.num_files += 1
+      end
+
+      file_info
+    end
+
+    ##
+    # Format up one or more files according to the given arguments.
+    #
+    # For simplicity, _argv_ is an array of strings, equivalent to the strings
+    # that would be passed on the command line. (This isn't a coincidence, as
+    # we _do_ pass in ARGV when running interactively). For a list of options,
+    # see rdoc/rdoc.rb. By default, output will be stored in a directory
+    # called +doc+ below the current directory, so make sure you're somewhere
+    # writable before invoking.
+    #
+    # Throws: RDocF95::Error on error
+
+    def document(argv)
+      TopLevel::reset
+
+      @options = Options.new GENERATORS
+      @options.parse argv
+
+      @last_created = nil
+
+      unless @options.all_one_file
+        @last_created = setup_output_dir(@options.op_dir, @options.force_update)
+      end
+
+      start_time = Time.now
+
+      file_info = parse_files @options
+
+      @options.title = "RDoc Documentation"
+
+      if file_info.empty?
+        $stderr.puts "\nNo newer files." unless @options.quiet
+      else
+        @gen = @options.generator
+
+        $stderr.puts "\nGenerating #{@gen.key.upcase}..." unless @options.quiet
+
+        require @gen.file_name
+
+        gen_class = ::RDocF95::Generator.const_get @gen.class_name
+        @gen = gen_class.for @options
+
+        pwd = Dir.pwd
+
+        Dir.chdir(@options.op_dir)  unless @options.all_one_file
+
+        begin
+          Diagram.new(file_info, @options).draw if @options.diagram
+          @gen.generate(file_info)
+          update_output_dir(".", start_time)
+        ensure
+          Dir.chdir(pwd)
+        end
+      end
+
+      unless @options.quiet
+        puts
+        @stats.print
+      end
+    end
+  end
+
+end
+