[sylpheed:33106] Re: Sylpheed documentation (was: Sylpheed 2.7.0 released)

[Petr Kovar]

Hi!

Antonio Ospite <ospite at studenti.unina.it>, Sun, 26 Jul 2009 00:22:44 +0200:

> On Sat, 25 Jul 2009 19:57:56 +0200
> Petr Kovar <pknbe at volny.cz> wrote:
> 
> > Hi!
> > 
> > rhubbell <Rhubbell at iHubbell.com>, Thu, 23 Jul 2009 22:32:44 -0700:
> > 
> > > On Thu, 23 Jul 2009 18:43:03 -0400
> > > Petr Kovar wrote:
> > > 
> > > --snip--snip--
> > > 
> > > I think we should ask the maintainer of Sylpheed, H. Yamamoto, what
> > > document format would have the best chance of being released each time
> > > Sylpheed is released.  If the answer is xml then that's what we do.
> > > And we start with an translation of the Japanese edition of the html
> > > pages using one of the online translators. I'm not a doc expert or
> > > even a novice but I'll try to help anyway.  Doing a recursive wget of
> > > the translated page would be a starting point.
> > 
> > I very much agree that we need to know Hiro's view on the situation.
> > As he follows this list, he'll probably give us some insight as to
> > whether he's his own plans for the Sylpheed docs, or whether he seeks
> > volunteers help.
> > 
> > Nevertheless, since the said SGML to XML migration has already begun
> > some time (well, years) ago, it'd be nothing but a step back to use
> > completely deprecated tools like linuxdoc SGML. It should be also said
> > that at the end, we need to work with the source documents anyway, as
> > we only export the documentation to HTML when we're finished.
> >
> 
> If the doc is in any XML format and it is going to be a 1:1 translation
> of the Japanese version, then XLIFF can be used as intermediate format
> for translators, I've recently come across this very interesting article
> about it: http://www.ibm.com/developerworks/xml/library/x-localis2/

Thanks for the link. The practice of sylpheeddoc was that each language
l10n has its own group of XML files to be localized with no automatic
interaction with the ever-updating English source. Changing this would be
more than appropriate I think, and XLIFF is one possibility.

However, Sylpheed uses gettext (PO files) for UI l10n, and I've had good
experiences with the xml2po tool[1] while working in the GNOME Translation
Project. See the statistics page e.g. for the gnome-terminal module[2] which
generates POT/PO files for translators automatically (while calling xml2po,
intltool, and some other tools). It's pretty simple and straightforward in
fact.

> > > If the answer is something else then we figure it out. Just keep it
> > > simple. The simpler it is the more likely it will get done and be
> > > maintained.  I say start easy/simple.
> > 
> > That's definitely true, and we should try to search for tools and work
> > flow processes that would suit needs of that not-so-big Sylpheed
> > documentation best. Perhaps have the not-so-skilled contributors work
> > with plain text or simple HTML, and then have the maintainer convert it
> > to valid DocBook? Not sure.
> > 
> > That being said, I'm playing with some fancy XML editors more or less
> > suitable for DocBook, like XXE, epcEdit or Vex, and hopefully find
> > something that is usable enough.

For what it's worth, I've a working docs build system on my PC now, using
just the simple xsltproc for generating HTML files. The original Makefile
uses a bunch of Java tools which seem to be a little bit overkill to me. I
also realized that only a half of the English manual has been converted to
XML till now, so unsurprisingly there's still a lot of work.

Furthermore, the said manual uses a collection of merely outdated
screenshots, but since the Japanese version nor the English version
incorporated in the Sylpheed SVN repository doesn't use any, a decision
whether or not to distribute screenshots has to be made.

Ricardo pointed out the Claws Mail documentation, that one uses Simplified
DocBook best suited for single-page documents. As long as the Sylpheed
documentation is distributed as multi-page, we probably stick with what
we've now, that is DocBook 4.2.

Best,
Petr Kovar

[1] http://linux.die.net/man/1/xml2po
[2] http://l10n.gnome.org/module/gnome-terminal/