Processing mixed content with REXML

ruby-talk
21

James, Jacob, Matthew, Robert, and Pedro:
   Thanks for bearing with me!

And thanks for the pointer to the newer API
docs. It's good to have.

Additional comments below.

Jacob Fugal wrote:

The best thing any of us, you and me included, can do about this
situation is not to try to engineer a better solution than RDoc, but
to go in and *write documentation*. I've started with the webrick
library myself -- hopefully another couple months down the road I can
get it finished and added to ruby-doc.org.

Agreed. The issue is not with the mechanism, but the
content. I much prefer the layout of the builder.rubyforge
pages, but that's not really a big issue.

When it comes to making improvements, Wiki pages are terrific. I created InstallingRuby and InstallingRubyGems
pages at http://wiki.rubygarden.org/Ruby, for the very
reason that I wanted to give back to the community. When
I can make things easier for someone coming along behind
me, I figure I've done my job.

I'll be happy to add material to the API comments, as
well. But it would be easier to do if there were some
sort of Wiki mechanism for that purpose.

For the moment, I'm pretty much coming up to speed on the
language and getting standard idioms ingrained so they're
at my fingertips. Things are progressing nicely, but I'm
not yet at the point that I download sources from a
remote cvs repository (although, when it comes to that,
I would prefer a remote Subversion repository).

So, that said, what's the best way to feedback info into
the APIs? Do I need to access the source code? If so,
where is it? The ruby-doc site doesn't have a link. I
tried rexml.sourceforge, but that doesn't exist. REXML's
home page has a link to Kou's Documentation Page, but
that link is broken. I can download the development
tree from that site, it gives no indication of how to
feedback any changes.

In short, I would love to add the following notes to
the API docs, somewhere:

    node_type
     --returns a symbol
         :attribute -- use node.value to get text
         :comment -- use node.to_s to get text
         :text -- use node.value to get text
         :cdata (maybe. not verified)
         :element -- see below

    node.attribute("attributeName")
       --returns an attribute node . Use .value on the
         attribute node (like a text node) to get it's string

    each
      --iterates over all child nodes
        see also: each_element, each_recursive

    to_a
      --returns an array of child nodes

But feeding back information like this should be
trivial. It should be a no-brainer. It should not
be the major undertaking that it is turning out to be.

thanks again, all
it's good to have friends
:_)

22

When it comes to making improvements, Wiki pages are
terrific. I created InstallingRuby and InstallingRubyGems
pages at http://wiki.rubygarden.org/Ruby, for the very
reason that I wanted to give back to the community. When
I can make things easier for someone coming along behind
me, I figure I've done my job.

I'll be happy to add material to the API comments, as
well. But it would be easier to do if there were some
sort of Wiki mechanism for that purpose.

Thanks for contributing to the wiki. There's actually a work in
progress which allows Ruby API docs which allow wiki style
annotations, which the maintainer could then roll back into the
"official" doc. I think this would be a great system. I believe the
package is called Rannotate. The idea was thrown out of including this
into ruby-doc.org itself, but I don't think anything's been done about
it.

So, that said, what's the best way to feedback info into
the APIs? Do I need to access the source code? If so,
where is it? The ruby-doc site doesn't have a link. I
tried rexml.sourceforge, but that doesn't exist. REXML's
home page has a link to Kou's Documentation Page, but
that link is broken. I can download the development
tree from that site, it gives no indication of how to
feedback any changes.

In short, I would love to add the following notes to
the API docs, somewhere:

    node_type
     --returns a symbol
         :attribute -- use node.value to get text
         :comment -- use node.to_s to get text
         :text -- use node.value to get text
         :cdata (maybe. not verified)
         :element -- see below

    node.attribute("attributeName")
       --returns an attribute node . Use .value on the
         attribute node (like a text node) to get it's string

    each
      --iterates over all child nodes
        see also: each_element, each_recursive

    to_a
      --returns an array of child nodes

The best place would probably be to post it on the ruby-doc mailing
list (yup, there is one!).

Jacob Fugal

···

On 6/16/06, Eric Armstrong <Eric.Armstrong@sun.com> wrote:

23

Ask and your wish shall be granted! I just found an API
doc Wiki (I think).

I was at the REXML doc page, looking at Node.to_s
http://www.ruby-doc.org/stdlib/libdoc/rexml/rdoc/

That undocumented method had this inscrutable bit of
code, that does't seem to do anything at all, as far
as I can tell:

    def to_s indent=-1
      rv = ""
      write rv,indent
      rv
    end

I'm sure it does /something/, so in an attempt to find
out what, I took a look at the Node.rb file.

There, I saw "To view or add comments on this documentation, please go to the API wiki."

I've been clicking everything I can find there, and for the
life of me I don't see any way to get to an actual API
page you can edit, but someone is clearly thinking in the
right direction!

Jacob Fugal wrote:

···

On 6/16/06, Eric Armstrong <Eric.Armstrong@sun.com> wrote:

