GNOME Bugzilla – Bug 673984
Glibmm html docs refer to a wrong css file in the released source tarballs
Last modified: 2012-10-03 15:20:04 UTC
The html docs in the released source tarball for glibmm[1] include to [2] whereas the correct location is just 'doxygen.css'. [1] http://ftp.gnome.org/pub/GNOME/sources/glibmm/2.32/glibmm-2.32.0.tar.xz [2] /home/murrayc/checkouts/gnome30/glibmm/docs/doxygen.css
Yes, I see that too. Does this happen when you build it? What version of doxygen do you have? (Note that doxygen --version is not always accurate.)
I don't get similar issues when building myself. I use Doxygen 1.7.6.1 (1.7.6.1-2ubuntu1 to be precise).
See doxygen bug 658218. Glibmm is perhaps the only mm module that is affected by this bug, because it's perhaps the only mm module that has a correct entry for HTML_STYLESHEET in docs/reference/Doxygen.in. -- Glibmm Doxygen.in: HTML_STYLESHEET = "@abs_top_srcdir@/docs/doxygen.css" Doxygen: HTML_STYLESHEET = "/home/kjell/checkout/gnome/glibmm/docs/doxygen.css" doxygen.log: No warning about doxygen.css docs/doxygen.css is copied to docs/reference/html/doxygen.css. html files: <link href="/home/kjell/checkout/gnome/glibmm/docs/doxygen.css" rel="stylesheet" type="text/css" /> -- Gtkmm Doxygen.in: HTML_STYLESHEET = "@MMDOCTOOLDIR@/doxygen.css" Doxygen: HTML_STYLESHEET = "${top_srcdir}/docs/doxygen.css" doxygen.log: Style sheet '${top_srcdir}/docs/doxygen.css' specified by HTML_STYLESHEET does not exist! A default doxygen.css (not gtkmm/docs/doxygen.css) is copied to docs/reference/html/doxygen.css. html files: <link href="doxygen.css" rel="stylesheet" type="text/css" /> The HTML_STYLESHEET entry in gtkmm/docs/reference/Doxygen.in and in many other Doxygen.in files may have been copied from mm-common/skeletonmm/doc/reference/ Doxygen.in. It would be possible to "fix" this doxygen bug by inserting some extra code in mm-common/util/doc-postprocess.pl, but it would be a bad "solution". It's much better to have the doxygen bug fixed in doxygen.
The filenames Doxygen.in and Doxygen in comment 3 should have been Doxyfile.in and Doxyfile. Doxygen bug 658218 is a duplicate of Doxygen bug 646319, even though it's not marked as such. Bug 646319 is said to be fixed in Doxygen 1.8.0, released 2012-02-25. I haven't checked if it really is fixed. I hope I'll soon get a newer version of Doxygen than 1.7.6.1 via Ubuntu's automatic update. It's not worth the trouble to install a new Doxygen version from source code. What shall we do with the erroneous Doxyfile.in files? I can change some of them. I can change mm-common/skeletonmm/doc/reference/Doxyfile.in now, but perhaps it's wise to wait half a year or so with the other ones. As long as people use erroneous versions of Doxygen, an erroneous version of Doxyfile.in (where Doxygen doesn't understand the HTML_STYLESHEET entry in Doxyfile) actually results in better html files. What's wrong with HTML_STYLESHEET = "@MMDOCTOOLDIR@/doxygen.css" in Doxyfile.in? Two things. In Doxyfile it's replaced by HTML_STYLESHEET = "${top_srcdir}/docs/doxygen.css" 1. Doxygen does not understand ${top_srcdir}. It does understand $(top_srcdir) which would be acceptable also in Makefile. 2. Make does not export top_srcdir to Doxygen. If Doxyfile contains "$(top_srcdir)/docs/doxygen.css", Doxygen interprets it as "/docs/doxygen.css". From the GNU make documentation: "Except by explicit request, make exports a variable only if it is either defined in the environment initially or set on the command line." There are at least three reasonable solutions. 1. Do as in glibmm. In Doxyfile.in HTML_STYLESHEET = "@abs_top_srcdir@/docs/doxygen.css" A drawback is that the directory name "docs" must be included in Doxyfile.in. This directory name is not the same in all modules ("docs" or "doc"), and is specified in configure.ac, MM_CONFIG_DOCTOOL_DIR([docs]) Ideally it should not be necessary to specify it in more locations than absolutely necessary. 2. Similar to alternative 1, but in Doxyfile.in HTML_STYLESHEET = "@abs_srcdir@/../doxygen.css" "/.." is necessary because doxygen.css is located one level above Doxyfile.in and Doxyfile. 3. In Doxyfile.in HTML_STYLESHEET = "$(MMDOCTOOLDIR)/doxygen.css" which is left unmodified in Doxyfile. In doc-reference.am, where Doxygen is called $(AM_V_GEN)(echo '@INCLUDE =' $(doc_config) && echo 'INPUT =' $(doc_input)) | MMDOCTOOLDIR="$(MMDOCTOOLDIR)" "$(DOXYGEN)" - MMDOCTOOLDIR="$(MMDOCTOOLDIR)" has been added. MMDOCTOOLDIR is then exported to Doxygen.
Now I've studied the MM_CONFIG_DOCTOOL_DIR m4 macro more closely, and noticed that if it's not used in configure.ac or is used without a parameter, then MMDOCTOOLDIR=`$PKG_CONFIG --variable=doctooldir mm-common-util` which may e.g. result in MMDOCTOOLDIR=/usr/share/mm-common/doctool I recommend alternative 3 in comment 4. It's the only alternative that suits both modules with and without MM_CONFIG_DOCTOOL_DIR([docs]) in configure.ac.
Thanks. That sounds OK, though I'm a little confused. Can I see a patch? Note that we can fix configure.ac files if necessary.
Created attachment 219465 [details] [review] patch: Use $(MMDOCTOOLDIR) instead of @MMDOCTOOLDIR@ in Doxyfile.in (mm-common) Here's a patch for mm-common. @MMDOCTOOLDIR@ should also be replaced by $(MMDOCTOOLDIR) in Doxyfile.in in a number of modules. I don't know if any configure.ac shall be modified. I don't know if MM_CONFIG_DOCTOOL_DIR is missing by design or by mistake in e.g. grilomm.
(In reply to comment #7) > I don't know if any configure.ac shall be modified. Well, I trust you to do what's correct. Please go ahead. > I don't know if > MM_CONFIG_DOCTOOL_DIR is missing by design or by mistake in e.g. grilomm. grilomm is very new (and by me) and just based on the skeletonmm project in mm-common.
I've pushed a modified patch to mm-common. It also adds MM_CONFIG_DOCTOOL_DIR([doc]) to skeletonmm/configure.ac. MM_CONFIG_DOCTOOL_DIR([doc]) or MM_CONFIG_DOCTOOL_DIR([docs]) was added to configure.ac in many modules in March 2011, but it was not added to mm-common/ skeletonmm/configure.ac. An oversight, I suppose. What remains now is to add MM_CONFIG_DOCTOOL_DIR([doc]) to grilomm/configure.ac and to replace @MMDOCTOOLDIR@ by $(MMDOCTOOLDIR) in a number of Doxyfile.in files. As I said in comment 4, I think we'd better wait with that until most people are likely to use Doxygen version 1.8.0 or later. - Correct Doxygen (1.8.0 or later), $(MMDOCTOOLDIR) in Doxyfile.in, MM_CONFIG_DOCTOOL_DIR([doc(s)]) in configure.ac: Doxygen copies doc(s)/doxygen.css to doc(s)/reference/html/doxygen.css, and inserts correct links to it in the .html files. The .html files look good in a web browser (Firefox). (Well, I haven't actually tested it with Doxygen 1.8.0, but I'm sure this is how it will work.) - Erroneous or correct Doxygen, @MMDOCTOOLDIR@ in Doxyfile.in, MM_CONFIG_DOCTOOL_DIR([doc(s)]) in configure.ac: Doxygen copies its default doxygen.css to doc(s)/reference/html/doxygen.css, and inserts correct links to it. The .html files look good in Firefox. Differs from the previous case, but still good. - Erroneous Doxygen (e.g. 1.7.6.1), $(MMDOCTOOLDIR) in Doxyfile.in, MM_CONFIG_DOCTOOL_DIR([doc(s)]) in configure.ac: Doxygen copies doc(s)/doxygen.css to doc(s)/reference/html/doxygen.css, and inserts links to doc(s)/doxygen.css, i.e. not to the copy in doc(s)/reference/html. The web browser may not find the doxygen.css file. Then the .html files look bad. It's the last of these 3 cases I think we should try to avoid. It would probably result in more bug reports. Now glibmm and libsigc++ behave more or less as in case 3, because they have a non-standard definition of HTML_STYLESHEET in Doxyfile.in. Since there is more to do, but not now, I keep this bug open.
>I think we'd better wait with that until most people > are likely to use Doxygen version 1.8.0 or later. Is that necessary? The generated html files are shipped in the release tarball, so we only need Murray or whoever builds the release tarball to have the correct version of Doxygen.
This seems to be fixed in the latest tarball: http://ftp.gnome.org/pub/GNOME/sources/glibmm/2.33/glibmm-2.33.13.tar.xz Please reopen if I am wrong.
This is fixed in the latest glibmm tarball because that tarball was generated with doxygen 1.8.1.1. The documentation in tarball glibmm 2.32.0 was badly formatted because it was generated with doxygen 1.7.6.1. This was actually no bug in glibmm, but in doxygen. In comment 9 I changed some files in mm-common/skeletonmm/. I have now copied those changes to grilomm. In order to build grilomm I first had to change many files, because grilo has been heavily changed in the last few months. The change in mm-common/skeletonmm/doc/reference/Doxyfile.in can be copied to more modules, but it's not important. It need not be copied to glibmm or libsigc++. The Doxyfile.in files in those modules are ok. In summary, I agree that this bug is fixed.