[RDOC] quoting YAML

[Joel VanderWerf]

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:.

 

[Jamis Buck]

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:

 

[Dave Thomas]

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.


Cheers

Dave

 

[Michael Neumann]

--------------080905060003020409040905
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

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

--------------080905060003020409040905
Content-Type: text/plain;
name="rdoc-markup-patch.diff"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename="rdoc-markup-patch.diff"

Index: simple_markup.rb
===================================================================
RCS file: /var/cvs/src/ruby/lib/rdoc/markup/simple_markup.rb,v
retrieving revision 1.2
diff -u -r1.2 simple_markup.rb
--- simple_markup.rb 24 Apr 2004 01:39:21 -0000 1.2
+++ simple_markup.rb 6 Dec 2004 14:12:55 -0000
@@ -304,6 +304,27 @@
next
end

+ # Arbitrary markup blocks
+ #
+ # markup-type{{{
+ # text text text
+ # text text text
+ # text text text
+ # }}}
+ #
+
+ if /^(.*)\{\{\{$/ =~ active_line
+ line.stamp(Line::BLOCK, level, $1, margin)
+ loop do
+ line = @lines.next
+ raise "non terminated block" if line.nil?
+ break if line.text =~ /^\s{#{margin}}\}\}\}$/
+ line.stamp(Line::BLOCK, level)
+ end
+ line.stamp(Line::BLOCK, level, :end)
+ next
+ end
+
# Then look for list entries. First the ones that have to have
# text following them (* xxx, - xxx, and dd. xxx)

@@ -455,6 +476,9 @@
end
wantedLevel = line.type == Line::HEADING ? line.param : line.level
end
+
+ # we are on the last line of the block.
+ wantedType = nil if line.type == Line::BLOCK and line.param == :end
end

block.normalize
Index: simple_markup/fragments.rb
===================================================================
RCS file: /var/cvs/src/ruby/lib/rdoc/markup/simple_markup/fragments.rb,v
retrieving revision 1.2
diff -u -r1.2 fragments.rb
--- simple_markup/fragments.rb 30 Aug 2004 14:20:56 -0000 1.2
+++ simple_markup/fragments.rb 6 Dec 2004 14:12:56 -0000
@@ -65,6 +65,31 @@
end
end

+ class Block < Fragment
+ type_name Line::BLOCK
+
+ def raw_lines
+ @lines[1..-2]
+ end
+
+ def lines
+ margin = @type
+ if raw_lines.all? {|l| l[0, margin].strip.empty? }
+ # all lines are indented by _margin_ whitespaces -> remove them!
+ raw_lines.map{|l| l[margin..-1]}
+ else
+ raw_lines
+ end
+ end
+
+ def add_text(txt)
+ super
+ @lines ||= []
+ @lines << txt
+ end
+ end
+
+
##
# A List is a fragment with some kind of label
#
@@ -159,7 +184,6 @@
end

def accept(am, visitor)
-
visitor.start_accepting

@fragments.each do |fragment|
@@ -180,6 +204,8 @@
visitor.accept_heading(am, fragment)
when Paragraph
visitor.accept_paragraph(am, fragment)
+ when Block
+ visitor.accept_block(am, fragment)
end
end

Index: simple_markup/lines.rb
===================================================================
RCS file: /var/cvs/src/ruby/lib/rdoc/markup/simple_markup/lines.rb,v
retrieving revision 1.1
diff -u -r1.1 lines.rb
--- simple_markup/lines.rb 1 Dec 2003 07:12:48 -0000 1.1
+++ simple_markup/lines.rb 6 Dec 2004 14:12:56 -0000
@@ -15,6 +15,7 @@
RULE = :RULE
PARAGRAPH = ARAGRAPH
VERBATIM = :VERBATIM
+ BLOCK = :BLOCK

# line type
attr_accessor :type
Index: simple_markup/to_html.rb
===================================================================
RCS file: /var/cvs/src/ruby/lib/rdoc/markup/simple_markup/to_html.rb,v
retrieving revision 1.1
diff -u -r1.1 to_html.rb
--- simple_markup/to_html.rb 1 Dec 2003 07:12:48 -0000 1.1
+++ simple_markup/to_html.rb 6 Dec 2004 14:12:57 -0000
@@ -110,6 +110,14 @@
@res << convert_heading(fragment.head_level, am.flow(fragment.txt))
end

+ def accept_block(am, fragment)
+ process_block(@res, fragment.param, fragment.lines, fragment.raw_lines)
+ end
+
+ def process_block(res, markup_type, lines, raw_lines)
+ # do nothing. subclass responsibility
+ end
+
# This is a higher speed (if messier) version of wrap

def wrap(txt, line_len = 76)

--------------080905060003020409040905--

 

[Dave Thomas]

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

 

[Michael Neumann]

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:irective, which is then transformed in the
ToHtml step (generate html for filename).

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!

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

 

[Joel VanderWerf]

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:

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