rdoc-f95 0.0.1

data/lib/rdoc-f95/generator/chm.rb

@@ -0,0 +1,113 @@
+require 'rdoc-f95/generator/html'
+
+class RDocF95::Generator::CHM < RDocF95::Generator::HTML
+
+  HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe"
+
+  ##
+  # Standard generator factory
+
+  def self.for(options)
+    new(options)
+  end
+
+  def initialize(*args)
+    super
+    @op_name = @options.op_name || "rdoc"
+    check_for_html_help_workshop
+  end
+
+  def check_for_html_help_workshop
+    stat = File.stat(HHC_PATH)
+  rescue
+    $stderr <<
+      "\n.chm output generation requires that Microsoft's Html Help\n" <<
+      "Workshop is installed. RDoc looks for it in:\n\n    " <<
+      HHC_PATH <<
+      "\n\nYou can download a copy for free from:\n\n" <<
+      "    http://msdn.microsoft.com/library/default.asp?" <<
+      "url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp\n\n"
+  end
+
+  ##
+  # Generate the html as normal, then wrap it in a help project
+
+  def generate(info)
+    super
+    @project_name = @op_name + ".hhp"
+    create_help_project
+  end
+
+  ##
+  # The project contains the project file, a table of contents and an index
+
+  def create_help_project
+    create_project_file
+    create_contents_and_index
+    compile_project
+  end
+
+  ##
+  # The project file links together all the various
+  # files that go to make up the help.
+
+  def create_project_file
+    template = RDocF95::TemplatePage.new @template::HPP_FILE
+    values = { "title" => @options.title, "opname" => @op_name }
+    files = []
+    @files.each do |f|
+      files << { "html_file_name" => f.path }
+    end
+
+    values['all_html_files'] = files
+
+    File.open(@project_name, "w") do |f|
+      template.write_html_on(f, values)
+    end
+  end
+
+  ##
+  # The contents is a list of all files and modules.
+  # For each we include  as sub-entries the list
+  # of methods they contain. As we build the contents
+  # we also build an index file
+
+  def create_contents_and_index
+    contents = []
+    index    = []
+
+    (@files+@classes).sort.each do |entry|
+      content_entry = { "c_name" => entry.name, "ref" => entry.path }
+      index << { "name" => entry.name, "aref" => entry.path }
+
+      internals = []
+
+      methods = entry.build_method_summary_list(entry.path)
+
+      content_entry["methods"] = methods unless methods.empty?
+      contents << content_entry
+      index.concat methods
+    end
+
+    values = { "contents" => contents }
+    template = RDocF95::TemplatePage.new @template::CONTENTS
+    File.open("contents.hhc", "w") do |f|
+      template.write_html_on(f, values)
+    end
+
+    values = { "index" => index }
+    template = RDocF95::TemplatePage.new @template::CHM_INDEX
+    File.open("index.hhk", "w") do |f|
+      template.write_html_on(f, values)
+    end
+  end
+
+  ##
+  # Invoke the windows help compiler to compiler the project
+
+  def compile_project
+    system(HHC_PATH, @project_name)
+  end
+
+end
+

data/lib/rdoc-f95/generator/chm/chm.rb

