* lib/rdoc.rb, lib/rdoc, test/rdoc: Update to RDoc 4.2.0.alpha(313287)

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@47391 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

11 files changed, 438 insertions, 22 deletions

diff --git a/lib/rdoc/generator/pot.rb b/lib/rdoc/generator/pot.rb
new file mode 100644
index 0000000000..db6f3a0354
--- /dev/null
+++ b/lib/rdoc/generator/pot.rb
@@ -0,0 +1,97 @@
+##
+# Generates a POT file.
+#
+# Here is a translator work flow with the generator.
+#
+# == Create .pot
+#
+# You create .pot file by pot formatter:
+#
+#   % rdoc --format pot
+#
+# It generates doc/rdoc.pot.
+#
+# == Create .po
+#
+# You create .po file from doc/rdoc.pot. This operation is needed only
+# the first time. This work flow assumes that you are a translator
+# for Japanese.
+#
+# You create locale/ja/rdoc.po from doc/rdoc.pot. You can use msginit
+# provided by GNU gettext or rmsginit provided by gettext gem. This
+# work flow uses gettext gem because it is more portable than GNU
+# gettext for Rubyists. Gettext gem is implemented by pure Ruby.
+#
+#   % gem install gettext
+#   % mkdir -p locale/ja
+#   % rmsginit --input doc/rdoc.pot --output locale/ja/rdoc.po --locale ja
+#
+# Translate messages in .po
+#
+# You translate messages in .po by a PO file editor. po-mode.el exists
+# for Emacs users. There are some GUI tools such as GTranslator.
+# There are some Web services such as POEditor and Tansifex. You can
+# edit by your favorite text editor because .po is a text file.
+# Generate localized documentation
+#
+# You can generate localized documentation with locale/ja/rdoc.po:
+#
+#   % rdoc --locale ja
+#
+# You can find documentation in Japanese in doc/. Yay!
+#
+# == Update translation
+#
+# You need to update translation when your application is added or
+# modified messages.
+#
+# You can update .po by the following command lines:
+#
+#   % rdoc --format pot
+#   % rmsgmerge --update locale/ja/rdoc.po doc/rdoc.pot
+#
+# You edit locale/ja/rdoc.po to translate new messages.
+
+class RDoc::Generator::POT
+
+  RDoc::RDoc.add_generator self
+
+  ##
+  # Description of this generator
+
+  DESCRIPTION = 'creates .pot file'
+
+  ##
+  # Set up a new .pot generator
+
+  def initialize store, options #:not-new:
+    @options    = options
+    @store      = store
+  end
+
+  ##
+  # Writes .pot to disk.
+
+  def generate
+    po = extract_messages
+    pot_path = 'rdoc.pot'
+    File.open(pot_path, "w") do |pot|
+      pot.print(po.to_s)
+    end
+  end
+
+  def class_dir
+    nil
+  end
+
+  private
+  def extract_messages
+    extractor = MessageExtractor.new(@store)
+    extractor.extract
+  end
+
+  autoload :MessageExtractor, 'rdoc/generator/pot/message_extractor'
+  autoload :PO,               'rdoc/generator/pot/po'
+  autoload :POEntry,          'rdoc/generator/pot/po_entry'
+
+end
diff --git a/lib/rdoc/generator/pot/message_extractor.rb b/lib/rdoc/generator/pot/message_extractor.rb
new file mode 100644
index 0000000000..ceabc5262a
--- /dev/null
+++ b/lib/rdoc/generator/pot/message_extractor.rb
@@ -0,0 +1,67 @@
+##
+# Extracts message from RDoc::Store
+
+class RDoc::Generator::POT::MessageExtractor
+
+  ##
+  # Creates a message extractor for +store+.
+
+  def initialize store
+    @store = store
+    @po = RDoc::Generator::POT::PO.new
+  end
+
+  ##
+  # Extracts messages from +store+, stores them into
+  # RDoc::Generator::POT::PO and returns it.
+
+  def extract
+    @store.all_classes_and_modules.each do |klass|
+      extract_from_klass(klass)
+    end
+    @po
+  end
+
+  private
+
+  def extract_from_klass klass
+    extract_text(klass.comment_location, klass.full_name)
+
+    klass.each_section do |section, constants, attributes|
+      extract_text(section.title ,"#{klass.full_name}: section title")
+      section.comments.each do |comment|
+        extract_text(comment, "#{klass.full_name}: #{section.title}")
+      end
+    end
+
+    klass.each_constant do |constant|
+      extract_text(constant.comment, constant.full_name)
+    end
+
+    klass.each_attribute do |attribute|
+      extract_text(attribute.comment, attribute.full_name)
+    end
+
+    klass.each_method do |method|
+      extract_text(method.comment, method.full_name)
+    end
+  end
+
+  def extract_text text, comment, location = nil
+    return if text.nil?
+
+    options = {
+      :extracted_comment => comment,
+      :references => [location].compact,
+    }
+    i18n_text = RDoc::I18n::Text.new(text)
+    i18n_text.extract_messages do |part|
+      @po.add(entry(part[:paragraph], options))
+    end
+  end
+
+  def entry msgid, options
+    RDoc::Generator::POT::POEntry.new(msgid, options)
+  end
+
+end
diff --git a/lib/rdoc/generator/pot/po.rb b/lib/rdoc/generator/pot/po.rb
new file mode 100644
index 0000000000..0d45c57dc1
--- /dev/null
+++ b/lib/rdoc/generator/pot/po.rb
@@ -0,0 +1,84 @@
+##
+# Generates a PO format text
+
+class RDoc::Generator::POT::PO
+
+  ##
+  # Creates an object that represents PO format.
+
+  def initialize
+    @entries = {}
+    add_header
+  end
+
+  ##
+  # Adds a PO entry to the PO.
+
+  def add entry
+    existing_entry = @entries[entry.msgid]
+    if existing_entry
+      entry = existing_entry.merge(entry)
+    end
+    @entries[entry.msgid] = entry
+  end
+
+  ##
+  # Returns PO format text for the PO.
+
+  def to_s
+    po = ''
+    sort_entries.each do |entry|
+      po << "\n" unless po.empty?
+      po << entry.to_s
+    end
+    po
+  end
+
+  private
+
+  def add_header
+    add(header_entry)
+  end
+
+  def header_entry
+    comment = <<-COMMENT
+SOME DESCRIPTIVE TITLE.
+Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+This file is distributed under the same license as the PACKAGE package.
+FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+
+    COMMENT
+
+    content = <<-CONTENT
+Project-Id-Version: PACKAGE VERSEION
+Report-Msgid-Bugs-To: 
+PO-Revision-Date: YEAR-MO_DA HO:MI+ZONE
+Last-Translator: FULL NAME <EMAIL@ADDRESS>
+Language-Team: LANGUAGE <LL@li.org>
+Language: 
+MIME-Version: 1.0
+Content-Type: text/plain; charset=CHARSET
+Content-Transfer-Encoding: 8bit
+Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;
+    CONTENT
+
+    options = {
+      :msgstr => content,
+      :translator_comment => comment,
+      :flags => ['fuzzy'],
+    }
+    RDoc::Generator::POT::POEntry.new('', options)
+  end
+
+  def sort_entries
+    headers, messages = @entries.values.partition do |entry|
+      entry.msgid.empty?
+    end
+    # TODO: sort by location
+    sorted_messages = messages.sort_by do |entry|
+      entry.msgid
+    end
+    headers + sorted_messages
+  end
+
+end
diff --git a/lib/rdoc/generator/pot/po_entry.rb b/lib/rdoc/generator/pot/po_entry.rb
new file mode 100644
index 0000000000..d4cef59ee9
--- /dev/null
+++ b/lib/rdoc/generator/pot/po_entry.rb
@@ -0,0 +1,140 @@
+##
+# A PO entry in PO
+
+class RDoc::Generator::POT::POEntry
+
+  # The msgid content
+  attr_reader :msgid
+
+  # The msgstr content
+  attr_reader :msgstr
+
+  # The comment content created by translator (PO editor)
+  attr_reader :translator_comment
+
+  # The comment content extracted from source file
+  attr_reader :extracted_comment
+
+  # The locations where the PO entry is extracted
+  attr_reader :references
+
+  # The flags of the PO entry
+  attr_reader :flags
+
+  ##
+  # Creates a PO entry for +msgid+. Other valus can be specified by
+  # +options+.
+
+  def initialize msgid, options = {}
+    @msgid = msgid
+    @msgstr = options[:msgstr] || ""
+    @translator_comment = options[:translator_comment]
+    @extracted_comment = options[:extracted_comment]
+    @references = options[:references] || []
+    @flags = options[:flags] || []
+  end
+
+  ##
+  # Returns the PO entry in PO format.
+
+  def to_s
+    entry = ''
+    entry << format_translator_comment
+    entry << format_extracted_comment
+    entry << format_references
+    entry << format_flags
+    entry << <<-ENTRY
+msgid #{format_message(@msgid)}
+msgstr #{format_message(@msgstr)}
+    ENTRY
+  end
+
+  ##
+  # Merges the PO entry with +other_entry+.
+
+  def merge other_entry
+    options = {
+      :extracted_comment  => merge_string(@extracted_comment,
+                                          other_entry.extracted_comment),
+      :translator_comment => merge_string(@translator_comment,
+                                          other_entry.translator_comment),
+      :references         => merge_array(@references,
+                                         other_entry.references),
+      :flags              => merge_array(@flags,
+                                         other_entry.flags),
+    }
+    self.class.new(@msgid, options)
+  end
+
+  private
+
+  def format_comment mark, comment
+    return '' unless comment
+    return '' if comment.empty?
+
+    formatted_comment = ''
+    comment.each_line do |line|
+      formatted_comment << "#{mark} #{line}"
+    end
+    formatted_comment << "\n" unless formatted_comment.end_with?("\n")
+    formatted_comment
+  end
+
+  def format_translator_comment
+    format_comment('#', @translator_comment)
+  end
+
+  def format_extracted_comment
+    format_comment('#.', @extracted_comment)
+  end
+
+  def format_references
+    return '' if @references.empty?
+
+    formatted_references = ''
+    @references.sort.each do |file, line|
+      formatted_references << "\#: #{file}:#{line}\n"
+    end
+    formatted_references
+  end
+
+  def format_flags
+    return '' if @flags.empty?
+
+    formatted_flags = flags.join(",")
+    "\#, #{formatted_flags}\n"
+  end
+
+  def format_message message
+    return "\"#{escape(message)}\"" unless message.include?("\n")
+
+    formatted_message = '""'
+    message.each_line do |line|
+      formatted_message << "\n"
+      formatted_message << "\"#{escape(line)}\""
+    end
+    formatted_message
+  end
+
+  def escape string
+    string.gsub(/["\\\t\n]/) do |special_character|
+      case special_character
+      when "\t"
+        "\\t"
+      when "\n"
+        "\\n"
+      else
+        "\\#{special_character}"
+      end
+    end
+  end
+
+  def merge_string string1, string2
+    [string1, string2].compact.join("\n")
+  end
+
+  def merge_array array1, array2
+      (array1 + array2).uniq
+  end
+
+end
diff --git a/lib/rdoc/generator/template/darkfish/_head.rhtml b/lib/rdoc/generator/template/darkfish/_head.rhtml
index 062160a751..c87ba95096 100644
--- a/lib/rdoc/generator/template/darkfish/_head.rhtml
+++ b/lib/rdoc/generator/template/darkfish/_head.rhtml
@@ -2,6 +2,13 @@
 
 <title><%= h @title %></title>
 
+<script type="text/javascript">
+  var rdoc_rel_prefix = "<%= rel_prefix %>/";
+</script>
+
+<script src="<%= asset_rel_prefix %>/js/jquery.js"></script>
+<script src="<%= asset_rel_prefix %>/js/darkfish.js"></script>
+
 <link href="<%= asset_rel_prefix %>/fonts.css" rel="stylesheet">
 <link href="<%= asset_rel_prefix %>/rdoc.css" rel="stylesheet">
 <% if @options.template_stylesheets.flatten.any? then %>
@@ -10,13 +17,3 @@
 <%   end %>
 <% end %>
 
-<script type="text/javascript">
-  var rdoc_rel_prefix = "<%= rel_prefix %>/";
-</script>
-
-<script src="<%= asset_rel_prefix %>/js/jquery.js"></script>
-<script src="<%= asset_rel_prefix %>/js/navigation.js"></script>
-<script src="<%= search_index_rel_prefix %>/js/search_index.js"></script>
-<script src="<%= asset_rel_prefix %>/js/search.js"></script>
-<script src="<%= asset_rel_prefix %>/js/searcher.js"></script>
-<script src="<%= asset_rel_prefix %>/js/darkfish.js"></script>
diff --git a/lib/rdoc/generator/template/darkfish/images/add.png b/lib/rdoc/generator/template/darkfish/images/add.png
index 6332fefea4..6332fefea4 100755..100644
--- a/lib/rdoc/generator/template/darkfish/images/add.png
+++ b/lib/rdoc/generator/template/darkfish/images/add.png
diff --git a/lib/rdoc/generator/template/darkfish/images/arrow_up.png b/lib/rdoc/generator/template/darkfish/images/arrow_up.png
index 1ebb193243..1ebb193243 100755..100644
--- a/lib/rdoc/generator/template/darkfish/images/arrow_up.png
+++ b/lib/rdoc/generator/template/darkfish/images/arrow_up.png
diff --git a/lib/rdoc/generator/template/darkfish/images/delete.png b/lib/rdoc/generator/template/darkfish/images/delete.png
index 08f249365a..08f249365a 100755..100644
--- a/lib/rdoc/generator/template/darkfish/images/delete.png
+++ b/lib/rdoc/generator/template/darkfish/images/delete.png
diff --git a/lib/rdoc/generator/template/darkfish/images/tag_blue.png b/lib/rdoc/generator/template/darkfish/images/tag_blue.png
index 3f02b5f8f8..3f02b5f8f8 100755..100644
--- a/lib/rdoc/generator/template/darkfish/images/tag_blue.png
+++ b/lib/rdoc/generator/template/darkfish/images/tag_blue.png
diff --git a/lib/rdoc/generator/template/darkfish/js/darkfish.js b/lib/rdoc/generator/template/darkfish/js/darkfish.js
index 06fef3b215..b789a65631 100644
--- a/lib/rdoc/generator/template/darkfish/js/darkfish.js
+++ b/lib/rdoc/generator/template/darkfish/js/darkfish.js
@@ -44,14 +44,6 @@ function hookSourceViews() {
   $('.method-heading').click( showSource );
 };
 
-function toggleDebuggingSection() {
-  $('.debugging-section').slideToggle();
-};
-
-function hookDebuggingToggle() {
-  $('#debugging-toggle img').click( toggleDebuggingSection );
-};
-
 function hookSearch() {
   var input  = $('#search-field').eq(0);
   var result = $('#search-results').eq(0);
@@ -129,12 +121,41 @@ function highlightClickTarget( event ) {
   };
 };
 
+function loadAsync(path, success) {
+  $.ajax({
+    url: rdoc_rel_prefix + path,
+    dataType: 'script',
+    success: success,
+    cache: true
+  });
+};
 
 $(document).ready( function() {
   hookSourceViews();
-  hookDebuggingToggle();
-  hookSearch();
   highlightLocationTarget();
-
   $('ul.link-list a').bind( "click", highlightClickTarget );
+
+  var search_scripts_loaded = {
+    navigation_loaded:   false,
+    search_loaded:       false,
+    search_index_loaded: false,
+    searcher_loaded:     false,
+  }
+
+  var search_success_function = function(variable) {
+    return (function (data, status, xhr) {
+      search_scripts_loaded[variable] = true;
+
+      if (search_scripts_loaded['navigation_loaded']   == true &&
+          search_scripts_loaded['search_loaded']       == true &&
+          search_scripts_loaded['search_index_loaded'] == true &&
+          search_scripts_loaded['searcher_loaded']     == true)
+        hookSearch();
+    });
+  }
+
+  loadAsync('js/navigation.js',   search_success_function('navigation_loaded'));
+  loadAsync('js/search.js',       search_success_function('search_loaded'));
+  loadAsync('js/search_index.js', search_success_function('search_index_loaded'));
+  loadAsync('js/searcher.js',     search_success_function('searcher_loaded'));
 });
diff --git a/lib/rdoc/generator/template/darkfish/rdoc.css b/lib/rdoc/generator/template/darkfish/rdoc.css
index 4f22adaae1..2f4dca7e08 100644
--- a/lib/rdoc/generator/template/darkfish/rdoc.css
+++ b/lib/rdoc/generator/template/darkfish/rdoc.css
@@ -23,12 +23,22 @@ h3 span,
 h4 span,
 h5 span,
 h6 span {
+  position: relative;
+
   display: none;
   padding-left: 1em;
+  line-height: 0;
+  vertical-align: baseline;
   font-size: 10px;
-  vertical-align: super;
 }
 
+h1 span { top: -1.3em; }
+h2 span { top: -1.2em; }
+h3 span { top: -1.0em; }
+h4 span { top: -0.8em; }
+h5 span { top: -0.5em; }
+h6 span { top: -0.5em; }
+
 h1:hover span,
 h2:hover span,
 h3:hover span,