GNOME Bugzilla – Bug 636318
Please make meld manual translatable by gnome-doc-utils
Last modified: 2014-01-11 09:18:29 UTC
Created attachment 175730 [details] Changed files for the Meld manual Hi, a long time ago I've committed a German translation of the meld manual. Unfortunately, my translation isn't considered yet by the gnome-doc-utils, and status tracking in the "Damned Lies" pages [1] is also impossible. Due to Meld is pure Python and doesn't use the autotools really, it could be a bit difficult to setup this. I have edited some of the needed files. Tarball is attached. The file /help/C/meld.xml has changed, and there are two new files too. Please remove the old OMF files and any translated XML files in the language-related subfolders. The file Makefile.am has to be renamed likely to Makefile, and some changes are needed. For an example for a working gnome-doc-utils stack in a Python application, have a look at the kupfer module [2]. For general explanations about gnome-doc-utils work, see [3]. [1] http://l10n.gnome.org/module/meld/ [2] http://git.gnome.org/browse/kupfer/ [3] http://library.gnome.org/devel/gnome-doc-make/0.20/
BTW, once it works, I could migrate the manual to the Mallard format, which is the recommended format for all newly to be written GNOME user documentation. It has to be updated anyway, this I could also do. There's no license defined yet for the manual. That's good, because the GNOME Documentation Project suggests to use a CreativeCommons License CC-BY-SA v3.0.
I haven't really had a chance to figure out how this might work. The lack of a build system for this kind of stuff in Meld really is a problem; it's just not something that a decision has been made on. I *am* sorry that this is holding up translations and the like, and I hope to get time to look at it. On the Mallard front, I think it's likely that Meld's documentation should be basically rewritten from scratch for the new style/format. However, I don't know when we'll migrate, due to Meld's somewhat conservative version requirements. It's possible that we could migrate our documentation to Mallard, and if the installed Yelp/whatever couldn't handle it, we'd forward to web-based documentation. This would also go well with setting up a new website for Meld.
»and if the installed Yelp/whatever couldn't handle it, we'd forward to web-based documentation. This would also go well with setting up a new website...« Web-based docs are provided almost automatically for GNOME documentation. Assuming the appropriate module is included in one of the JHBuild modulesets, the manuals from the tarballs are automatically parsed and converted to HTML. The output gets into the GNOME Documentation Library [1]. Then you can embed these pages into Meld's website or link to them. For the time being, we should concentrate the effort to make Meld's manual translatable anyway. Doesn't matter if in DocBook or Mallard. According to my experience, some more people take notice of it once it is translatable. [1] http://library.gnome.org/
Automatic generation of documentation would be great, but as far as I know, Meld isn't in any of the jhbuild modulesets. I agree that fixing the translation of the manual is important, but that more-or-less equates to fixing Meld's build system. As I said, I hope to get time to look at the options here and make a decision regarding autotools/distutils/waf/etc. Regarding your last point, I'm concerned that fixing translation of the manual will be taken as a sign that it should be translated, whereas it seems likely that our help should be rewritten in a completely different style in the near future.
If you decide to use Waf, you could perhaps reuse the build stack from Kupfer, as mentioned in my first message. I know that the maintainer of Kupfer had heavy problems with implementing the gnome-doc-utils, but he found a solution for. In my mind, Waf seems to be the easiest way, compared with Autotools.
*** Bug 446157 has been marked as a duplicate of this bug. ***
*** Bug 605440 has been marked as a duplicate of this bug. ***
Created attachment 190185 [details] Autotooled Meld I'm attaching a release tarball (except not really; this isn't actually Meld 1.5.2, it's just current git with patches) of Meld with autotools support, including support for gnome-doc-utils. I've also patched so that we actually launch translated help docs. I should emphasise that I don't think that additional translation of the manual is a good idea at the moment. A rewrite with the move to Mallard-style docs is warranted, and wasted translation effort is bad. However, that doesn't mean we shouldn't use what we currently have. I'm sure I've made several mistakes with both autotools and gnome-doc-utils at this point, so testing of both installed and uninstalled use of Meld would be fantastic.
Just tested the tarball. First I installed in /usr/local, but the needed meld modules were not found. After installing it under /usr, it works fine. The program works as expected, and the translated help files are created and shown in Yelp. Now it would be time to rewrite the manual based on Mallard. Perhaps we could also think about to throw gnome-doc-utils away (yes, really!) and use yelp-tools instead. This has some advantages, especially regarding l10n for the docs. Our good old xml2po (part of g-d-u) has almost reached the end of its lifetime and well be replaced step-by-step by itstool (part of yelp-tools) from GNOME 3.2 on. The first manual which will use itstool is gnome-user-docs [1]. Have a look at it to get an impression. In any case, I would prevent the i18n team from presenting the current meld manual in the status pages for the time being. No translator should waste his time with translating a deprecated manual. Claude Paroz (i18n team) is in the CC list anyway. [1] http://git.gnome.org/browse/gnome-user-docs/tree/gnome-help
Just ping me (or gnome-i18n) as soon as you want translators start to work on the manual translation. It won't appear on l10n.gnome.org for the time being.
The /usr/local install should work if /usr/local/lib/python/site-packages (or whatever it decides your python package directory should be) is on the python module path. If you *do* have it on the module path and the /usr/local install still doesn't work, then that's a bug I need to fix. As for yelp-tools, yes I'd love to use them instead. However, the current Meld release series is planned to be the final GTK 2.x series. Porting to yelp-tools would seem to be a natural thing to do along with the Gnome/Gtk 3 porting?
The location that yelp-tools installs to is only supported by Yelp 3, so definitely only transition if you're targetting Gnome 3.
(In reply to comment #12) > The location that yelp-tools installs to is only supported by Yelp 3, so > definitely only transition if you're targetting Gnome 3. That's why we should use gnome-doc-utils for the time being, unless the new manual will come along with a GTK+3 based release.
The 'new' manual isn't really new anymore, but current HEAD will (i.e., should) build and install translated help files if they're found. This involves a custom reimplementation of some of the yelp-tools autotools integration for python's distutils, so it's quite likely that there are issues. In particular, if there's anything that we can do to better integrate with l10n.gnome.org, let me know. I think this means that the manual is ready for translation.
Indeed, I had to tweak our toolchain detection stuff in Damned Lies to be able to properly generate the pot file. https://git.gnome.org/browse/damned-lies/commit/?id=bac9f55e20b2b79434ded74db0cc3d788879a967 Should be ready for translation on our side now: https://l10n.gnome.org/module/meld/