@@ -0,0 +1,98 @@
+require 'rdoc-f95/generator/chm'
+require 'rdoc-f95/generator/html/html'
+
+module RDocF95::Generator::CHM::CHM
+
+  HTML = RDocF95::Generator::HTML::HTML
+
+  INDEX = HTML::INDEX
+
+  CLASS_INDEX = HTML::CLASS_INDEX
+  CLASS_PAGE = HTML::CLASS_PAGE
+  FILE_INDEX = HTML::FILE_INDEX
+  FILE_PAGE = HTML::FILE_PAGE
+  METHOD_INDEX = HTML::METHOD_INDEX
+  METHOD_LIST = HTML::METHOD_LIST
+
+  FR_INDEX_BODY = HTML::FR_INDEX_BODY
+
+  # This is a nasty little hack, but hhc doesn't support the <?xml tag, so...
+  BODY = HTML::BODY.sub!(/<\?xml.*\?>/, '')
+  SRC_PAGE = HTML::SRC_PAGE.sub!(/<\?xml.*\?>/, '')
+
+  HPP_FILE = <<-EOF
+[OPTIONS]
+Auto Index = Yes
+Compatibility=1.1 or later
+Compiled file=<%= values["opname"] %>.chm
+Contents file=contents.hhc
+Full-text search=Yes
+Index file=index.hhk
+Language=0x409 English(United States)
+Title=<%= values["title"] %>
+
+[FILES]
+<% values["all_html_files"].each do |all_html_files| %>
+<%= all_html_files["html_file_name"] %>
+<% end # values["all_html_files"] %>
+  EOF
+
+  CONTENTS = <<-EOF
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<HTML>
+<HEAD>
+<meta name="GENERATOR" content="Microsoft&reg; HTML Help Workshop 4.1">
+<!-- Sitemap 1.0 -->
+</HEAD><BODY>
+<OBJECT type="text/site properties">
+	<param name="Foreground" value="0x80">
+	<param name="Window Styles" value="0x800025">
+	<param name="ImageType" value="Folder">
+</OBJECT>
+<UL>
+<% values["contents"].each do |contents| %>
+	<LI> <OBJECT type="text/sitemap">
+		<param name="Name" value="<%= contents["c_name"] %>">
+		<param name="Local" value="<%= contents["ref"] %>">
+		</OBJECT>
+<% if contents["methods"] then %>
+<ul>
+<% contents["methods"].each do |methods| %>
+	<LI> <OBJECT type="text/sitemap">
+		<param name="Name" value="<%= methods["name"] %>">
+		<param name="Local" value="<%= methods["aref"] %>">
+		</OBJECT>
+<% end # contents["methods"] %>
+</ul>
+<% end %>
+        </LI>
+<% end # values["contents"] %>
+</UL>
+</BODY></HTML>
+  EOF
+
+  CHM_INDEX = <<-EOF
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<HTML>
+<HEAD>
+<meta name="GENERATOR" content="Microsoft&reg; HTML Help Workshop 4.1">
+<!-- Sitemap 1.0 -->
+</HEAD><BODY>
+<OBJECT type="text/site properties">
+	<param name="Foreground" value="0x80">
+	<param name="Window Styles" value="0x800025">
+	<param name="ImageType" value="Folder">
+</OBJECT>
+<UL>
+<% values["index"].each do |index| %>
+	<LI> <OBJECT type="text/sitemap">
+		<param name="Name" value="<%= index["name"] %>">
+		<param name="Local" value="<%= index["aref"] %>">
+		</OBJECT>
+<% end # values["index"] %>
+</UL>
+</BODY></HTML>
+  EOF
+
+end
+

data/lib/rdoc-f95/generator/html.rb

