From: Eric Hodel <drbrain@...7.net>
Date: 2008-04-01T08:36:45+09:00
Subject: Re: RDoc 2 (Was: Improvements to RDoc (ideas for GSoC))

Please don't top-post.

On Mar 30, 2008, at 10:58 AM, Jeremy McAnally wrote:
> I'd written an RDoc alternative called DocR that used ERb, but I'm
> glad you switched to ERb.  Saves me a lot of effort and maintenance
> crap. :)
>
> I'm looking to make a small hook or DSL or something for extensions to
> the RDoc markup (see what Merb is doing with their markup or maybe
> YARD or whatever) to let people add interesting things (for example a
> public API might want to add the automatic appending of resource URLs
> to the docs or something).  I'll grab it out of trunk and look at it
> tonight.

It's easy to add "specials" to RDoc markup, depending upon how  
complicated you want them to be.  I wrote a small wiki using RDoc 2's  
markup here:

http://blog.segment7.net/articles/2008/02/14/an-rdoc-wiki

A WikiWord is handled like this:

class WikiHtml < RDoc::Markup::ToHtml
   def initialize
     super

     @markup.add_special(/\b(([A-Z][a-z]+){2,})\b/, :WIKIWORD)
   end

   def handle_special_WIKIWORD(special)
     "<a href=#{special.text}>#{special.text}</a>"
   end
end

And you can use WikiHtml to convert text like so:

wiki_html = WikiHtml.new
html = wiki_html.convert <<-EOF
= Some heading

WikiWord links to some other page
EOF