Re: gtk-doc xml stuff

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.


Email: james daa com au              | 2003 Call for Papers out
WWW: |

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]