@@ -0,0 +1,370 @@
+require 'fileutils'
+
+require 'rdoc-f95/generator'
+require 'rdoc-f95/markup/to_html'
+
+##
+# We're responsible for generating all the HTML files from the object tree
+# defined in code_objects.rb. We generate:
+#
+# [files]   an html file for each input file given. These
+#           input files appear as objects of class
+#           TopLevel
+#
+# [classes] an html file for each class or module encountered.
+#           These classes are not grouped by file: if a file
+#           contains four classes, we'll generate an html
+#           file for the file itself, and four html files
+#           for the individual classes.
+#
+# [indices] we generate three indices for files, classes,
+#           and methods. These are displayed in a browser
+#           like window with three index panes across the
+#           top and the selected description below
+#
+# Method descriptions appear in whatever entity (file, class, or module) that
+# contains them.
+#
+# We generate files in a structure below a specified subdirectory, normally
+# +doc+.
+#
+#  opdir
+#     |
+#     |___ files
+#     |       |__  per file summaries
+#     |
+#     |___ classes
+#             |__ per class/module descriptions
+#
+# HTML is generated using the Template class.
+
+class RDocF95::Generator::HTML
+
+  include RDocF95::Generator
+  include RDocF95::Generator::MarkUp
+
+  ##
+  # Generator may need to return specific subclasses depending on the
+  # options they are passed. Because of this we create them using a factory
+
+  def self.for(options)
+    RDocF95::Generator::AllReferences.reset
+    RDocF95::Generator::Method.reset
+
+    if options.all_one_file
+      RDocF95::Generator::HTMLInOne.new options
+    else
+      new options
+    end
+  end
+
+  class << self
+    protected :new
+  end
+
+  ##
+  # Set up a new HTML generator. Basically all we do here is load up the
+  # correct output temlate
+
+  def initialize(options) #:not-new:
+    @options = options
+    load_html_template
+  end
+
+  ##
+  # Build the initial indices and output objects
+  # based on an array of TopLevel objects containing
+  # the extracted information.
+
+  def generate(toplevels)
+    @toplevels  = toplevels
+    @files      = []
+    @classes    = []
+
+    write_style_sheet
+    gen_sub_directories()
+    build_indices
+    generate_html
+  end
+
+  private
+
+  ##
+  # Load up the HTML template specified in the options.
+  # If the template name contains a slash, use it literally
+
+  def load_html_template
+    template = @options.template
+
+    unless template =~ %r{/|\\} then
+      template = ::File.join('rdoc-f95', 'generator', @options.generator.key,
+                             template)
+    end
+
+    require template
+
+    @template = self.class.const_get @options.template.upcase
+    @options.template_class = @template
+
+  rescue LoadError
+    $stderr.puts "Could not find HTML template '#{template}'"
+    exit 99
+  end
+
+  ##
+  # Write out the style sheet used by the main frames
+
+  def write_style_sheet
+    return unless @template.constants.include? :STYLE or
+                  @template.constants.include? 'STYLE'
+
+    template = RDocF95::TemplatePage.new @template::STYLE
+
+    unless @options.css then
+      open RDocF95::Generator::CSS_NAME, 'w' do |f|
+        values = {}
+
+        if @template.constants.include? :FONTS or
+           @template.constants.include? 'FONTS' then
+          values["fonts"] = @template::FONTS
+        end
+
+        template.write_html_on(f, values)
+      end
+    end
+  end
+
+  ##
+  # See the comments at the top for a description of the directory structure
+
+  def gen_sub_directories
+    FileUtils.mkdir_p RDocF95::Generator::FILE_DIR
+    FileUtils.mkdir_p RDocF95::Generator::CLASS_DIR
+  rescue
+    $stderr.puts $!.message
+    exit 1
+  end
+
+  def build_indices
+    @files, @classes = RDocF95::Generator::Context.build_indicies(@toplevels,
+                                                               @options)
+  end
+
+  ##
+  # Generate all the HTML
+
+  def generate_html
+    # the individual descriptions for files and classes
+    gen_into(@files)
+    gen_into(@classes)
+    # and the index files
+    gen_file_index
+    gen_class_index
+    gen_method_index
+    gen_main_index
+
+    # this method is defined in the template file
+    write_extra_pages if defined? write_extra_pages
+  end
+
+  def gen_into(list)
+    list.each do |item|
+      if item.document_self
+        op_file = item.path
+        FileUtils.mkdir_p(::File.dirname(op_file))
+        open(op_file, "w") { |file| item.write_on(file) }
+      end
+    end
+
+  end
+
+  def gen_file_index
+    gen_an_index @files, 'Files', @template::FILE_INDEX, "fr_file_index.html"
+  end
+
+  def gen_class_index
+    gen_an_index(@classes, 'Classes', @template::CLASS_INDEX,
+                 "fr_class_index.html")
+  end
+
+  def gen_method_index
+    gen_an_index(RDocF95::Generator::Method.all_methods, 'Methods',
+                 @template::METHOD_INDEX, "fr_method_index.html")
+  end
+
+  def gen_an_index(collection, title, template, filename)
+    template = RDocF95::TemplatePage.new @template::FR_INDEX_BODY, template
+    res = []
+    collection.sort.each do |f|
+      if f.document_self
+        res << { "href" => f.path, "name" => f.index_name }
+      end
+    end
+
+    values = {
+      "entries"    => res,
+      'list_title' => CGI.escapeHTML(title),
+      'index_url'  => main_url,
+      'charset'    => @options.charset,
+      'style_url'  => style_url('', @options.css),
+    }
+
+    open filename, 'w' do |f|
+      template.write_html_on(f, values)
+    end
+  end
+
+  ##
+  # The main index page is mostly a template frameset, but includes the
+  # initial page. If the <tt>--main</tt> option was given, we use this as
+  # our main page, otherwise we use the first file specified on the command
+  # line.
+
+  def gen_main_index
+    template = RDocF95::TemplatePage.new @template::INDEX
+
+    open 'index.html', 'w'  do |f|
+      classes = @classes.sort.map { |klass| klass.value_hash }
+
+      values = {
+        'main_page'     => @main_page,
+        'initial_page'  => main_url,
+        'style_url'     => style_url('', @options.css),
+        'title'         => CGI.escapeHTML(@options.title),
+        'charset'       => @options.charset,
+        'classes'       => classes,
+      }
+
+      values['inline_source'] = @options.inline_source
+
+      template.write_html_on f, values
+    end
+  end
+
+  ##
+  # Returns the url of the main page
+
+  def main_url
+    @main_page = @options.main_page
+    @main_page_ref = nil
+    if @main_page
+      @main_page_ref = AllReferences[@main_page]
+      if @main_page_ref then
+        @main_page_path = @main_page_ref.path
+      else
+        $stderr.puts "Could not find main page #{@main_page}"
+      end
+    end
+
+    unless @main_page_path then
+      file = @files.find { |file| file.document_self }
+      @main_page_path = file.path if file
+    end
+
+    unless @main_page_path then
+      $stderr.puts "Couldn't find anything to document"
+      $stderr.puts "Perhaps you've used :stopdoc: in all classes"
+      exit 1
+    end
+
+    @main_page_path
+  end
+
+end
+
+class RDocF95::Generator::HTMLInOne < RDocF95::Generator::HTML
+
+  def initialize(*args)
+    super
+  end
+
+  ##
+  # Build the initial indices and output objects
+  # based on an array of TopLevel objects containing
+  # the extracted information.
+
+  def generate(info)
+    @toplevels  = info
+    @hyperlinks = {}
+
+    build_indices
+    generate_xml
+  end
+
+  ##
+  # Generate:
+  #
+  # * a list of RDocF95::Generator::File objects for each TopLevel object.
+  # * a list of RDocF95::Generator::Class objects for each first level
+  #   class or module in the TopLevel objects
+  # * a complete list of all hyperlinkable terms (file,
+  #   class, module, and method names)
+
+  def build_indices
+    @files, @classes = RDocF95::Generator::Context.build_indices(@toplevels,
+                                                              @options)
+  end
+
+  ##
+  # Generate all the HTML. For the one-file case, we generate
+  # all the information in to one big hash
+
+  def generate_xml
+    values = {
+      'charset' => @options.charset,
+      'files'   => gen_into(@files),
+      'classes' => gen_into(@classes),
+      'title'        => CGI.escapeHTML(@options.title),
+    }
+
+    # this method is defined in the template file
+    write_extra_pages if defined? write_extra_pages
+
+    template = RDocF95::TemplatePage.new @template::ONE_PAGE
+
+    if @options.op_name
+      opfile = open @options.op_name, 'w'
+    else
+      opfile = $stdout
+    end
+    template.write_html_on(opfile, values)
+  end
+
+  def gen_into(list)
+    res = []
+    list.each do |item|
+      res << item.value_hash
+    end
+    res
+  end
+
+  def gen_file_index
+    gen_an_index(@files, 'Files')
+  end
+
+  def gen_class_index
+    gen_an_index(@classes, 'Classes')
+  end
+
+  def gen_method_index
+    gen_an_index(RDocF95::Generator::Method.all_methods, 'Methods')
+  end
+
+  def gen_an_index(collection, title)
+    res = []
+    collection.sort.each do |f|
+      if f.document_self
+        res << { "href" => f.path, "name" => f.index_name }
+      end
+    end
+
+    return {
+      "entries" => res,
+      'list_title' => title,
+      'index_url'  => main_url,
+    }
+  end
+
+end
+
+