Re: gtk-doc xml stuff

[James Henstridge <james daa com au>]

Matthias Clasen wrote:

> > Okay.  I was hoping to be able to dump jade and SGML completely, and go 
> > with xsltproc for everything. 
> >    
>
> Yes that would be nice in the longer term as well, and it is nice that we
> seem to have started tackling this in complementary areas.
>
>  
>
> > After porting the stylesheet, I was 
> > thinking of changing the docs to use XIncludes rather than entities to 
> > pull in the generated portions of the document.
> >    
>
> I'm not sure I'm too fond of this idea. Whats bad about entities apart 
> from
> the fact that W3C didn't invent them ? 
Well, in the libglade reference docs, in the main file 
(libglade-docs.sgml), I have a list of entity defs pointing at the 
generated documentation, and then down in the body of the document I 
have references to these entity defs.  Using xincludes, I would only 
need one lot of references to the generated documentation.

And since an xinclude'd document can xinclude other documents, gtk-doc 
could be modified to output an XML file that consisted of xincludes of 
all the other files.  That way I would only need a single reference to 
the generated documentation in libglade-docs.sgml.

> > This way, the files representing the different sections can be valid XML 
> >    
>
>  
>
> > documents themselves (so a section could have its own entities, for 
> > instance),
> >    
>
> You can achieve the same with entities (SUBDOC entities). But it is not so
> important that the sections are valid, its more important the the 
> resulting
> document is valid. And you loose validation for IDREFs if you move to 
> xinclude, AFAIK.
Can't libxml do validation after the xincludes?

> > and you don't need to keep the list of entity definitions and 
> > entity references in the main file in sync.
> >    
>
> Well, since the entities are referenced in the main file as well, I don't
> see the real benefit.
I guess I don't like having to repeat the information, as it is one more 
thing to worry about when making additions to the documentation.  As I 
mentioned above, it should be possible to set things up so only a single 
xinclude is required.

> > Also, XIncludes work recursively, so you could combine a number of 
> > reference docs into a larger book set.
> >    
>
> I don't understand this comment. Entity references also "work recursively"
> whatever you mean by this. And there is no problem to combine a number
> of docbook <book>s into a docbook <set>, if you're after that.
I mean that one xincluded document can xinclude another, and that the 
path names you use in the xinclude are relative to the including 
document, rather than the toplevel one.

James.

--
Email: james daa com au              | Linux.conf.au 2003 Call for Papers out
WWW:   http://www.daa.com.au/~james/ |   http://conf.linux.org.au/cfp.html