rdoc 3.9.5 → 3.10.pre.1

data/lib/rdoc/markup/to_html_crossref.rb

@@ -1,6 +1,3 @@
-require 'rdoc/markup/to_html'
-require 'rdoc/cross_reference'
-
 ##
 # Subclass of the RDoc::Markup::ToHtml class that supports looking up method
 # names, classes, etc to create links.  RDoc::CrossReference is used to
@@ -41,8 +38,8 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
     @cross_reference = RDoc::CrossReference.new context
 
     @markup.add_special crossref_re, :CROSSREF
-    @markup.add_special(/rdoc-ref:\S+\w/, :HYPERLINK)
 
+    @context       = context
     @from_path     = from_path
     @hyperlink_all = hyperlink_all
     @show_hash     = show_hash
@@ -57,6 +54,8 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
     name = name[1..-1] unless @show_hash if name[0, 1] == '#'
 
+    name = "#{CGI.unescape $'} at #{$1}" if name =~ /(.*[^#:])@/
+
     text = name unless text
 
     link lookup, text
@@ -92,6 +91,25 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
     super
   end
 
+  ##
+  # +special+ is an rdoc-schemed link that will be converted into a hyperlink.
+  # For the rdoc-ref scheme the cross-reference will be looked up and the
+  # given name will be used.
+  #
+  # All other contents are handled by
+  # {the superclass}[rdoc-ref:RDoc::Markup::ToHtml#handle_special_RDOCLINK]
+
+  def handle_special_RDOCLINK special
+    url = special.text
+
+    case url
+    when /\Ardoc-ref:/ then
+      cross_reference $'
+    else
+      super
+    end
+  end
+
   ##
   # Generates links for <tt>rdoc-ref:</tt> scheme URLs and allows
   # RDoc::Markup::ToHtml to handle other schemes.
@@ -106,13 +124,26 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # Creates an HTML link to +name+ with the given +text+.
 
   def link name, text
+    if name =~ /(.*[^#:])@/ then
+      name = $1
+      label = $'
+    end
+
     ref = @cross_reference.resolve name, text
 
     case ref
     when String then
       ref
     else
-      "<a href=\"#{ref.as_href @from_path}\">#{text}</a>"
+      path = ref.as_href @from_path
+
+      if path =~ /#/ then
+        path << "-label-#{label}"
+      else
+        path << "#label-#{label}"
+      end if label
+
+      "<a href=\"#{path}\">#{text}</a>"
     end
   end
 

data/lib/rdoc/markup/to_html_snippet.rb

@@ -0,0 +1,270 @@
+##
+# Outputs RDoc markup as paragraphs with inline markup only.
+
+class RDoc::Markup::ToHtmlSnippet < RDoc::Markup::ToHtml
+
+  ##
+  # After this many characters the input will be cut off.
+
+  attr_reader :character_limit
+
+  ##
+  # The number of characters seen so far.
+
+  attr_reader :characters # :nodoc:
+
+  ##
+  # The attribute bitmask
+
+  attr_reader :mask
+
+  ##
+  # After this many paragraphs the input will be cut off.
+
+  attr_reader :paragraph_limit
+
+  ##
+  # Count of paragraphs found
+
+  attr_reader :paragraphs
+
+  ##
+  # Creates a new ToHtmlSnippet formatter that will cut off the input on the
+  # next word boundary after the given number of +characters+ or +paragraphs+
+  # of text have been encountered.
+
+  def initialize characters = 100, paragraphs = 3, markup = nil
+    super markup
+
+    @character_limit = characters
+    @paragraph_limit = paragraphs
+
+    @characters = 0
+    @mask       = 0
+    @paragraphs = 0
+
+    @markup.add_special RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
+  end
+
+  ##
+  # Adds +heading+ to the output as a paragraph
+
+  def accept_heading heading
+    @res << "<p>#{to_html heading.text}\n"
+
+    add_paragraph
+  end
+
+  ##
+  # Raw content is untrusted and ignored.
+
+  def accept_raw raw
+  end
+
+  ##
+  # Rules are ignored
+
+  def accept_rule rule
+  end
+
+  def accept_paragraph paragraph
+    para = @in_list_entry.last || "<p>"
+
+    @res << "#{para}#{wrap to_html paragraph.text}\n"
+
+    add_paragraph
+  end
+
+  ##
+  # Finishes consumption of +list_item+
+
+  def accept_list_item_end list_item
+  end
+
+  ##
+  # Prepares the visitor for consuming +list_item+
+
+  def accept_list_item_start list_item
+    @res << list_item_start(list_item, @list.last)
+  end
+
+  ##
+  # Prepares the visitor for consuming +list+
+
+  def accept_list_start list
+    @list << list.type
+    @res << html_list_name(list.type, true)
+    @in_list_entry.push ''
+  end
+
+  ##
+  # Adds +verbatim+ to the output
+
+  def accept_verbatim verbatim
+    throw :done if @characters >= @character_limit
+    input = verbatim.text.rstrip
+
+    text = truncate input
+    text << ' ...' unless text == input
+
+    super RDoc::Markup::Verbatim.new text
+
+    add_paragraph
+  end
+
+  ##
+  # Prepares the visitor for HTML snippet generation
+
+  def start_accepting
+    super
+
+    @characters = 0
+  end
+
+  ##
+  # Removes escaping from the cross-references in +special+
+
+  def handle_special_CROSSREF special
+    special.text.sub(/\A\\/, '')
+  end
+
+  ##
+  # Lists are paragraphs, but notes and labels have a separator
+
+  def list_item_start list_item, list_type
+    throw :done if @characters >= @character_limit
+
+    case list_type
+    when :BULLET, :LALPHA, :NUMBER, :UALPHA then
+      "<p>"
+    when :LABEL, :NOTE then
+      start = "<p>#{to_html list_item.label} &mdash; "
+      @characters += 1 # try to include the label
+      start
+    else
+      raise RDoc::Error, "Invalid list type: #{list_type.inspect}"
+    end
+  end
+
+  ##
+  # Returns just the text of +link+, +url+ is only used to determine the link
+  # type.
+
+  def gen_url url, text
+    if url =~ /^rdoc-label:([^:]*)(?::(.*))?/ then
+      type = "link"
+    elsif url =~ /([A-Za-z]+):(.*)/ then
+      type = $1
+    else
+      type = "http"
+    end
+
+    if (type == "http" or type == "https" or type == "link") and
+       url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then
+      ''
+    else
+      text.sub(%r%^#{type}:/*%, '')
+    end
+  end
+
+  ##
+  # In snippets, there are no lists
+
+  def html_list_name list_type, open_tag
+    ''
+  end
+
+  ##
+  # Throws +:done+ when paragraph_limit paragraphs have been encountered
+
+  def add_paragraph
+    @paragraphs += 1
+
+    throw :done if @paragraphs >= @paragraph_limit
+  end
+
+  ##
+  # Marks up +content+
+
+  def convert content
+    catch :done do
+      return super
+    end
+
+    end_accepting
+  end
+
+  ##
+  # Converts flow items +flow+
+
+  def convert_flow flow
+    throw :done if @characters >= @character_limit
+
+    res = []
+    @mask = 0
+
+    flow.each do |item|
+      case item
+      when RDoc::Markup::AttrChanger then
+        off_tags res, item
+        on_tags  res, item
+      when String then
+        text = convert_string item
+        res << truncate(text)
+      when RDoc::Markup::Special then
+        text = convert_special item
+        res << truncate(text)
+      else
+        raise "Unknown flow element: #{item.inspect}"
+      end
+
+      if @characters >= @character_limit then
+        off_tags res, RDoc::Markup::AttrChanger.new(0, @mask)
+        break
+      end
+    end
+
+    res << ' ...' if @characters >= @character_limit
+
+    res.join
+  end
+
+  ##
+  # Maintains a bitmask to allow HTML elements to be closed properly.  See
+  # RDoc::Markup::Formatter.
+
+  def on_tags res, item
+    @mask ^= item.turn_on
+
+    super
+  end
+
+  ##
+  # Maintains a bitmask to allow HTML elements to be closed properly.  See
+  # RDoc::Markup::Formatter.
+
+  def off_tags res, item
+    @mask ^= item.turn_off
+
+    super
+  end
+
+  ##
+  # Truncates +text+ at the end of the first word after the character_limit.
+
+  def truncate text
+    length = text.length
+    characters = @characters
+    @characters += length
+
+    return text if @characters < @character_limit
+
+    remaining = @character_limit - characters
+
+    text =~ /\A(.{#{remaining},}?)(\s|$)/m # TODO word-break instead of \s?
+
+    $1
+  end
+
+end
+

data/lib/rdoc/markup/to_label.rb

@@ -0,0 +1,55 @@
+require 'cgi'
+
+##
+# Creates HTML-safe labels suitable for use in id attributes.  Tidylinks are
+# converted to their link part and cross-reference links have the suppression
+# marks removed (\\SomeClass is converted to SomeClass).
+
+class RDoc::Markup::ToLabel < RDoc::Markup::Formatter
+
+  ##
+  # Creates a new formatter that will output HTML-safe labels
+
+  def initialize markup = nil
+    super
+
+    @markup.add_special RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
+    @markup.add_special(/(((\{.*?\})|\b\S+?)\[\S+?\])/, :TIDYLINK)
+
+    add_tag :BOLD, '', ''
+    add_tag :TT,   '', ''
+    add_tag :EM,   '', ''
+  end
+
+  ##
+  # Converts +text+ to an HTML-safe label
+
+  def convert text
+    label = convert_flow @am.flow text
+
+    CGI.escape label
+  end
+
+  ##
+  # Converts the CROSSREF +special+ to plain text, removing the suppression
+  # marker, if any
+
+  def handle_special_CROSSREF special
+    text = special.text
+
+    text.sub(/^\\/, '')
+  end
+
+  ##
+  # Converts the TIDYLINK +special+ to just the text part
+
+  def handle_special_TIDYLINK special
+    text = special.text
+
+    return text unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/
+
+    $1
+  end
+
+end
+

data/lib/rdoc/markup/to_rdoc.rb

@@ -1,6 +1,3 @@
-require 'rdoc/markup/formatter'
-require 'rdoc/markup/inline'
-
 ##
 # Outputs RDoc markup as RDoc markup! (mostly)
 

data/lib/rdoc/markup/to_table_of_contents.rb

@@ -0,0 +1,62 @@
+##
+# Extracts just the RDoc::Markup::Heading elements from a
+# RDoc::Markup::Document to help build a table of contents
+
+class RDoc::Markup::ToTableOfContents < RDoc::Markup::Formatter
+
+  @to_toc = nil
+
+  ##
+  # Singleton for ToC generation
+
+  def self.to_toc
+    @to_toc ||= new
+  end
+
+  ##
+  # Output accumulator
+
+  attr_reader :res
+
+  ##
+  # Adds +heading+ to the table of contents
+
+  def accept_heading heading
+    @res << heading
+  end
+
+  ##
+  # Returns the table of contents
+
+  def end_accepting
+    @res
+  end
+
+  ##
+  # Prepares the visitor for text generation
+
+  def start_accepting
+    @res = []
+  end
+
+  ##
+  # Ignores the content of nodes that aren't headings
+
+  def ignore node
+  end
+
+  # :stopdoc:
+  alias accept_raw             ignore
+  alias accept_rule            ignore
+  alias accept_blank_line      ignore
+  alias accept_paragraph       ignore
+  alias accept_verbatim        ignore
+  alias accept_list_end        ignore
+  alias accept_list_item_start ignore
+  alias accept_list_item_end   ignore
+  alias accept_list_end_bullet ignore
+  alias accept_list_start      ignore
+  # :startdoc:
+
+end
+