GNOME Bugzilla – Bug 369550
[docs] Use gnome-doc-utils for the user manual
Last modified: 2006-12-27 20:04:22 UTC
To help the docs team work with the user guide, please set up the manual with gnome-doc-utils. There is currently no content, so you might as well start from scratch rather than migrate.
*** This bug has been marked as a duplicate of 369538 ***
This one's about glchess, and bug 369538 is for Sudoku.
Could you maybe unduplicate this? For Sudoko, as there's already a manual, it's a 'would be nice'. For GLChess, no work can be done on the manual until this is done.
Would it be possible to get some help from the GDP to use gnome-doc-utils? Since glChess does not have any existing documentation, it would be possible to use some kind of template for new projects starting from scratch with gnome-doc-utils. Yes, I have read http://live.gnome.org/GnomeDocUtilsMigration Does it contain all steps required for *new* projects?
I've mentioned this to Don Scorgie on IRC, so he should be along soon. :) I've just added a template for an application manual to gnome-doc-utils, data/templates/gnome-app-template.xml.
Don has added these instructions to the wiki: http://live.gnome.org/GnomeDocUtilsCreateNew
I'm not able to migrate glchess to gnome-doc-utils. I get this error message: make[1]: Circular C/glchess <- C/glchess dependency dropped. make[1]: *** No rule to make target `.xml', needed by `C/glchess'. Stop. Could I get some help migrating glchess to gnome-doc-utils?
Created attachment 78048 [details] [review] gnome-doc-utils patch Here's the patch I tried so far, which failed miserably.
Try adding 'help/C/glchess.xml' first.
Couple of questions / comments on the patch: * You seem to be missing help/glchess.omf.in (although, this is probably due to CVS stupidity rather than anything else) * No --disable-scrollkeeper in DISTCHECK_CONFIGURE_FLAGS in the top-level Makefile.am (minor issue) * You're glchess.xml in CVS is missing some fields required to generate the omf. See http://live.gnome.org/GnomeDocUtilsMigrationHowTo Step 4 for a list of fields that are needed (also look into other manuals for where / how to add them) I'm not sure exactly why you're getting circular dependancies though. Possibly because of the omf issue, but I don't think so. I'll have a look through soon.
I have tried all suggestions from Don. So unless someone submits a patch for gnome-games to use gnome-doc-utils, it will not happen.
Still no luck with migrating to gnome-doc-utils. Perhaps it's not possible to migrate to gnome-doc-utils for only one game (glchess), when the existing games still use the old setup.
Created attachment 78874 [details] [review] Use g-d-u for glchess documentation It sure is. I've made use of your patch and created a change which makes it work for me: if nobody complains, I'll commit it.
Thanks for making gnome-doc-utils work with glChess, you can commit the patch if you are confident that it is correct and that gnome-games passes the 'make distcheck' tests. If you are interested in helping with migrating the rest of gnome-games to g-d-u, that would also be very much appreciated.
Thanks Danilo :) What did you do differently, and did the instructions on http://live.gnome.org/GnomeDocUtilsCreateNew miss this?
The important thing was "xmllint --valid glchess/help/C/glchess.xml" which showed me that XML file was completely broken (which is why "make distcheck" didn't pass even with the above patch). I don't think there was any other difference, I just added missing bits from Andreas' last patch. Committed my last patch along with fixes for glchess.xml.
Danilo, now I get the following error message when running ./autogen.sh on gnome-games, Could you please correct this error as soon as possible? Running intltoolize... Running aclocal-1.9... Running autoconf... Running autoheader... Running automake-1.9... cp: cannot stat `INSTALL': No such file or directory automake-1.9: cannot open < gnome-doc-utils.make: No such file or directory
Andreas, what version of gnome-autogen.sh (from gnome-common module in Gnome CVS) do you have? And what version of gnome-doc-utils?
IOW, gnome-autogen.sh should run gnome-doc-prepare for you, which should copy gnome-doc-utils.make over.
Oh boy, with so much branch changes and going left and right, configure.in changes ended up not being committed. Hopefully fixed now.
Yes, it is fixed now. Thanks for the quick fix!
Now I get another error when running 'make install' in the glchess directory: /bin/sh ../../mkinstalldirs /usr/local/share/gnome/help/glchess/C /usr/bin/install -c -m 644 C/legal.xml /usr/local/share/gnome/help/glchess/C/legal.xml /usr/bin/install -c -m 644 C/glchess.xml /usr/local/share/gnome/help/glchess/C/glchess.xml /bin/sh ../../mkinstalldirs /usr/local/share/omf/glchess /usr/bin/install -c -m 644 glchess-C.omf /usr/local/share/omf/glchess/glchess-C.omf /usr/bin/install: cannot stat `glchess-C.omf': No such file or directory
This is using version: gnome-doc-prepare (GNU gnome-doc-utils) 0.8.0
This has now been fixed in CVS, by adding some missing XML elements to the docs.
Here's another compilation error when running 'make distcheck': Danilo, could you please try running 'make distcheck' again? mkdir -p -- /home/rosdal/gnome/gnome-games/gnome-games-2.17.4.1/_inst/share/omf/glchess /usr/bin/install -c -m 644 glchess-C.omf /home/rosdal/gnome/gnome-games/gnome-games-2.17.4.1/_inst/share/omf/glchess/glchess-C.omf scrollkeeper-update -p /var/lib/scrollkeeper -o /home/rosdal/gnome/gnome-games/gnome-games-2.17.4.1/_inst/share/omf/glchess /var/lib/scrollkeeper/scrollkeeper_docs: Ikke tilgang make[4]: *** [install-doc-omf] Error 1 make[4]: Leaving directory `/home/rosdal/gnome/gnome-games/gnome-games-2.17.4.1/_build/glchess/help' make[3]: *** [install-am] Error 2 make[3]: Leaving directory `/home/rosdal/gnome/gnome-games/gnome-games-2.17.4.1/_build/glchess/help' make[2]: *** [install-recursive] Error 1 make[2]: Leaving directory `/home/rosdal/gnome/gnome-games/gnome-games-2.17.4.1/_build/glchess' make[1]: *** [install-recursive] Error 1 make[1]: Leaving directory `/home/rosdal/gnome/gnome-games/gnome-games-2.17.4.1/_build'
Running 'make distcheck' as root solves the problem. If I recall correctly, distcheck didn't require root access before this patch, though...
Andreas, this is a problem with scrollkeeper: see bug #354357 for details. Now, I am not sure we need to test omf file installation in distcheck. Shaun?