Bug 18147

Summary:	telepathy-glib API reference contains weird markup.
Product:	Telepathy	Reporter:	Murray Cumming <murrayc>
Component:	tp-glib	Assignee:	Telepathy bugs list <telepathy-bugs>
Status:	RESOLVED MOVED	QA Contact:	Telepathy bugs list <telepathy-bugs>
Severity:	normal
Priority:	medium	CC:	pochu27
Version:	unspecified
Hardware:	Other
OS:	All
Whiteboard:
i915 platform:		i915 features:
Bug Depends on:	24641
Bug Blocks:

Description Murray Cumming 2008-10-21 02:30:11 UTC

Some API reference documentation, such as this
http://telepathy.freedesktop.org/doc/telepathy-glib/telepathy-glib-connection-manager.html#tp-cli-connection-manager-call-request-connection
contain huge amounts of weird markup, making it unreadable.

For instance,
"
<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request a <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> object representing a given account on a given protocol with the given parameters.
"

Comment 1 Simon McVittie 2010-12-03 09:09:47 UTC

*** Bug 32079 has been marked as a duplicate of this bug. ***

Comment 2 Simon McVittie 2010-12-03 09:24:35 UTC

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.

Comment 3 GitLab Migration User 2019-12-03 19:23:03 UTC

-- GitLab Migration Automatic Message --

This bug has been migrated to freedesktop.org's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.freedesktop.org/telepathy/telepathy-glib/issues/8.

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.