Re: Infrastructure proposal (Re: Translating Emacs manuals is of strategic importance)

[Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>]

> On Jan 5, 2024, at 22:02, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Date: Fri, 05 Jan 2024 08:20:51 +0000
>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> Cc: Po Lu <luangruo@yahoo.com>, Eli Zaretskii <eliz@gnu.org>, Vincent Belaïche <vincent.b.1@hotmail.fr>, emacs-devel@gnu.org, rms@gnu.org
>> 
>> * translation and proofreading/validation
>> 
>> Now that we have emacs/doc/lang/[lg], what do you think of having
>> something like emacs/doc/lang/drafts/[lg], where people would commit
>> draughts to be proofread/validated?
> 
> I prefer to use special Git branches for that.  This is how we handle
> any changes that are not yet ready to be landed on the master branch,
> and I see no reason to invent special conventions for manual
> translations.

What would be the best way to name the branch? It would be nice to have 
a standard way of naming branches that include documents that require 
proofreading, because it is less easy to find a branch than to find a 
folder.

>> * version numbers
>> 
>> We’d need to have somewhere in the translation the base commit number
>> of the English original, so that when the file is in
>> emacs/doc/lang/[lg] people know how recent the document is.
> 
> You assume the translations will be mostly outdated.

No. I assume that there might be some discrepancy, sometimes, and a 
commit number is a very easy way to see if there is, or not.

> I'm not so sure, but if that indeed happens, we'll think of something.  
> I don't think this is a hard problem to solve.

Indeed, it is not. Writing in the texi source the commit number on which 
the translation is based is pretty easy.

But whatever else works for you is fine.

>> * reduction of redundant work
>> 
>> To make sure people don’t translate documents that are already worked
>> on, we’d need a matrix where the files are assigned, and willing
>> contributors could check the matrix and would also announce their
>> willingness to work on such and such chapter here (pretty much like the
>> W3C does for its translation process), for ex:
> 
> I'd worry about this when we have more than a couple translations.
> Also, the translation matrix is maintained by TP, and I'm not sure we
> should have our own copy; we could simply rely on TP in this aspect.

I’m really not talking about the TP here.

Since you insist (and it’s fair) on not delegating work to 
external groups, there is going to be the need to coordinate things 
from here. And a simple tabulated file should do the trick.

>> * technical requirements
>> 
>> An extra step would be a technical requirement that the file was
>> properly checked for spelling/grammar with the tools that Emacs
>> provides and that it properly builds on the various systems where it
>> was handled, to ensure that the lead does not have to do too much grunt
>> work on the deliverables.
> 
> Every piece of documentation submitted to Emacs is expected to be
> spell-checked, and Emacs supports spell-checking of every language for
> which the available spell-checkers have dictionaries.  So I don't see
> any special problem here.

It is not a technical problem. It is a human problem. This is a 
proposal to explicitly require that all translations are thoroughly 
spell/grammar checked with the tools that are provided by emacs, 
because it is  a fact that lots of people don’t spell/grammar check 
their work. And we can’t really say how Emacs translators will behave 
since Vincent is the first to commit a manual (and his commit to master 
was full of errors, and I don’t mean that to disparage him or his work, 
I’m just stating that as a fact).

>> * information
>> 
>> We’d need a readme file to make all that explicit.
> 
> Yes.  Feel free to submit it.

I will, when we have something to write. This mail is an attempt at 
creating a first draft, in fact. So, when an agreement/vision is 
reached it will not be hard to move all that to a readme file.

>> * publication
>> 
>> For each emacs release, the texi files would be compiled into
>> appropriate formats (minimally info) so that people can easily install
>> them.
> 
> That's part of the release procedure, so there's no reason to consider
> it specially.

Maybe, but it’s a good thing that it is on paper so that translators 
understand how their work is handled. We can’t expect translators to 
understand the fine aspects of the Emacs release process.

>  We already have translated reference cards, for example
> (see etc/refcards/ in the Emacs tree), from which we generate PDF when
> a release tarball is prepared.

Do you suggest that the manuals could also be published as PDF?