[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Debian Policy released: localized manpages

Hello Christian,
as the one originally suggesting this I guess I might add something.

On Sun, Aug 16, 2009 at 09:49:13AM +0200, Christian Perrier wrote:
> Before people "blindly" update their Standards-Version, I deeply
> suggest looking at this item:
> >   * Localized man pages should either be kept up-to-date with the
> >     original version or warn that they're not up-to-date, either with
> >     warning text or by showing missing or changed portions in the
> >     original language.                                        [12.1]
> *many* packages do provide localized manpages where l10n is handled
> "manually" (the translated manpages are just a copy of the original
> ones....where English is manually replaced by the said language). With
> such setup, it is nearly impossible to guarantee that the localized
> manpage is in sync with the original one.

The background is rather simple: Those man pages can cause quite a bit
of a problem. At least for German there are lots of man pages which
are clearly outdated, some are not even a translation at all, because
at some point someone wanted a German man page (or the customers
wanted one) and a brief version was written, without any indication of
the status. So users who are happy to read the German version have no
indication that they read an outdated or incomplete text. I've heard
(and experienced) several occasions where the users looked for help in
a man page, read the German version, did not find it and assumed it
won't work (and asked me/online for alternatives just to be told, to
use the switch -XYZ which simply was not explained in the German

And the text is IMHO sufficient. With such an manual setup the
maintainer should talk to upstream to get something like the
following in the beginning of each translated man page (of course, in
the target language where possible):

This man page is updated infrequently|manually. Thus it might be out
of date. In doubt, also refer to the original English version which
you can read by issuing
LANG=C man foobar

Maybe on debian-i18n we could issue a call for translation of this
text (once we agreed on a phrase) such that maintainers using a patch
system could add it already until a solution with upstream is found.

> As such, this "should" prevents *many* packages to meet 3.8.3 for
> Standards-Version. You may thus want to check things carefully..:)

> (thankfully for our release date, this "should" is not a "must"...:-))

I (maybe wrongly) assumed a »should« to be: Do it if possible and be
ready to explain if not. A shall/must is something mandatory. But if
policy is different, then the verb "should" be adjusted. But I would
not use something like "may" or "can" as this would defeat the

The intend really should be that maintainers start checking the status
of their man page translations and talk to their upstream about
Maybe upstream thinks about switching to po4a or something similar
already? Otherwise upstream could contact the translators
of the man pages and ask them to add a note or something similar to
the man page. I'm quite aware that this probably will take years. But
we have to start somewhen.



[1] That is, if upstream maintains a man page. Otherwise the
    maintainer could consider i18n the Debian provided man page using,
    e.g. po4a.
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

Attachment: signature.asc
Description: Digital signature

Reply to: