missing referenced SGML file when building documentation

[andreasbaumann]

version 0.3.2

./configure --prefix=/usr --enable-gtk-doc
make

results in:

warning: failed to load external entity "../xml/tree_index.sgml"
../keybinder-docs.sgml:26: element include: XInclude error : could not load ../xml/tree_index.sgml, and no fallback was found
make[1]: *** [Makefile:730: html-build.stamp] Error 6
make[1]: Leaving directory '/build/libkeybinder3/src/keybinder-3.0-0.3.2/docs'

Where are those SGML file supposed to come from?

[ulidtko]

@andreasbaumann try running make V=1. The docs do build on my system (Ubuntu 18.04.3) from this repo master, having installed the gtk-doc-tools package.

From what I briefly tested, the whole docs/xml directory is created by a call to gtkdoc-mkdb.
That call is made from toplevel gtk-doc.make included from docs/Makefile.am here:

keybinder/docs/Makefile.am

Lines 84 to 85 in 13b4dbd

	# This includes the standard gtk-doc make rules, copied by gtkdocize.
	include $(top_srcdir)/gtk-doc.make

That gtk-doc.make isn't in the repo; as the comment suggests, it's put there somewhere during ./autogen.sh (hell I despise GNU Autotools).

Hope that helps.

[andreasbaumann]

So,

make -j <n>

with n>1 might be a problem here.. thanks :-)

[andreasbaumann]

Aha. Found it. Obviously in newer versions of gtkdoc it builds a xml/object_index.sgml
and no longer a xml/tree_index.sgml (as referenced in keybinder-docs.sgml).

So the following snippet in keybinder-docs.sgml should contain:

<title>Object Hierarchy</title> ```

Now the problem is: how can you make documentation build with different versions
of gtkdoc?

[andreasbaumann]

I should say I'm using gtk-doc 1.31 on Archlinux.

[ulidtko]

Now the problem is: how can you make documentation build with different versions of gtkdoc?

Oh geez. @andreasbaumann can you please poke the gnome people (e.g. on IRC) on what we're supposed to do in this situation?

@GNOME thanks for breaking app compat again! You're the best!..

[andreasbaumann]

Poked :-)

https://gitlab.gnome.org/GNOME/gtk/issues/2133

https://gitlab.gnome.org/GNOME/gtk-doc/issues/103

[andreasbaumann]

Have a look at their feedback in https://gitlab.gnome.org/GNOME/gtk-doc/issues/103 :

"In your case the fix is simple - in https://github.com/kupferlauncher/keybinder/blob/master/docs/keybinder-docs.sgml#L24 - just don't include files you don't need anyway. From a quick look at your sources your library is not providing gobjects - its a plain c library."