When it comes to making improvements, Wiki pages are
terrific. I created InstallingRuby and InstallingRubyGems
pages at http://wiki.rubygarden.org/Ruby, for the very
reason that I wanted to give back to the community. When
I can make things easier for someone coming along behind
me, I figure I've done my job.

I'll be happy to add material to the API comments, as
well. But it would be easier to do if there were some
sort of Wiki mechanism for that purpose.

Thanks for contributing to the wiki. There's actually a work in
progress which allows Ruby API docs which allow wiki style
annotations, which the maintainer could then roll back into the
"official" doc. I think this would be a great system. I believe the
package is called Rannotate. The idea was thrown out of including this
into ruby-doc.org itself, but I don't think anything's been done about
it.

So, that said, what's the best way to feedback info into
the APIs? Do I need to access the source code? If so,
where is it? The ruby-doc site doesn't have a link. I
tried rexml.sourceforge, but that doesn't exist. REXML's
home page has a link to Kou's Documentation Page, but
that link is broken. I can download the development
tree from that site, it gives no indication of how to
feedback any changes.

In short, I would love to add the following notes to
the API docs, somewhere:

    node_type
     --returns a symbol
         :attribute -- use node.value to get text
         :comment -- use node.to_s to get text
         :text -- use node.value to get text
         :cdata (maybe. not verified)
         :element -- see below

    node.attribute("attributeName")
       --returns an attribute node . Use .value on the
         attribute node (like a text node) to get it's string

    each
      --iterates over all child nodes
        see also: each_element, each_recursive

    to_a
      --returns an array of child nodes

The best place would probably be to post it on the ruby-doc mailing
list (yup, there is one!).

Jacob Fugal

24

Eric Armstrong wrote:

Ask and your wish shall be granted! I just found an API
doc Wiki (I think).

I was at the REXML doc page, looking at Node.to_s
http://www.ruby-doc.org/stdlib/libdoc/rexml/rdoc/

..

There, I saw "To view or add comments on this documentation, please go to the API wiki."

I've been clicking everything I can find there, and for the
life of me I don't see any way to get to an actual API
page you can edit, but someone is clearly thinking in the
right direction!

Ah, sadly, the default CSS for RDoc disguises links to look like not-links. The link is the text "the API wiki"

I'll see about correcting this on the site.

···

--
James Britt

"The greatest obstacle to discovery is not ignorance, but the illusion of knowledge."
  - D. Boorstin

25

I was at the REXML doc page, looking at Node.to_s
http://www.ruby-doc.org/stdlib/libdoc/rexml/rdoc/

That undocumented method had this inscrutable bit of
code, that does't seem to do anything at all, as far
as I can tell:

    def to_s indent=-1
      rv = ""
      write rv,indent
      rv
    end

My guess is that the +write+ method (which is probably private or
protected), writes the actual contents of the tree into its first
argument, using the indentation specified. So we create a string to
write into, pass it on to the write function, then return that string.
Violá!

But this wasn't really your point, so I'll get on with it...

There, I saw "To view or add comments on this documentation,
please go to the API wiki."

I've been clicking everything I can find there, and for the
life of me I don't see any way to get to an actual API
page you can edit, but someone is clearly thinking in the
right direction!

This isn't quite the wiki-annotations I was referring to. Instead what
this is is a wiki page dedicated to each rdoc page. Each of those
pages are blank by default. You're not editing *the* API page, but
rather a page *related* to the API page. The Rannotate library that I
was referring to takes it a step further by allowing you to edit a
chunk *embedded* in the API page, but you still aren't editing the API
documentation itself. Two of the benefits are that there are several
of these chunks per page -- one for each method, as well as one for
the page itself -- and that the notes are viewable inline with the
rest of the documentation.

See http://ruby.outertrack.com/ for an example of Rannotate in action.
(I don't know how many annotations have actually been added there, but
you can play with the functionality.)

Jacob Fugal

···

On 6/16/06, Eric Armstrong <Eric.Armstrong@sun.com> wrote:

26

Jacob Fugal wrote:

See http://ruby.outertrack.com/ for an example of Rannotate in action.
(I don't know how many annotations have actually been added there, but
you can play with the functionality.)

First, I /love/ the format of those pages. They just became
my standard API reference.

But, oddly, from REXML::Element, I'm not seeing a link to
the parent class, Parent.

I'm adding notes to that class now. It's unfortunate that
the system makes me reenter my email address each time.
But it's livable.

It's also unfortunate that there is no way to access the
lists of classes when you visit a class. You can see that
classes' methods, but that's it. To get to another class,
you have to back up, which loses the context. For example,
you might be reading a method and want to open 2 or 3
related classes in separate windows.

Weird. node_type() isn't implemented in the Node class.
I would have expected it there. It must be in a superclass.
Sure wish I could see what they are.

How strange. I just went back to the Parent page looking
for node_type, and I don't see the notes I added. Maybe
it takes a while? Rather disconcerting.

Well, I checked Node, Element, Parent, and Child. That's
as much of the hierarchy as I recall from memory. Never
did find node_type. Might have just missed, but it's too
hard to switch between classes to look again.

In short, this is a great idea that is very close to being
ready for prime time. I look forward to the next version.