rdoc 2.5.11 → 3.0

data/lib/rdoc/markup/{preprocess.rb → pre_process.rb}

@@ -1,12 +1,15 @@
 require 'rdoc/markup'
+require 'rdoc/encoding'
 
 ##
 # Handle common directives that can occur in a block of text:
 #
-# : include : filename
+#   \:include: filename
 #
-# RDoc plugin authors can register additional directives to be handled through
-# RDoc::Markup::PreProcess::register
+# Directives can be escaped by preceding them with a backslash.
+#
+# RDoc plugin authors can register additional directives to be handled by
+# using RDoc::Markup::PreProcess::register
 
 class RDoc::Markup::PreProcess
 
@@ -52,18 +55,25 @@ class RDoc::Markup::PreProcess
   # +code_object+.  See RDoc::CodeObject#metadata
 
   def handle text, code_object = nil
-    text.gsub!(/^([ \t]*#?[ \t]*):(\w+):([ \t]*)(.+)?\n/) do
-      next $& if $3.empty? and $4 and $4[0, 1] == ':'
+    # regexp helper (square brackets for optional)
+    # $1      $2  $3        $4      $5
+    # [prefix][\]:directive:[spaces][param]newline
+    text.gsub!(/^([ \t]*#?[ \t]*)(\\?):(\w+):([ \t]*)(.+)?\n/) do
+      # skip something like ':toto::'
+      next $& if $4.empty? and $5 and $5[0, 1] == ':'
+
+      # skip if escaped
+      next "#$1:#$3:#$4#$5\n" unless $2.empty?
 
       prefix    = $1
-      directive = $2.downcase
-      param     = $4
+      directive = $3.downcase
+      param     = $5
 
       case directive
       when 'include' then
         filename = param.split[0]
-        include_file filename, prefix
-
+        encoding = if defined?(Encoding) then text.encoding else nil end
+        include_file filename, prefix, encoding
       else
         result = yield directive, param if block_given?
 
@@ -88,27 +98,38 @@ class RDoc::Markup::PreProcess
   end
 
   ##
-  # Include a file, indenting it correctly.
-
-  def include_file(name, indent)
-    if full_name = find_include_file(name) then
-      content = if defined?(Encoding) then
-                  File.binread full_name
-                else
-                  File.read full_name
-                end
-      # HACK determine content type and force encoding
-      content = content.sub(/\A# .*coding[=:].*$/, '').lstrip
-
-      # strip leading '#'s, but only if all lines start with them
-      if content =~ /^[^#]/ then
-        content.gsub(/^/, indent)
-      else
-        content.gsub(/^#?/, indent)
-      end
-    else
+  # Handles the <tt>:include: _filename_</tt> directive.
+  #
+  # If the first line of the included file starts with '#', and contains
+  # an encoding information in the form 'coding:' or 'coding=', it is
+  # removed.
+  #
+  # If all lines in the included file start with a '#', this leading '#'
+  # is removed before inclusion. The included content is indented like
+  # the <tt>:include:</tt> directive.
+  #--
+  # so all content will be verbatim because of the likely space after '#'?
+  # TODO shift left the whole file content in that case
+  # TODO comment stop/start #-- and #++ in included file must be processed here
+
+  def include_file name, indent, encoding
+    full_name = find_include_file name
+
+    unless full_name then
       warn "Couldn't find file to include '#{name}' from #{@input_file_name}"
-      ''
+      return ''
+    end
+
+    content = RDoc::Encoding.read_file full_name, encoding
+
+    # strip magic comment
+    content = content.sub(/\A# .*coding[=:].*$/, '').lstrip
+
+    # strip leading '#'s, but only if all lines start with them
+    if content =~ /^[^#]/ then
+      content.gsub(/^/, indent)
+    else
+      content.gsub(/^#?/, indent)
     end
   end
 

data/lib/rdoc/markup/raw.rb

@@ -27,6 +27,9 @@ class RDoc::Markup::Raw
     self.class == other.class and text == other.text
   end
 
+  ##
+  # Calls #accept_raw+ on +visitor+
+
   def accept visitor
     visitor.accept_raw self
   end
@@ -63,3 +66,4 @@ class RDoc::Markup::Raw
   end
 
 end
+

data/lib/rdoc/markup/rule.rb

@@ -3,6 +3,9 @@
 
 class RDoc::Markup::Rule < Struct.new :weight
 
+  ##
+  # Calls #accept_rule on +visitor+
+
   def accept visitor
     visitor.accept_rule self
   end

data/lib/rdoc/markup/text_formatter_test_case.rb

@@ -0,0 +1,116 @@
+require 'rdoc/markup/formatter_test_case'
+
+##
+# Test case for creating new plain-text RDoc::Markup formatters.  See also
+# RDoc::Markup::FormatterTestCase
+#
+# See test_rdoc_markup_to_rdoc.rb for a complete example.
+#
+# Example:
+#
+#  class TestRDocMarkupToNewTextFormat < RDoc::Markup::TextFormatterTestCase
+#
+#    add_visitor_tests
+#    add_text_tests
+#
+#    def setup
+#      super
+#
+#      @to = RDoc::Markup::ToNewTextFormat.new
+#    end
+#
+#    def accept_blank_line
+#      assert_equal :junk, @to.res.join
+#    end
+#
+#    # ...
+#
+#  end
+
+class RDoc::Markup::TextFormatterTestCase < RDoc::Markup::FormatterTestCase
+
+  ##
+  # Adds test cases to the calling TestCase.
+
+  def self.add_text_tests
+    self.class_eval do
+
+      ##
+      # Test case that calls <tt>@to.accept_heading</tt>
+
+      def test_accept_heading_indent
+        @to.start_accepting
+        @to.indent = 3
+        @to.accept_heading @RM::Heading.new(1, 'Hello')
+
+        accept_heading_indent
+      end
+
+      ##
+      # Test case that calls <tt>@to.accept_rule</tt>
+
+      def test_accept_rule_indent
+        @to.start_accepting
+        @to.indent = 3
+        @to.accept_rule @RM::Rule.new(1)
+
+        accept_rule_indent
+      end
+
+      ##
+      # Test case that calls <tt>@to.accept_verbatim</tt>
+
+      def test_accept_verbatim_indent
+        @to.start_accepting
+        @to.indent = 2
+        @to.accept_verbatim @RM::Verbatim.new("hi\n", " world\n")
+
+        accept_verbatim_indent
+      end
+
+      ##
+      # Test case that calls <tt>@to.accept_verbatim</tt> with a big indent
+
+      def test_accept_verbatim_big_indent
+        @to.start_accepting
+        @to.indent = 2
+        @to.accept_verbatim @RM::Verbatim.new("hi\n", "world\n")
+
+        accept_verbatim_big_indent
+      end
+
+      ##
+      # Test case that calls <tt>@to.accept_paragraph</tt> with an indent
+
+      def test_accept_paragraph_indent
+        @to.start_accepting
+        @to.indent = 3
+        @to.accept_paragraph @RM::Paragraph.new(('words ' * 30).strip)
+
+        accept_paragraph_indent
+      end
+
+      ##
+      # Test case that calls <tt>@to.accept_paragraph</tt> with a long line
+
+      def test_accept_paragraph_wrap
+        @to.start_accepting
+        @to.accept_paragraph @RM::Paragraph.new(('words ' * 30).strip)
+
+        accept_paragraph_wrap
+      end
+
+      ##
+      # Test case that calls <tt>@to.attributes</tt> with an escaped
+      # cross-reference.  If this test doesn't pass something may be very
+      # wrong.
+
+      def test_attributes
+        assert_equal 'Dog', @to.attributes("\\Dog")
+      end
+
+    end
+  end
+
+end
+

data/lib/rdoc/markup/to_ansi.rb

@@ -1,10 +1,13 @@
-require 'rdoc/markup/inline'
+require 'rdoc/markup/to_rdoc'
 
 ##
 # Outputs RDoc markup with vibrant ANSI color!
 
 class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
 
+  ##
+  # Creates a new ToAnsi visitor that is ready to output vibrant ANSI color!
+
   def initialize
     super
 
@@ -23,12 +26,15 @@ class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
     add_tag :EM,   "\e[4m", "\e[m"
   end
 
+  ##
+  # Overrides indent width to ensure output lines up correctly.
+
   def accept_list_item_end list_item
     width = case @list_type.last
             when :BULLET then
               2
             when :NOTE, :LABEL then
-              @res << "\n"
+              @res << "\n" unless res.length == 1
               2
             else
               bullet = @list_index.last.to_s
@@ -39,6 +45,9 @@ class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
     @indent -= width
   end
 
+  ##
+  # Adds coloring to note and label list items
+
   def accept_list_item_start list_item
     bullet = case @list_type.last
              when :BULLET then
@@ -62,6 +71,9 @@ class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
     end
   end
 
+  ##
+  # Starts accepting with a reset screen
+
   def start_accepting
     super
 

data/lib/rdoc/markup/to_bs.rb

@@ -1,4 +1,4 @@
-require 'rdoc/markup/inline'
+require 'rdoc/markup/to_rdoc'
 
 ##
 # Outputs RDoc markup with hot backspace action!  You will probably need a
@@ -8,6 +8,9 @@ require 'rdoc/markup/inline'
 
 class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
 
+  ##
+  # Returns a new ToBs that is ready for hot backspace action!
+
   def initialize
     super
 
@@ -22,8 +25,12 @@ class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
   def init_tags
     add_tag :BOLD, '+b', '-b'
     add_tag :EM,   '+_', '-_'
+    add_tag :TT,   ''  , ''   # we need in_tt information maintained
   end
 
+  ##
+  # Makes heading text bold.
+
   def accept_heading heading
     use_prefix or @res << ' ' * @indent
     @res << @headings[heading.level][0]
@@ -44,7 +51,6 @@ class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
     when '+_' then @in_em = true
     when '-_' then @in_em = false
     end
-
     ''
   end
 

data/lib/rdoc/markup/to_html.rb

@@ -8,6 +8,8 @@ require 'cgi'
 
 class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
+  include RDoc::Text
+
   ##
   # Maps RDoc::Markup::Parser::LIST_TOKENS types to HTML tags
 
@@ -15,7 +17,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     :BULLET => ['<ul>', '</ul>'],
     :LABEL  => ['<dl>', '</dl>'],
     :LALPHA => ['<ol style="display: lower-alpha">', '</ol>'],
-    :NOTE   => ['<table>', '</table>'],
+    :NOTE   => ['<table class="rdoc-list">', '</table>'],
     :NUMBER => ['<ol>', '</ol>'],
     :UALPHA => ['<ol style="display: upper-alpha">', '</ol>'],
   }
@@ -48,6 +50,9 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     File.join(*from)
   end
 
+  ##
+  # Creates a new formatter that will output HTML
+
   def initialize
     super
 
@@ -103,13 +108,15 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     end
   end
 
+  # :section: Special handling
+
   ##
-  # And we're invoked with a potential external hyperlink mailto:
-  # just gets inserted. http: links are checked to see if they
+  # And we're invoked with a potential external hyperlink. <tt>mailto:</tt>
+  # just gets inserted. <tt>http:</tt> links are checked to see if they
   # reference an image. If so, that image gets inserted using an
-  # <img> tag. Otherwise a conventional <a href> is used.  We also
-  # support a special type of hyperlink, link:, which is a reference
-  # to a local file whose path is relative to the --op directory.
+  # <tt><img></tt> tag. Otherwise a conventional <tt><a href></tt> is used.
+  # We also support a special type of hyperlink, <tt>link:</tt>, which is a
+  # reference to a local file whose path is relative to the --op directory.
 
   def handle_special_HYPERLINK(special)
     url = special.text
@@ -118,7 +125,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
   ##
   # Here's a hypedlink where the label is different to the URL
-  #  <label>[url] or {long label}[url]
+  # <label>[url] or {long label}[url]
 
   def handle_special_TIDYLINK(special)
     text = special.text
@@ -130,8 +137,10 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     gen_url url, label
   end
 
+  # :section: Utilities
+
   ##
-  # This is a higher speed (if messier) version of wrap
+  # Wraps +txt+ to +line_len+
 
   def wrap(txt, line_len = 76)
     res = []
@@ -159,173 +168,150 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
       sp += 1 while sp < ep and txt[sp] == ?\s
     end
 
-    res.join
+    res.join.strip
   end
 
-  ##
   # :section: Visitor
 
+  ##
+  # Prepares the visitor for HTML generation
+
   def start_accepting
     @res = []
     @in_list_entry = []
     @list = []
   end
 
+  ##
+  # Returns the generated output
+
   def end_accepting
     @res.join
   end
 
+  ##
+  # Adds +paragraph+ to the output
+
   def accept_paragraph(paragraph)
-    @res << annotate("<p>") + "\n"
-    @res << wrap(convert_flow(@am.flow(paragraph.text)))
-    @res << annotate("</p>") + "\n"
+    @res << "\n<p>"
+    @res << wrap(to_html(paragraph.text))
+    @res << "</p>\n"
   end
 
+  ##
+  # Adds +verbatim+ to the output
+
   def accept_verbatim(verbatim)
-    @res << annotate("<pre>") << "\n"
-    @res << CGI.escapeHTML(verbatim.text)
-    @res << annotate("</pre>") << "\n"
+    @res << "\n<pre>"
+    @res << CGI.escapeHTML(verbatim.text.rstrip)
+    @res << "</pre>\n"
   end
 
+  ##
+  # Adds +rule+ to the output
+
   def accept_rule(rule)
     size = rule.weight
     size = 10 if size > 10
-    @res << "<hr style=\"height: #{size}px\"></hr>"
+    @res << "<hr style=\"height: #{size}px\">\n"
   end
 
+  ##
+  # Prepares the visitor for consuming +list+
+
   def accept_list_start(list)
     @list << list.type
-    @res << html_list_name(list.type, true) << "\n"
+    @res << html_list_name(list.type, true)
     @in_list_entry.push false
   end
 
+  ##
+  # Finishes consumption of +list+
+
   def accept_list_end(list)
     @list.pop
     if tag = @in_list_entry.pop
-      @res << annotate(tag) << "\n"
+      @res << tag
     end
     @res << html_list_name(list.type, false) << "\n"
   end
 
+  ##
+  # Prepares the visitor for consuming +list_item+
+
   def accept_list_item_start(list_item)
     if tag = @in_list_entry.last
-      @res << annotate(tag) << "\n"
+      @res << tag
     end
 
     @res << list_item_start(list_item, @list.last)
   end
 
+  ##
+  # Finishes consumption of +list_item+
+
   def accept_list_item_end(list_item)
     @in_list_entry[-1] = list_end_for(@list.last)
   end
 
-  def accept_blank_line(blank_line)
-    # @res << annotate("<p />") << "\n"
-  end
-
-  def accept_heading(heading)
-    @res << convert_heading(heading.level, @am.flow(heading.text))
-  end
-
-  def accept_raw raw
-    @res << raw.parts.join("\n")
-  end
-
-  private
-
   ##
-  # Converts string +item+
+  # Adds +blank_line+ to the output
 
-  def convert_string(item)
-    in_tt? ? convert_string_simple(item) : convert_string_fancy(item)
+  def accept_blank_line(blank_line)
+    # @res << annotate("<p />") << "\n"
   end
 
   ##
-  # Escapes HTML in +item+
+  # Adds +heading+ to the output
 
-  def convert_string_simple(item)
-    CGI.escapeHTML item
+  def accept_heading(heading)
+    @res << "\n<h#{heading.level}>"
+    @res << to_html(heading.text)
+    @res << "</h#{heading.level}>\n"
   end
 
   ##
-  # Converts ampersand, dashes, elipsis, quotes, copyright and registered
-  # trademark symbols to HTML escaped Unicode.
-
-  def convert_string_fancy(item)
-    # convert ampersand before doing anything else
-    item.gsub(/&/, '&amp;').
-
-    # convert -- to em-dash, (-- to en-dash)
-      gsub(/---?/, '&#8212;'). #gsub(/--/, '&#8211;').
-
-    # convert ... to elipsis (and make sure .... becomes .<elipsis>)
-      gsub(/\.\.\.\./, '.&#8230;').gsub(/\.\.\./, '&#8230;').
+  # Adds +raw+ to the output
 
-    # convert single closing quote
-      gsub(%r{([^ \t\r\n\[\{\(])\'}, '\1&#8217;'). # }
-      gsub(%r{\'(?=\W|s\b)}, '&#8217;').
-
-    # convert single opening quote
-      gsub(/'/, '&#8216;').
-
-    # convert double closing quote
-      gsub(%r{([^ \t\r\n\[\{\(])\"(?=\W)}, '\1&#8221;'). # }
-
-    # convert double opening quote
-      gsub(/"/, '&#8220;').
-
-    # convert copyright
-      gsub(/\(c\)/, '&#169;').
-
-    # convert registered trademark
-      gsub(/\(r\)/, '&#174;')
+  def accept_raw raw
+    @res << raw.parts.join("\n")
   end
 
   ##
-  # Converts headings to hN elements
+  # CGI escapes +text+
 
-  def convert_heading(level, flow)
-    [annotate("<h#{level}>"),
-     convert_flow(flow),
-     annotate("</h#{level}>\n")].join
+  def convert_string(text)
+    CGI.escapeHTML text
   end
 
   ##
-  # Determins the HTML list element for +list_type+ and +open_tag+
+  # Determines the HTML list element for +list_type+ and +open_tag+
 
   def html_list_name(list_type, open_tag)
     tags = LIST_TYPE_TO_HTML[list_type]
     raise RDoc::Error, "Invalid list type: #{list_type.inspect}" unless tags
-    annotate tags[open_tag ? 0 : 1]
+    tags[open_tag ? 0 : 1]
   end
 
   ##
-  # Starts a list item
+  # Returns the HTML tag for +list_type+, possible using a label from
+  # +list_item+
 
   def list_item_start(list_item, list_type)
     case list_type
     when :BULLET, :LALPHA, :NUMBER, :UALPHA then
-      annotate("<li>")
-
+      "<li>"
     when :LABEL then
-      annotate("<dt>") +
-        convert_flow(@am.flow(list_item.label)) +
-        annotate("</dt>") +
-        annotate("<dd>")
-
+      "<dt>#{to_html list_item.label}</dt>\n<dd>"
     when :NOTE then
-      annotate("<tr>") +
-        annotate("<td valign=\"top\">") +
-        convert_flow(@am.flow(list_item.label)) +
-        annotate("</td>") +
-        annotate("<td>")
+      "<tr><td class=\"rdoc-term\"><p>#{to_html list_item.label}</p></td>\n<td>"
     else
       raise RDoc::Error, "Invalid list type: #{list_type.inspect}"
     end
   end
 
   ##
-  # Ends a list item
+  # Returns the HTML end-tag for +list_type+
 
   def list_end_for(list_type)
     case list_type
@@ -340,5 +326,12 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     end
   end
 
+  ##
+  # Converts +item+ to HTML using RDoc::Text#to_html
+
+  def to_html item
+    super convert_flow @am.flow item
+  end
+
 end