Package: python3-sphinxcontrib.devhelp
Version: 2.0.0-2
Severity: important
Tags: upstream patch
Forwarded: https://github.com/sphinx-doc/sphinxcontrib-devhelp/pull/38
Control: affects -1 + gnome-builder manuals python-mpd2
This extension produces an index in devhelp format, which is intended to
be readable by tools like Devhelp (in Debian <= 13), GNOME Builder, and
GNOME Manuals (which replaces Devhelp in Debian 14).
However, it currently outputs an obsolete version of the devhelp syntax,
format version v1 (distinguished by the .devhelp.gz extension), which
isn't parsed by the foundry library used by gnome-builder and manuals.
To be usable in those applications, the index should be in devhelp
format v2:
- file needs to be named ${NAME}.devhelp2 and uncompressed
- <book> needs xmlns="http://www.devhelp.net/book"; and version="2"
- <function> contains <keyword> elements with a type attribute, not
<function> elements
(At the moment python3-sphinxcontrib.devhelp seems to assume that the
version attribute of the <book> is meant to be the version of the
software being documented, for example version="3.1.2" for python-mpd2;
but if you look at a devhelp index generated by gtk-doc or gi-docgen,
which are the de facto standard implementations, you'll see that the
version attribute is always 2.)
An implementation of this has been proposed upstream in
<https://github.com/sphinx-doc/sphinxcontrib-devhelp/pull/38>.
Thanks,
smcv
