Rdoc allowing arbitrary HTML


#1

Hi all

I just really needed this for footnotes and some fun in my rdoc.
It is a very primitive patch allowing to write arbitrary HTML code in
rdoc like this
%html (1)

%html

I thought I will share this patch which seems to work.

Caveat, if you include %html into your rdoc and create anything else
than html
it will bomb, first I thaught of implementing the accept_pure_html in
the other visitor servers transparently, but that seems somehow wrong,
maybe a warning would be in order?

P.S.
The patch is from mercurial’s diff, please apply with -p1 and say Y to
the strange question about reverse diff.

Cheers
Robert


#2

Robert D. wrote:

I just really needed this for footnotes and some fun in my rdoc.
It is a very primitive patch allowing to write arbitrary HTML code in
rdoc like this
%html (1)

%html

I thought I will share this patch which seems to work.

Thanks! I was just wondering how to mess with RDoc’s engine…

The patch is from mercurial’s diff, please apply with -p1 and say Y to
the strange question about reverse diff.

I’m going to add it directly to my project, as a monkey-patch, not to my
raw
RDoc.

And here’s my RDoc wish-list:

  • the ability to alias a link to another part of the project. Example:

    assert_xpath[AssertXPath#assert_xpath]
    -> assert_xpath

    that would shorten the cross-link from another module

  • the ability to transclude a snip of source from one module into the
    doc for another. For example, assert_xpath’s doc should not say:

    See AssertXPathTest#test_assert_xpath

    The contents of that test case should simply appear in the doc
    itself.

  • alternative, pretty, persistent URIs for items. Not:

    http://assertxpath.rubyforge.org/classes/AssertXPath.html#M000106

    but:

    http://assertxpath.rubyforge.org/classes/AssertXPath.html#assert_xpath

    (Note I can do this with your patch, manually, by putting in an
    anchor)

  • Each page should have a linker to the root index.html

  • Ability to stick a method on the page where it belongs, instead
    of the page for the class where it happens to be!

  • link to complete source (I might be missing this one!)

  • don’t trip over this colon:

    send(:“format_#{item.kind}”, item, ypath)

Finally, this might be pilot error, but certain class names I simply
cannot
get out of the class list…


#3

On Jul 29, 2007, at 09:41 , Phlip wrote:

And here’s my RDoc wish-list:

don’t put that here, file feature requests on the ruby project and
categorize them properly.


#4

On Jul 29, 2007, at 08:32 , Robert D. wrote:

I just really needed this for footnotes and some fun in my rdoc.
It is a very primitive patch allowing to write arbitrary HTML code in
rdoc like this

<allow_html.patch>

please file this as a patch on the ruby project on rubyforge and
categorize it appropriately.


#5

On 7/29/07, Joel VanderWerf removed_email_address@domain.invalid wrote:


vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

OP is not aware of anything, OP just wanted to share the code, that’s
all folks…
I decided to do so in a form of a patch, if that was misleading, well,
OP apologizes.

Cheers
Robert


#6

Ryan D. wrote:

please file this as a patch on the ruby project on rubyforge and
categorize it appropriately.

But the OP should be aware that there is a bit of a backlog. There are
limited programmer resources to handle patches, so putting the patches
up on the ML is a good way to distribute them to those who want to
monkey-patch. We should, IMO, keep sending patches to the ML (as well as
to the rubyforge tracker).


#7

Robert D. wrote:


vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

OP is not aware of anything, OP just wanted to share the code, that’s
all folks…
I decided to do so in a form of a patch, if that was misleading, well,
OP apologizes.

Sorry, Robert (I’ll stop calling you “OP”–that’s a bad habit!). I
didn’t mean that to sound like a complaint. Realistically, if you want
to benefit more users, please post to the ruby-talk ML (might be better
than core for that purpose). I appreciate seeing patches like this, and
probably others do as well.


#8

On 7/29/07, Joel VanderWerf removed_email_address@domain.invalid wrote:


vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407

OP is not aware of anything, OP just wanted to share the code, that’s
all folks…
I decided to do so in a form of a patch, if that was misleading, well,
OP apologizes.

Sorry, Robert (I’ll stop calling you “OP”–that’s a bad habit!). I
No offense taken, but it was extremely funny to talk of myself as OP. :slight_smile:
didn’t mean that to sound like a complaint. Realistically, if you want
to benefit more users, please post to the ruby-talk ML (might be better
than core for that purpose).
I cross posted, you are right posting to core was completely missleading

I appreciate seeing patches like this, and
probably others do as well.
Hmm I do not think it is a great achievement but than it was quite
some work to do, so I wanted to share. [ Why the hack did I not tell
this clearly the first time??? ]

Now if you really think there is some value in this I am glad to put
it into better form

Next time I will be clearer, your feedback was ok Joël, but clearer
the second time :slight_smile:
R.


#9

Robert D.

%html

I thought I will share this patch which seems to work.

This patch doesn’t seem complete. For example…

if /^\s*%html/ === line.text then
line.text.sub!("%html","")
line.stamp( Line::PURE_HTML, level )

  • dbg “in simple_markup”,line
    next
    end

The patch only says to remove the dbg line; it doesn’t seem to say to
add
the %html lines around it, which are the point of the exercise. And I
can’t
find PURE_HTML anywhere.


#10

On 7/29/07, Phlip removed_email_address@domain.invalid wrote:

 line.stamp( Line::PURE_HTML, level )

http://www.oreilly.com/catalog/9780596510657/
“Test Driven Ajax (on Rails)”
assert_xpath, assert_javascript, & assert_ajax

It seems that the diff has been made against an intermediate version,
I can send you the files off list if you want.

I have not completely understood RDoc and please be aware that this is
err very basic; A first issue I found is that if you say

aaa

%html (1)

bbb

you will have a paragraph around (1)
can be fixed with
%html aaa
%html (1)
%html bbb
but that was not the real purpose, I should need to study what exactly
the visitors do with the annotated lines, soo few time :frowning:

Cheers
Robert


#11

On Jul 29, 2007, at 11:50 , Joel VanderWerf wrote:

Ryan D. wrote:

please file this as a patch on the ruby project on rubyforge and
categorize it appropriately.

But the OP should be aware that there is a bit of a backlog. There
are limited programmer resources to handle patches, so putting the
patches up on the ML is a good way to distribute them to those who
want to monkey-patch. We should, IMO, keep sending patches to the
ML (as well as to the rubyforge tracker).

No, patches should not come to the ML first anymore. I’ve taken over
as top level ticket triage for the project as a whole and assigned
second level triage for all the major categories. In this case, it
should be categorized as “Documentation, ri, and rdoc” which would
autoassign it to Eric H…


#12

Robert D. wrote:

It seems that the diff has been made against an intermediate version,
I can send you the files off list if you want.

No prob: I reproduced what you did as a monkey patch, available below my
sig.

It’s only long because one of the methods I had to patch was poorly
factored
and run-on. Other than that, the Visitor Pattern made the actual patch
super
easy!

I put this in my Rakefile, and because that calls RDoc internally, it
gets
the new feature. Thanks for the code sample, because this is exactly
what I
was about to start researching!

aaa

%html (1)

bbb

you will have a paragraph around (1)
can be fixed with
%html aaa
%html (1)
%html bbb

I didn’t get a paragraph around it, so I didn’t need the workaround. Yet
note you have two blanks in “# aaa” - they cause a

 aaa
.

Now I dibs first crack at the Wish List I just posted! Nobody else can
do
them!


Phlip
http://www.oreilly.com/catalog/9780596510657/
“Test Driven Ajax (on Rails)”
assert_xpath, assert_javascript, & assert_ajax

##################################################################

eek eek ook ook patch to add %html directive to RDocage

require ‘rdoc/rdoc’
require ‘rdoc/markup/simple_markup’
require ‘rdoc/markup/simple_markup/lines’
require ‘rdoc/markup/simple_markup/fragments’
require ‘rdoc/markup/simple_markup/to_html’

module SM

class Line
PURE_HTML = :PURE_HTML
end

class PureHTML < Fragment
type_name Line::PURE_HTML
end

class ToHtml
def accept_pure_html(am, fragment)
@res << fragment.txt
end
end

class LineCollection
def accept(am, visitor)
visitor.start_accepting

  @fragments.each do |fragment|
    case fragment
    when Verbatim
      visitor.accept_verbatim(am, fragment)
    when PureHTML
       visitor.accept_pure_html(am, fragment)
    when Rule
      visitor.accept_rule(am, fragment)
    when ListStart
      visitor.accept_list_start(am, fragment)
    when ListEnd
      visitor.accept_list_end(am, fragment)
    when ListItem
      visitor.accept_list_item(am, fragment)
    when BlankLine
      visitor.accept_blank_line(am, fragment)
    when Heading
      visitor.accept_heading(am, fragment)
    when Paragraph
      visitor.accept_paragraph(am, fragment)
    end
  end

  visitor.end_accepting
end

end

class SimpleMarkup
private

def assign_types_to_lines(margin = 0, level = 0)

  while line = @lines.next

    if /^\s*%html/ === line.text then
      line.text.sub!("%html","")
      line.stamp( Line::PURE_HTML, level )
      next
    end  #  ERGO  move this monkey-patch towards the real RDoc!

    if line.isBlank?
      line.stamp(Line::BLANK, level)
      next
    end

    # if a line contains non-blanks before the margin, then it must

belong
# to an outer level

    text = line.text

    for i in 0...margin
      if text[i] != SPACE
        @lines.unget
        return
      end
    end

    active_line = text[margin..-1]

    # Rules (horizontal lines) look like
    #
    #  ---   (three or more hyphens)
    #
    # The more hyphens, the thicker the rule
    #

    if /^(---+)\s*$/ =~ active_line
      line.stamp(Line::RULE, level, $1.length-2)
      next
    end

    # Then look for list entries. First the ones that have to have
    # text following them (* xxx, - xxx, and dd. xxx)

    if SIMPLE_LIST_RE =~ active_line

      offset = margin + $1.length
      prefix = $2
      prefix_length = prefix.length

      flag = case prefix
             when "*","-" then ListBase::BULLET
             when /^\d/   then ListBase::NUMBER
             when /^[A-Z]/ then ListBase::UPPERALPHA
             when /^[a-z]/ then ListBase::LOWERALPHA
             else raise "Invalid List Type: #{self.inspect}"
             end

      line.stamp(Line::LIST, level+1, prefix, flag)
      text[margin, prefix_length] = " " * prefix_length
      assign_types_to_lines(offset, level + 1)
      next
    end


    if LABEL_LIST_RE =~ active_line
      offset = margin + $1.length
      prefix = $2
      prefix_length = prefix.length

      next if handled_labeled_list(line, level, margin, offset, 

prefix)
end

    # Headings look like
    # = Main heading
    # == Second level
    # === Third
    #
    # Headings reset the level to 0

    if active_line[0] == ?= and active_line =~ /^(=+)\s*(.*)/
      prefix_length = $1.length
      prefix_length = 6 if prefix_length > 6
      line.stamp(Line::HEADING, 0, prefix_length)
      line.strip_leading(margin + prefix_length)
      next
    end

    # If the character's a space, then we have verbatim text,
    # otherwise

    if active_line[0] == SPACE
      line.strip_leading(margin) if margin > 0
      line.stamp(Line::VERBATIM, level)
    else
      line.stamp(Line::PARAGRAPH, level)
    end
  end
end

end
end

eek eek ook ook patch to add %html directive to RDocage

##################################################################


#13

On 8/1/07, Phlip removed_email_address@domain.invalid wrote:

the lieutenants. A real patch that provided a lite plugin mechanism to RDoc
should rise faster than patches that add one or two dumb directives.
Thanks a lot Philip :(.
I would say that my ill adviced and badly labeled trial to share some
code was quite a disaster, getting me even some insults, well deserved
without any doubt.
I however ask myself if this is the style we normally apply?
I agree with Philip that if we cannot discuss our code we will never
provide anything useful…

Robert


#14

Joel VanderWerf wrote:

Ryan D. wrote:

please file this as a patch on the ruby project on rubyforge and
categorize it appropriately.

But the OP should be aware that there is a bit of a backlog.

Hence, these forums should help allow only the best ideas to percolate
up to
the lieutenants. A real patch that provided a lite plugin mechanism to
RDoc
should rise faster than patches that add one or two dumb directives.


#15

Robert D. wrote:

I however ask myself if this is the style we normally apply?
I agree with Philip that if we cannot discuss our code we will never
provide anything useful…

Dude, I was stuck on your exact problem just before you posted.

A high-volume forum generates a crew of regulars who tend to get
trigger-happy about FAQs and such. Try policing a group yourself to
see how easy and fun it is!


#16

On 8/1/07, Phlip removed_email_address@domain.invalid wrote:

see how easy and fun it is!
Philip I am losing you here, what are you talking about? I guess this
thread is dead now, but I am still here to discuss RDoc if someone has
to say something about here.

Cheers
Robert