On Tue, 2006-02-28 at 14:37 +0200, Alexander Shopov wrote: > Hi guys, > > This will certainly wait for the months after the March release and > subversion migration but I *do* think that we should all press to get > the structure for the documentation of packages heavily standardized. > The maintenance of translation of documentation is several times more > time intensive for me to do than maintenance of interface translations.
Certainly. I didn't expect that we'd have a perfect solution right off the bat. But we got infrastructure in place that we can actually use. Issues will crop up, and we'll address them. So, now we have issues. Danilo and I can soon get hacking for 2.16, wherein we'll have the desktop 100% documented and have that documentation 100% translated. :) > 1. We have po* subdirectories to hold the translations. We should expect > the help to always be in help* I agree. In fact, I generally push for a two-directory layout, like so: /sound-juicer/help/sound-juicer/C/sound-juicer.xml Note the extra sound-juicer directory. This allows you to add new documents without having to move stuff around in your source tree. When we switch to subversion after 2.14, we'll be better able to change directory names. A longer-term goal is to get developer documentation also using xml2po for translations. Developer docs have traditionally been put under the "doc" or "docs" subdirectory. I think using help for user help and docs for developer docs is perfectly fine. Another related issue is what to do about ChangeLog files. With po files for interface translations, we have a single po directory, and a ChangeLog for that directory. Translators can just prepend to po/ChangeLog, and maintainers can easily check this file when compiling release notes. With documentation, we have basically four choices: 1) /module/ChangeLog 2) /module/help/ChangeLog 3) /module/help/docname/ChangeLog 4) /module/help/docname/lang/ChangeLog Choice (1) has all sorts of problems. It means we all have to do full checkouts for documentation and translations, and it increases the chance of conflicts. Choice (4) creates lots of ChangeLog files, making it hader for maintainers to track changes when compiling release notes. This will inevitably lead to credits being omitted from release notes. I consider (2) and (3) the only feasible options. When a module isn't following my recommended two-level layout, they degenerate into exactly the same thing. Translators would need to check out one directory above their language, but they'll need to do that anyway to merge new messages from the DocBook. Both the writers and the translators would put messages in the common ChangeLog for the document, and we'd train maintainers to look at that for release notes. Anybody else have different thoughts on that? > 2. The way a new language is included should be standard. I generally > could live with the configure.in/configure.ac dichotomy, but today I had > to include the translation of gcalctool - writing Makefiles.am is not > the translators task. For the documentation translations, it's currently necessary to modify the DOC_LINGUAS file in the Makefile.am of the document's top directory. I don't particularly see Makefile.am edits as any harder than configure.in edits. But then, we've already had at least case of a translation not being included because of this. One option is just to train translators on this. They already need to know how to work with xml2po instead of intltool for documentation translation. We really do try to make things as easy as possible for translators, and to let them use a single tool chain, but sometimes it's just necessary for them to learn something new. We could attempt to use the ALL_LINGUAS from configure.in, but we'll have problems. We might be able to solve those problems, but they will arise. Notably, what do you do if a language has provided interface translations but not documentation translations? Far from being uncommon, it's actually the norm right now. So do we just do the subset of ALL_LINGUAS for which there exists a po file in the appropriate language directory? That's possible, but implicit rules tend to create problem. We have at least two cases where we have implicit rules in gnome-doc-utils.make (the .omf.in and figures/*.png), and both have caused problems already. I'm open to suggestions. > 3. I do believe that the xml2po translation has begun, but we should > have it finished in all modules. Making xml2po is one thing, but then > re-merging the po to xml becomes tasking and error prone (at least for me). Danilo and I have talked about ways of doing xml2po merges and such without using make. We understand that haveing to configure a package just to do translations is a big hassle. This will get addressed for 2.16. > 4. We have got to have a way easily to check the validity of > translation. msgfmt is fine for po-files, Emacs serves me fine there, > but getting things right for the documentation is more error prone. > Partial XMl conformance is difficult even for trivial cases of > "partial", especially if you do things in your head. Sure. Currently, running 'make check' will validate all the translations (including the source) against the DTD. This is really really nice. It means distcheck will fail if people don't write correct DocBook. I've even considered doing the validation on just 'make all', but I'd want to do some sort of timestamping hackery so it doesn't constantly happen. But you want to validate the contents of your messages without having to configure and make and all that crap. And that makes perfect sense, particularly given what I said to (3). I'm not sure how well we can manage validity checks, particularly given stuff like <placeholder-$/> elements. But well-formedness checks are certainly doable. Danilo? -- Shaun _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
