From: james@...
Date: 2002-02-23T15:15:36+09:00
Subject: RE: rdoc/xml questions

> From: dave@thomases.com [mailto:dave@thomases.com]On Behalf Of Dave
> Thomas
> 
> 
> 
> I'm wondering about having rdoc generate xml output, and have a couple
> of questions.

Three things worth considering: 
1. Which form is easiest for a human to read and understand?
2. Which format contains the most information?
3. Which format is easier to write code for processing?

The relative value of these can vary; perhaps this XML is not really 
intended for raw consumption by humans, as people will view the results
of an XSLT transformation.  


> 
> 1. Given the Ruby source
> 
>        # comment 1
>        class A
>           # comment 2
>           class B
>           end
>        end
> 
>    how should the corresponding XML be generated in terms of
>    nesting. Logically, you might want to see
> 
>       <class name="A">
>          <class name="A::B">
>            <description>
>              comment 2
>            </description>
>          </class>
>          <description>
>            comment 1
>          </description>
>        </class>

I'm unhappy with name="A::B", as it hides the relationship of A to B
inside the attribute value, using non-XML notation. Perhaps
          <class name="B" container="A">

or something along those lines

> 
>    However, it might also make sense in terms of processing to instead
>    have
> 
>       <class name="A">
>          <description>
>            comment 1
>          </description>
>        </class>
> 
>        <class name="A::B">
>          <description>
>            comment 2
>          </description>
>        </class>
> 
>    What are the arguments either way.

One can transform one to the other, but the first is easier for people to pick
out the relationship, and possibly easier to process using XSLT templates.

> 
> 
> 2. For hyperlinking between things, should I use my own tags, or are there
>    benefits to using xlink/xpointer?

A possible benefit is the use of existing code to process the data.  I'm also 
wondering if there exists some appropriate RDF-based syntax that can be used for 
this.  (On the other hand, that may just make this more complicated than it need be.)

xlink/xpointer defines things like two-way links and transclusion, and reusing
an existing spec might make it easier to explain (i.e., "Go read the XLink/XPointer
specs").

James

> 
> 
> Cheers
> 
> 
> Dave
>