[RDOC] quoting YAML

ruby-talk
1

I'm trying to embed YAML output in a simple markup file (not a ruby code file) that gets fed into RDoc. I want the YAML text to show up as a literal. So I indent. For instance:

···

---
   foo:
     :bar: 3

The problem is that the :bar: causes RDoc to complain about an "Unrecognized directive".

How can I quote this text so that RDoc doesn't look for directives? I've tried various combinations of <tt>, blackslashes, :enddoc:.

2

I actually ran into this when I wrote that article about Copland and
Needle for RubyForge--one of my examples had a similar line in it.
I was able to work around it by putting a space before the second
colon:

···

On 17:31 Mon 06 Dec , Joel VanderWerf wrote:

I'm trying to embed YAML output in a simple markup file (not a ruby code
file) that gets fed into RDoc. I want the YAML text to show up as a
literal. So I indent. For instance:

  ---
  foo:
    :bar: 3

The problem is that the :bar: causes RDoc to complain about an
"Unrecognized directive".

How can I quote this text so that RDoc doesn't look for directives? I've
tried various combinations of <tt>, blackslashes, :enddoc:.

  ---
  foo:
    :bar : 3

- Jamis

--
Jamis Buck
jgb3@email.byu.edu
http://www.jamisbuck.org/jamis

3

Sorry about that. It's a hole in the way RDoc handles directives. At the point it is scanning for them, it hasn't yet done the analysis on the internal structure of the comment block, so it doesn't know that your :bar: is in a literal code block.

Cheers

Dave

···

On Dec 6, 2004, at 2:31, Joel VanderWerf wrote:

I'm trying to embed YAML output in a simple markup file (not a ruby code file) that gets fed into RDoc. I want the YAML text to show up as a literal. So I indent. For instance:

  ---
  foo:
    :bar: 3

The problem is that the :bar: causes RDoc to complain about an "Unrecognized directive".

4

Dave Thomas wrote:

I'm trying to embed YAML output in a simple markup file (not a ruby code file) that gets fed into RDoc. I want the YAML text to show up as a literal. So I indent. For instance:

  ---
  foo:
    :bar: 3

The problem is that the :bar: causes RDoc to complain about an "Unrecognized directive".

Sorry about that. It's a hole in the way RDoc handles directives. At the point it is scanning for them, it hasn't yet done the analysis on the internal structure of the comment block, so it doesn't know that your :bar: is in a literal code block.

Dave, I've a patch that allows arbitrary markup blocks, like:

   code{{{
   foo:
     :bar: 3
   }}}

or simply:

   {{{
   this is code
   ...
   }}}

It could be used for:

   * including html: html{{{ .... }}}
   * large parts of code
   * table processors
   ...

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.

What do you thinK?

The arbitrary markup patch is appended.

Regards,

   Michael

rdoc-markup-patch.diff (3.82 KB)

···

On Dec 6, 2004, at 2:31, Joel VanderWerf wrote:

5

Jamis Buck wrote:

···

On 17:31 Mon 06 Dec , Joel VanderWerf wrote:

I'm trying to embed YAML output in a simple markup file (not a ruby code file) that gets fed into RDoc. I want the YAML text to show up as a literal. So I indent. For instance:

---
foo:
   :bar: 3

The problem is that the :bar: causes RDoc to complain about an "Unrecognized directive".

How can I quote this text so that RDoc doesn't look for directives? I've tried various combinations of <tt>, blackslashes, :enddoc:.

I actually ran into this when I wrote that article about Copland and
Needle for RubyForge--one of my examples had a similar line in it.
I was able to work around it by putting a space before the second
colon:

  ---
  foo:
    :bar : 3

Thanks, Jamis. I can live with that, since it's legal YAML.

6

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.

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.

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?

Cheers

Dave

···

On Dec 6, 2004, at 8:15, Michael Neumann wrote:

7

Dave Thomas 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

···

On Dec 6, 2004, at 8:15, Michael Neumann wrote: