GNOME Bugzilla – Bug 326113
Switch to gnome-doc-utils for the documentation
Last modified: 2006-02-21 10:52:29 UTC
It'd be great to switch to gnome-doc-utils to handle the documentation. It would really help translators. Right now, someone sent a french translation for the doc and it's hard to verify that the translation is okay. See http://live.gnome.org/GnomeDocUtilsMigrationHowTo I can help if you need some help.
copy myself, the migration to docutils could start after documentation was updated (bug 314001).
Created attachment 59642 [details] [review] An initial patch I still have to finish to test it, a lot of images are missing in Makefile.am, and maybe some xml files could be removed, but it seems to work
Created attachment 59643 [details] the omf.in file to add in rhythmbox/help/ directory
Ported to gnome-doc-utils on HEAD. Vincent, could you please notify this to gnome-i18n@gnome.org and gnome-doc-list@gnome.org (are you subscribed, aren't you?) There are two issues: * the manual's description is not showed while browsing with Yelp in Application->Multimedia section. * some figures are not showed I think it's related to some missing or "malformed-but-valid" contents in <articleinfo> section of rhythmbox.xml. For example, running `make` in help/, you will see this output: db2omf: Missing abstract element with role description but this element is here now :-| Moreover please note that history info are missing. About figures, it seems the some are inside <figure><mediaobject><imageobject><imagedata>, some inside <figure><screenshot><graphic>, some inside <figure><screenshot><mediaobject><imageobject><imagedata>. What's the right one? I will checkout the GDL templates from CVS.
Hello Luca, I'm the personn who did the update of the documentation, I'm not a documentation guru (It was my first doc) but I can look a it <figure> markup inconsitency if you want. I'll be happy you to help me to correct any errors. my nick is crevette on IRC
Give me a day or two to check the <articleinfo> stuff. Meanwhile please note that GDP suggests to use this[1], but after my commit I can see only figures with id "fig-iradio" and "fig-notification-zone" that are using <figure><screenshot><graphic> This is stange. [1] http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/ar01s03.html#screenshots PS sorry, I never used IRC
Doh! It seems that I was reading the wrong file in Yelp. Now it seems that all figures are showed. Of course switch to the way suggested by GDP is still a tast to perform :-) PS unfortunately "db2omf: Missing abstract element with role description" is still here :-(
OK, I found it. 1. You have to place the <abstract role="description"> element inside <articleinfo> 2. You have to list <revisions> in <revhistory> putting the more recent as last, or the OMF file will have wrong data.
Created attachment 59759 [details] [review] Tha patch to close this bug, really Here are the changes listed in my previous commit, plus some changes to manual: * remove unused entities[1] * use entities for appversion, manversion and appname as suggested in GDP templage * put <abstract role="description"> inside </articleinfo> * add <revhistory> * remove <application> from section titles * remove <sect2> in introduction, and put text directly in <sec1> * cosmetic changes to <sect1 id=introduction> (alignment, indent [2 chars]...) * use 2.0.1 as manrevison (2 means GNOME2, if I remember well) Please try, I'll commit if it's OK. [1] — trick too. There are warnings at compile time, but no issue on help viewing
For &mdash I set the entity to remove a warning in xmllint, I don't know it is "authorized" or not to use such trick. :)
Patch committed. I think we can close this bug :-)
I close it regarding last comment