From: Michael Neumann <mneumann@...>
Date: 2004-12-07T00:05:10+09:00
Subject: Re: [RDOC] quoting YAML

Dave Thomas wrote:
> 
> On Dec 6, 2004, at 8:15, Michael Neumann wrote:
> 
>> Dave, I've a patch that allows arbitrary markup blocks, like:
>>
>>   code{{{
>>   foo:
>>     :bar: 3
>>   }}}
> 
> 
> I'm guessing this doesn't help in this particular case, as the scanning 
> for directives would occur before this is executed.

Ah, sure. That's why I suggested to move the directive handling into the 
markup stuff, so it's context sensitive.

   :include:filename

would then generate a Line::Directive, which is then transformed in the 
ToHtml step (generate html for filename).

>> It could be used for:
>>
>>   * including html: html{{{ .... }}}
> 
> 
> Does this patch work well with ri generation? In principle I like the 
> idea, but I'd also like to keep RDoc markup device independent, and this 
> seems to break that.

There's no html{{{ ... }}} directive. You can overwrite 
SM::ToHtml#process_block and get passed "html" as directive name, and 
the content of the block. So you can do anything with it. I would not 
include a html-directive by default, but one can simply add this 
herself. It's extensible!

>> Another thing I'd like to see is some kind of generic directive, like:
>>
>>   !source(test.rb)
>>
>> which is similar to the preprocess directive (:include:filename), but 
>> build into the markup, so that it can be more easily used (by rdoc 
>> extenders). Of course it should be generic, so that I can overwrite a 
>> ToHtml#handle_directive and implement my own directives.
> 
> 
> Could you describe a use for this?

I'm currently writing a rdoc2slides application 
(http://www.ntecs.de/viewcvs/viewcvs/Utils/rdoc2slide/), which makes it 
easy to develop presentations using rdoc. For code snipets, it's 
sometimes nice to just include them from a file (+ colorize), and not 
copy them into the presentation via copy&paste.

What I'm currently doing is to preprocess the input and substitue

   :source:filename

by

   colorize-file(filename){{{
   }}}

And the colorize-file directive then colorizes the file and writes the 
html to the output (+ adds a link to download the file).
(note that I'm misusing the {{{...}}}, as there's currently no easy way 
to do that in a different way).

My idea is:

   * either leave the pre-process directives as is and add a !directive
     to the markup
   * or move the :directive to the markup and remove the pre-process step

Regards,

   Michael