[Po4a-dev]Bug#171378: add support for doc-base

[Denis Barbier]

On Sun, Dec 01, 2002 at 05:27:56PM -0600, Adam DiCarlo wrote:
> 
> Package: po-debconf
> Severity: wishlist
> 
> As discussed with the package maintainer, we feel the best way to move
> forward with doc-base i18n is to use the same techniques this package
> provides for debconf templates.  This exploits existing PO mechanisms
> and should hook in well with the translation apparatus at
> <URL:http://www.debian.org/intl/l10n/po-debconf/>.
> 
> Corresponding bugs have been filed against doc-base to make the
> necessary changes to the docreg file format to support the type of
> l10n provided by this system.

[Cc: po4a-dev ML where we discuss po-debconf development and other PO stuff]
[Send to 171378-quiet, I am only trying to make my mind on this issue]

Here are some random thoughts.

 What is po-debconf?
 =-=-=-=-=-=-=-=-=-=

Po-debconf is a set of tools to manage debconf templates files with PO
files.  It mainly contains 2 scripts: debconf-updatepo and po2debconf.
The former updates PO files when master templates files are changed, and
the latter merges master templates file and translated strings into a
single file (it is equivalent to debconf-mergetemplate).
This package also ships debconf2pot (but this program is useless in most
cases) and debconf-gettextize.  This program converts files from the old
templates.xx format to the new format based on PO files.

 I18n of doc-base
 =-=-=-=-=-=-=-=-

There are 2 goals:
  (a) provide translated entries
  (b) register translated documents
Of course po-debconf only deals with (a), (b) won't be discussed at aLL
here.

 Po-debconf internals
 =-=-=-=-=-=-=-=-=-=-

In fact debconf-updatepo and po2debconf are only wrappers to intltool
(a set of tools written by GNOME developers for their i18n work) scripts.
There were 2 distinct issues when designing po-debconf:
  * intltool did not recognize our rfc822 format.  I hacked it, and my
    patches are applied upstream, but as our format is not clearly
    defined, there are small variations and both versions always
    slightly differ.
  * intltool interface is really awful, and we wanted po-debconf
    interface to be intuitive.
Wrapper scripts is certainly the best approach.

 How can po-debconf be useful to doc-base?
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Despite its name, po-debconf is not debconf specific and can deal with
most rfc822 formatted files, like doc-base or control files.
There are 2 problems with doc-base:
  * po-debconf follows deb-control(5) formatting, i.e. long fields are
    splitted into short and long forms, the latter being allowed to
    contain several paragraphs.
  * po-debconf does not recognizes tabs at first column for continuation
    lines, but I will allow them in the next release.

 How to add support for doc-base?
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

I am very reluctant to add a slightly different rfc822 format, intltool
upstreams will surely not appreciate to support two similar but distinct
rfc822 formats for Debian needs.  The only problem I found is with
continuation lines, in particular with Abstract field.  From my point of
view, it could be merged with the Title field, the latter being the short
form, and the latter being the long form.  Field name does not matter,
it does not have to be Description necessarily.  And it should neither
be Title nor Abstract, so that doc-base can automatically detect that
this is a new format without having to manage a Version field.
All other fields with continuation lines should also be fixed, but they
are harmless if not localized.

Once done, existing tools would work out of the box, except for
debconf-gettextize which is debconf specific.  We will have to write
a doc-base-gettextize script, but as there was previously no i18n support,
its main task is to prepend underscores to translatable entries.

Doc-base and debconf will then share the debian/po/ directory, we have
to make sure it can be done without trouble.

 Has po-debconf to be renamed?
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Of course running po2debconf to generate a merged doc-base file is a silly
idea.  There are several alternatives:
  (a)  Rename po-debconf and its scripts to make them more generic
  (b)  Merge po-debconf and intltool
  (c)  Merge stock intltool and the intltool scripts of po-debconf, and let
       po-debconf ship wrappers
  (d)  ship hacked intltool scripts in a separate package, and wrappers
       either in their own package or in doc-base/debconf

(d) is my preferred choice, until this work is stabilized.  It may be
merged with intltool when it is mature.
This choice also depends whether Adam wants to maintain his own doc-base
wrappers.  If not, (a) may also be an option.  But in this case we have
to see with Joey Hess how not to break debconf.

Denis