From: Michael Neumann <mneumann@...>
Date: 2004-12-06T23:15:56+09:00
Subject: Re: [RDOC] quoting YAML

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

Dave Thomas wrote:
> 
> 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".
> 
> 
> 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 = :PARAGRAPH
     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--