[Bacula-devel-fr] Converting the manual from html to texinfo

[Kern S. <ke...@si...>]

Hello,

Mathieu Arnold has offered to modify my existing html2texi Perl script
to convert the manual from html to texinfo.  In addition, but Karl
Cunningham and Phil Stracchino have offered to do the same thing.
My initial reaction was OK, Mathieu was the first, he can do the
project, but I've been rethinking things, and first, the project is much
bigger than just a Perl script; second, I'm no longer sure that texinfo
is the right document format; and third, I think there is more than
enough for all three of you to do.

Problem:
1. The current Bacula document is written in html.
2. The table of contents is painfully made by hand.
3. There is no index.
4. We have a French translation in process, and I would *really* like to
have some way that we can easily see the changes from one release to the
next so that they can be applied easily to the French version.
5. The document needs to be broken into several documents:
    User's Guide
    Reference Manual
    Tutorial
    Developer's Guide (already done)

So, let's put problem #5 to the side for the moment and consider the
first four only.

Solution:
- Convert the document to some other document formating language.

New problem:
- What language?

Possible Solutions:
- Docbook: NO! it is the world's most poorly documented program and
basically uses XML, which is *very* user UNFRIENDLY.

- Texinfo: OK, not bad, it responds to problems 1-3 pretty well, but it
is a *very* limited (easy to use) language; needs Emacs to link the
@nodes and make the @menu tables; the output has certain texinfo
artifacts; it can be multiple files, but generally is all in one file. 
I converted the apcupsd manual from docbook to texinfo, and am *much*
happier with it. Producing PostScript, one big html, or multiple html
files is easy.

- LaTex: I used LaTex from about 1982 to 1992 and found it quite good.
It is a bit tricky to setup the beginning of the document, but creating
tables, cross-references, indexes, ... is not really too hard -- perhaps
not as clean and simple as Texinfo, but one has a *much* more capable
formatter. Producing Postscript is easy, as for html I am not sure. I
note that Python has a Latex2html script that produces beautiful web
documentation. If that is available I would be very happy.

- Some other formatter?
  E.g. Word or OpenOffice?  Generally they produce poor html, no
Postscript, but do handle #4 very well.

So, that is where I am, as you can see, leaning a bit more toward LaTex
at the moment. I found two html2latex converters, one in Perl and one in
C. For what I want, there would certainly need be some modifications.


Steps:
1. Decide what formatter to use.
2. Decide what conversion tool to use.
3. Decide what modifications to the conversion tool are needed, if any.
4. Make the conversion.

I would be very interested in your comments and any ideas on how to
organize this project.

Best regards, Kern