Re: Abiword documentation update project started

On Fri, 1 Sep 2006, J.M. Maurer wrote:

> Date: Fri, 01 Sep 2006 10:27:39 +0200
> From: J.M. Maurer <uwog@uwog.net>
> To: Alan Horkan <horkana@maths.tcd.ie>
> Cc: AbiWord Developer Mailing List <abiword-dev@abisource.com>
> Subject: Re: Abiword documentation update project started
>
> > So is the plan to change the master files to Docbook and then generate
> > HTML/PDF from the Docbook to serve the needs of other platforms?
>
> Yes
>
> > The plan if there is one has not been clearly explained yet. While it
> > would be great to get good help in Docbook format for Gnome it would be a
> > shame to leave the other platforms behind or an attempt was made to start
> > new documentation from scratch instead of refactoring and improving the
> > old.
>
> Nothing must be gnome specific
>
> > I always thought the biggest advantage of using ABW as a master format
> > would mean at least one platform would use Abiword itself to view the ABW
> > help files directly.
>
> In cryptic form:
>
> -> master docbook files
> -> use xml2po to let translators translate the docs
> -> abiword -> HTML (-> WinHelp even?)

WinHelp, ick. Well if it could be done within an existing docbook
toolchain that would be cool but most likely it would require a lot of
extra effort and use of microsoft tools to generate the CHM from a HTML
version of the documentation.

> -> something -> OSX's native format

(What do they use, out of interest?)

> -> something [1] -> yelp
>
> [1] whatever GNOME people use to convert docbook to something yelp
> understand (or yelp does docbook natively, right?)

I'm not sure of the details but Gnome uses docbook and then some
combination of scrollkeeper and Yelp (I think Yelp does understand
dockbook natively). There are plans underway to improve the
interoperability of Gnome and KDE help systems but I'm not sure how much
progress that is making. The plan would allow KDE users to view Docbook
format help in the KDE Help browser rather than Yelp.
The Yelp developers have no intenion of a windows port - use the standard
system on windows they said - so PDF, HTML or something else will still be
needed. HTML seems like the best bet because it is useful in some cases
like Maemo/Nokia 770 not to install the documentation and refer to a web
based copy instead. (It would be nice if the documentation was all
grouped together in a subsection of the site and we were able to use
google to search site:help.abisource.com or docs.abisource.com or
something like that.)

-- 
Alan