Re: XML DocBook patch

[Owen Taylor <otaylor redhat com>]

Damon Chaplin <damon ximian com> writes:

> On Thu, 2002-04-11 at 23:02, Owen Taylor wrote:
> > 
> > Toshio Kuratomi <badger prtr-13 ucsc edu> writes:
> > 
> > > Enclosed is a patch that enables gives gtkdoc-mkdb a new output flag:
> > > --output-format=[xml|sgml]
> > > When --output-format=xml is given gtkdoc-mkdb spits out xml output as xml
> > > rather than sgml (The only difference thus far is that gtkdoc-mkdb closes
> > > the anchor and colspec tags and using .xml as the file extension.)
> > > 
> > > There are also commented out changes that would move the default output
> > > directory from ./sgml to ./docbook.  I think this is a more logical
> > > directory name but I think it'll require some updates to client makefiles so
> > > I disabled it for now.
> > 
> > I was looking over this patch (very much later....) and I'm wondering...
> > Why can't we just always close the tags? 
> > 
> > If we did that, the only effect of the --output-format switch would
> > be the extension of the generated files?
> 
> Yes, I don't think it would be a problem. We can just change it and see
> if it breaks.

I think the general consensus is that there are some tags that can't be
closed in SGML docbook. 

I think we can clean up the patch a little though for these tags. Toshio's
patch (http://mail.gnome.org/archives/gtk-doc-list/2001-May/msg00039.html)
has a number of declarations of the form:

if ($OUTPUT_FORMAT =~ m/xml/i) {
+	$close_anchor="</anchor>";

[...]

+	$desc = "<refsect2>\n<title><anchor id=\"$id\">$close_anchor${symbol}()</title>\n";

Which I think we can simplify to:
 
if ($OUTPUT_FORMAT =~ m/xml/i) {
+	$xml_close="/";

+	$desc = "<refsect2>\n<title><anchor id=\"$id\"$xml_close>${symbol}()</title>\n";

Using the <anchor/> form for a single tag.

> Any ideas about the cross-references?
> Maybe we can use a <ulink> element with a special URL type that the help
> viewer understands and knows how to resolve.

I've been looking at this some recently ... after studying XLST a little
bit, Daniel's mail on the subject makes more sense to me than it did
originally.
 
 - We can certainly do exactly what we are doing now, but using the
   XML tools and a little more cleanly. 

   (The validation that id="" tags point to id's in the document is done in 
   the stylesheet, not in the processor, so we can override it.)

 - We can probably get rid of the need for gtkdoc-fixref, and do 
   something like:

    xsltproc --parameter gtkdocindex "/usr/share/gtk-doc/html/index.xml" /usr/share/gtk-doc/gtk-doc.xsl gtk-docs.xml

   Where index.sml would contain something like:

   <indexset>
    <docindex>glib/index.xml</docindex>
    <docindex>pango/index.xml</docindex>
   </indexset>

   I don't think we can do _everything_ automatically in the stylesheets, however,
   since the gtkdoc-fixref "find index.sgml in all subdirectories" idea isn't
   expressable in XSLT.

   So, we'll have to have some sort of install step where we add document specific
   indexes to a global index.

I think maintaining straight HTML ouput is important for things like having the
docs on a web page.

And I don't think we can really just install the raw XML docbook and have the 
conversion done on the fly ... if we did that, we'd have no way of resolving
references like #gint, since we wouldn't know what document they point into.

Regards,
                                        Owen