From: Phlip <phlip2005@...>
Date: 2007-07-30T07:19:06+09:00
Subject: Re: Rdoc allowing arbitrary HTML

Robert Dober wrote:

> It seems that the diff has been made against an intermediate version,
> I can send you the files off list if you want.

No prob: I reproduced what you did as a monkey patch, available below my 
sig.

It's only long because one of the methods I had to patch was poorly factored 
and run-on. Other than that, the Visitor Pattern made the actual patch super 
easy!

I put this in my Rakefile, and because that calls RDoc internally, it gets 
the new feature. Thanks for the code sample, because this is exactly what I 
was about to start researching!

> #  aaa
> # %html <sup>(1)</sup>
> # bbb
>
> you will have a paragraph around (1)
> can be fixed with
> %html aaa
> %html <sup>(1)</sup>
> %html bbb

I didn't get a paragraph around it, so I didn't need the workaround. Yet 
note you have two blanks in "#  aaa" - they cause a <pre> aaa</pre>.

Now I dibs first crack at the Wish List I just posted! Nobody else can do 
them!

-- 
  Phlip
  http://www.oreilly.com/catalog/9780596510657/
  "Test Driven Ajax (on Rails)"
  assert_xpath, assert_javascript, & assert_ajax

##################################################################
##  eek eek ook ook patch to add %html directive to RDocage

require 'rdoc/rdoc'
require 'rdoc/markup/simple_markup'
require 'rdoc/markup/simple_markup/lines'
require 'rdoc/markup/simple_markup/fragments'
require 'rdoc/markup/simple_markup/to_html'

module SM

  class Line
    PURE_HTML = :PURE_HTML
  end

  class PureHTML < Fragment
    type_name Line::PURE_HTML
  end

  class ToHtml
    def accept_pure_html(am, fragment)
      @res << fragment.txt
    end
  end

  class LineCollection
    def accept(am, visitor)
      visitor.start_accepting

      @fragments.each do |fragment|
        case fragment
        when Verbatim
          visitor.accept_verbatim(am, fragment)
        when PureHTML
           visitor.accept_pure_html(am, fragment)
        when Rule
          visitor.accept_rule(am, fragment)
        when ListStart
          visitor.accept_list_start(am, fragment)
        when ListEnd
          visitor.accept_list_end(am, fragment)
        when ListItem
          visitor.accept_list_item(am, fragment)
        when BlankLine
          visitor.accept_blank_line(am, fragment)
        when Heading
          visitor.accept_heading(am, fragment)
        when Paragraph
          visitor.accept_paragraph(am, fragment)
        end
      end

      visitor.end_accepting
    end

  end

  class SimpleMarkup
  private

    def assign_types_to_lines(margin = 0, level = 0)

      while line = @lines.next

        if /^\s*%html/ === line.text then
          line.text.sub!("%html","")
          line.stamp( Line::PURE_HTML, level )
          next
        end  #  ERGO  move this monkey-patch towards the real RDoc!

        if line.isBlank?
          line.stamp(Line::BLANK, level)
          next
        end

        # if a line contains non-blanks before the margin, then it must 
belong
        # to an outer level

        text = line.text

        for i in 0...margin
          if text[i] != SPACE
            @lines.unget
            return
          end
        end

        active_line = text[margin..-1]

        # Rules (horizontal lines) look like
        #
        #  ---   (three or more hyphens)
        #
        # The more hyphens, the thicker the rule
        #

        if /^(---+)\s*$/ =~ active_line
          line.stamp(Line::RULE, level, $1.length-2)
          next
        end

        # Then look for list entries. First the ones that have to have
        # text following them (* xxx, - xxx, and dd. xxx)

        if SIMPLE_LIST_RE =~ active_line

          offset = margin + $1.length
          prefix = $2
          prefix_length = prefix.length

          flag = case prefix
                 when "*","-" then ListBase::BULLET
                 when /^\d/   then ListBase::NUMBER
                 when /^[A-Z]/ then ListBase::UPPERALPHA
                 when /^[a-z]/ then ListBase::LOWERALPHA
                 else raise "Invalid List Type: #{self.inspect}"
                 end

          line.stamp(Line::LIST, level+1, prefix, flag)
          text[margin, prefix_length] = " " * prefix_length
          assign_types_to_lines(offset, level + 1)
          next
        end


        if LABEL_LIST_RE =~ active_line
          offset = margin + $1.length
          prefix = $2
          prefix_length = prefix.length

          next if handled_labeled_list(line, level, margin, offset, prefix)
        end

        # Headings look like
        # = Main heading
        # == Second level
        # === Third
        #
        # Headings reset the level to 0

        if active_line[0] == ?= and active_line =~ /^(=+)\s*(.*)/
          prefix_length = $1.length
          prefix_length = 6 if prefix_length > 6
          line.stamp(Line::HEADING, 0, prefix_length)
          line.strip_leading(margin + prefix_length)
          next
        end

        # If the character's a space, then we have verbatim text,
        # otherwise

        if active_line[0] == SPACE
          line.strip_leading(margin) if margin > 0
          line.stamp(Line::VERBATIM, level)
        else
          line.stamp(Line::PARAGRAPH, level)
        end
      end
    end
  end
end

##  eek eek ook ook patch to add %html directive to RDocage
##################################################################