Forum: Ruby Rdoc allowing arbitrary HTML

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
Robert D. (Guest)
on 2007-07-29 19:32
(Received via mailing list)
Attachment: allow_html.patch (0 Bytes)
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 <a href="#fn1">(1)</a>
...
  %html <a name="fn1" />

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
Phlip (Guest)
on 2007-07-29 20:42
(Received via mailing list)
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 <a href="#fn1">(1)</a>
> ...
>  %html <a name="fn1" />
>
> 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]
         -> <a href='..'>assert_xpath</a>

   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/AssertXPa...

   but:

   http://assertxpath.rubyforge.org/classes/AssertXPa...

   (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...
Ryan D. (Guest)
on 2007-07-29 21:44
(Received via mailing list)
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.
Ryan D. (Guest)
on 2007-07-29 21:48
(Received via mailing list)
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.
Joel VanderWerf (Guest)
on 2007-07-29 22:52
(Received via mailing list)
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).
Robert D. (Guest)
on 2007-07-29 23:21
(Received via mailing list)
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
Joel VanderWerf (Guest)
on 2007-07-29 23:29
(Received via mailing list)
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.
Robert D. (Guest)
on 2007-07-29 23:46
(Received via mailing list)
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. :)
> 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 :)
R.
Phlip (Guest)
on 2007-07-30 01:26
(Received via mailing list)
Robert D.

>  %html <a name="fn1" />
>
> 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.
Robert D. (Guest)
on 2007-07-30 01:49
(Received via mailing list)
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 <sup>(1)</sup>
# bbb

you will have a paragraph around (1)
can be fixed with
%html aaa
%html <sup>(1)</sup>
%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 :(

Cheers
Robert
Phlip (Guest)
on 2007-07-30 02:20
(Received via mailing list)
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 <sup>(1)</sup>
> # bbb
>
> you will have a paragraph around (1)
> can be fixed with
> %html aaa
> %html <sup>(1)</sup>
> %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 <pre> aaa</pre>.

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
##################################################################
Ryan D. (Guest)
on 2007-08-01 02:09
(Received via mailing list)
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..
Phlip (Guest)
on 2007-08-01 07:11
(Received via mailing list)
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.
Robert D. (Guest)
on 2007-08-01 10:32
(Received via mailing list)
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
Phlip (Guest)
on 2007-08-01 15:42
(Received via mailing list)
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!
Robert D. (Guest)
on 2007-08-01 16:43
(Received via mailing list)
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
This topic is locked and can not be replied to.