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

[Francois Barriere]

Hello there,

   i'm the old maintainer of the english manual and the sylpheeddoc
project on SF. Due to a lack of time, I haven't done any work on this
for years... I will be happy to find someone to lead the project, and
will also be happy to help, as much as I can...
I will also be happy to find a native english writer to lead the project...

The switch to XML was initiated because the linuxdoc toolchain is no
longer maintained in all the distributions, and it's hard to get a
working version today, while the XML/DocBook tools have progressed
a lot and are widely distributed and maintained.

As the existing english doc is really old, it may be better to start
from the Japanese manual (with an automatic translation to get the
structure and an idea of the content of each section).

With DocBook/XML you can filter the screenshot (AFAIR, there was a
filtering step in the old documentation build process for this) and
generate two kinds of ouputs: one without screenshots for the doc
shipped with Sylpheed and another one with screenshot for a printable
(or online) version. We can also generate PDFs from DocBook, use includes
to make the FAQ appear either as a separate document or included in the
manual, etc...

Using DocBook frequently to generate technical documentation I would
recommend the use of XXE as the editor (easy to use, almost WYSIWYG,
full support of includes,etc) and the SAXON XSLT processor (as it supports
a lot of extensions used by the DocBook stylesheets). It is then possible
to generate PDFs using the Apache FOP. The drawback is the need of a full
Java runtime, as all these tools are Java...
The use of xsltproc is possible if you only need the HTML output (I think
the support of xsltproc has been improved in the DocBook stylesheets to
support the needed extensions).

Francois.

-- 
   Francois BARRIERE                          ATMEL
                                              Zone Industrielle
   Tel: (33) 0 442 53 61 98                   13106 ROUSSET
E-Mail: francois.barriere at atmel.com           FRANCE
                 ---------------------------------
Everyone knows that debugging is twice as hard as writing a program 
in the first place. So if you're as clever as you can be when you write it, 
how will you ever debug it? (Brian Kernighan)
                 ---------------------------------