Re: <\!> in doc comments?

[James Henstridge <james daa com au>]

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?

James.

--
Email: james daa com au
WWW:   http://www.daa.com.au/~james/