svn merge weirdness
I stumbled over a strange svn problem today, while merging the xml2po branch into TRUNK:
svn: Working copy path 'ChangeLog.pre-2-4' does not exist in repository
photo by zen Sutherland on flickr.com
I found two possible solutions in the net, but none of them seemed to work:
- “edit the “.svn/entries” file, and look for an incorrect revision=”0″ attribute, and set it to the correct value.” ( see http://www.axlrosen.net/stuff/svnproblem.html)
- “At this point, the only way I found to repair my working copy was to delete the directory containing the problematic file, check it out again [...]” (see http://svn.haxx.se/dev/archive-2006-03/0795.shtml)
I checked the ‘entries’ file, but couldn’t spot a ‘revision’ attribute at all. Solution two wouldn’t work, or I had to wipe out the whole gimp-help-2 module.
What I did now is to remove the files temporary (aprox. 10 files) and try again. I got the merge working afterwards. Although it is cumbersome, because you won’t spot the erroneus file in a dry run.
GIMP 2.6 is out …
GIMP Help Browser using webkit.
… and the Manual will be next.
The current plan is to release the last tarball of the manual suitable for the GIMP 2.4 release a.s.a.p. It should still be installed by most of the desktops until GIMP 2.6 is provided by the distributions.
We’re currently still working heavily to migrate most of the translations from DocBook/XML to po/gettext. The biggest problem for us is the missing 1:1 mapping between reference language to a translation. We’re trying to minimize the site effects when splitting the translations and using xml2po’s reuse option for a content migration. Ulf D. Ehlert wrote a Python script, which will splitt the reference language from the translation “as good as possible”.
As long this script is ready and we’re able to migrate, we’re up to speed to document GIMP 2.6.
GIMP Tips Dialog
The tips-dialog now provides a link to show more information in the user manual. Don't bother - the dialog has already been internationalized and has either only English or only German strings.
Liams Idea made it into GIMP: the tips dialog now provides a link to more information in the user manual which covers the topic displayed as a tip.
I liked the idea providing a button which links to the manual and started hacking. My first attempt used a third button in the dialog. Peter Sikking disagreed with a third button. The buttons become to prominent in the dialog and a link should be displayed. Sven helped in providing useful development information. This feature will be available in the next stable release of GIMP (2.6).
GIMP Manual Build Architecture Status
GIMP Help Browser using webkit.
We’re currently in a huge overhaul of the build system the GIMP Manual is using (see my last post).
Ulf D. Ehlert works on a custom Makefile, which can extract the strings, creates automatically pot files, as well as po files and is able to create localized DocBook/XML. He’s still working hard to improve the script. Thanks to publican – it helped to reuse some of the Makefile code the project provides to create pot and po files automatically (I still need to communicate that with the publican folks – sorry guys).
I hope we can merge his changes as soon as possible with a current xml2po branch to test it. Hopefully other developers around will help to improve the Makefile.
We’ve still performance issues. Creating the HTML pages for the translations takes ages, and it will take more when we switch to support gettext.
GIMP Manual Future Decisions
GIMP Help Browser using webkit.
Help Browser Improvements
I’m very happy about Svens changes for the next stable version of GIMP (2.6). The help browser uses now webkit to render the manual and can even now load the manual from the net if the user have an internet connection. I think that’ll make the access to our manual more easier for the most of GIMP users.
Manual switches to gettext
The user manual is written using DocBook/XML. The translation is seperated by ‘lang’ attributes. There is no reference language. Therefore the manual is written in various languages, seperated by ‘lang’ attributes.
We’re currently working hard to figure out a possible migration strategy of the current manual to gettext. Our build system need to be customized to manage the translations hold in *.po files. There are currently two possible candidates for this:
Publican provides a lot of the functionality we need to update/manage the translations. So has a very specific purpose. It uses the automake/autotool build system, we’re using as well. It is written by people at Red-Hat and can compile hundreds of manuals in the row. Ulf D. Ehlert and I elaborated a possible migration to publican and we figured a few pros and cons:
Pro:
- provides all the functionality needed to manage and build documentation using gettext
Contra:
- complete switch to Publican and be dependant from it
- feels like we won’t need most of the functionality implemented to compile all (other manuals)
WAF though is a build system written in Python. It’s ment to replace the currently widely automake/autotools toolchain, which is currently widely in use by a lot of open source projects.
Pro:
- It’s easier to understand and can better handle the complex process of building and installing our manual. I find it sometimes very cumbersome to express what the autotools/automake should do using bash expressions. I find it much easier to do this in Python or any other high level language than bash (don’t misunderstand me: bash is fine for batch processing).
Contra:
- WAF uses tools to provide configuring/building software. There seems to be no such tool available which provides the functionality to build our manual. We probably need to write our own tool. Not a problem though, but we need to do it and it will cost time.
- “Not compatible” to our GIMP/GNOME (modules) which use automake/autotools.
I will try to write a build script for our purpose using WAF and I also want to communicate more with the publican people. I think this will sort out our current “problems” choosing a system.
Well, could be, that I overlooked or misunderstood something elaborating those tools. I’m sorry if something is not correct, while I was checking.
Update: Ulf sent me already a patch based on autotools/automake, which uses a bit of the publican infrustructure. Think that points out the direction where we’re heading now 
LGM Aftermath LGM Aftermath
or: How I learned how to write documentation the hard way.
Current situation
The current situation for the GIMP user manual is this:
- The user manual is written using DocBook/XML.
- Each DocBook/XML file contains all translations separated by lang attributes.
When I joined the documentation project back in 2003, we thought, that the separation of author and translator brings unnecessary barriers:
- Authors can only write in one language (reference language)
- Translators can only translate a string given by the reference language and are enforced to do only that (translation slaves)
Our model (mixing translations with the actual documentation writing) was superior, because the classic model of translators didn’t exist anymore. Every writer was free to describe a GIMP function or GIMP model in it’s own way. The only problem we had: No translator was able to join us, because the writing of DocBook/XML scared everyone away. Additionally – in the meantime – maintaining all translations became a burden for everyone.
Libre Grafics Meeting 2008
I saw dark clouds coming upon me this time. Me as the one who still defended our model of creating documentation for GIMP. Andy Fitzsimon used the GIMP manual as a bad example of an unmaintainable documentation in his talk. He is right, as well as all the other guys who tried to tell us.
Back in 2007 I couldn’t see, that our way we create documentation was supposed to fail:
- lack of contributors a.k.a translators. Writing XML as a translator is hard. There are a lot of tools available for translators which provide a very nice and usable GUI.
- not focusing on one language which will be the reference language.
You can only concentrate on one thing and not on eleven other manuals simultaneously. - and the worst: Trying to invent the wheel.
Tools and Architecture is already developed by others. They do have disadvantages though, but you can’t solve them by creating something new and just thinking, it will be better than other tools because it’s new.
I learned my lesson. We now switch to a system using one reference language and creating translations from this language. Andy Fitzsimon introduced publican as a possible basis, as well as Erik Gebers introducing Scenari. Both noteworthy tools which are interesting to look at.
