GNOME Bugzilla – Bug 335239
Using gnome-doc-utils for gtk-doc documentation
Last modified: 2008-06-07 12:38:39 UTC
The gtk-doc documentation is currently unavailable as an online reference and only available as part of the gtk-doc source tarball. The developer community would appreciate it if the documentation is made available online in several formats. A link to a tarball that contains HTML and CHM (Compiled HTML) documentation generated from the original source tarball using xsltproc and docbook follows: http://www.jamesbooker.co.uk/~jburd/gnu/gtk/gtk-doc/gtk-doc-1.5-doc.tar.gz Regards, Yesudeep.
Created attachment 61669 [details] gtk-doc documentation in html and chm formats
IMHO, the way to go should be generate the documentation to be used by devhelp. It can be done with something like: $ xsltproc --nonet --xinclude --stringparam gtkdoc.bookname gtk-doc \ --stringparam gtkdoc.version "1.6" --output html/ \ $(top_dir)/devhelp2.xsl gtk-doc-manual.xml or something like that.
This is two fold: 1) distributor does not package it. Please file bugs against distributions. 2) it should be in library.gnome.org for the future.
Yesudeep, what do you expect from the gtk-doc project in this regard? German, gtk-doc in fact generates the docs that are used by devhelp. I will close this as NOTABUG in about two weeks, unless someone clarifies the intention of this report.
IMO the intention is clear and good: to have the gtk-doc manual available on-line alongside with other Gtk+/Gnome API references, whitepapers and books, i.e. reachable from http://developer.gnome.org/doc/ and http://gtk.org/gtk-doc/ (or wherever these are going to end up in the future). If you and Damon cannot arrange this, who can? Granted, there is http://developer.gnome.org/arch/doc/authors.html but this seems to be an old document, updated by no one for a long time.
Well this is a job for the web-site maintainers, it has nothing to do with gtk-doc itself. I will move the bug to the website project.
Moving to the library.gnome.org component.
As written on gnome-web-list@, gtk-doc will automatically be picked up if moved to gnome-doc-utils, reassigning to gtk-doc :)
And here is how to do it: http://live.gnome.org/GnomeDocUtilsTranslationMigration
Erm. Its http://live.gnome.org/GnomeDocUtilsMigrationHowTo
Created attachment 93687 [details] [review] gtk-doc migration Stefan, you can test it :) Once it is applied, we have to "Let gnome-i18n@gnome.org and gnome-doc-list@gnome.org know about it!"
btw make check fails on my ubuntu, with xmllint --noout --noent --path C:./C --xinclude --postvalid ./C/gtk-doc-manual.xml xmllint --noout --dtdvalid 'http://scrollkeeper.sourceforge.net/dtds/scrollkeeper-omf-1.0/scrollkeeper-omf.dtd' gtk-doc-manual-C.omf /bin/bash: line 1: 31959 Segmentation fault (core dumped) xmllint --noout --noent --path "$xmlpath" --xinclude --postvalid "$d$lc/gtk-doc-manual.xml" Can you do also a make check?
Could you remake the patch ? $ patch --dry-run <0001-gtk-doc-migration.patch patching file .cvsignore patching file Makefile.am Hunk #1 succeeded at 74 (offset 2 lines). patching file autogen.sh patching file configure.in Hunk #2 succeeded at 139 (offset 3 lines). patching file .cvsignore Hunk #1 succeeded at 1 with fuzz 2. patching file ChangeLog Reversed (or previously applied) patch detected! Assume -R? [n] n Apply anyway? [n] n Skipping patch. 1 out of 1 hunk ignored -- saving rejects to file ChangeLog.rej patching file Makefile.am Reversed (or previously applied) patch detected! Assume -R? [n] n Apply anyway? [n] n Skipping patch. 1 out of 1 hunk ignored -- saving rejects to file Makefile.am.rej The next patch would delete the file gtk-doc-manual-C.omf.in, which does not exist! Assume -R? [n] n Apply anyway? [n] n Skipping patch. 1 out of 1 hunk ignored can't find file to patch at input line 280 Perhaps you should have used the -p or --strip option? The text leading up to this was: -------------------------- |diff --git a/help/manual/C/gtk-doc-manual.xml b/help/manual/C/gtk-doc-manual.xml |index 33e84ac..915c442 100644 |--- a/help/manual/C/gtk-doc-manual.xml |+++ b/help/manual/C/gtk-doc-manual.xml -------------------------- File to patch: Skip this patch? [y] y Skipping patch. 3 out of 3 hunks ignored The next patch would create the file ChangeLog, which already exists! Assume -R? [n] n Apply anyway? [n] n Skipping patch. 1 out of 1 hunk ignored -- saving rejects to file ChangeLog.rej patching file Makefile.am Hunk #1 FAILED at 1. 1 out of 1 hunk FAILED -- saving rejects to file Makefile.am.rej patching file gtk-doc-manual.omf.in The next patch would create the file .cvsignore, which already exists! Assume -R? [n] n Apply anyway? [n] n Skipping patch. 1 out of 1 hunk ignored -- saving rejects to file .cvsignore.rej
Created attachment 93804 [details] [review] [PATCH] gtk-doc migration .svnignore | 26 ++++++++ Makefile.am | 6 ++- autogen.sh | 6 ++ configure.in | 5 +- help/manual/.svnignore | 4 + help/manual/C/ChangeLog | 102 ------------------------------- help/manual/C/Makefile.am | 17 ----- help/manual/C/gtk-doc-manual-C.omf.in | 34 ----------- help/manual/C/gtk-doc-manual.xml | 13 ++++- help/manual/ChangeLog | 106 +++++++++++++++++++++++++++++++++ help/manual/Makefile.am | 10 ++- help/manual/gtk-doc-manual.omf.in | 15 +++++ m4/.svnignore | 1 + 13 files changed, 185 insertions(+), 160 deletions(-)
This looks better now. I still got there failed merges: ./.svnignore.rej ./ChangeLog.rej make sure you add the comment when commiting ./Makefile.am.rej this was tried in basedir and not in help/manual running ./autogen.sh gives a warning still. /usr/bin/gnome-doc-prepare You should update your 'aclocal.m4' by running aclocal. Putting files in AC_CONFIG_MACRO_DIR, 'm4'. cd: 310: can't cd to m4 After I did mkdir 'm4' in toplevel that worked. I can cofirm the crash though: cd help/manual gdb --args xmllint --noout --noent --path C:../../../help/manual/C --xinclude --postvalid ../../../help/manual/C/gtk-doc-manual.xml Program received signal SIGSEGV, Segmentation fault. 0x08051059 in xmllintExternalEntityLoader (URL=0x0, ID=0x806a930 "-//OASIS//DTD DocBook XML V4.1.2//EN", ctxt=0x8060288) at xmllint.c:256 256 xmllint.c: No such file or directory. in xmllint.c (gdb) bt
+ Trace 155843
The crasher seems to be ubuntu related. I filed it as: https://bugs.launchpad.net/ubuntu/+source/libxml2/+bug/133981 As a workaround you can remove --path options in gnome-doc-utils.make. The patch itself looks good now.
*** Bug 503712 has been marked as a duplicate of this bug. ***
If switching to d-g-u, can also scrap the older-system's build tools (omf.make and xmldocs.make) and remove the existing scrollkeeper tests from configure.in (SCROLLKEEPER_BUILD_REQUIRED has actually never been used for anything!).
Created attachment 103287 [details] [review] [1/1] gtk-doc migration Makefile.am | 7 ++- autogen.sh | 10 +++ configure.in | 8 +-- help/manual/C/ChangeLog | 102 --------------------------------- help/manual/C/Makefile.am | 17 ------ help/manual/C/gtk-doc-manual-C.omf.in | 34 ----------- help/manual/C/gtk-doc-manual.xml | 13 ++++- help/manual/Makefile.am | 10 ++- omf.make | 61 -------------------- xmldocs.make | 101 -------------------------------- 10 files changed, 37 insertions(+), 326 deletions(-)
(In reply to comment #18) > If switching to d-g-u, can also scrap the older-system's build tools (omf.make > and xmldocs.make) and remove the existing scrollkeeper tests from configure.in > (SCROLLKEEPER_BUILD_REQUIRED has actually never been used for anything!). The latest patch clean those files. Regarding the circular dependency in jhbuild, the solution is to get rid of the AM_GLIB_GETTEXT macro in configure.in of gnome-doc-utils: see bug 510915. Once this bug is fixed, I guess, I can apply the patch. Adding 510915 as a dep.
(btw, xmllint does not crash anymore on gutsy)
Created attachment 103288 [details] [review] [1/1] gtk-doc migration .svnignore | 26 ++++++++ Makefile.am | 7 ++- autogen.sh | 10 +++ configure.in | 8 +-- help/manual/.svnignore | 4 + help/manual/C/ChangeLog | 102 ------------------------------- help/manual/C/Makefile.am | 17 ----- help/manual/C/gtk-doc-manual-C.omf.in | 34 ----------- help/manual/C/gtk-doc-manual.xml | 22 +++++++- help/manual/ChangeLog | 106 +++++++++++++++++++++++++++++++++ help/manual/Makefile.am | 10 ++- help/manual/gtk-doc-manual.omf.in | 15 +++++ m4/.svnignore | 1 + omf.make | 61 ------------------- xmldocs.make | 101 ------------------------------- 15 files changed, 198 insertions(+), 326 deletions(-)
Stefan, I'd suggest you to do the post release, and then I can apply this patch (I just have to type git-svn dcommit :) I am just annoyed by the distcheck which is release not working on my system (might be the -j2, not because of this patch) if you are fine, I can also bump version number as you did during 1.10. what do you think, I really would like to see gtk-doc in library.gnome.org.
ok Stefan, I did not receive mail about about patch review, because bugz was dead yesteray, but I just comitted it. Hopefully, it won't break anything :)
Hi all, We (Gentoo) are currently hitting a bug that was fixed by Marc-André's patch. Is there an ETA for a new release? Thanks PS, sorry for the bug spam, gtk-doc ML seems kind of dead
Remi, the lists is alive, but noone is posting there and as I am the only active develoeprs there right now its not so useful. Regarding a release I have no date planned yet. There are a few things that I want to get done for 1.11 - I am also not sure how much it is already tested. So will be at least a month from now one.