Re: [PATCH v2 1/2] l10n: Introduce framework for localizing man pages

From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Mar 18, 2017, 22:17 UTC
Message-ID: <1595815.mnbOBApe2i@cayenne>
In-Reply-To: <xmqqfuia1ifx.fsf@gitster.mtv.corp.google.com>

Le samedi 18 mars 2017, 12:41:22 CET Junio C Hamano a écrit :

Show 23 quoted lines

> Jean-Noel Avila <jn.avila@free.fr> writes:
> > Providing git in localized version is a good step for general adoption
> > of the tool. But as of now, if one needs to refer to the manual pages,
> > they are still confronted to english. The aim is to provide
> > documentation to users in their own language.
> 
> Please outline how the end result looks like here.  Where are the
> localized man pages installed?  Do installers get to choose to build
> and install the localization for some but not all languages and if
> so how?  etc.
> 
> > signed-off-by: Jean-Noel Avila <jn.avila@free.fr>
> 
> s/sign/Sign/;
> 
> > -man: man1 man5 man7
> > +man: man1 man5 man7 man_l10n
> 
> Hmmm, at least in the early days of the topic, I'd prefer that "make
> doc" and "make install" I need to run dozens of times a day from the
> toplevel not to require po4a.
> 
> Thanks.

Fair enough.

Anyway, now I see there's a take away from the discussion thread. Right now the man pages are tagged with the actual version of git, because the documentation is supposed to change at the same pace as the code. But that may not be true for translations, In this case, the automatic running of po4a will generate fuzzy matches which are not going to be used in the translated texts, leading to patchworked manpages, depending on the level of acceptance of untranslated entities.

If we want to freeze the translated manpages at a given version of git until a new version of the manpages is fully translated, we'll have to commit the translated .txt and force in some way the version to freeze (not using the generic asciidoc target of the Makefile). But, that may drag the version of translations far behind the original if translation is stalled.

Or maybe people will not be so upset by mixed language manpages when the translation is lagging, but will prefer to have a "best available translation" of up-to-date pages. Plus that would be managed automatically by po4a's level of translation threshold to effectively generate a translated man page as long as the untranslated parts are still sparse in the mixed-up text.

For now, I keep this last option.