Re: setting-up.txt, Makefiles

[Malcolm Tredinnick <malcolm commsecure com au>]

On Tue, 2003-11-18 at 16:54, Aaron Weber wrote:
> Currently distributed docs for gtkdoc say to copy the content of
> "examples/configure.in" into your own configure.in file.  
> 
> However, the configure.in and other example files are not shipped with
> the gtkdoc packages (at least, not with mine on SuSe 8.2).
> 
> What should get put into one's configure.in and Makefiles, and where
> should we locate that content?

The examples/configure.in is not really relevant any longer. Instead,
the project's configure.in file should use the GTK_DOC_CHECK macro. So,
typically, it will say GTK_DOC_CHECK(1.0) or something like that in
configure.in. Of course, there are examples of projects around that do
not currently do this. This is because there is no red alert-style
emergency situation to upgrade from what they previously had that was
working. Over time, hopefully, most core modules will upgrade to the
more maintainable GTK_DOC_CHECK macro, but I wouldn't be holding my
breath.

If you really wanted to ship a sample Makefile.am file, then again, the
one in examples/ is old and crufty and should not be the example: it
assumes SGML format for the documentation (not recommended), it is
pretty much unmaintianable, since if any bug is found the bug fix will
never filter down to the people who have just cut and pasted that file,
etc. The currently recommended way to start the gtk-doc related
Makefile.am is to copy something like the doc/Makefile.am in libglade,
or for more advanced usage, gtk+/docs/reference/gtk/Makefile.am.

If you were to ship such a Makefile.am, I would mark it as DATA and
install it in the documentation directory for the package. But the
documentation should at least include a small example (it is not very
long, since the bulk of the Makefile is included from elsewhere).

Hopefully, as part of getting the documentation organised, you can
submit a patch to clean up the examples directory in gtk-doc. :-)

Cheers,
Malcolm