Re: <\!> in doc comments?

Matthias Clasen wrote:

Hi James,

you shouldn't try to process SGML with XML tools...
I wasn't aware that gtk-doc is going to move over
to xml.
At the moment it isn't. I have a separate set of scripts that makes the Gtk docs look a little like python docs, and was experimenting with using Docbook/XML instead of SGML. This was the one place it tripped up.

Possibly moving gtk-doc over to XML and xsltproc would be a good idea in the future. The main change would be to rewrite the gtk-doc DSSSL script in XSL. I took a quick look at this, but got a bit lost in some of the more complicated scheme functions :( Also, from my experiments xsltproc seems to be a bit slower with large documents with many chunks and xrefs compared to Jade :(

I introduced the empty declarations (ie <!>) in order
to suppress the IMO irritating links in examples, which are blindly inserted by the gtk-doc perl scripts for
anything which resembles the pattern g[a-z_]*(). In order
to suppress it, I needed to insert something between ( and )
which - is not the empty string - contributes the empty string to the SGML document after parsing

This leaves basically three possibilities:
a) an entity with an empty replacement text (&empty;)
b) a comment declaration (<!-- empty -->)
c) an empty declaration  (<!>)
(there are some more possibilities when using more arcane SGML features)

I chose c), since it seemed the most elegant. Unfortunately it is
also the only possibility which is not valid XML. I would have probably been better to sacrifice elegance for interoperability and use a comment declaration.
Feel free to s/<!>/<!-- -->/g.

Okay. I have applied this change, although I thought the resulting HTML from gtk-doc would end up as a <gtkdoclink> element (because it would be a dangling link) which would be ignored by a web browser. Is this not the case?


Email: james daa com au

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