[Bug 18147] telepathy-glib API reference contains weird markup.

[bugzilla-daemon at freedesktop.org]

https://bugs.freedesktop.org/show_bug.cgi?id=18147

Simon McVittie <simon.mcvittie at collabora.co.uk> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         Depends on|                            |24641

--- Comment #2 from Simon McVittie <simon.mcvittie at collabora.co.uk> 2010-12-03 09:24:35 PST ---
This is harder to fix than you might think, because the D-Bus API documentation
is in HTML + extensions, whereas the telepathy-glib API reference is in
Docbook-embedded-in-comments (gtk-doc). The tools that generate the C code
(glib-client-gen.py and glib-ginterface-gen.py) would have to be adapted to:

* turn the Telepathy-specific extensions into HTML (we already have code to do
this, although hyperlinks would need adjusting - making them point to the
online copy of the D-Bus API docs would probably be enough)
* turn HTML (or at least the subset of it that we actually use) into Docbook
markup
* put that Docbook markup in the comments that gtk-doc parses

When this bug was originally filed, we used XSLT for the code generation, so
doing that was basically impossible (XSLT is unsuitable for Perl-style
text-mangling).

We now use Python, so it may be possible to solve this, but it'd still be
rather awkward (unless someone's already written a HTML-subset-to-Docbook
converter that we can use?).

Porting the code-generation tools to use specparser.py rather than parsing it
themselves is a prerequisite for this, IMO.

-- 
Configure bugmail: https://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.
You are the assignee for the bug.