GNOME Bugzilla – Bug 90689
Built documentation should be distributed.
Last modified: 2004-12-22 21:47:04 UTC
the 'dot' program used by doxygen is non-free, and therefore is not used when building debs of gtkmm. Doxygen seems to be perfectly capable of building the relevant diagrams without it, though, providing you set the HAVE_DOT variable correctly. This will do so. Index: configure.in =================================================================== RCS file: /cvs/gnome/gtkmm-root/base/configure.in,v retrieving revision 1.103 diff -u -r1.103 configure.in --- configure.in 10 Aug 2002 17:39:37 -0000 1.103 +++ configure.in 14 Aug 2002 01:00:44 -0000 @@ -179,6 +179,9 @@ # This will be much slower. GTKMM_ARG_ENABLE_FULLDOCS() +# Check for the dot program +AC_CHECK_PROG(HAVE_DOT,[dot],[YES],[NO]) + # Dummy conditional just to make automake-1.4 happy. # We need an always-false condition in docs/Makefile.am. Index: docs/reference/Doxyfile.in =================================================================== RCS file: /cvs/gnome/gtkmm-root/base/docs/reference/Doxyfile.in,v retrieving revision 1.11 diff -u -r1.11 Doxyfile.in --- docs/reference/Doxyfile.in 23 Apr 2002 15:39:05 -0000 1.11 +++ docs/reference/Doxyfile.in 14 Aug 2002 01:00:44 -0000 @@ -155,7 +155,7 @@ # Configuration options related to the dot tool #--------------------------------------------------------------------------- CLASS_DIAGRAMS = YES -HAVE_DOT = YES +HAVE_DOT = @HAVE_DOT@ CLASS_GRAPH = YES COLLABORATION_GRAPH = NO TEMPLATE_RELATIONS = NO
Dot builds _better_ diagrams. I don't want 2 versions of the same documentation. Do you expect to distribute the documentation in a deb? In a separate deb? Maybe we should just generate it as part of the whole build.
Yes, I am distributing it, in a separate deb for gtkmm (only because it's so large), and in the -dev package for the other modules. I build it with a simple 'make -C docs/reference' (and patching Doxyfile.in) I noticed that with non-dot, the diagrams are slightly less complete, but I think distributing reference docs is important, and would not want to put them into "non-free" or "contrib".
OK, so let's build the documentation when we build the .h/,cc files. I think that means building it when we are in maintainer mode. I don't want to distribute 2 versions of the same documentation, and I don't want to distribute crippled documentation.
I'm kind of hoping that someone provides a patch to build the documentation when the .h/.cc files are built, and to add them to make dist.
They say that it's open source: http://www.research.att.com/sw/tools/graphviz/download.html If their license isn't really OpenSource(TM) then maybe they should be persuaded to use a different license, or to get it certified.
I will see if the Stephen (maintainer of graphviz debs) has investigated that. In the meantime, springgraph looks like an excellent drop-in replacement for dot: http://www.chaosreigns.com/code/springgraph/ Here is what the ref. docs look like when springgraph is used: http://pokey.css.washington.edu/debian/gtkmm/gtkmm1.3/gtkmm1.3-1.3.24/docs/reference/html/ -brad
I seem to have been mistaken about springgraph. I can't get it to work at all, now.
Look at the ListStore page, for instance. Only dot properly combines virtual base classes.
Did you get any response from the graphviz maintainer?
Please respond.
Here's what he said: Bradley Bell wrote: > > Hi, are there any plans to move graphviz into main? It would be useful to > build the reference documentation that goes into the gtkmm debs. I need to have our legal group review the license and get a more definitive answer to AT&T. At this time we consider this to be non-free due to the licensing issues. Regards, Stephen
OK, so it looks like it's still best to distribute the built documentation. And we need a patch for that.
I'll see what I can do.
Here is a patch to do this, but: 1) I am concerned that it more than doubles the size of the tarball - to almost 5Mb. 2) The reference docs are not rebuilt unless you do a manual "make clean all" in docs/reference. I'd like the reference docs to rebuild always when in "maintainer mode".
Created attachment 12087 [details] [review] gtkmm_dist_docs.patch
Created attachment 12097 [details] [review] gtkmm_dist_docs2.patch - revised for cvs changes
Then again, GTK+ does the same thing and is 8Mb. Applied.