g-ir-doc-tool can produce invalid XML
In GIMP, we have some function docs with XML tag-like syntax:
* Menu paths are untranslated paths to menus and submenus with the
* syntax `<Prefix>/Path/To/Submenu`, for example `<Image>/Layer/Transform`
It's not XML of course, it's just our internal syntax for menus, as it has been for dozens of years (so we can't change this, and we need to document/tell people that's what they need to write for our API to know where your custom menu item should go).
Unfortunately, g-ir-doc-tool
(which we use as an intermediate step to generate Python and gjs HTML docs with yelp-build) simply copies this as-is, i.e. that it creates invalid XML in its resulting .page
file:
<title>Gimp.Procedure.add_menu_path</title>
<synopsis><code mime="text/x-python">
@accepts(Gimp.Procedure, unicode)
@returns(none)
def add_menu_path(self, menu_path):
# Python wrapper for gimp_procedure_add_menu_path()
</code></synopsis>
<p>Adds a menu path to the procedure. Only procedures which have a menu
label can add a menu path.</p> <p>Menu paths are untranslated paths to menus and submenus with the
syntax `<Prefix>/Path/To/Submenu`, for example `<Image>/Layer/Transform`</p> <p>See also: <link xref="Gimp.PlugIn.add_menu_branch"/>.</p>
<p>Since 3.0</p>
Therefore, when further processed, our build breaks.
Note that we could use an entity (<
), and that's what we used to have here actually, but we recently moved from gtk-doc
to g-ir-docgen
as this is apparently the new recommended tool for API documentation generation, and this tool uses more of a markdown-style format and doesn't require the <
to be an XML entity. Of course, the g-ir-docgen
is the main C API doc, so we prefer to favor it, but we would still like to continue generating a Python and JS API doc, i.e. with gir-doc-tool
/yelp-build
.
My workaround right now is to add an ugly intermediate step to search-and-replace the broken XML (fortunately we only have few) and fix it before processing it. But it would be nice that g-ir-doc-tool
would just replace any <
into an entity (and other similar character which could break the output) and therefore not produce broken XML. ;-)