Where to contribute manual translations ?

Where to contribute manual translations ?

[Vincent Belaïche]

[-- Attachment #1: Type: text/plain, Size: 849 bytes --]

Hello,

Where is the right place to contribute a translation to French of the SES manual ?
Is it there : https://savannah.nongnu.org/projects/emacsdoc-fr
French GNU Emacs manual - Summary [Savannah]<https://savannah.nongnu.org/projects/emacsdoc-fr>
Savannah is a central point for development, distribution and maintenance of free software, both GNU and non-GNU.
savannah.nongnu.org

Or can it be placed directly under the Emacs repo (or is there any git submodule planned under directory doc for that ?)

Another question : how to internationalize docstrings ? IMHO it would be great if the docstring could have some info manual anchor in it, and one could display it from the currently selected language manual. Besides, reading docstring from manual via some anchor is basically what Calc does with some kitchen tricks.

   Vincent.

[-- Attachment #2: Type: text/html, Size: 4039 bytes --]

Re: Where to contribute manual translations ?

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> Date: Wed, 27 Dec 2023 21:14:06 +0000
> msip_labels: 
> 
> Where is the right place to contribute a translation to French of the SES manual ?

We don't have a place yet.  Do you intend to contribute this to the
Emacs project, so that this manual is maintained as part of Emacs and
distributed with the release tarballs, or do you intend to make it a
separately-maintained manual available from outside of emacs.git?  In
the latter case, perhaps making it a GNU ELPA package could be a
possibility?

> Is it there : https://savannah.nongnu.org/projects/emacsdoc-fr

It could be.  But I'm not sure it's the best place, at least from the
discoverability POV.

> Or can it be placed directly under the Emacs repo (or is there any git submodule planned under
> directory doc for that ?)

It can, if you'd like to contribute this manual to the Emacs project,
and keep maintaining it as part of Emacs.

> Another question : how to internationalize docstrings ? IMHO it would be great if the docstring could
> have some info manual anchor in it, and one could display it from the currently selected language
> manual. Besides, reading docstring from manual via some anchor is basically what Calc does with
> some kitchen tricks.  

We don't yet have the necessary infrastructure for translating doc
strings.  This was discussed in the past several times, and the
conclusion was that it's a non-trivial project.  Some of the previous
discussions:

  https://lists.gnu.org/archive/html/emacs-devel/2017-04/msg00750.html
  https://lists.gnu.org/archive/html/emacs-devel/2017-05/msg00645.html
  https://lists.gnu.org/archive/html/emacs-devel/2017-05/msg00751.html
  https://lists.gnu.org/archive/html/emacs-devel/2017-05/msg00806.html
  https://lists.gnu.org/archive/html/emacs-devel/2019-03/msg00081.html
  https://lists.gnu.org/archive/html/help-gnu-emacs/2021-07/msg00422.html

RE: Where to contribute manual translations ?

[Vincent Belaïche]

[-- Attachment #1: Type: text/plain, Size: 2650 bytes --]

Dear Eli,

Thank you for your quick and very complete reply. Yes, I think that the best would be for me to have this translation under the Emacs project, as it would be kept consistent with the source code. Is doc/fr/misc/ses.texi OK for the French version path, as the original is doc/misc/ses.texi ?

   V.
________________________________
De : emacs-devel-bounces+vincent.b.1=hotmail.fr@gnu.org <emacs-devel-bounces+vincent.b.1=hotmail.fr@gnu.org> de la part de Eli Zaretskii <eliz@gnu.org>
Envoyé : jeudi 28 décembre 2023 08:15
À : Vincent Belaïche <vincent.b.1@hotmail.fr>
Cc : emacs-devel@gnu.org <emacs-devel@gnu.org>
Objet : Re: Where to contribute manual translations ?

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> Date: Wed, 27 Dec 2023 21:14:06 +0000
> msip_labels:
>
> Where is the right place to contribute a translation to French of the SES manual ?

We don't have a place yet.  Do you intend to contribute this to the
Emacs project, so that this manual is maintained as part of Emacs and
distributed with the release tarballs, or do you intend to make it a
separately-maintained manual available from outside of emacs.git?  In
the latter case, perhaps making it a GNU ELPA package could be a
possibility?

> Is it there : https://savannah.nongnu.org/projects/emacsdoc-fr

It could be.  But I'm not sure it's the best place, at least from the
discoverability POV.

> Or can it be placed directly under the Emacs repo (or is there any git submodule planned under
> directory doc for that ?)

It can, if you'd like to contribute this manual to the Emacs project,
and keep maintaining it as part of Emacs.

> Another question : how to internationalize docstrings ? IMHO it would be great if the docstring could
> have some info manual anchor in it, and one could display it from the currently selected language
> manual. Besides, reading docstring from manual via some anchor is basically what Calc does with
> some kitchen tricks.

We don't yet have the necessary infrastructure for translating doc
strings.  This was discussed in the past several times, and the
conclusion was that it's a non-trivial project.  Some of the previous
discussions:

  https://lists.gnu.org/archive/html/emacs-devel/2017-04/msg00750.html
  https://lists.gnu.org/archive/html/emacs-devel/2017-05/msg00645.html
  https://lists.gnu.org/archive/html/emacs-devel/2017-05/msg00751.html
  https://lists.gnu.org/archive/html/emacs-devel/2017-05/msg00806.html
  https://lists.gnu.org/archive/html/emacs-devel/2019-03/msg00081.html
  https://lists.gnu.org/archive/html/help-gnu-emacs/2021-07/msg00422.html


[-- Attachment #2: Type: text/html, Size: 5182 bytes --]

Re: Where to contribute manual translations ?

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> Date: Thu, 28 Dec 2023 11:41:20 +0000
> 
> Thank you for your quick and very complete reply. Yes, I think that the best would be for me to have
> this translation under the Emacs project, as it would be kept consistent with the source code. Is
> doc/fr/misc/ses.texi OK for the French version path, as the original is doc/misc/ses.texi ?

SGTM, but I'd like to hear from Stefan Kangas (CC'ed) as well, before
we make the final decision, as this seems to create a precedent.

Stefan, do you think doc/LANG, where LANG is a language name, is okay
for keeping translations of manuals to language LANG?

Another question is what would be the file name of the corresponding
Info file, and in what directory should it be generated by makeinfo?

Re: Where to contribute manual translations ?

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> SGTM, but I'd like to hear from Stefan Kangas (CC'ed) as well, before
> we make the final decision, as this seems to create a precedent.
>
> Stefan, do you think doc/LANG, where LANG is a language name, is okay
> for keeping translations of manuals to language LANG?
>
> Another question is what would be the file name of the corresponding
> Info file, and in what directory should it be generated by makeinfo?

How do other GNU projects manage these files?  For instance there is a
Ukrainian and a Slovak translation of the help2man manual on my computer
(whose presence I cannot explain), so if other GNU projects have already
adopted a scheme for organizing documentation translations, we should
follow in their footsteps, if only for consistency's sake.

Re: Where to contribute manual translations ?

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: Vincent Belaïche <vincent.b.1@hotmail.fr>,  Stefan
>  Kangas
>  <stefankangas@gmail.com>,  emacs-devel@gnu.org
> Date: Thu, 28 Dec 2023 22:01:45 +0800
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > SGTM, but I'd like to hear from Stefan Kangas (CC'ed) as well, before
> > we make the final decision, as this seems to create a precedent.
> >
> > Stefan, do you think doc/LANG, where LANG is a language name, is okay
> > for keeping translations of manuals to language LANG?
> >
> > Another question is what would be the file name of the corresponding
> > Info file, and in what directory should it be generated by makeinfo?
> 
> How do other GNU projects manage these files?

Tell me which projects do that, and I will have a look.

FWIW, I'm not aware of any such projects, and don't know which
conventions they use.

Re: Where to contribute manual translations ?

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
>> CC: "emacs-devel@gnu.org" <emacs-devel@gnu.org>
>> Date: Thu, 28 Dec 2023 11:41:20 +0000
>>
>> Thank you for your quick and very complete reply. Yes, I think that the best would be for me to have
>> this translation under the Emacs project, as it would be kept consistent with the source code. Is
>> doc/fr/misc/ses.texi OK for the French version path, as the original is doc/misc/ses.texi ?
>
> SGTM, but I'd like to hear from Stefan Kangas (CC'ed) as well, before
> we make the final decision, as this seems to create a precedent.
>
> Stefan, do you think doc/LANG, where LANG is a language name, is okay
> for keeping translations of manuals to language LANG?

I'd probably prefer to keep them in a subdirectory like

    doc/translations/<...>

My main concern with adding new files [with similar names] is ease of
autocompleting, both inside the doc/ directory, and when using
`project-find-file' together with flexible matching styles.

For the latter case especially, I find that having duplicate file names
under version control often causes conflicts.  Thus, I'd rather we avoid
that if possible.

I'd suggest something like

    doc/translations/$SECTION/$LANG-$MANUAL.texi

so that we end up with

    doc/translations/misc/fr-ses.texi

.

I also considered something like

    doc/translations/$LANG/$SECTION/$MANUAL

so that in this case we end up with

    doc/translations/fr/misc/ses.texi

but that has the same problem that we end up with duplicate file names.
It's also perhaps somewhat overblown given that we only expect to have a
very small number of translated manuals for the foreseeable future.[1]

WDYT?

> Another question is what would be the file name of the corresponding
> Info file, and in what directory should it be generated by makeinfo?

I'm less concerned with autocompleting in this directory, and it's not
under version control.  So it should be easier to change the structure
later, I think.

Perhaps for now something like

    info/$LANG/$MANUAL

is okay?

We could then add the language-specific directory to
`Info-directory-list' based on the users locale, or something along
those lines.

For the sake of completion, I'll mention that we might at some point
want to consider publishing the translated manual on our web pagess.

Footnotes:
[1]  I'm not aware of anyone else working on translating our manuals.

Re: Where to contribute manual translations ?

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Thu, 28 Dec 2023 07:32:08 -0800
> Cc: emacs-devel@gnu.org
> 
> > Stefan, do you think doc/LANG, where LANG is a language name, is okay
> > for keeping translations of manuals to language LANG?
> 
> I'd probably prefer to keep them in a subdirectory like
> 
>     doc/translations/<...>
> 
> My main concern with adding new files [with similar names] is ease of
> autocompleting, both inside the doc/ directory, and when using
> `project-find-file' together with flexible matching styles.
> 
> For the latter case especially, I find that having duplicate file names
> under version control often causes conflicts.  Thus, I'd rather we avoid
> that if possible.
> 
> I'd suggest something like
> 
>     doc/translations/$SECTION/$LANG-$MANUAL.texi
> 
> so that we end up with
> 
>     doc/translations/misc/fr-ses.texi
> 
> .
> 
> I also considered something like
> 
>     doc/translations/$LANG/$SECTION/$MANUAL
> 
> so that in this case we end up with
> 
>     doc/translations/fr/misc/ses.texi
> 
> but that has the same problem that we end up with duplicate file names.
> It's also perhaps somewhat overblown given that we only expect to have a
> very small number of translated manuals for the foreseeable future.[1]
> 
> WDYT?

If we are going to call the source files of the translations of
manuals as MANUAL-LANG.texi, then we don't need a separate directory,
we could instead put them all in the same directories.  That is, we
could have doc/misc/ses.texi and doc/mist/ses-fr.texi.  This would be
simpler, I think?

> > Another question is what would be the file name of the corresponding
> > Info file, and in what directory should it be generated by makeinfo?
> 
> I'm less concerned with autocompleting in this directory, and it's not
> under version control.  So it should be easier to change the structure
> later, I think.
> 
> Perhaps for now something like
> 
>     info/$LANG/$MANUAL
> 
> is okay?

Why not info/$MANUAL-$LANG.info ?

And I think we should look at what other projects do, if we find such
projects.

Re: Where to contribute manual translations ?

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> If we are going to call the source files of the translations of
> manuals as MANUAL-LANG.texi, then we don't need a separate directory,
> we could instead put them all in the same directories.  That is, we
> could have doc/misc/ses.texi and doc/mist/ses-fr.texi.  This would be
> simpler, I think?

It would be simpler, yes.  But it's nice to be able to have a directory
where a simple `ls` gives you "all the manuals that exist" without
having to filter for all languages, or manually check to see if they are
translations.  (Unfortunately, filtering out "-[a-z][a-z].texi" doesn't
work due to files like mairix-el.texi.)

So moving it all into a directory like doc/translations makes things a
little bit more complicated, but arguably also a bit tidier.

OTOH, we could always change things around later if it starts becoming a
problem.  For now, it's all a bit hypothetical given that it's only one
file.  :-)

> Why not info/$MANUAL-$LANG.info ?

Users of non-French locales do not want to see the French manual(s), I
think.  OTOH, if I start Emacs with something like

    LANG=fr_FR emacs -Q

I would probably like to see the french manual.

Re: Where to contribute manual translations ?

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Thu, 28 Dec 2023 09:04:15 -0800
> Cc: vincent.b.1@hotmail.fr, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > If we are going to call the source files of the translations of
> > manuals as MANUAL-LANG.texi, then we don't need a separate directory,
> > we could instead put them all in the same directories.  That is, we
> > could have doc/misc/ses.texi and doc/mist/ses-fr.texi.  This would be
> > simpler, I think?
> 
> It would be simpler, yes.  But it's nice to be able to have a directory
> where a simple `ls` gives you "all the manuals that exist" without
> having to filter for all languages, or manually check to see if they are
> translations.  (Unfortunately, filtering out "-[a-z][a-z].texi" doesn't
> work due to files like mairix-el.texi.)
> 
> So moving it all into a directory like doc/translations makes things a
> little bit more complicated, but arguably also a bit tidier.
> 
> OTOH, we could always change things around later if it starts becoming a
> problem.  For now, it's all a bit hypothetical given that it's only one
> file.  :-)
> 
> > Why not info/$MANUAL-$LANG.info ?
> 
> Users of non-French locales do not want to see the French manual(s), I
> think.  OTOH, if I start Emacs with something like
> 
>     LANG=fr_FR emacs -Q
> 
> I would probably like to see the french manual.

So what will be in the menu in info/dire we distribute?

And if we are going to have separate directories for each language,
both under doc/ and under info/, why do we also have to name the files
FOO-fr.texi or FOO-fr.info?

RE: Where to contribute manual translations ?

[Vincent Belaïche]

[-- Attachment #1: Type: text/plain, Size: 3207 bytes --]

Hello,

Just to react to one of the comment made on this thread. I think too that this is a good idea if the compiled documents do not have the same file names, like ses-xx.info for xx language translation, and ses.info for the original language. This is because, at least for the translator it is practical to have both manual in the same dir, and therefore they need different names. Also when you make absolute node reference it is probably better if the name is different for different language, although I took care to keep the same node names to make easier language switching. The same applies to the direntry menu item.

Now, concerning the source filename, frankly speaking, I cannot understand why it would be a problem to have the same names given that they are in different directories. I think that having different source file names complexifies comparison of source file trees to see at a glance which manuals have translations, and which don't. Nevertheless I won't make a fuss, and I do not strongly object to this if I am alone of the opinion that it is a bad idea to have different source filenames.

   Vincent.

________________________________
De : emacs-devel-bounces+vincent.b.1=hotmail.fr@gnu.org <emacs-devel-bounces+vincent.b.1=hotmail.fr@gnu.org> de la part de Eli Zaretskii <eliz@gnu.org>
Envoyé : jeudi 28 décembre 2023 18:14
À : Stefan Kangas <stefankangas@gmail.com>
Cc : vincent.b.1@hotmail.fr <vincent.b.1@hotmail.fr>; emacs-devel@gnu.org <emacs-devel@gnu.org>
Objet : Re: Where to contribute manual translations ?

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Thu, 28 Dec 2023 09:04:15 -0800
> Cc: vincent.b.1@hotmail.fr, emacs-devel@gnu.org
>
> Eli Zaretskii <eliz@gnu.org> writes:
>
> > If we are going to call the source files of the translations of
> > manuals as MANUAL-LANG.texi, then we don't need a separate directory,
> > we could instead put them all in the same directories.  That is, we
> > could have doc/misc/ses.texi and doc/mist/ses-fr.texi.  This would be
> > simpler, I think?
>
> It would be simpler, yes.  But it's nice to be able to have a directory
> where a simple `ls` gives you "all the manuals that exist" without
> having to filter for all languages, or manually check to see if they are
> translations.  (Unfortunately, filtering out "-[a-z][a-z].texi" doesn't
> work due to files like mairix-el.texi.)
>
> So moving it all into a directory like doc/translations makes things a
> little bit more complicated, but arguably also a bit tidier.
>
> OTOH, we could always change things around later if it starts becoming a
> problem.  For now, it's all a bit hypothetical given that it's only one
> file.  :-)
>
> > Why not info/$MANUAL-$LANG.info ?
>
> Users of non-French locales do not want to see the French manual(s), I
> think.  OTOH, if I start Emacs with something like
>
>     LANG=fr_FR emacs -Q
>
> I would probably like to see the french manual.

So what will be in the menu in info/dire we distribute?

And if we are going to have separate directories for each language,
both under doc/ and under info/, why do we also have to name the files
FOO-fr.texi or FOO-fr.info?


[-- Attachment #2: Type: text/html, Size: 5299 bytes --]

Re: Where to contribute manual translations ?

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> Tell me which projects do that, and I will have a look.

I mentioned one: help2man.  Its English manual is saved under the name
/usr/share/info/help2man.info, to whose localized variants the language
codes of their respective languages are appended: help2man-uk.info.gz,
help2man-sv.info.gz, and so on.

Thanks.

Re: Where to contribute manual translations ?

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> Users of non-French locales do not want to see the French manual(s), I
>> think.  OTOH, if I start Emacs with something like
>>
>>     LANG=fr_FR emacs -Q
>>
>> I would probably like to see the french manual.
>
> So what will be in the menu in info/dire we distribute?
>
> And if we are going to have separate directories for each language,
> both under doc/ and under info/, why do we also have to name the files
> FOO-fr.texi or FOO-fr.info?

I had in mind a shared directory for all translations, but we would
compile them to separate directories under info such that

    doc/translations/misc/ses-fr.texi

compiles into

    info/fr/ses-fr.info

In the info/$LANG directories, we would put a separate `dir` file.
Then we could simply add those language specific directories to
`Info-directory-list' based on the locale, I think.

The main purpose of having "ses-fr.texi" is to avoid having several
files with the same file name under version control, which I personally
find very confusing.

I have no strong opinion about the naming of the .info file, but I
thought that from the point of view of info, it would have to be in two
files: `ses´ and `ses-fr`, if they are to co-exist.  Being able to
access both the original and translated manuals at the same time seems
useful.

(I'm open to better ideas than what I present above, of course.)

Re: Where to contribute manual translations ?

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: vincent.b.1@hotmail.fr,  stefankangas@gmail.com,  emacs-devel@gnu.org
> Date: Fri, 29 Dec 2023 08:42:26 +0800
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Tell me which projects do that, and I will have a look.
> 
> I mentioned one: help2man.

Thanks, but do you know about any others?

> Its English manual is saved under the name
> /usr/share/info/help2man.info, to whose localized variants the
> language codes of their respective languages are appended:
> help2man-uk.info.gz, help2man-sv.info.gz, and so on.

For naming the Info files, that's what I tend to as well.  The Info
directory hierarchy in general and the structure of the DIR files in
particular assume flat directories, so if we want to have
language-specific subdirectories, we'd need to tweak INFOPATH or
Info-directory-list.  Which I think is not justified, and will need
cooperation of the Texinfo maintainers.

Re: Where to contribute manual translations ?

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Thu, 28 Dec 2023 18:05:41 -0800
> Cc: vincent.b.1@hotmail.fr, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > And if we are going to have separate directories for each language,
> > both under doc/ and under info/, why do we also have to name the files
> > FOO-fr.texi or FOO-fr.info?
> 
> I had in mind a shared directory for all translations, but we would
> compile them to separate directories under info such that
> 
>     doc/translations/misc/ses-fr.texi
> 
> compiles into
> 
>     info/fr/ses-fr.info
> 
> In the info/$LANG directories, we would put a separate `dir` file.
> Then we could simply add those language specific directories to
> `Info-directory-list' based on the locale, I think.

Using subdirectories in the Info hierarchy is problematic: not only
will we need to tweak Info-directory-list, we'll also need to
coordinate with Texinfo so that the stand-alone Info reader supports
these subdirectories (which means either that INFOPATH will need to
include them, or that the Info reader would need to be modified to
search those subdirectories without them appearing in INFOPATH).

Come to think of that, adding those directories to Info-directory-list
is also not the best idea, since there will be eventually many such
subdirectories, and the search for Info manuals will become much
slower as result.  We could teach info.el that FOO-fr.info should be
in the "fr" subdirectory of each directory in Info-directory-list, or
have stuff like "(fr/ses-fr)." in DIR, but how is this better than
just having ses-fr.info in the info directory to begin with?

So I think having MANUAL-LANG.info files which are translations of
MANUAL.info to the various languages LANG, and having them in the same
single directory, is the best alternative, as its impact on existing
code and distros is minimal, almost non-existent.

> The main purpose of having "ses-fr.texi" is to avoid having several
> files with the same file name under version control, which I personally
> find very confusing.

I'm okay with having subdirectories in the doc/ directory, if that has
some, even small, advantages.

Re: Where to contribute manual translations ?

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> So I think having MANUAL-LANG.info files which are translations of
> MANUAL.info to the various languages LANG, and having them in the same
> single directory, is the best alternative, as its impact on existing
> code and distros is minimal, almost non-existent.

OK, then let's do it that way.

However, does that mean that, e.g. `ses-fr`, would always be listed, or
would it be listed only when using a French locale?  I imagine that most
users would never want to look at most foreign language manuals (they
typically speak only a few languages), so showing all translations risks
mostly getting in the way.

RE: Where to contribute manual translations ?

[Vincent Belaïche]

[-- Attachment #1: Type: text/plain, Size: 1446 bytes --]

To Stefan:
> However, does that mean that, e.g. `ses-fr`, would always be listed,
> or would it be listed only when using a French locale?  I imagine that
> most users would never want to look at most foreign language manuals
> (they typically speak only a few languages), so showing all
> translations risks mostly getting in the way.

I suspect that there should be some option in the configure script to tell for which language you want the manuals.

   V.

________________________________
De : Stefan Kangas <stefankangas@gmail.com>
Envoyé : vendredi 29 décembre 2023 10:02
À : Eli Zaretskii <eliz@gnu.org>
Cc : vincent.b.1@hotmail.fr <vincent.b.1@hotmail.fr>; emacs-devel@gnu.org <emacs-devel@gnu.org>
Objet : Re: Where to contribute manual translations ?

Eli Zaretskii <eliz@gnu.org> writes:

> So I think having MANUAL-LANG.info files which are translations of
> MANUAL.info to the various languages LANG, and having them in the same
> single directory, is the best alternative, as its impact on existing
> code and distros is minimal, almost non-existent.

OK, then let's do it that way.

However, does that mean that, e.g. `ses-fr`, would always be listed, or
would it be listed only when using a French locale?  I imagine that most
users would never want to look at most foreign language manuals (they
typically speak only a few languages), so showing all translations risks
mostly getting in the way.

[-- Attachment #2: Type: text/html, Size: 3433 bytes --]

Re: Where to contribute manual translations ?

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Fri, 29 Dec 2023 01:02:21 -0800
> Cc: vincent.b.1@hotmail.fr, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > So I think having MANUAL-LANG.info files which are translations of
> > MANUAL.info to the various languages LANG, and having them in the same
> > single directory, is the best alternative, as its impact on existing
> > code and distros is minimal, almost non-existent.
> 
> OK, then let's do it that way.

So, to summarize:

  . Texinfo sources go into the doc/LANG/ subdirectory, under which
    there should be the same subdirectories 'emacs', 'lispref', misc'
    etc. (we will actually create a directory when the first
    translation of the corresponding English manual will be
    submitted);
  . Texinfo sources of a translation of MANUAL.texi into the language
    LANG will be called MANUAL-LANG.texi;
  . Info output should go to info/MANUAL-LANG.info (this should be
    specified in the @setfilename directive in the Texinfo source).

OK?

> However, does that mean that, e.g. `ses-fr`, would always be listed, or
> would it be listed only when using a French locale?

If ses-fr.info is installed, then it will be listed, yes.

> I imagine that most users would never want to look at most foreign
> language manuals (they typically speak only a few languages), so
> showing all translations risks mostly getting in the way.

This is something to coordinate with both the Texinfo project and the
downstream distros, I think.  Basically, if a user never wants to see
ses-fr.info, that user should not install it in the first place.  It
is possible to do something more sophisticated based on the locale,
but that would require coordination with the Texinfo project, and then
how would that support users who, for some reason, want to have
manuals in several languages available?  So it sounds a bit
complicated, and I'd say let the sleeping dogs lie at this point.

Re: Where to contribute manual translations ?

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> So, to summarize:
>
>   . Texinfo sources go into the doc/LANG/ subdirectory, under which
>     there should be the same subdirectories 'emacs', 'lispref', misc'
>     etc. (we will actually create a directory when the first
>     translation of the corresponding English manual will be
>     submitted);
>   . Texinfo sources of a translation of MANUAL.texi into the language
>     LANG will be called MANUAL-LANG.texi;
>   . Info output should go to info/MANUAL-LANG.info (this should be
>     specified in the @setfilename directive in the Texinfo source).
>
> OK?

Yes, sounds good.

> This is something to coordinate with both the Texinfo project and the
> downstream distros, I think.  Basically, if a user never wants to see
> ses-fr.info, that user should not install it in the first place.  It
> is possible to do something more sophisticated based on the locale,
> but that would require coordination with the Texinfo project, and then
> how would that support users who, for some reason, want to have
> manuals in several languages available?  So it sounds a bit
> complicated, and I'd say let the sleeping dogs lie at this point.

OK, that's fine by me.  We can always revisit it later, if it starts
becoming a problem.  It might not be worth the effort if it only
concerns one or two manuals.

Re: Where to contribute manual translations ?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Where do people propose to look for a list of translations of manuals?
Who would collect this list, and verify that each one is done properly
(for instance, in accord with the license)?

This takes human attention -- a program can't do that job.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Where to contribute manual translations ?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Stefan, do you think doc/LANG, where LANG is a language name, is okay
  > > for keeping translations of manuals to language LANG?

You seem to be talking about how to organize a collection fo manuals
about various manuals.  The plan you've proposed might make sense for
its internal organization, but the crucial question is, WHERE WOULD WE
PUT IT and who would run it?

If we want to put lots of GNU manuals on the web for general access,
this should not e part of Emacs development.  The place for it is
on gnu.org, but not as part of the Emacs pages.

That belongs at the leve of the GNU Project, and I should discuss it
with the GNU webmasters.  They should make this collection -- if they
have not already.

We can set up gnu.org/manuals for a place to put them.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Where to contribute manual translations ?

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: emacs-devel@gnu.org
> Date: Fri, 29 Dec 2023 22:20:06 -0500
> 
> Where do people propose to look for a list of translations of manuals?

I'm not sure we need a list, but it will be easy to create one if we
do.  Something similar to etc/tutorials/TUTORIAL.translators, perhaps?

> Who would collect this list, and verify that each one is done properly
> (for instance, in accord with the license)?

What does that entail, exactly?  I'm not aware of anything similar we
do with tutorial translations.

Re: Where to contribute manual translations ?

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: eliz@gnu.org, vincent.b.1@hotmail.fr, emacs-devel@gnu.org
> Date: Fri, 29 Dec 2023 22:22:31 -0500
> 
> You seem to be talking about how to organize a collection fo manuals
> about various manuals.  The plan you've proposed might make sense for
> its internal organization, but the crucial question is, WHERE WOULD WE
> PUT IT and who would run it?
> 
> If we want to put lots of GNU manuals on the web for general access,
> this should not e part of Emacs development.  The place for it is
> on gnu.org, but not as part of the Emacs pages.

We were discussing the places for the Texinfo sources and the
corresponding Info manuals.  We didn't discuss the HTML output of
that, and my initial thinking about this is for now to exempt the
translations from the process of producing HTML docs for uploading to
the gnu.org site (see admin/make-manuals and admin/upload-manuals, and
their description in admin/make-tarball.txt).

> That belongs at the leve of the GNU Project, and I should discuss it
> with the GNU webmasters.  They should make this collection -- if they
> have not already.
> 
> We can set up gnu.org/manuals for a place to put them.

Yes.  But that's a separate issue, not the one we discussed.

RE: Where to contribute manual translations ?

[Vincent Belaïche]

[-- Attachment #1: Type: text/plain, Size: 3034 bytes --]

Hello,

I have pushed the French translation of SES manual to master, here is a patch to make the compilation :

[https://res-h3.public.cdn.office.net/assets/mail/file-icon/png/generic_16x16.png]patch.diff<https://1drv.ms/u/s!AkDIBBjRAOVwg3y54YIxSCu3e2MI>

Since I am not the maintainer of these Makefile.in scripts, I did not dare push this change.

To @Andrés Ramírez<mailto:rrandresf@hotmail.com>, BTW I have added you into the acknowledgement section, in anticipation of the programmatic stuff to which you contributed quite a few suggestions. Please be patient, probably some time is going to ellapse before I can find a time slot to finalize it.

   Vincent.

PS-1 : I realize that the commit message of the change is quite short, whereas there was also a few updates to the English version with the change. Sorry for the oblivious committing, I can provide a more detailed change record if need be.
PS-2 : I named the subdirectory « lang » rather than « translations », it seems more usual/concise a name to me without loss of clarity. Please feel free to rename « translations » if « lang » hurts anybody.
PS-3 : last but not least, happy new year 2024 to all, blessed be the Church of Emacs, and let us follow Holy Ignutius on the narrow path of well designed software.
________________________________
De : emacs-devel-bounces+vincent.b.1=hotmail.fr@gnu.org <emacs-devel-bounces+vincent.b.1=hotmail.fr@gnu.org> de la part de Eli Zaretskii <eliz@gnu.org>
Envoyé : samedi 30 décembre 2023 08:10
À : rms@gnu.org <rms@gnu.org>
Cc : stefankangas@gmail.com <stefankangas@gmail.com>; vincent.b.1@hotmail.fr <vincent.b.1@hotmail.fr>; emacs-devel@gnu.org <emacs-devel@gnu.org>
Objet : Re: Where to contribute manual translations ?

> From: Richard Stallman <rms@gnu.org>
> Cc: eliz@gnu.org, vincent.b.1@hotmail.fr, emacs-devel@gnu.org
> Date: Fri, 29 Dec 2023 22:22:31 -0500
>
> You seem to be talking about how to organize a collection fo manuals
> about various manuals.  The plan you've proposed might make sense for
> its internal organization, but the crucial question is, WHERE WOULD WE
> PUT IT and who would run it?
>
> If we want to put lots of GNU manuals on the web for general access,
> this should not e part of Emacs development.  The place for it is
> on gnu.org, but not as part of the Emacs pages.

We were discussing the places for the Texinfo sources and the
corresponding Info manuals.  We didn't discuss the HTML output of
that, and my initial thinking about this is for now to exempt the
translations from the process of producing HTML docs for uploading to
the gnu.org site (see admin/make-manuals and admin/upload-manuals, and
their description in admin/make-tarball.txt).

> That belongs at the leve of the GNU Project, and I should discuss it
> with the GNU webmasters.  They should make this collection -- if they
> have not already.
>
> We can set up gnu.org/manuals for a place to put them.

Yes.  But that's a separate issue, not the one we discussed.


[-- Attachment #2: Type: text/html, Size: 6460 bytes --]

SES manual French translation (Re: Where to contribute manual translations ?)

[Jean-Christophe Helary]

Nice start for the new year :)

Hello Vincent,

> On Jan 1, 2024, at 9:27, Vincent Belaïche <vincent.b.1@hotmail.fr> wrote:
> 
> Hello,
> 
> I have pushed the French translation of SES manual to master,

It seems like you left French parts in the English manual as "todo 
items".

For ex. l.168-210.

https://git.savannah.gnu.org/cgit/emacs.git/tree/doc/misc/ses.texi#n168

Even if they're tagged as @ignore, I'm not sure that's good practice 
for potential translators to other languages.

There are quite a few errors that could have been avoided by a 
spelling/grammatical check. LanguageTool can be used in Emacs for this. 
It is quite convenient. Here are a few :

c-à-d. → c.-à-d.
Les valeurs des cellules sont spécifiés → spécifiées
varaiables → variables

There are inconsistencies between infinitive form and imperative form 
to describe actions. Etc.

Let me really suggest that we organize a proper process to 
translate/proofread/commit, similar to what other big free software 
endeavors have.

The Savannah project is dead. We can create another one, discuss our 
issues there and push the deliverables to the Emacs repo when they are 
ready.

-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Eli Zaretskii]

> Date: Mon, 01 Jan 2024 07:57:01 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,
>  "stefankangas@gmail.com" <stefankangas@gmail.com>,
>  "emacs-devel@gnu.org" <emacs-devel@gnu.org>, Richard Stallman <rms@gnu.org>
> 
> It seems like you left French parts in the English manual as "todo 
> items".
> 
> For ex. l.168-210.
> 
> https://git.savannah.gnu.org/cgit/emacs.git/tree/doc/misc/ses.texi#n168
> 
> Even if they're tagged as @ignore, I'm not sure that's good practice 
> for potential translators to other languages.

Those should be moved to ses-fr.texi, possibly together with the
original English text and some references to it.  Keeping those
comments in ses.texi is not TRT.

> The Savannah project is dead. We can create another one, discuss our 
> issues there and push the deliverables to the Emacs repo when they are 
> ready.

Why not discuss it here and install any changes you agree upon
directly?  I'd prefer not to have a separate intermediate repository,
as that would complicate maintenance, especially if other French
speakers join the effort.

Thanks.

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Jean-Christophe Helary]

> On Jan 1, 2024, at 21:22, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Date: Mon, 01 Jan 2024 07:57:01 +0000
>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> Cc: Eli Zaretskii <eliz@gnu.org>,
>> "stefankangas@gmail.com" <stefankangas@gmail.com>,
>> "emacs-devel@gnu.org" <emacs-devel@gnu.org>, Richard Stallman <rms@gnu.org>
>> 
>> It seems like you left French parts in the English manual as "todo
>> items".
>> 
>> For ex. l.168-210.
>> 
>> https://git.savannah.gnu.org/cgit/emacs.git/tree/doc/misc/ses.texi#n168
>> 
>> Even if they're tagged as @ignore, I'm not sure that's good practice
>> for potential translators to other languages.
> 
> Those should be moved to ses-fr.texi, possibly together with the
> original English text and some references to it.  Keeping those
> comments in ses.texi is not TRT.

TRT? The right thing?

>> The Savannah project is dead. We can create another one, discuss our
>> issues there and push the deliverables to the Emacs repo when they are
>> ready.
> 
> Why not discuss it here and install any changes you agree upon
> directly?  I'd prefer not to have a separate intermediate repository,
> as that would complicate maintenance, especially if other French
> speakers join the effort.

Sure. I don’t see any problem discussing French grammatical issues here 
and having committers directly install files, of course.

My opinion is that translators should not work directly in texi format, 
for the reasons that I mentioned earlier in the thread, namely because 
emacs documentation evolves quickly and all the problems identified in 
such localization/translation processes have found solutions with PO 
based translation processes.

If we were to have a robust translation process within the emacs 
repository (and there is no reason why we can’t, since all the major 
free software endeavours around have one), we’d need an intermediate 
location where PO files are generated (with po4a) as the documentation 
evolves. And translators would update the translations found there, and 
there would be a process that converts back the translations to texi 
and puts them in the proper location (the one that was decided upon 
here).

If we were to do that within the emacs repository/development process 
that would mean adding a dependency to po4a, having an automated 
process that triggers po4a when a documentation file is modified, 
triggering po4a when a po has been committed to convert the file back 
to texi, and copying the proper files to the emacs docs files hierarchy.

Or maybe we could have that done manually (I could install the PO files 
in a dedicated repository when I see modifications to a file).

I’m talking about that when I say “other repository”. What I’m doing in 
my repo is basically providing PO files semi-regularly to people who are 
interested and I happen to translate the PO files in OmegaT (but that’s 
not relevant to the process really since one could use po-mode in emacs). 
It’s also the way other projects work. They “delegate” the process to 
specialized localization groups and each group has a few committers 
that handle the installation in the “mother” project.


-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Where to contribute manual translations ?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > You seem to be talking about how to organize a collection fo manuals
  > > about various manuals.  The plan you've proposed might make sense for
  > > its internal organization, but the crucial question is, WHERE WOULD WE
  > > PUT IT and who would run it?
  > > 
  > > If we want to put lots of GNU manuals on the web for general access,
  > > this should not e part of Emacs development.  The place for it is
  > > on gnu.org, but not as part of the Emacs pages.

  > We were discussing the places for the Texinfo sources and the
  > corresponding Info manuals.

That's _which formats_ -- but I'm asking, _which manuals_?

Is this meant to cover the manuals that we now distribute with Emacs>
Those plua a few selectde additional ones?  (Which ones?)
All GNU manuals?
All manuals in Texinfo that we would want the GNU system to contain?

The mail in this thread has amounted to hundreds of lines, so mostly I
could only skim it.  In that skimming I never saw anything which
touched on this, the most basic question.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

RE: SES manual French translation (Re: Where to contribute manual translations ?)

[Vincent Belaïche]

[-- Attachment #1: Type: text/plain, Size: 3094 bytes --]

Hello J-Ch,

>Nice start for the new year :)
>
>Hello Vincent,
>> On Jan 1, 2024, at 9:27, Vincent Belaïche <vincent.b.1@hotmail.fr> wrote:
>>
>> Hello,
>>
>> I have pushed the French translation of SES manual to master,
>
>It seems like you left French parts in the English manual as "todo
>items".
>
>For ex. l.168-210.
>
>https://git.savannah.gnu.org/cgit/emacs.git/tree/doc/misc/ses.texi#n168
>
>Even if they're tagged as @ignore, I'm not sure that's good practice
>for potential translators to other languages.

I did it this way, in order to keep both contents aligned and do not
loose any contributed text, whatever is between « @ignore » … « @end
ignore » anyway does not go to the output document, this remains only in
the source code. Note that in addition of the « @ignore » I've put a
TODO comment for the translator to know that there is some re-alignment
to do.

Also, this new text may still need some adjustment, so I was not too in
a hurry to translate it to English (and may be some good will with a
better command of English than mine can also do that :-P ). One of the
motivation of translating the manual to French was also to make it
easier for me to contribute to it, and once I am satisfied with the
text, propagate to the English version.
>
>There are quite a few errors that could have been avoided by a
>spelling/grammatical check. LanguageTool can be used in Emacs for this.
>It is quite convenient. Here are a few :
>
>c-à-d. → c.-à-d.
>Les valeurs des cellules sont spécifiés → spécifiées
>varaiables → variables

Thank-you for reporting that, I just fixed and pushed quite a number of
fixes. Actually, I must admit that I had not paid too much attention
(and even almost not at all) to this, as my first intention was to
provide a makeinfo-compiling ses-fr.texi for those interested in
upgrading the Makefile.in script and experimenting this upgrade.

BTW, in the Makefile.in patch which I provided in my previous email, I
also had to tamper with the org.texi generation as there was a version
check error.

>
>There are inconsistencies between infinitive form and imperative form
>to describe actions. Etc.

Which form do you recommend ? Probably in French using infinitive is
better, but sometimes I translated too litterally and used the
imperative, like the English do.
>
>Let me really suggest that we organize a proper process to
>translate/proofread/commit, similar to what other big free software
>endeavors have.
>
>The Savannah project is dead. We can create another one, discuss our
>issues there and push the deliverables to the Emacs repo when they are
>ready.
>

I think that I have to install OmegaT and experiment it before I can
reply to this suggestion. I am not going to have time for this before
quite some time. I let you know when I do that. Just be patient …

   V.

>--
>Jean-Christophe Helary @jchelary@emacs.ch
>https://traductaire-libre.org
>https://mac4translators.blogspot.com
>https://sr.ht/~brandelune/omegat-as-a-book/





[-- Attachment #2: Type: text/html, Size: 13588 bytes --]

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Eli Zaretskii]

> Date: Mon, 01 Jan 2024 12:56:42 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Vincent Belaïche <vincent.b.1@hotmail.fr>, stefankangas@gmail.com, emacs-devel@gnu.org, rms@gnu.org
> 
> >> https://git.savannah.gnu.org/cgit/emacs.git/tree/doc/misc/ses.texi#n168
> >> 
> >> Even if they're tagged as @ignore, I'm not sure that's good practice
> >> for potential translators to other languages.
> > 
> > Those should be moved to ses-fr.texi, possibly together with the
> > original English text and some references to it.  Keeping those
> > comments in ses.texi is not TRT.
> 
> TRT? The right thing?

Yes.

> My opinion is that translators should not work directly in texi format, 
> for the reasons that I mentioned earlier in the thread, namely because 
> emacs documentation evolves quickly and all the problems identified in 
> such localization/translation processes have found solutions with PO 
> based translation processes.

Finding an efficient way of updating translations of the manuals is a
worthy goal, but it's a separate issue.  At least in the case of
ses.texi (and many other manuals in doc/misc) the rate of changes is
quite low, as you can see from "git log".

> If we were to have a robust translation process within the emacs 
> repository (and there is no reason why we can’t, since all the major 
> free software endeavours around have one), we’d need an intermediate 
> location where PO files are generated (with po4a) as the documentation 
> evolves. And translators would update the translations found there, and 
> there would be a process that converts back the translations to texi 
> and puts them in the proper location (the one that was decided upon 
> here).

If and when you decide on doing that, I'm guessing that we will need
to keep the original "source" files for the translations in the Git
repository, and find a suitable way of producing *.texi from them.
I'm not sure po4a is the best alternative; we should probably consider
others as well and find what is best for us.

> If we were to do that within the emacs repository/development process 
> that would mean adding a dependency to po4a, having an automated 
> process that triggers po4a when a documentation file is modified, 
> triggering po4a when a po has been committed to convert the file back 
> to texi, and copying the proper files to the emacs docs files hierarchy.
> 
> Or maybe we could have that done manually (I could install the PO files 
> in a dedicated repository when I see modifications to a file).
> 
> I’m talking about that when I say “other repository”. What I’m doing in 
> my repo is basically providing PO files semi-regularly to people who are 
> interested and I happen to translate the PO files in OmegaT (but that’s 
> not relevant to the process really since one could use po-mode in emacs). 
> It’s also the way other projects work. They “delegate” the process to 
> specialized localization groups and each group has a few committers 
> that handle the installation in the “mother” project.

I think we cannot "delegate" anyone else to keep the sources for us.
GNU projects must keep all the sources as part of their tree, and the
release tarballs must include all the sources required to produce the
final products.  So keeping this in a separate repository as the means
of avoiding a dependency on some tool is not an acceptable solution
for us.

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: Eli Zaretskii <eliz@gnu.org>, "stefankangas@gmail.com"
> 	<stefankangas@gmail.com>, "emacs-devel@gnu.org" <emacs-devel@gnu.org>,
> 	Richard Stallman <rms@gnu.org>
> Date: Mon, 1 Jan 2024 15:40:57 +0000
> 
> >Even if they're tagged as @ignore, I'm not sure that's good practice
> >for potential translators to other languages.
> 
> I did it this way, in order to keep both contents aligned and do not
> loose any contributed text, whatever is between « @ignore » … « @end
> ignore » anyway does not go to the output document, this remains only in
> the source code. Note that in addition of the « @ignore » I've put a
> TODO comment for the translator to know that there is some re-alignment
> to do.

I understand, but please don't do that.  Please move this to the
French translation, and if you need to copy the English text or have a
reference to it, that's fine.  The English source of ses.texi should
not have any text that is specific to some translation of it, it is
incorrect to do that, and we should fix that ASAP.

Thanks.

RE: SES manual French translation (Re: Where to contribute manual translations ?)

[Vincent Belaïche]

[-- Attachment #1: Type: text/plain, Size: 2204 bytes --]

Dear Eli,

No problem, I did and pushed the clean-up you have required. There is nothing to move to the French translation, as this was extra material that I had only contributed yet in the French version while doing the translation, and that needed to be propagated to the English version, and to make this easier (like re-finding in the French version the whole context) I had included this text in ignored block in addition to have some comment indicated need for re-alignment.

  Vincent.
________________________________
De : emacs-devel-bounces+vincent.b.1=hotmail.fr@gnu.org <emacs-devel-bounces+vincent.b.1=hotmail.fr@gnu.org> de la part de Eli Zaretskii <eliz@gnu.org>
Envoyé : lundi 1 janvier 2024 17:09
À : Vincent Belaïche <vincent.b.1@hotmail.fr>
Cc : jean.christophe.helary@traductaire-libre.org <jean.christophe.helary@traductaire-libre.org>; stefankangas@gmail.com <stefankangas@gmail.com>; emacs-devel@gnu.org <emacs-devel@gnu.org>; rms@gnu.org <rms@gnu.org>
Objet : Re: SES manual French translation (Re: Where to contribute manual translations ?)

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: Eli Zaretskii <eliz@gnu.org>, "stefankangas@gmail.com"
>        <stefankangas@gmail.com>, "emacs-devel@gnu.org" <emacs-devel@gnu.org>,
>        Richard Stallman <rms@gnu.org>
> Date: Mon, 1 Jan 2024 15:40:57 +0000
>
> >Even if they're tagged as @ignore, I'm not sure that's good practice
> >for potential translators to other languages.
>
> I did it this way, in order to keep both contents aligned and do not
> loose any contributed text, whatever is between « @ignore » … « @end
> ignore » anyway does not go to the output document, this remains only in
> the source code. Note that in addition of the « @ignore » I've put a
> TODO comment for the translator to know that there is some re-alignment
> to do.

I understand, but please don't do that.  Please move this to the
French translation, and if you need to copy the English text or have a
reference to it, that's fine.  The English source of ses.texi should
not have any text that is specific to some translation of it, it is
incorrect to do that, and we should fix that ASAP.

Thanks.


[-- Attachment #2: Type: text/html, Size: 3802 bytes --]

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "jean.christophe.helary@traductaire-libre.org"
> 	<jean.christophe.helary@traductaire-libre.org>, "stefankangas@gmail.com"
> 	<stefankangas@gmail.com>, "emacs-devel@gnu.org" <emacs-devel@gnu.org>,
> 	"rms@gnu.org" <rms@gnu.org>
> Date: Mon, 1 Jan 2024 18:54:03 +0000
> 
> No problem, I did and pushed the clean-up you have required. There is nothing to move to the French
> translation, as this was extra material that I had only contributed yet in the French version while doing
> the translation, and that needed to be propagated to the English version, and to make this easier
> (like re-finding in the French version the whole context) I had included this text in ignored block in
> addition to have some comment indicated need for re-alignment.

Thanks.  If there's anything to be added to the English version, we
can do that as a separate commit.

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Stefan Kangas]

Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
writes:

>> Why not discuss it here and install any changes you agree upon
>> directly?  I'd prefer not to have a separate intermediate repository,
>> as that would complicate maintenance, especially if other French
>> speakers join the effort.
>
> Sure. I don’t see any problem discussing French grammatical issues here
> and having committers directly install files, of course.

I think it's fine to use our existing infrastructure for now.

If the volume gets too high/distracting, we can consider a separate
mailing list for the translation work.

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Jean-Christophe Helary]

> On Jan 2, 2024, at 1:00, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> Finding an efficient way of updating translations of the manuals is a
> worthy goal, but it's a separate issue.  At least in the case of
> ses.texi (and many other manuals in doc/misc) the rate of changes is
> quite low, as you can see from "git log".

It’s an issue I’m discussing here because you suggested that we discuss 
translation issues here :)

>> If we were to have a robust translation process within the emacs
>> repository (and there is no reason why we can’t, since all the major
>> free software endeavours around have one), we’d need an intermediate
>> location where PO files are generated (with po4a) as the documentation
>> evolves. And translators would update the translations found there, and
>> there would be a process that converts back the translations to texi
>> and puts them in the proper location (the one that was decided upon
>> here).
> 
> If and when you decide on doing that, I'm guessing that we will need
> to keep the original "source" files for the translations in the Git
> repository, and find a suitable way of producing *.texi from them.
> I'm not sure po4a is the best alternative; we should probably consider
> others as well and find what is best for us.

Do you have other alternatives in mind? I personally don’t have a 
preference for PO/po4a either but po4a is probably the best solution 
around for handling texi files at the moment. If the Emacs/TextInfo 
projects manage to provide a robust solution for translating the 
documentation that does not depend on po4a, that would be awesome, 
though.

What matters is that we have an intermediate format with bilingual 
chunks. The 2 main formats in the area are PO and XLIFF and for 
historical reasons the free software community is using PO.

XLIFF is better at associating reference data (previous similar 
translations, terminology) and works with associated XML standards (the 
“chunks” are based on SRX, terminology uses TBX, reference translations 
use TMX, etc.) but requires translation tools that understand all the 
underlying XML structure.

Both formats require a process similar to what gettext does with code 
files.

If we were not to use an intermediate format and directly use texi, 
we’d need a translation reference format, like TMX, but it could be 
translated PO files, since they share a similar structure. The 
translators would translate chunk by chunk and need a tool that 
identifies already translated chunks from the reference format and use 
them instead.

If we want a robust translation process, there is no way around using 
bilingual chunks at one point in the process, but I’m biased because 
translating is my job and the current processes revolve around that so 
maybe I’m not seeing things that are more obvious.

> I think we cannot "delegate" anyone else to keep the sources for us.
> GNU projects must keep all the sources as part of their tree, and the
> release tarballs must include all the sources required to produce the
> final products.  So keeping this in a separate repository as the means
> of avoiding a dependency on some tool is not an acceptable solution
> for us.

Oh. I had not thought about it that way. Interesting. Thank you.

My point was not about delegating to avoid a dependency on some tool so 
much as letting translator groups do things the way that’s best for 
them. That’s why I understand that there is a need to keep technical 
discussions here, but for obvious reasons most translations-related 
discussions should not take place here (and that’s also the reason why 
there is a user list for emacs).

I’d rather see all the infrastructure hosted within the Emacs project.



-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Jean-Christophe Helary]

> On Jan 2, 2024, at 8:06, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
> Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> writes:
> 
>>> Why not discuss it here and install any changes you agree upon
>>> directly?  I'd prefer not to have a separate intermediate repository,
>>> as that would complicate maintenance, especially if other French
>>> speakers join the effort.
>> 
>> Sure. I don’t see any problem discussing French grammatical issues here
>> and having committers directly install files, of course.
> 
> I think it's fine to use our existing infrastructure for now.
> 
> If the volume gets too high/distracting, we can consider a separate
> mailing list for the translation work.

I understand. Thank you. But I don’t think we should expect translators 
discussing translation issues to do that in English. That would be 
weird and not practical.

-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Jean-Christophe Helary]

> On Jan 2, 2024, at 0:40, Vincent Belaïche <vincent.b.1@hotmail.fr> wrote:
> 
> Hello J-Ch,
> 
> Also, this new text may still need some adjustment, so I was not too in
> a hurry to translate it to English (and may be some good will with a
> better command of English than mine can also do that :-P ). One of the
> motivation of translating the manual to French was also to make it
> easier for me to contribute to it, and once I am satisfied with the
> text, propagate to the English version.

I totally understand :)

> Thank-you for reporting that, I just fixed and pushed quite a number of
> fixes. Actually, I must admit that I had not paid too much attention
> (and even almost not at all) to this,

!!! :) OMG... :)

What about using a branch dedicated to proofreading? You’d push to that 
branch when you have something, inform the crowd with a relevant 
subject and interested parties in Cc and once the commits are accepted 
move things to master?

> as my first intention was to
> provide a makeinfo-compiling ses-fr.texi for those interested in
> upgrading the Makefile.in script and experimenting this upgrade.

Nice.

> Which form do you recommend ? Probably in French using infinitive is
> better, but sometimes I translated too litterally and used the
> imperative, like the English do.

It depends on the context.

https://vitrinelinguistique.oqlf.gouv.qc.ca/24208/la-grammaire/le-verbe/modes/imperatif/distinction-entre-limperatif-et-linfinitif

But it needs to be consistent.

> I think that I have to install OmegaT and experiment it before I can
> reply to this suggestion. I am not going to have time for this before
> quite some time. I let you know when I do that. Just be patient …

:) Considering what Eli suggests, which is very reasonable, I don’t 
think there will be a need to create another repository/project 
somewhere.

What matters is that we just find a process that allows us to 
(generally speaking) properly sync modifications in the English sources 
and only update the relevant parts of the French file. Right now, since 
there is no infrastructure in the emacs project to do that, there is a 
need to temporarily provide that outside the project, but once that’s 
settled we’ll be able to use processes provided here.

A number of files have already been translated on my repository, so it 
would be nice to be able to share that with you depending on your 
interest and slowly progress from there. Since I use PO files, you 
don’t really need to use OmegaT, but once you see what OmegaT brings to the 
process I think that you’ll be convinced that it’s a very nice approach 
to do translation work.

> >--
> >Jean-Christophe Helary @jchelary@emacs.ch
> >https://traductaire-libre.org
> >https://mac4translators.blogspot.com
> >https://sr.ht/~brandelune/omegat-as-a-book/

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Stefan Kangas]

Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
writes:

>> I think it's fine to use our existing infrastructure for now.
>>
>> If the volume gets too high/distracting, we can consider a separate
>> mailing list for the translation work.
>
> I understand. Thank you. But I don’t think we should expect translators
> discussing translation issues to do that in English. That would be
> weird and not practical.

I didn't think of that, but now that you have mentioned it you are
obviously correct.

Perhaps if the number of such discussions are anyways very small, we
could allow them in our bug tracker.

Where do these types of discussions take place now?  How many are
regularly participating in the French language translation effort?

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Jean-Christophe Helary]

> On Jan 2, 2024, at 9:32, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
> Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> writes:
> 
>>> I think it's fine to use our existing infrastructure for now.
>>> 
>>> If the volume gets too high/distracting, we can consider a separate
>>> mailing list for the translation work.
>> 
>> I understand. Thank you. But I don’t think we should expect translators
>> discussing translation issues to do that in English. That would be
>> weird and not practical.
> 
> I didn't think of that, but now that you have mentioned it you are
> obviously correct.
> 
> Perhaps if the number of such discussions are anyways very small, we
> could allow them in our bug tracker.
> 
> Where do these types of discussions take place now?  How many are
> regularly participating in the French language translation effort?

Currently, it's only Vincent and I, here.

As far as I remember, the emacs documentation French translation has 
actively stopped being a "project" in the very early 00's (the date of 
the last commit of the Savannah project Vincent mentioned).

I "took over" (for lack of a better word) a few years later, when I 
started to become interested in emacs, but nothing serious happened. 
That was within the traduc.org association (and NPO focusing on 
translating free software documentation). But the association is now 
not very active, although its members are still doing things here and 
there.

"We" were mainly organizing this:

https://traduc.org/FrontPage

Which includes the Gnu Translation Project:

http://translationproject.org/team/fr.html

I rebooted the emacs documentation project 3 years ago and, as I 
mentioned early in the thread, I use it as an internship project for 
students in technical translation MAs. So there are irregular 
discussions taking place in my repo list, but what I'm also aiming at 
with the internship is getting students used to various processes so 
generally speaking moving the discussions to a more emacs-centric place 
would be no problem at all.

Considering past discussions on this list and translation activity in 
other projects, I have no doubt that once the Emacs project offers some 
infrastructure to translate its documentation, there will be a lot of 
interest in a number of languages.

So, keeping the discussion here while we get the infrastructure ready is 
the best choice, I think, and considering the possibility to have a 
dedicated translator’s list in the medium term would be good.

-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Stefan Kangas]

Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
writes:

> Considering past discussions on this list and translation activity in
> other projects, I have no doubt that once the Emacs project offers some
> infrastructure to translate its documentation, there will be a lot of
> interest in a number of languages.
>
> So, keeping the discussion here while we get the infrastructure ready is
> the best choice, I think, and considering the possibility to have a
> dedicated translator’s list in the medium term would be good.

That sounds good, thanks.

Do you intend to work on the aforementioned infrastructure?

Re: Where to contribute manual translations ?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Who would collect this list, and verify that each one is done properly
  > > (for instance, in accord with the license)?

  > What does that entail, exactly?  I'm not aware of anything similar we
  > do with tutorial translations.

We get copyright assignment for tutorial translations, just as we do
for other contributionrs to Emacs.  We could do that for translations
of manuals, too.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Where to contribute manual translations ?

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: stefankangas@gmail.com, emacs-devel@gnu.org
> Date: Mon, 01 Jan 2024 22:17:15 -0500
> 
>   > > Who would collect this list, and verify that each one is done properly
>   > > (for instance, in accord with the license)?
> 
>   > What does that entail, exactly?  I'm not aware of anything similar we
>   > do with tutorial translations.
> 
> We get copyright assignment for tutorial translations, just as we do
> for other contributionrs to Emacs.  We could do that for translations
> of manuals, too.

We already do that.  So if copyright assignments are the only aspect
we should be aware of, we are already okay.  Your original comment
sounded more general.

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Jean-Christophe Helary]

> On Jan 2, 2024, at 12:14, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
> Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> writes:
> 
>> Considering past discussions on this list and translation activity in
>> other projects, I have no doubt that once the Emacs project offers some
>> infrastructure to translate its documentation, there will be a lot of
>> interest in a number of languages.
>> 
>> So, keeping the discussion here while we get the infrastructure ready is
>> the best choice, I think, and considering the possibility to have a
>> dedicated translator’s list in the medium term would be good.
> 
> That sounds good, thanks.
> 
> Do you intend to work on the aforementioned infrastructure?

If I understand all the implications and if it’s reasonably within my 
(possibly expendable) skill set, I’d love to help.

-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translation of manuals (was: SES manual French translation)

[Eli Zaretskii]

> Date: Mon, 01 Jan 2024 23:11:19 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: vincent.b.1@hotmail.fr, stefankangas@gmail.com, emacs-devel@gnu.org, rms@gnu.org
> 
> > On Jan 2, 2024, at 1:00, Eli Zaretskii <eliz@gnu.org> wrote:
> > 
> > Finding an efficient way of updating translations of the manuals is a
> > worthy goal, but it's a separate issue.  At least in the case of
> > ses.texi (and many other manuals in doc/misc) the rate of changes is
> > quite low, as you can see from "git log".
> 
> It’s an issue I’m discussing here because you suggested that we discuss 
> translation issues here :)

I just said it's a separate issue, not that it shouldn't be discussed
here.  I started a new thread.

> > If and when you decide on doing that, I'm guessing that we will need
> > to keep the original "source" files for the translations in the Git
> > repository, and find a suitable way of producing *.texi from them.
> > I'm not sure po4a is the best alternative; we should probably consider
> > others as well and find what is best for us.
> 
> Do you have other alternatives in mind?

Not at the moment, no.  And I'm not even sure this is our
Emacs-specific problem to solve.  If the GNU Project is going to
support translations of the manuals, the ways of doing that should be
discussed project-wide, probably on then Texinfo mailing list or at
least with the participation of the Texinfo developers.

> If we were not to use an intermediate format and directly use texi, 
> we’d need a translation reference format, like TMX, but it could be 
> translated PO files, since they share a similar structure. The 
> translators would translate chunk by chunk and need a tool that 
> identifies already translated chunks from the reference format and use 
> them instead.

We could for starters invent some simple technique of our own, like
markers within the Texinfo sources that identify small enough chunks
of text, or something similar.

And again: the rate of change of the misc manuals is quite low.  If
and when someone will decide to translate the Emacs user manual or the
ELisp reference manual, then we'll have a serious problem with keeping
up with the rate of changes.  But not before that.

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Eli Zaretskii]

> Date: Mon, 01 Jan 2024 23:14:20 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Eli Zaretskii <eliz@gnu.org>, Vincent Belaïche <vincent.b.1@hotmail.fr>, emacs-devel@gnu.org, rms@gnu.org
> 
> > I think it's fine to use our existing infrastructure for now.
> > 
> > If the volume gets too high/distracting, we can consider a separate
> > mailing list for the translation work.
> 
> I understand. Thank you. But I don’t think we should expect translators 
> discussing translation issues to do that in English. That would be 
> weird and not practical.

No one ever said that this list is limited to English.  You just need
to realize that writing in any other language will automatically
narrow the set of people who'd bother reading your posts.

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

>>> If and when you decide on doing that, I'm guessing that we will need
>>> to keep the original "source" files for the translations in the Git
>>> repository, and find a suitable way of producing *.texi from them.
>>> I'm not sure po4a is the best alternative; we should probably consider
>>> others as well and find what is best for us.
>> 
>> Do you have other alternatives in mind?
> 
> Not at the moment, no.  And I'm not even sure this is our
> Emacs-specific problem to solve.  If the GNU Project is going to
> support translations of the manuals, the ways of doing that should be
> discussed project-wide, probably on then Texinfo mailing list or at
> least with the participation of the Texinfo developers.

The GNU project is already supporting translation of documentation.

https://translationproject.org/extra/matrix.html

(TexInfo is there too)

>> If we were not to use an intermediate format and directly use texi,
>> we’d need a translation reference format, like TMX, but it could be
>> translated PO files, since they share a similar structure. The
>> translators would translate chunk by chunk and need a tool that
>> identifies already translated chunks from the reference format and use
>> them instead.
> 
> We could for starters invent some simple technique of our own, like
> markers within the Texinfo sources that identify small enough chunks
> of text, or something similar.

Markers are already here (TexInfo commands, end of sentence markers, 
etc.).

Some commands in TexInfo have translatable contents, others do not.
 
There are segmentation rule sets that are shared in the “industry” 
that have splitting rules and exception rules based on the source 
language (like “in English split on a period followed by a space” with 
exceptions such as “not after M. ”, etc.) Rules are based on regular 
expressions.

A rule is basically a set of “before the split” / “after the split” 
regex. Exceptions have a similar structure. They are treated first and 
“lock” a potential split. Then splitting rules are applied. You end up 
with a list of “segments”.


> And again: the rate of change of the misc manuals is quite low.  If
> and when someone will decide to translate the Emacs user manual or the
> ELisp reference manual, then we'll have a serious problem with keeping
> up with the rate of changes.  But not before that.

I’m sorry I did not make myself clear. *I* for one am working on it. 
There are about 2 million words in the various manuals and I’ve 
translated (or recycled) about 130,000. I’m focusing on the Emacs 
manual at the moment, and I sometimes do a few paragraphs in the Lisp 
reference or the introduction. I have barely touched the miscellaneous 
manuals.

The process I’m using is based on converting texi files to PO and then 
to translate the PO files with appropriate “computer aided translation” 
software.

I’m totally fine with the emacs project taking a totally different 
approach, but it’s not like free software translation teams have not 
already worked for decades on tested processes.

Honestly, the easiest way to handle the translation of Emacs documents 
would be to contact the TP project manager and to discuss what’s the 
best way to do that, while thinking of what kind of infrastructure we 
want on the emacs side to handle how to store/build all the translations.


-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 2, 2024, at 22:16, Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org> wrote:
> 
>> Not at the moment, no.  And I'm not even sure this is our
>> Emacs-specific problem to solve.  If the GNU Project is going to
>> support translations of the manuals, the ways of doing that should be
>> discussed project-wide, probably on then Texinfo mailing list or at
>> least with the participation of the Texinfo developers.
> 
> The GNU project is already supporting translation of documentation.
> 
> https://translationproject.org/extra/matrix.html
> 
> (TexInfo is there too)

Apologies. This is the message strings. NOT the documentation.

-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translation of manuals

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> And again: the rate of change of the misc manuals is quite low.  If
> and when someone will decide to translate the Emacs user manual or the
> ELisp reference manual, then we'll have a serious problem with keeping
> up with the rate of changes.  But not before that.

I think this might only be true of the SES manual and not of the others,
if my observation that many of them receive updates at roughly monthly
intervals is correct.  Taken alone this figure is not all that daunting,
but it is substantial enough that with the resources our translators
will be realistically capable of dedicating to the task of updating
them, they cannot match this rate of change, and the translations will
remain outdated most of the time.

Considering that several of the frequently updated manuals are merged
from external sources with their change history lost during transfer,
this rate probably doesn't reflect the true frequency of changes being
made to them.  On the contrary, it is much higher.

It doesn't help that the originals of a number of these manuals are also
written in a different markup language, and remain that way prior to
their compilation during the Emacs build process.

As such the question becomes whether we should be maintaining these
translations at all; here are some arguments as to why not:

Besides help2man (whose info page turns out to be far too small to be
worthy of consideration), there are no GNU projects in the business of
translating their manuals to languages not English.  The manual of most
interest to our users is the user manual, with the Lisp reference manual
a close second, and if we balk at translating these two, the purpose of
translating the small fry is defeated by the certainty that their
intended readership will already have read documentation in English.

What's more, there is a translation of our user manual being circulated
over the Internet _right now_ on sites bearing no relation to us:

  https://crowdin.com/project/emacs-manual-chinese

To all appearances it has lost most of its momentum, which is the
probable fate of any like translations that we should take charge of:
there's no reason to believe that merely providing accommodation for a
translation will magically increase interest in its upkeep to a level
sufficient to make it sustainable.

Maybe we should leave aspiring translators to author translations of our
manuals at their own pace.  It's no great loss if users have to search a
little, and will save us from ever distributing outdated manuals or
concerning ourselves with rescuing them when (not if) interest in them
diminishes to a level where it is not anymore possible to update them in
tandem with changes to their source documents.

Re: Translation of manuals (was: SES manual French translation)

[Eli Zaretskii]

> Date: Tue, 02 Jan 2024 13:16:53 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Vincent Belaïche <vincent.b.1@hotmail.fr>, stefankangas@gmail.com, emacs-devel@gnu.org, rms@gnu.org
> 
> > Not at the moment, no.  And I'm not even sure this is our
> > Emacs-specific problem to solve.  If the GNU Project is going to
> > support translations of the manuals, the ways of doing that should be
> > discussed project-wide, probably on then Texinfo mailing list or at
> > least with the participation of the Texinfo developers.
> 
> The GNU project is already supporting translation of documentation.
> 
> https://translationproject.org/extra/matrix.html
> 
> (TexInfo is there too)

AFAIK, that matrix shows the state of translation of message catalogs
of each project, which is not what we are talking about here.  If I'm
wrong, would you mind pointing me at the translated Info manuals of
the projects in the matrix?

> >> If we were not to use an intermediate format and directly use texi,
> >> we’d need a translation reference format, like TMX, but it could be
> >> translated PO files, since they share a similar structure. The
> >> translators would translate chunk by chunk and need a tool that
> >> identifies already translated chunks from the reference format and use
> >> them instead.
> > 
> > We could for starters invent some simple technique of our own, like
> > markers within the Texinfo sources that identify small enough chunks
> > of text, or something similar.
> 
> Markers are already here (TexInfo commands, end of sentence markers, 
> etc.).

I meant markers specifically for translators, so that it would be easy
to detect chunk(s) of text that was/were modified, and update their
translations.

> Some commands in TexInfo have translatable contents, others do not.

I didn't mean Texinfo commands, I meant mainly the plain text which is
85% of any Texinfo manual.

> Honestly, the easiest way to handle the translation of Emacs documents 
> would be to contact the TP project manager and to discuss what’s the 
> best way to do that, while thinking of what kind of infrastructure we 
> want on the emacs side to handle how to store/build all the translations.

That could also be a good idea.  Although TP is AFAIK mainly busy with
translating short messages, not large manuals of the kind we have in
Emacs.

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 2, 2024, at 22:35, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> The GNU project is already supporting translation of documentation.
>> 
>> https://translationproject.org/extra/matrix.html
>> 
>> (TexInfo is there too)
> 
> AFAIK, that matrix shows the state of translation of message catalogs
> of each project, which is not what we are talking about here.  If I'm
> wrong, would you mind pointing me at the translated Info manuals of
> the projects in the matrix?

As I just wrote, I stand corrected. The TP matrix is about message 
strings.

> I meant markers specifically for translators, so that it would be easy
> to detect chunk(s) of text that was/were modified, and update their
> translations.

Don't you think that would be a bit burdensome for authors? Or do you 
mean semi-automatically?

>> Honestly, the easiest way to handle the translation of Emacs documents
>> would be to contact the TP project manager and to discuss what’s the
>> best way to do that, while thinking of what kind of infrastructure we
>> want on the emacs side to handle how to store/build all the translations.
> 
> That could also be a good idea.  Although TP is AFAIK mainly busy with
> translating short messages, not large manuals of the kind we have in
> Emacs.

Do you mind if I send him a mail?

-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translation of manuals (was: SES manual French translation)

[Eli Zaretskii]

> Date: Tue, 02 Jan 2024 13:51:38 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Vincent Belaïche <vincent.b.1@hotmail.fr>, stefankangas@gmail.com, emacs-devel@gnu.org, rms@gnu.org
> 
> > I meant markers specifically for translators, so that it would be easy
> > to detect chunk(s) of text that was/were modified, and update their
> > translations.
> 
> Don't you think that would be a bit burdensome for authors? Or do you 
> mean semi-automatically?

If there are markers, then finding the chunks whose translations
should be updated could be scripted, yes.  It could be done with an
Emacs Lisp program, for example.

> >> Honestly, the easiest way to handle the translation of Emacs documents
> >> would be to contact the TP project manager and to discuss what’s the
> >> best way to do that, while thinking of what kind of infrastructure we
> >> want on the emacs side to handle how to store/build all the translations.
> > 
> > That could also be a good idea.  Although TP is AFAIK mainly busy with
> > translating short messages, not large manuals of the kind we have in
> > Emacs.
> 
> Do you mind if I send him a mail?

No, of course I don't mind.

Re: SES manual French translation (Re: Where to contribute manual translations ?)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I understand. Thank you. But I don’t think we should expect translators 
  > discussing translation issues to do that in English. That would be 
  > weird and not practical.

We have organized translation teams for www.gnu.org -- one for each language.
Perhaps we should do the same thing for translations of manuals.
Or perhaps the translators of manuals should join those teams.

I could ask some of those translators to join this discussion.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Where to contribute manual translations ?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > We get copyright assignment for tutorial translations, just as we do
  > for other contributionrs to Emacs.  We could do that for translations
  > of manuals, too.

I should correct what I said before.  If the manual is copyright FSF
and we want to include the translation in Emacs, we definitely should
get copyright assignments for the translation.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Translation of manuals (was: SES manual French translation)

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Tue, 02 Jan 2024 13:51:38 +0000
>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> Cc: Vincent Belaïche <vincent.b.1@hotmail.fr>, stefankangas@gmail.com, emacs-devel@gnu.org, rms@gnu.org
>>
>> > I meant markers specifically for translators, so that it would be easy
>> > to detect chunk(s) of text that was/were modified, and update their
>> > translations.
>>
>> Don't you think that would be a bit burdensome for authors? Or do you
>> mean semi-automatically?
>
> If there are markers, then finding the chunks whose translations
> should be updated could be scripted, yes.  It could be done with an
> Emacs Lisp program, for example.

A "chunk" here means something like a sentence, or even smaller.  It is
therefore impractical to add such markers to the source text.

Translating Emacs manuals is of strategic importance

[Stefan Kangas]

Po Lu <luangruo@yahoo.com> writes:

> The manual of most interest to our users is the user manual, with the
> Lisp reference manual a close second, and if we balk at translating
> these two, the purpose of translating the small fry is defeated by the
> certainty that their intended readership will already have read
> documentation in English.

It is exactly the opposite, in fact: you start with the small fry, and
work your way up from there.

Few people start a project like "let's translate the ELisp manual",
whereas some might say something like "let's translate the ERT manual".
Then they get confidence and move on to bigger tasks.

> What's more, there is a translation of our user manual being circulated
> over the Internet _right now_ on sites bearing no relation to us:
>
>   https://crowdin.com/project/emacs-manual-chinese

It would have been much better if that had already been copyright
assigned to the FSF and merged into Emacs.

> there's no reason to believe that merely providing accommodation for a
> translation will magically increase interest in its upkeep to a level
> sufficient to make it sustainable.
>
> Maybe we should leave aspiring translators to author translations of our
> manuals at their own pace.  It's no great loss if users have to search a
> little, and will save us from ever distributing outdated manuals or
> concerning ourselves with rescuing them when (not if) interest in them
> diminishes to a level where it is not anymore possible to update them in
> tandem with changes to their source documents.

We don't need to "magically increase interest" for this work to be
useful, however.  An outdated manual in a language you can read is
infinitely more useful than a bleeding edge one in one that you can't.
We just have to make sure to date it or say which version it covers.

Furthermore, even a halfway house gives a starting point for someone to
continue the work later.

We have huge number of potential users that do not speak English
fluently to the level where they're able to read our manuals.  Thus,
translating manuals to other languages has strategic importance, if we
want to promote Emacs and free software.  Therefore, I think that we
should not take a defeatist stance here.

While we might currently lack the resources to lead the charge, we
should not discourage people interested in doing the work.  On the
contrary.

Re: Where to contribute manual translations ?

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Tue, 02 Jan 2024 23:12:30 -0500
> 
>   > We get copyright assignment for tutorial translations, just as we do
>   > for other contributionrs to Emacs.  We could do that for translations
>   > of manuals, too.
> 
> I should correct what I said before.  If the manual is copyright FSF
> and we want to include the translation in Emacs, we definitely should
> get copyright assignments for the translation.

Yes, of course.  And we do, as I said.

Re: Translation of manuals (was: SES manual French translation)

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Tue, 2 Jan 2024 20:38:27 -0800
> Cc: vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Date: Tue, 02 Jan 2024 13:51:38 +0000
> >> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> >> Cc: Vincent Belaïche <vincent.b.1@hotmail.fr>, stefankangas@gmail.com, emacs-devel@gnu.org, rms@gnu.org
> >>
> >> > I meant markers specifically for translators, so that it would be easy
> >> > to detect chunk(s) of text that was/were modified, and update their
> >> > translations.
> >>
> >> Don't you think that would be a bit burdensome for authors? Or do you
> >> mean semi-automatically?
> >
> > If there are markers, then finding the chunks whose translations
> > should be updated could be scripted, yes.  It could be done with an
> > Emacs Lisp program, for example.
> 
> A "chunk" here means something like a sentence, or even smaller.  It is
> therefore impractical to add such markers to the source text.

If chunks were sentences, that would be impractical, indeed.  But I
very much doubt that this is a good idea for translating manuals
(message catalogs use short phrases because most messages in programs
are themselves short phrases or single sentences).  Translating a
sentence out of its context is much harder than translating a whole
paragraph, because different languages have different ways of
explaining technical issues, and a good translation might well require
rearrange or rewrite sentences.

So my initial thinking was that whole paragraphs, and sometimes more,
should be marked as a unit.  And that is much more practical than
marking short phrases or single sentences.

Re: Translating Emacs manuals is of strategic importance

[Po Lu]

Stefan Kangas <stefankangas@gmail.com> writes:

> It is exactly the opposite, in fact: you start with the small fry, and
> work your way up from there.
>
> Few people start a project like "let's translate the ELisp manual",
> whereas some might say something like "let's translate the ERT manual".
> Then they get confidence and move on to bigger tasks.

This places excessive weight on the abstract objective of promoting
users' self-assurance, in an area where we should instead be evaluating
immediate benefit.  Not to mention that potential contributors are
assuredly posessed of the confidence to embark on larger tasks such as
translating the user or Lisp reference manuals, as the translation I
linked earlier shows.

The danger in accepting such translations is not a potential shortage of
contributors _willing_ to take up their upkeep whom we might attract by
distributing them under our own seal of approval, it is the motivation
and ability of such contributors (many of whom have offered us their
services) to carry such tasks to completion.  Without this we will land
ourselves with a collection of incomplete manuals and accountability for
their faults, which will place yet more strain on an already-burdened
group of contributors, none of whom, I trust, can dedicate enough of
their time to maintaining such manuals in just the languages widely
spoken in technical circles (i.e. German, French, Russian, Hebrew), let
alone each and every language that might see interest expressed in being
the target of a translation of the Emacs manual, or that our users
speak.

> It would have been much better if that had already been copyright
> assigned to the FSF and merged into Emacs.

To me, it rather seems as though we would be better off _without_
overreaching ourselves by merging a partial translation that has not
seen activity in two years in the expectation of someone volunteering to
complete it.

> We don't need to "magically increase interest" for this work to be
> useful, however.  An outdated manual in a language you can read is
> infinitely more useful than a bleeding edge one in one that you can't.
> We just have to make sure to date it or say which version it covers.
>
> Furthermore, even a halfway house gives a starting point for someone to
> continue the work later.

There is nothing to suggest that users cannot locate an outdated or
incomplete manual over the Internet.  I don't dispute that they serve a
worthwhile (if not crucial) purpose, my reservations are that we should
not take _responsibility_ for them while being fully aware of factors
that make for a very real chance that they won't deliver.  Then if the
time comes when interest in them does increase such that it becomes
sound for us to assume that responsibility, we can always revisit any
decisions that might have been made up to that time.

> We have huge number of potential users that do not speak English
> fluently to the level where they're able to read our manuals.  Thus,
> translating manuals to other languages has strategic importance, if we
> want to promote Emacs and free software.

Nowhere did I deny this, but see below.

> Therefore, I think that we should not take a defeatist stance here.
> While we might currently lack the resources to lead the charge, we
> should not discourage people interested in doing the work.  On the
> contrary.

Being realistic in our estimate of our own capabilities is not
defeatism, nor is requesting that interested participants stage their
work separately discouraging, which incidentally won't preclude
obtaining copyright assignment for such work should it ever come to
that.

TIA.

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 3, 2024, at 22:06, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Stefan Kangas <stefankangas@gmail.com>
>> Date: Tue, 2 Jan 2024 20:38:27 -0800
>> Cc: vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>>>> Date: Tue, 02 Jan 2024 13:51:38 +0000
>>>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>>>> Cc: Vincent Belaïche <vincent.b.1@hotmail.fr>, stefankangas@gmail.com, emacs-devel@gnu.org, rms@gnu.org
>>>> 
>>>>> I meant markers specifically for translators, so that it would be easy
>>>>> to detect chunk(s) of text that was/were modified, and update their
>>>>> translations.
>>>> 
>>>> Don't you think that would be a bit burdensome for authors? Or do you
>>>> mean semi-automatically?
>>> 
>>> If there are markers, then finding the chunks whose translations
>>> should be updated could be scripted, yes.  It could be done with an
>>> Emacs Lisp program, for example.
>> 
>> A "chunk" here means something like a sentence, or even smaller.  It is
>> therefore impractical to add such markers to the source text.
> 
> If chunks were sentences, that would be impractical, indeed.  But I
> very much doubt that this is a good idea for translating manuals
> (message catalogs use short phrases because most messages in programs
> are themselves short phrases or single sentences).  Translating a
> sentence out of its context is much harder than translating a whole
> paragraph, because different languages have different ways of
> explaining technical issues, and a good translation might well require
> rearrange or rewrite sentences.

Indeed. But “marking” sentences does not mean that they can’t be 
translated by using different structures. A practical example for that 
is when translating 2 sentences with one sentence with two parts 
separated by a comma.

Also, translating a sentence never happens out of its context. There is 
the sentence before and the sentence after and all are visually present 
during the translation. So it’s easy for the translator to take the 
context into account.

There are some sentences that will take a wholly different meaning 
depending on the context, but such sentences are usually short 
*and* less attached to the context, so they do need special treatment. 
But that’s considered during the translation process.

I understand that you have some translating experience, but I am not 
sure that we see the same issues.

> So my initial thinking was that whole paragraphs, and sometimes more,
> should be marked as a unit.  And that is much more practical than
> marking short phrases or single sentences.

I’m not sure I understand what kind of marks you envision. Paragraphs 
are already marked by surrounding empty lines.

-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translation of manuals (was: SES manual French translation)

[Eli Zaretskii]

> Date: Wed, 03 Jan 2024 13:30:44 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Stefan Kangas <stefankangas@gmail.com>, Vincent Belaïche <vincent.b.1@hotmail.fr>, emacs-devel@gnu.org, rms@gnu.org
> 
> > If chunks were sentences, that would be impractical, indeed.  But I
> > very much doubt that this is a good idea for translating manuals
> > (message catalogs use short phrases because most messages in programs
> > are themselves short phrases or single sentences).  Translating a
> > sentence out of its context is much harder than translating a whole
> > paragraph, because different languages have different ways of
> > explaining technical issues, and a good translation might well require
> > rearrange or rewrite sentences.
> 
> Indeed. But “marking” sentences does not mean that they can’t be 
> translated by using different structures. A practical example for that 
> is when translating 2 sentences with one sentence with two parts 
> separated by a comma.
> 
> Also, translating a sentence never happens out of its context. There is 
> the sentence before and the sentence after and all are visually present 
> during the translation. So it’s easy for the translator to take the 
> context into account.

If context is important when translating technical documentation (and
it is IME), then any change in a paragraph will in many cases affect
more than the sentence corresponding to the one modified in English.

Moreover, a good translation of a paragraph will in many cases produce
a translated paragraph without 1:1 correspondence between sentences.
So changes in the original will need to consider much more than a
single sentence anyway.

> I understand that you have some translating experience, but I am not 
> sure that we see the same issues.
> 
> > So my initial thinking was that whole paragraphs, and sometimes more,
> > should be marked as a unit.  And that is much more practical than
> > marking short phrases or single sentences.
> 
> I’m not sure I understand what kind of marks you envision. Paragraphs 
> are already marked by surrounding empty lines.

I mean, for example, give each paragraph a number, like so:

@node Display Margins
  @subsection Displaying in the Margins
  @cindex display margins
  @cindex margins, display

  @c para 1234
    A buffer can have blank areas called @dfn{display margins} on the
  left and on the right.  Ordinary text never appears in these areas,
  but you can put things into the display margins using the
  @code{display} property.  There is currently no way to make text or
  images in the margin mouse-sensitive.

  @c para 1235
    The way to display something in the margins is to specify it in a
  margin display specification in the @code{display} property of some
  text.  This is a replacing display specification, meaning that the
  text you put it on does not get displayed; the margin display appears,
  but that text does not.

  @c para 1236
    A margin display specification looks like @code{((margin
  right-margin) @var{spec})} or @code{((margin left-margin) @var{spec})}.
  Here, @var{spec} is another display specification that says what to
  display in the margin.  Typically it is a string of text to display,
  or an image descriptor.

When paragraph #1234 in the English original was modified, translators
will know that they need to update the translation of the
corresponding paragraph(s) (could be more than one) in their
translations, and nothing else.  It should be easy to analyze the
diffs, look for the "@c para NNNN" marks, and present the translator
with the corresponding paragraph(s) from the translation.

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 3, 2024, at 22:53, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> If context is important when translating technical documentation (and
> it is IME), then any change in a paragraph will in many cases affect
> more than the sentence corresponding to the one modified in English.
> 
> Moreover, a good translation of a paragraph will in many cases produce
> a translated paragraph without 1:1 correspondence between sentences.
> So changes in the original will need to consider much more than a
> single sentence anyway.

I’m not sure this is the place to discuss translation theory and as a 
practitioner who pays my bills mostly with translation I can say with 
confidence that over the millions of words I’ve translated in more than 
20 years (including published translations), there are only few cases 
where I needed to fundamentally alter the structure of a paragraph.

Working both from Japanese and English to French on contracts varying 
for poetry to electronic circuitry, I think my experience is wide 
enough that I can assert this: in a time of dehumanization of whatever 
technology touches, it’s OK for translators to say that a good 
translation often requires changing a lot of things. In practice, 
though, paragraph structure is rarely where change happens. Simply 
because it is easier to make a good translation by respecting paragraph 
structure. Now experience may vary, and different language pairs may 
require different arrangements.

>> I’m not sure I understand what kind of marks you envision. Paragraphs
>> are already marked by surrounding empty lines.
> 
> I mean, for example, give each paragraph a number, like so:

Ok, so the markers are IDs.

> @node Display Margins
>  @subsection Displaying in the Margins
>  @cindex display margins
>  @cindex margins, display

As long as the above strings are to be translated, they need an ID too.

>  @c para 1234
> 
>  @c para 1235
> 
>  @c para 1236

Is the numbering automatic?

What if you add paragraphs in the middle, like Vincent did? Will the 
author have to check the IDs and add a number that’s not used already?

There are plenty of issues with static IDing parts of a document.

Here is the way po4a "transforms" the paragraphs that you used as an example:

#. type: Plain text
#: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs -
#: Sources/doc/lispref/display.texi:5613
msgid ""
"A buffer can have blank areas called @dfn{display margins} on the left and "
"on the right.  Ordinary text never appears in these areas, but you can put "
"things into the display margins using the @code{display} property.  There is "
"currently no way to make text or images in the margin mouse-sensitive."
msgstr ""

#. type: Plain text
#: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs -
#: Sources/doc/lispref/display.texi:5619
msgid ""
"The way to display something in the margins is to specify it in a margin "
"display specification in the @code{display} property of some text.  This is "
"a replacing display specification, meaning that the text you put it on does "
"not get displayed; the margin display appears, but that text does not."
msgstr ""

#. type: Plain text
#: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs -
#: Sources/doc/lispref/display.texi:5625
msgid ""
"A margin display specification looks like @code{((margin right-margin) "
"@var{spec})} or @code{((margin left-margin) @var{spec})}.  Here, @var{spec} "
"is another display specification that says what to display in the margin.  "
"Typically it is a string of text to display, or an image descriptor."
msgstr ""

The ID is the paragraph. Which makes sense, because translators can 
know that a paragraph has not been translated because its ID is not 
associated with contents.

> When paragraph #1234 in the English original was modified, translators
> will know that they need to update the translation of the
> corresponding paragraph(s) (could be more than one) in their
> translations, and nothing else.  It should be easy to analyze the
> diffs, look for the "@c para NNNN" marks, and present the translator
> with the corresponding paragraph(s) from the translation.

I think po-mode already does that and all the "out of emacs" tools do 
too.

-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translating Emacs manuals is of strategic importance

[Stefan Kangas]

Po Lu <luangruo@yahoo.com> writes:

> The danger in accepting such translations is not a potential shortage of
> contributors _willing_ to take up their upkeep whom we might attract by
> distributing them under our own seal of approval, it is the motivation
> and ability of such contributors (many of whom have offered us their
> services) to carry such tasks to completion.  Without this we will land
> ourselves with a collection of incomplete manuals and accountability for
> their faults, which will place yet more strain on an already-burdened
> group of contributors, none of whom, I trust, can dedicate enough of
> their time to maintaining such manuals in just the languages widely
> spoken in technical circles (i.e. German, French, Russian, Hebrew), let
> alone each and every language that might see interest expressed in being
> the target of a translation of the Emacs manual, or that our users
> speak.

If I understand you correctly, your concern is that we will be
responsible for the translations.  To me, that would imply that we will
have to spend significant time maintaining them.  But I don't think it
will be like that in practice.  Instead, we have to make it clear that
the translation teams (often: interested individuals) for the respective
languages will be responsible for the translations.

Furthermore, only the English manual can be considered canonical for the
foreseeable future, since we cannot proofread translations like we do
with the English one.  It therefore makes a lot of sense to add suitable
disclaimers (dates, version numbers, etc.) to the translated manuals.

We could perhaps consider having several "tiers" of manuals: one
"nursery" for those are not yet meaningfully ready for distribution, one
"attic" for those that are no longer reasonably maintained, and one for
those that we actually do consider up to scratch.  The decision for what
goes where could be based on a dialogue between the maintainers and the
translators of various manuals.

> There is nothing to suggest that users cannot locate an outdated or
> incomplete manual over the Internet.  I don't dispute that they serve a
> worthwhile (if not crucial) purpose, my reservations are that we should
> not take _responsibility_ for them while being fully aware of factors
> that make for a very real chance that they won't deliver.  Then if the
> time comes when interest in them does increase such that it becomes
> sound for us to assume that responsibility, we can always revisit any
> decisions that might have been made up to that time.

I believe that the moment will _never_ present itself when we are sent a
patch containing a fully translated, high-quality and up-to-date manual
backed with an active team of translators, copyright assigned and ready
to be merged.  We have to build things up over time, and preferably in
communication with the translators themselves.

From the outside, it is likely that the impression is that we are rather
uninterested in translating Emacs to other languages.  The fact that
there are fully translated materials distributed elsewhere speaks to
that.  If we double down on a workflow where we are happy to see manuals
translated, but do not want to distribute them, then that impression
will be cemented.

On the other hand, if we already had the infrastructure in place for
translations, it would be more clear that we are, in fact, interested.
This would be true even if we had only a small handful of manuals or
work-in-progress translations there: at least we would have a framework.

Our obviously central position in the Emacs world means that this in
itself could help promote these efforts, and hopefully also encourage
volunteers to take on translation work.

> Being realistic in our estimate of our own capabilities is not
> defeatism, nor is requesting that interested participants stage their
> work separately discouraging, which incidentally won't preclude
> obtaining copyright assignment for such work should it ever come to
> that.

It was not my intention to call your stance defeatist, but rather to
warn against it, since the current situation is neither fixed nor
impossible to change.  I apologize if I was being unclear.

I'm interested in hearing what people think about this, but if
Jean-Christophe and others intend to set up the relevant infrastructure
in emacs.git, I think we should try to encourage that.

I do think it is important that we are careful to set things up in such
a way that the translating work isn't too disruptive for regular Emacs
development.  Personally, I also would like to never have to see the
French translations in the course of my usage of Emacs: only users that
ask for it specifically, or use a French locale should see them.

Re: Translating Emacs manuals is of strategic importance

[Jean-Christophe Helary]

Thank you Stefan for Ccing this very interesting exchange.

> On Jan 4, 2024, at 13:46, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
> I'm interested in hearing what people think about this, but if
> Jean-Christophe and others intend to set up the relevant infrastructure
> in emacs.git, I think we should try to encourage that.

I’m hoping that Eli will see the benefit of the PO format, the way it 
is (currently) prepared by po4a, even if the Emacs and TexInfo projects 
end up creating a different but relatively compatible tool/process.

Using PO for the manuals will bring to the Emacs community a 
considerable number of qualified and experienced free software 
translator teams.

It will also have the benefit of allowing the easy conversion of 
already existing translations so that they can be provided to teams who 
want to update them.

> I do think it is important that we are careful to set things up in such
> a way that the translating work isn't too disruptive for regular Emacs
> development.

Now that, thanks to Vincent, we have a location for the texi 
translations, I think the next step is simply to make an announcement 
about that (if I had known it would be that simple to actually get the 
ball rolling, I would have proposed that a long time ago).

If, after careful evaluation, a system that provides automatic po (or 
equivalent) files is established, that would allow translator teams to 
rely on Emacs infrastructure and provide an even better workflow for 
teams, one similar to what they are used to in similar important free 
software packages (I’m thinking of gnu/linux distribution 
documentation, of LibreOffice, etc.)

> Personally, I also would like to never have to see the
> French translations in the course of my usage of Emacs: only users that
> ask for it specifically, or use a French locale should see them.

I have honestly no idea how to modify Emacs so that it offers a choice 
of manual languages to users. But once the manuals are provided in texi 
format and build into info files, they should be easy to install and 
peruse by anybody (even if a tutorial maybe necessary).

Also, I fully agree with you about the strategic importance of having 
Emacs and the related manuals translated. Emacs is not anymore a 
developer-only system and a considerable number of users who are not 
scared of learning exotic tools would dive into it and write easy 
automation thanks to the introduction to emacs lisp. That’s a huge 
chance for free software.


-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translation of manuals (was: SES manual French translation)

[Eli Zaretskii]

> Date: Wed, 03 Jan 2024 23:14:13 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: stefankangas@gmail.com, vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org
> 
> > On Jan 3, 2024, at 22:53, Eli Zaretskii <eliz@gnu.org> wrote:
> > 
> > If context is important when translating technical documentation (and
> > it is IME), then any change in a paragraph will in many cases affect
> > more than the sentence corresponding to the one modified in English.
> > 
> > Moreover, a good translation of a paragraph will in many cases produce
> > a translated paragraph without 1:1 correspondence between sentences.
> > So changes in the original will need to consider much more than a
> > single sentence anyway.
> 
> I’m not sure this is the place to discuss translation theory and as a 
> practitioner who pays my bills mostly with translation I can say with 
> confidence that over the millions of words I’ve translated in more than 
> 20 years (including published translations), there are only few cases 
> where I needed to fundamentally alter the structure of a paragraph.

My experience, while certainly smaller than yours, is the opposite.
Perhaps it's because you implicitly assume that the original text was
structured and divided into sentences in the most optimal sense,
whereas I many times find it not to be so, and my translations are
therefore explain the subject better (IMO) than the original and their
structure is more logical.  And that's even before we consider the
fact that the optimal structure in general depends on the language.

> Working both from Japanese and English to French on contracts varying 
> for poetry to electronic circuitry, I think my experience is wide 
> enough that I can assert this: in a time of dehumanization of whatever 
> technology touches, it’s OK for translators to say that a good 
> translation often requires changing a lot of things. In practice, 
> though, paragraph structure is rarely where change happens. Simply 
> because it is easier to make a good translation by respecting paragraph 
> structure. Now experience may vary, and different language pairs may 
> require different arrangements.

IME, I read a sizeable chunk of text first, and then express the ideas
in that chunk the best I can.  Sentence by sentence translation is
something I frequently find to be inadequate.

There are also specific difficulties with terminology: where some term
sounds very differently, grammar-wise, in another language, there's no
other way than to restructure the sentences to make the text sound
natural in its language.  Language grammar can also get in the way:
some languages have 3 genders, other only 2; the use of construct
state has different rules in different languages; etc.  Catering to
these differences alone will many times necessitate changes in
sentence order and paragraph structure, to avoid text that reads like
it was written in another language or translated by the likes of
Google Translate.

> > @node Display Margins
> >  @subsection Displaying in the Margins
> >  @cindex display margins
> >  @cindex margins, display
> 
> As long as the above strings are to be translated, they need an ID too.

Not necessarily.  These present special issues in Texinfo, to be
resolved in some reasonable way.  For example, if node names are
translated, pointers to them will stop working, so there's a problem
right there.  Index entries should be translated, of course, but they
are their own paragraph, I think, as they rarely change together.
Section names are also a paragraph of their own.

> >  @c para 1234
> > 
> >  @c para 1235
> > 
> >  @c para 1236
> 
> Is the numbering automatic?

If a tool exists that aids this process, then definitely.  E.g., a
Lisp program.

> What if you add paragraphs in the middle, like Vincent did? Will the 
> author have to check the IDs and add a number that’s not used already?

The author or a tool, yes.

> There are plenty of issues with static IDing parts of a document.

Sure.  We are in uncharted territory here, so issues are a legion.

> The ID is the paragraph. Which makes sense, because translators can 
> know that a paragraph has not been translated because its ID is not 
> associated with contents.

Translation is a human job, and translating a manual is more so,
because the context is much more important than when translating short
phrases.  So it seems to me that seeing diffs in terms of paragraphs
using a format where the markers are only used to detect changes, and
the rest are text differences, is better than using the PO methods,
where the comparison with the previous version is much harder because
PO decorations are much more massive.

But we certainly should consider using PO as one possible alternative.

> > When paragraph #1234 in the English original was modified, translators
> > will know that they need to update the translation of the
> > corresponding paragraph(s) (could be more than one) in their
> > translations, and nothing else.  It should be easy to analyze the
> > diffs, look for the "@c para NNNN" marks, and present the translator
> > with the corresponding paragraph(s) from the translation.
> 
> I think po-mode already does that and all the "out of emacs" tools do 
> too.

Maybe so.  But I wouldn't assume that PO could be easily stretched to
this kind of jobs, since it wasn't originally designed for them.

Re: Translating Emacs manuals is of strategic importance

[Po Lu]

Stefan Kangas <stefankangas@gmail.com> writes:

> If I understand you correctly, your concern is that we will be
> responsible for the translations.  To me, that would imply that we will
> have to spend significant time maintaining them.  But I don't think it
> will be like that in practice.  Instead, we have to make it clear that
> the translation teams (often: interested individuals) for the respective
> languages will be responsible for the translations.
>
> Furthermore, only the English manual can be considered canonical for the
> foreseeable future, since we cannot proofread translations like we do
> with the English one.  It therefore makes a lot of sense to add suitable
> disclaimers (dates, version numbers, etc.) to the translated manuals.

If that be so, why is it of great importance for us to distribute these
translations ourselves, further undermining our public image by their
raw nature?

It is not worth inventing elaborate systems for classifying or
disclaiming manuals and judging which we are directly responsible for,
when another option is to simply refuse involvement in the development
of such non-essential manuals and leave the forces of interest to take
their course, to no detriment of actual readers.

> We could perhaps consider having several "tiers" of manuals: one
> "nursery" for those are not yet meaningfully ready for distribution, one
> "attic" for those that are no longer reasonably maintained, and one for
> those that we actually do consider up to scratch.  The decision for what
> goes where could be based on a dialogue between the maintainers and the
> translators of various manuals.

This scheme is far too complicated for the number of translations or
translators on the horizon.

> I believe that the moment will _never_ present itself when we are sent a
> patch containing a fully translated, high-quality and up-to-date manual
> backed with an active team of translators, copyright assigned and ready
> to be merged.  We have to build things up over time, and preferably in
> communication with the translators themselves.
>
> From the outside, it is likely that the impression is that we are rather
> uninterested in translating Emacs to other languages.  The fact that
> there are fully translated materials distributed elsewhere speaks to
> that.  If we double down on a workflow where we are happy to see manuals
> translated, but do not want to distribute them, then that impression
> will be cemented.
>
> On the other hand, if we already had the infrastructure in place for
> translations, it would be more clear that we are, in fact, interested.
> This would be true even if we had only a small handful of manuals or
> work-in-progress translations there: at least we would have a framework.
>
> Our obviously central position in the Emacs world means that this in
> itself could help promote these efforts, and hopefully also encourage
> volunteers to take on translation work.

You are speaking out of an interest in sending the message that
translations are welcome in Emacs to encourage the creation of new
translations, which is one potential means to an end, namely, to
encourage non-English speakers to learn Emacs.  This end is well-served
whether such manuals be distributed by us or not, under the condition
that they are complete and up-to-date, so the question of outside belief
regarding our priorities is immaterial, and their existence does no more
than attest to interest from translators.

However, the fact I was trying to emphasize is that the consistent
failure of such efforts arise not from an absence of interest, which is
plausibly addressable by promoting them ourselves, but a shortage of
time experienced by already-interested contributors that is beyond our
control, being more in the realm of rent and gas prices and suchlike,
and that it is best not to intercede in affairs and processes in a
manner that we are powerless to change them by, all the while
inconveniencing ourselves yet more.

> It was not my intention to call your stance defeatist, but rather to
> warn against it, since the current situation is neither fixed nor
> impossible to change.  I apologize if I was being unclear.

I don't disagree that it is possible to change, only that it is not by
our distributing miscellaneous translations before so much as the
distant prospect of a full translation of the prinicpal manuals emerges.

TIA.

Re: Translation of manuals (was: SES manual French translation)

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> There are plenty of issues with static IDing parts of a document.
>
> Sure.  We are in uncharted territory here, so issues are a legion.

I think the job will be easier if we use established tools and workflows
if at all possible.

>> I think po-mode already does that and all the "out of emacs" tools do
>> too.
>
> Maybe so.  But I wouldn't assume that PO could be easily stretched to
> this kind of jobs, since it wasn't originally designed for them.

IIUC, it's what Jean-Christophe's has already been using here:

    https://git.sr.ht/~brandelune/emacs_documentation_repository

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 4, 2024, at 15:34, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> My experience, while certainly smaller than yours, is the opposite.

I’m certainly not here to play an argument from authority game, so 
forget what I wrote. It is not relevant to the discussion at hand.

> Perhaps it's because you implicitly assume that the original text was
> structured and divided into sentences in the most optimal sense,

More pragmatically, it is because I am a freelance worker who is paid 
by the hour. I can’t allow myself to give more to the client than what 
I am paid for. I need to assume that the source document is of 
reasonable quality and that its intent is clear.

When I translate or otherwise contribute to free software projects, the 
ethics are slightly different, but that does not profoundly change the 
way I work.

>>> @node Display Margins
>>> @subsection Displaying in the Margins
>>> @cindex display margins
>>> @cindex margins, display
>> 
>> As long as the above strings are to be translated, they need an ID too.
> 
> Not necessarily.  These present special issues in Texinfo, to be
> resolved in some reasonable way.  For example, if node names are
> translated, pointers to them will stop working, so there's a problem
> right there.

In my current translation of the Emacs manual, I’m translating the 
nodes so that they make sense on their own. I agree their function is 
mostly to work as invisible keywords/link anchors, but if the 
translation is well done, that should not be an issue.

>  Index entries should be translated, of course, but they
> are their own paragraph, I think, as they rarely change together.
> Section names are also a paragraph of their own.
> 
>>> @c para 1234
>>> 
>>> @c para 1235
>>> 
>>> @c para 1236
>> 
>> Is the numbering automatic?
> 
> If a tool exists that aids this process, then definitely.  E.g., a
> Lisp program.
> 
>> What if you add paragraphs in the middle, like Vincent did? Will the
>> author have to check the IDs and add a number that’s not used already?
> 
> The author or a tool, yes.
> 
>> There are plenty of issues with static IDing parts of a document.
> 
> Sure.  We are in uncharted territory here, so issues are a legion.

:) In all honesty, I’m not ready to contribute to developing such a 
system. Not that I don’t think it would not be beneficial, on the 
contrary, but because my skill set would not be of much help, and I’d 
rather discuss issues of already existing systems.

> Translation is a human job, and translating a manual is more so,
> because the context is much more important than when translating short
> phrases.  So it seems to me that seeing diffs in terms of paragraphs
> using a format where the markers are only used to detect changes, and
> the rest are text differences, is better than using the PO methods,
> where the comparison with the previous version is much harder because
> PO decorations are much more massive.

Ok, I understand now what your issue is with PO. If we start from the 
idea that a diff is what is going to help us find the parts to update, 
then the less decorations the better.

Decorations are irrelevant in OmegaT. Only the msgid contents is taken 
into account. Decorations are also not shown in the OmegaT editor. I 
just see the paragraphs, above, below, and I translate the text 
contents without worrying about the decorations.

> But we certainly should consider using PO as one possible alternative.

At least until a robust system is implemented for Emacs/Texinfo.

>>> When paragraph #1234 in the English original was modified, translators
>>> will know that they need to update the translation of the
>>> corresponding paragraph(s) (could be more than one) in their
>>> translations, and nothing else.  It should be easy to analyze the
>>> diffs, look for the "@c para NNNN" marks, and present the translator
>>> with the corresponding paragraph(s) from the translation.
>> 
>> I think po-mode already does that and all the "out of emacs" tools do
>> too.
> 
> Maybe so.  But I wouldn't assume that PO could be easily stretched to
> this kind of jobs, since it wasn't originally designed for them.

Development of po4a is ongoing (I just received a mail this morning 
from the dev list). If it did not serve a practical and useful purpose 
for some users I’m not sure it would still be around.


-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 4, 2024, at 15:58, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
>>> There are plenty of issues with static IDing parts of a document.
>> 
>> Sure.  We are in uncharted territory here, so issues are a legion.
> 
> I think the job will be easier if we use established tools and workflows
> if at all possible.
> 
>>> I think po-mode already does that and all the "out of emacs" tools do
>>> too.
>> 
>> Maybe so.  But I wouldn't assume that PO could be easily stretched to
>> this kind of jobs, since it wasn't originally designed for them.
> 
> IIUC, it's what Jean-Christophe's has already been using here:
> 
>    https://git.sr.ht/~brandelune/emacs_documentation_repository

That’s correct.

The script that I use is here:

https://git.sr.ht/~brandelune/emacs_documentation_repository/tree/main/item/emacs_docs2po.sh

Pardon my poor shell scripting skills. Plus it’s only the script that converts in the texi → po direction. I’ve not written the one in the other direction.

The display.texi chapter is here:

https://git.sr.ht/~brandelune/emacs_documentation_repository/tree/main/item/doc/emacs/display.texi.fr.po

JFYI, the paragraphs that Eli quoted earlier are displayed this way in OmegaT:

===

¶

A buffer can have blank areas called @dfn{display margins} on the left and on the right.

Ordinary text never appears in these areas, but you can put things into the display margins using the @code{display} property.

There is currently no way to make text or images in the margin mouse-sensitive.

¶

The way to display something in the margins is to specify it in a margin display specification in the @code{display} property of some text.

This is a replacing display specification, meaning that the text you put it on does not get displayed; the margin display appears, but that text does not.

¶

A margin display specification looks like @code{((margin right-margin) @var{spec})} or @code{((margin left-margin) @var{spec})}.

Here, @var{spec} is another display specification that says what to display in the margin.

Typically it is a string of text to display, or an image descriptor.

¶

===

I have special regex to handle all the texi commands. I describe them here:

https://goshikidai.blogspot.com/2021/08/#définitions


-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translation of manuals (was: SES manual French translation)

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Wed, 3 Jan 2024 22:58:46 -0800
> Cc: vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> There are plenty of issues with static IDing parts of a document.
> >
> > Sure.  We are in uncharted territory here, so issues are a legion.
> 
> I think the job will be easier if we use established tools and workflows
> if at all possible.

We could only recommend such tools.  The actual choice is up to the
person who works on translations.  If the choice of the tools also
affects the source form in which the translations are kept in the
repository, we will need to consider those aspects as well.

> >> I think po-mode already does that and all the "out of emacs" tools do
> >> too.
> >
> > Maybe so.  But I wouldn't assume that PO could be easily stretched to
> > this kind of jobs, since it wasn't originally designed for them.
> 
> IIUC, it's what Jean-Christophe's has already been using here:
> 
>     https://git.sr.ht/~brandelune/emacs_documentation_repository

That's one data point, yes.  I can speak for myself here: I would not
want to use PO for this kind of job.  Its way of showing the
documentation as a series of unrelated strings makes it hard to read
the document and understand what it's saying.  PO was originally
designed for translating message strings, which are generally
unrelated to one another, which is not the case here.

So yes, PO could be tweaked for this job, but I'm not sure this is the
best solution, certainly not for everyone.

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 4, 2024, at 17:26, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> I can speak for myself here: I would not
> want to use PO for this kind of job.  Its way of showing the
> documentation as a series of unrelated strings makes it hard to read
> the document and understand what it's saying. 

??? All the paragraphs are in the same order as they are in the texi 
file. You can actually read the chapter from its beginning to its end 
in the PO file with indication about its original location as meta 
information.

It is not a series of unrelated strings, or maybe I am not properly 
understanding what you mean.


-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translation of manuals (was: SES manual French translation)

[Eli Zaretskii]

> Date: Thu, 04 Jan 2024 09:10:40 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Stefan Kangas <stefankangas@gmail.com>, Vincent Belaïche <vincent.b.1@hotmail.fr>, emacs-devel@gnu.org, rms@gnu.org
> 
> > On Jan 4, 2024, at 17:26, Eli Zaretskii <eliz@gnu.org> wrote:
> > 
> > I can speak for myself here: I would not
> > want to use PO for this kind of job.  Its way of showing the
> > documentation as a series of unrelated strings makes it hard to read
> > the document and understand what it's saying. 
> 
> ??? All the paragraphs are in the same order as they are in the texi 
> file. You can actually read the chapter from its beginning to its end 
> in the PO file with indication about its original location as meta 
> information.
> 
> It is not a series of unrelated strings, or maybe I am not properly 
> understanding what you mean.

The stuff PO adds, before and after the text, is clutter that gets in
the way of reading.

We don't need to argue here: to each their own, and the fact that I
dislike PO doesn't mean you need to defend it or try convincing me
that I should like it.

Re: Where to contribute manual translations ?

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "emacs-devel@gnu.org" <emacs-devel@gnu.org>, Richard Stallman
> 	<rms@gnu.org>
> Date: Mon, 1 Jan 2024 00:27:28 +0000
> 
> I have pushed the French translation of SES manual to master, here is a patch to make the compilation :
> 
> [https://res-h3.public.cdn.office.net/assets/mail/file-icon/png/generic_16x16.png]patch.diff<https://1drv.ms/u/s!AkDIBBjRAOVwg3y54YIxSCu3e2MI>
> 
> Since I am not the maintainer of these Makefile.in scripts, I did not dare push this change.

Could you please post that patch here, either inline or as an
attachment?

Thanks.

Translation of the Org mode manual (was: Translation of manuals (was: SES manual French translation))

[Ihor Radchenko]

Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
writes:
> I’m not sure this is the place to discuss translation theory...

Let me steer this discussion to non-texi manuals - Org mode manual.
We also had a few requests about translations, although Org mode needs
are more general compared to a very focused task of translating texi
manuals:

1. Org mode manual itself, just like the other Emacs manuals may need to
   be translated. However, Org mode manual source is written in Org mode
   format, not texi. It is just transformed to texi as one of the export
   options.

2. Org mode website has several translations (French, Japanese, and
   Mandarin). The website sources are written in Org mode, but the work
   of translation was done be enthusiasts, and we have no good system to
   maintain the main English version of the website in sync with the
   translations.

3. A number of Org mode users are using Org sources to publish
   multi-lingual books. Such publishing is a bit more challenging
   compared to translation as it requires special book layout.

Therefore, there is a demand to have a toolset for translating Org mode
documents.

So far, I have been thinking about some way to support translations with
ideas rather similar to raised in this topic:

1. Mark paragraphs/headings/other structural elements with an ID

2. Split translation into chunks linked to the original source IDs and
   their text hash

3. When exporting from Org source to target format (texi, html, pdf,
   etc), allow choosing the target language(s) and ensure consistency
   between translations and their possibly changed sources.

However, I did not know about po4a. It is possible that many of the
necessary design decisions are already in place in po4a.

> ...
> I think po-mode already does that and all the "out of emacs" tools do 
> too.

May you share the most important features of po-mode that you find
essential to your translation work?

>> @node Display Margins
>>  @subsection Displaying in the Margins
>>  @cindex display margins
>>  @cindex margins, display
>
> As long as the above strings are to be translated, they need an ID too.
>
>>  @c para 1234
>> 
>>  @c para 1235
>> 
>>  @c para 1236
>
> Is the numbering automatic?
>
> What if you add paragraphs in the middle, like Vincent did? Will the 
> author have to check the IDs and add a number that’s not used already?
>
> There are plenty of issues with static IDing parts of a document.

May you please elaborate on the issues with static IDs?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Translation of the Org mode manual (was: Translation of manuals (was: SES manual French translation))

[Jean-Christophe Helary]

Ihor,

Thank you for chiming in.

> On Jan 4, 2024, at 20:34, Ihor Radchenko <yantar92@posteo.net> wrote:
> 
> Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> writes:
>> I’m not sure this is the place to discuss translation theory...
> 
> Let me steer this discussion to non-texi manuals - Org mode manual.

Sure.

> We also had a few requests about translations, although Org mode needs
> are more general compared to a very focused task of translating texi
> manuals:
> 
> 1. Org mode manual itself, just like the other Emacs manuals may need to
>   be translated. However, Org mode manual source is written in Org mode
>   format, not texi. It is just transformed to texi as one of the export
>   options.

That’s correct and that texi file seems to choke po4a, which is the 
reason my script removes it and uses the .org original instead.

I use the txt filter in po4a to convert it to po:

https://git.sr.ht/~brandelune/emacs_documentation_repository/tree/main/item/emacs_docs2po.sh#L71

The result is here:

https://git.sr.ht/~brandelune/emacs_documentation_repository/tree/main/item/doc/misc/org.org.fr.po

And looks like this:

---
#. type: Plain text
#: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs -
#: Sources/doc/misc/org.org:24
msgid ""
"Org Mode is an authoring tool and a TODO lists manager for GNU Emacs.  It "
"relies on a lightweight plain-text markup language used in files with the "
"=.org= extension."
msgstr ""

#. type: Plain text
#: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs -
#: Sources/doc/misc/org.org:31
msgid ""
"As an authoring tool, Org helps you write structured documents and provides "
"exporting facilities. Org files can also be used for literate programming "
"and reproducible research.  As a TODO lists manager, Org helps you organize "
"your tasks in a flexible way, from daily needs to detailed project-planning, "
"allowing logging, multiple views on your tasks, exporting your agendas, etc."
msgstr ""

#. type: Plain text
#: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs -
#: Sources/doc/misc/org.org:38
msgid ""
"Org mode is implemented on top of Outline mode, which makes it possible to "
"keep the content of large files well structured.  Visibility cycling and "
"structure editing help to work with the tree.  Tables are easily created "
"with a built-in table editor.  Plain text URL-like links connect to "
"websites, emails, Usenet messages, BBDB entries, and any files related to "
"the projects."
msgstr ""
---

In OmegaT it looks like this (all the po decorations are hidden - 
protected - in the editor, only the translatable parts are displayed):

---
¶

Org Mode is an authoring tool and a TODO lists manager for GNU Emacs.

It relies on a lightweight plain-text markup language used in files 
with the =.org= extension.

¶

As an authoring tool, Org helps you write structured documents and 
provides exporting facilities.

Org files can also be used for literate programming and reproducible 
research.

As a TODO lists manager, Org helps you organize your tasks in a 
flexible way, from daily needs to detailed project-planning, allowing 
logging, multiple views on your tasks, exporting your agendas, etc.

¶

Org mode is implemented on top of Outline mode, which makes it possible 
to keep the content of large files well structured.

Le cycle de visualisation et la modification de la structure aident à 
travailler avec l'arborescence.

Les tableaux sont facilement créés avec un éditeur de tableau intégré.

Les liens de type URL en texte brut se connectent aux sites Web, aux 
e-mails, aux messages Usenet, aux entrées BBDB et à tous les fichiers liés 
aux projets.

¶
---

You’ll notice that a few sentences have been translated in the last 
paragraph.

In other tools that support the PO format, similarly the PO decorations 
would be hidden from view.

> 2. Org mode website has several translations (French, Japanese, and
>   Mandarin). The website sources are written in Org mode, but the work
>   of translation was done be enthusiasts, and we have no good system to
>   maintain the main English version of the website in sync with the
>   translations.

I think you should take a look at how Debian does that, even if their 
site sources are not in org. The process is the same. Debian has a huge 
amount of experience in documentation/web localization.

> 3. A number of Org mode users are using Org sources to publish
>   multi-lingual books. Such publishing is a bit more challenging
>   compared to translation as it requires special book layout.

Indeed.

> Therefore, there is a demand to have a toolset for translating Org mode
> documents.
> 
> So far, I have been thinking about some way to support translations with
> ideas rather similar to raised in this topic:
> 
> 1. Mark paragraphs/headings/other structural elements with an ID
> 
> 2. Split translation into chunks linked to the original source IDs and
>   their text hash
> 
> 3. When exporting from Org source to target format (texi, html, pdf,
>   etc), allow choosing the target language(s) and ensure consistency
>   between translations and their possibly changed sources.
> 
> However, I did not know about po4a. It is possible that many of the
> necessary design decisions are already in place in po4a.

po4a has been around for a while and is used in a lot of free 
documentation projects. A lot of tools that free software translators 
use fully support the PO format and the translation teams are used to 
the process of team translating/proofreading/validating/committing.

I am sure Martin Quinson would appreciate development of a dedicated 
org mode filter. Right now, as I wrote above, the plain text filter is 
sufficient.

Also, po4a is not only a filter, it is a tool equivalent to gettext but 
focused on documentation formats. You should check its documentation to 
see how your workflow could benefit from its design.

>> ...
>> I think po-mode already does that and all the "out of emacs" tools do
>> too.
> 
> May you share the most important features of po-mode that you find
> essential to your translation work?

I don’t use po-mode. po-mode is not sufficient (now) for most of the 
professional translation that I handle.

>>> @node Display Margins
>>> @subsection Displaying in the Margins
>>> @cindex display margins
>>> @cindex margins, display
>> 
>> As long as the above strings are to be translated, they need an ID too.
>> 
>>> @c para 1234
>>> 
>>> @c para 1235
>>> 
>>> @c para 1236
>> 
>> Is the numbering automatic?
>> 
>> What if you add paragraphs in the middle, like Vincent did? Will the
>> author have to check the IDs and add a number that’s not used already?
>> 
>> There are plenty of issues with static IDing parts of a document.
> 
> May you please elaborate on the issues with static IDs?

For one, the fact that the numbering ends up not being sequential after 
a while. If you have a tool that does all the grunt work, then any 
kind of ID system should work.

In PO, the message is the ID.



-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 4, 2024, at 19:04, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> The stuff PO adds, before and after the text, is clutter that gets in
> the way of reading.
> 
> We don't need to argue here: to each their own, and the fact that I
> dislike PO doesn't mean you need to defend it or try convincing me
> that I should like it.

I apologize if it came out like this.

I’m not trying to convince you that PO is better than anything. I was 
just trying to understand what you did not like about it because I was 
not seeing what you were seeing and I’ve been translating PO files for 
money (and not) for 15 years now.

I understand now that you’d prefer to work in Emacs for all the 
translation work and that PO is indeed ugly when you look at it in the 
current (almost non-existing) state of Emacs based translation tools.

That’s something that either needs to be fixed (the po-mode authors 
might want to investigate better ways to display information) or 
ignored if Emacs/TexInfo decide to develop something different.

If for now we agree that having a location to put the translated texi 
files is a huge step forward, I’m sure that little by little teams will 
find ways to handle the translation process and provide emacs with fine 
translations.


-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translation of manuals (was: SES manual French translation)

[Stefan Kangas]

Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
writes:

> More pragmatically, it is because I am a freelance worker who is paid
> by the hour. I can’t allow myself to give more to the client than what
> I am paid for. I need to assume that the source document is of
> reasonable quality and that its intent is clear.
>
> When I translate or otherwise contribute to free software projects, the
> ethics are slightly different, but that does not profoundly change the
> way I work.

When you do volunteer translations and deeply care about the source
material, the process is indeed different.  I myself often end up with
long lists of proposed edits to the original.

Improving ses.texi was one motivation for Vincent when he translated it
to French, IIUC.  I'm sure some translators will want to do that, and
others won't.

The flip-side is that doing it can get very time consuming.

> Decorations are irrelevant in OmegaT. Only the msgid contents is taken
> into account. Decorations are also not shown in the OmegaT editor. I
> just see the paragraphs, above, below, and I translate the text
> contents without worrying about the decorations.

BTW, OmegaT is well worth trying out for anyone interested in
translating.

My hope is that we eventually will have something similar for Emacs, of
course, but we are very far off still.  I'm not aware of any project
that has attempted to build that.

Re: Translating Emacs manuals is of strategic importance

[Stefan Kangas]

Po Lu <luangruo@yahoo.com> writes:

> If that be so, why is it of great importance for us to distribute these
> translations ourselves, further undermining our public image by their
> raw nature?

Thanks for voicing your concerns.  I think I see now where you are
coming from.

I understand your concern about not distributing and promoting something
half-baked.  I myself have had some serious concerns about the quality
of translations in Free Software, and I have voiced those concerns here
in the past.  It would even be fair to say that I myself have taken a
defeatist stance at times.

Still, I note that many people are happy to be using the translations
that exist, and consider that better than reading English.  This
observation, and thinking about this more strategically from the point
of view of promoting GNU and Emacs, has lead me to revise my stance.

With more users will also come people interested in contributing.  If we
have nothing at all, on the other hand, it is not so easy to see how to
get the ball rolling.

I also note that for French, we already have a professional translator
on board (Jean-Christophe).  We can attract others in the future.  And
Vincent has volunteered time to this as well, of course.

> It is not worth inventing elaborate systems for classifying or
> disclaiming manuals and judging which we are directly responsible for,
> when another option is to simply refuse involvement in the development
> of such non-essential manuals and leave the forces of interest to take
> their course, to no detriment of actual readers.

I believe that we can get around the public perception issue by having
the work principally take place on master, but without distributing
unfinished translations in the release tarball.  This was the intention
when I proposed having a "nursery" for translations that aren't yet
complete.

There is also _no_rush_ with marking a translation as finished.  If it
takes a decade or two, then so be it.  Emacs is not going away, and
neither are the fact that humans use different languages.  It won't be
worse than the current situation; I think it will be better in many
ways.

I'm still interested in knowing if anyone sees any serious issues with
the basic idea of keeping a nursery.  The exact details would have to be
worked out, of course, including what we call it.

>> We could perhaps consider having several "tiers" of manuals: one
>> "nursery" for those are not yet meaningfully ready for distribution, one
>> "attic" for those that are no longer reasonably maintained, and one for
>> those that we actually do consider up to scratch.  The decision for what
>> goes where could be based on a dialogue between the maintainers and the
>> translators of various manuals.
>
> This scheme is far too complicated for the number of translations or
> translators on the horizon.

I know that you disagree, but _if_ we were to develop translations of
on master, how would you propose going about it?

It is clear that we don't want to distribute and/or promote manuals that
are not yet finished.

Re: Translating Emacs manuals is of strategic importance

[Stefan Kangas]

Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
writes:

> Using PO for the manuals will bring to the Emacs community a
> considerable number of qualified and experienced free software
> translator teams.
>
> It will also have the benefit of allowing the easy conversion of
> already existing translations so that they can be provided to teams who
> want to update them.

At the very least, it should be well worth our time to open the door.
Then we will see what type of interest and contributions we can garner.
Maybe it will take some time.

This is why I think it would make sense to get our basic processes in
place.

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 5, 2024, at 9:04, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
> Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> writes:
> 
>> More pragmatically, it is because I am a freelance worker who is paid
>> by the hour. I can’t allow myself to give more to the client than what
>> I am paid for. I need to assume that the source document is of
>> reasonable quality and that its intent is clear.
>> 
>> When I translate or otherwise contribute to free software projects, the
>> ethics are slightly different, but that does not profoundly change the
>> way I work.
> 
> When you do volunteer translations and deeply care about the source
> material, the process is indeed different.  I myself often end up with
> long lists of proposed edits to the original.

I do submit a list of mistakes and their fixes when I translate for 
money, because we’re also proofreaders in a way.

> Improving ses.texi was one motivation for Vincent when he translated it
> to French, IIUC.  I'm sure some translators will want to do that, and
> others won't.
> 
> The flip-side is that doing it can get very time consuming.

Haha! Yes. That’s why I fully rewrote the OmegaT manual last year to 
prepare the 6.0 release. :)

>> Decorations are irrelevant in OmegaT. Only the msgid contents is taken
>> into account. Decorations are also not shown in the OmegaT editor. I
>> just see the paragraphs, above, below, and I translate the text
>> contents without worrying about the decorations.
> 
> BTW, OmegaT is well worth trying out for anyone interested in
> translating.

It’s the only free software translation editor for professional (and 
committed amateur) translators. Since its first release in 2002, we 
managed to keep it free of “cloud versions for money” and other kinds of 
strings. As the current project coordinator, I insist on saying that it 
is “free software” and not “open source software”, and I introduced the 
4 freedoms in the short help text that’s displayed when you launch 6.0.

We have infrastructure on non-free systems (github for one), but that’s 
parts I don’t have skills to propose fixes for and we’re all volunteers. 
But I’m currently exploring ways to remove such dependencies. Etc.

> My hope is that we eventually will have something similar for Emacs, of
> course, but we are very far off still.  I'm not aware of any project
> that has attempted to build that.

There were discussions on the emacs user list a while back that was 
started by Macin Borkowski, where I attempted to explain what was the 
typical process in “professional” tools (or rather, using the industry 
standards that are TMX/SRX, etc.) 

https://lists.gnu.org/archive/html/help-gnu-emacs/2020-05/msg00168.html

The thread extended into December of that year and it was really 
interesting.

OmegaT is the reason why I got interested in emacs. That was slightly 
before the Common Lisp revival of the early 2000s. Before Seibel wrote 
his Common Lisp book. The editor “field” in OmegaT does not come with 
all the editing features that Emacs has (obviously) and I thought that 
maybe it would be worth trying to have it the other way round, i.e. 
build something like OmegaT on emacs. At the time I was making a lot of 
(free) seminars in Japan to introduce OmegaT in the hope of finding 
developers. One managed to use a python to java “bridge” to interact 
with OmegaT from Emacs, but that was it.

I’m not holding my breath for such a “mode” to be developed. But it’s 
OK. I would not think of writing SVG images in Emacs, so I’m fine doing 
my translation work in OmegaT. I use Emacs for other things.


-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translating Emacs manuals is of strategic importance

[Po Lu]

Stefan Kangas <stefankangas@gmail.com> writes:

> Thanks for voicing your concerns.  I think I see now where you are
> coming from.
>
> I understand your concern about not distributing and promoting something
> half-baked.  I myself have had some serious concerns about the quality
> of translations in Free Software, and I have voiced those concerns here
> in the past.  It would even be fair to say that I myself have taken a
> defeatist stance at times.
>
> Still, I note that many people are happy to be using the translations
> that exist, and consider that better than reading English.  This
> observation, and thinking about this more strategically from the point
> of view of promoting GNU and Emacs, has lead me to revise my stance.
>
> With more users will also come people interested in contributing.  If we
> have nothing at all, on the other hand, it is not so easy to see how to
> get the ball rolling.
>
> I also note that for French, we already have a professional translator
> on board (Jean-Christophe).  We can attract others in the future.  And
> Vincent has volunteered time to this as well, of course.

Are Jean-Christophe and Vincent capable of translating the Emacs user
manual and maintaining it in an up-to-date condition, both now and a
decade in the future, and would such efforts of theirs be impaired in
any manner if they took place outside the Emacs repository, under their
own supervision?

> I believe that we can get around the public perception issue by having
> the work principally take place on master, but without distributing
> unfinished translations in the release tarball.  This was the intention
> when I proposed having a "nursery" for translations that aren't yet
> complete.
>
> There is also _no_rush_ with marking a translation as finished.  If it
> takes a decade or two, then so be it.  Emacs is not going away, and
> neither are the fact that humans use different languages.  It won't be
> worse than the current situation; I think it will be better in many
> ways.
>
> I'm still interested in knowing if anyone sees any serious issues with
> the basic idea of keeping a nursery.  The exact details would have to be
> worked out, of course, including what we call it.

My position is not motivated by concern for our image, in large part,
but is one of clearly defining the extent of our responsibilities.  Just
as we are not responsible for packages in NonGNU ELPA, beyond trivial
house-keeping work related to their packaging, so we need not take
charge of translations, which, much like packages, users can make use of
whether developed as part of Emacs or not.

In addition the argument against including packages in the repository
applies far more to translations than to packages, as such translations
are not indispensable for our users or ever possible to complete,
because they are derivatives of source material that is constantly
undergoing modification.

> I know that you disagree, but _if_ we were to develop translations of
> on master, how would you propose going about it?

I don't know.  As I said, I consider the idea of developing them under
the Emacs umbrella fundamentally flawed given the resources at our
disposal.

> It is clear that we don't want to distribute and/or promote manuals that
> are not yet finished.

As harsh as this might sound, translation our manuals will be no more
challenging if we leave translators to "fend for themselves" and
maintain them separately, than if they conduct the work within our
repository without assistance that would place an unacceptable burden on
us.

Re: Translating Emacs manuals is of strategic importance

[Jean-Christophe Helary]

> On Jan 5, 2024, at 9:34, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
>>> We could perhaps consider having several "tiers" of manuals: one
>>> "nursery" for those are not yet meaningfully ready for distribution, one
>>> "attic" for those that are no longer reasonably maintained, and one for
>>> those that we actually do consider up to scratch.  The decision for what
>>> goes where could be based on a dialogue between the maintainers and the
>>> translators of various manuals.
>> 
>> This scheme is far too complicated for the number of translations or
>> translators on the horizon.

We have little translations and translators on the horizons not because 
they do not potentially exist, but because Emacs was always seen as a 
closed English-only system.

Emacs is *the* free software movement flagship. There is no equivalent 
in the history of the movement. Still, it is the one that has 
historically shown the least interest in, or practical commitment to, 
translation and localization.

The fact that most consequent free software projects have full-fledge 
translation (and translation quality) support says a lot about the sad 
state of Emacs in that regard. And translation/localization projects 
already existed pre-utf-8, so it’s not so much the lack of interest on 
the Emacs side than the passive dismissal of anything that smells like 
translation related (I’ve read a number of very silly things here, and 
not so long ago, about the fact that people who needed to work in Emacs 
should be able to read English, etc.)

I’m really glad that Vincent’s commit has actually started to stir the 
pot, because the mere fact that we did not have a location within the 
Emacs sources to put our translations was probably one of the major 
show stoppers for all translation endeavours.

Now that we have that, we can, and should, consider how to deal with 
the new situation. Right after Vincent’s first commit, I did a rough 
check and found dozens of trivial mistakes. I mentioned them here and 
Vincent was quick to fix them (I did not check the fixes).

So we need some sort of QA process. The discussion is, does the QA take 
place here, on devel, or in other places where translation “teams” do 
all the things they need to do before a final commit.

The Translation Project has a solution. Free software maintainers send 
(po) files to the TP, the files are handled by the various teams and 
sent back to the TP (after appropriate QA and validation) to be 
included in the final builds. Major gnu/linux distributions too have 
solutions. Each distribution has a translation team with all the 
committed languages represented, they have deadlines, QA checks, 
proofreading, etc. And things work and distributions (including their 
manuals) are published as multilingual systems.

Emacs and TexInfo being what they are, it is fair to suggest that we 
should have a system that only relies on the two for translation, hence 
the discussion about IDing texi chunks and so forth, instead of relying 
on yet another dependency (po4a) and a format that’s not easy on the 
eyes (po).

But the thing is that all existing free software multilingual 
communities work with PO already, so offering a temporary bridge to PO 
would ensure that we get the best expertise from already existing teams 
and that would give us the time to elaborate on what part we want to 
have Emacs and TexInfo play in the process.


-- 
Jean-Christophe Helary @jchelary@emacs. ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translation of manuals (was: SES manual French translation)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

let's not discuss the general nature of translation in this list, It
is a specialized subtopic that we don't need to design as part of
Emacs.  If there is no place else to discuss it, you can use
emacs-tangents.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Translating Emacs manuals is of strategic importance

[Emanuel Berg]

Jean-Christophe Helary wrote:

> Emacs is *the* free software movement flagship. There is no
> equivalent in the history of the movement. Still, it is the
> one that has historically shown the least interest in, or
> practical commitment to, translation and localization.

Why do you think that is?

-- 
underground experts united
https://dataswamp.org/~incal

Re: Translation of manuals (was: SES manual French translation)

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Thu, 4 Jan 2024 16:04:15 -0800
> Cc: Vincent Belaïche <vincent.b.1@hotmail.fr>, 
> 	emacs-devel@gnu.org, rms@gnu.org
> 
> BTW, OmegaT is well worth trying out for anyone interested in
> translating.
> 
> My hope is that we eventually will have something similar for Emacs

Seconded.  The thought that I'd need to use "another editor" to
translate text is...unthinkable.

Patches welcome.

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

[Jean-Christophe Helary]

> On Jan 5, 2024, at 9:35, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
> Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> writes:
> 
>> Using PO for the manuals will bring to the Emacs community a
>> considerable number of qualified and experienced free software
>> translator teams.
>> 
>> It will also have the benefit of allowing the easy conversion of
>> already existing translations so that they can be provided to teams who
>> want to update them.
> 
> At the very least, it should be well worth our time to open the door.
> Then we will see what type of interest and contributions we can garner.
> Maybe it will take some time.
> 
> This is why I think it would make sense to get our basic processes in
> place.


* 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?

Let’s say that we’d have a committer per language (what’s called a 
“language lead”). Contributors would send her the draughts they have 
worked on. The lead would commit the file to /drafts/[lg] and make a 
call here for proofreaders, for ex:


```
Subject: [FR] emacs-gnutls.texi ready for proofreading

emacs-gnutls.texi est prêt pour la révision. Utilisez cette liste pour 
échanger sur les problèmes importants et pour envoyer vos patches.
```

or something similar.

And interested parties would do their things: discuss issues here, in 
French, or Japanese, or Chinese, depending on the target language or 
send patches, etc.

For some manuals, there could be groups that already have an 
infrastructure for translation, like what is emerging for org-mode. In 
such cases, the group could send a final document right away for 
committing, considering that all the validation has taken place 
upstream.


* 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.


* 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:


```
Subject: [FR] quelqu’un travaille sur ido.texi ?

J’ai vérifié la table des assignations et on dirait que personne ne 
travaille sur ido.texi. Je peux le prendre ?
```


* 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.


* information

We’d need a readme file to make all that explicit.


* publication

For each emacs release, the texi files would be compiled into 
appropriate formats (minimally info) so that people can easily install 
them.



I think we basically only need these “steps” here (besides for the 
copyright assignment). All the rest would grow “organically” behind the 
scenes. Have I missed something?

-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translating Emacs manuals is of strategic importance

[Eli Zaretskii]

> Date: Fri, 05 Jan 2024 02:36:29 +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
> 
> We have little translations and translators on the horizons not because 
> they do not potentially exist, but because Emacs was always seen as a 
> closed English-only system.
> 
> Emacs is *the* free software movement flagship. There is no equivalent 
> in the history of the movement. Still, it is the one that has 
> historically shown the least interest in, or practical commitment to, 
> translation and localization.

This is at least inaccurate, and quite a bit unfair, I must say.  The
fact that Emacs does not yet support localized translated messages is
correct, of course, but explaining that by lack of interest and
practical commitment is not.  I think even the response of the
maintainers to Vincent's submission speaks volumes about the level of
our interest and commitment.

> The fact that most consequent free software projects have full-fledge 
> translation (and translation quality) support says a lot about the sad 
> state of Emacs in that regard. And translation/localization projects 
> already existed pre-utf-8, so it’s not so much the lack of interest on 
> the Emacs side than the passive dismissal of anything that smells like 
> translation related (I’ve read a number of very silly things here, and 
> not so long ago, about the fact that people who needed to work in Emacs 
> should be able to read English, etc.)

Silly things people sometimes say here aside (and everyone who reads
this list should be able to distinguish between wrong or even silly
opinions of some and the official POV of the Emacs maintainers), the
projects that have translations all do it using gettext and the
related infrastructure.  All they need is to wrap strings in the
various printf's with _(), and the rest is a matter of having a
message catalog translated to the target language.  So it is quite
simple for those programs to provide localized messages.  (Though even
with that problem solved by gettext, some languages cannot be
adequately supported -- for example, gettext is abysmally inadequate
for R2L languages, and it is no accident that most projects have no
translations for such languages.)

By contrast, the few discussions of this we had here clearly show that
gettext is not enough for Emacs.  We need more elaborate and more
flexible infrastructure that suits the unique requirements of Emacs,
where the line dividing code from documentation is so blurred that the
gettext's model is no longer applicable.  In addition, gettext is not
suited well to a project where most of the code is loaded at run time
as needed, and the documentation strings and messages to the user are
read from several sources, instead of being hard-coded in the code --
how do you package message catalogs in this situation?

Last, but not least: most of meaningful messages in Emacs are not
printf-style phrases, but doc strings, and gettext doesn't handle
those.  (The only other GNU project I know of which has similar doc
strings -- GDB -- doesn't translate those doc strings, although the
GDB messages are translated, and that is not a coincidence, IMO.)
There are also other non-trivial issues, as discussed in the past.

So before you accuse the project as a whole in being "passively
dismissive" wrt translations, a reality check is in order.  The real
reasons are not the lack of interest or us being lazy.

The real reason is that no one has yet stepped forward to take this
job upon themselves, let alone saw through that the job is done to the
degree that it can be used project-wide.  And since no significant
development in Emacs ever happens without someone volunteering for the
job and then seeing it through, this job still awaits its volunteers.
All of the similar significant additions to Emacs in the related areas
happened only because we were lucky enough to have volunteers.  Some
examples:

  . the Unicode support
  . the support for bidirectional editing and R2L languages
  . the support for modern complex text-shaping

If we were not lucky, Emacs could have been lacking these important
features.  For example, we could still be devoid or supporting R2L
languages, which are spoken by hundreds of millions of people.  Then
someone else could perhaps accuse us of being "passively dismissive"
about bidi.

What this means is that serious translation of doc strings and
messages in Emacs will not happen unless someone starts working on it,
and working seriously.  Working, not talking.  And since no one
stepped forward for such a long time, one possible explanation of that
could be that the Emacs community, as a whole, doesn't consider this a
significant problem.  The community, not the project management.  (If
this is what people think, I personally disagree with them, but then
Emacs is a community-driven project, and it is hard to take it in
directions that the community doesn't support, let alone supports
enthusiastically.)

> I’m really glad that Vincent’s commit has actually started to stir the 
> pot, because the mere fact that we did not have a location within the 
> Emacs sources to put our translations was probably one of the major 
> show stoppers for all translation endeavours.

Nothing is farther from the truth.  There was no need to "stir the
pot": as soon as Vincent came up with his translation, he was
immediately asked whether adding that to Emacs would be possible.
That alone should speak volumes of the attitude of the current (and
past) maintainers wrt making Emacs friendlier to people whose first
language is not English.

> The Translation Project has a solution. Free software maintainers send 
> (po) files to the TP, the files are handled by the various teams and 
> sent back to the TP (after appropriate QA and validation) to be 
> included in the final builds. Major gnu/linux distributions too have 
> solutions. Each distribution has a translation team with all the 
> committed languages represented, they have deadlines, QA checks, 
> proofreading, etc. And things work and distributions (including their 
> manuals) are published as multilingual systems.

We could create a translation team for Emacs, but the TP
infrastructure is IMNSHO inappropriate for translating large manuals.
(In case you didn't know, I'm one of the TP team leaders, so I know
something about that.)  As with many other aspects of i18n, Emacs
needs its own special solutions here, or at least the Texinfo project
should come up with a solution for the GNU Project as a whole, since
we are not the only GNU project that uses Texinfo.  It is unreasonable
to expect the Emacs project to solve problems that are common to all
the GNU projects, and accuse us of lack of interest because those
problems are not yet solved satisfactorily.

> But the thing is that all existing free software multilingual 
> communities work with PO already, so offering a temporary bridge to PO 
> would ensure that we get the best expertise from already existing teams 
> and that would give us the time to elaborate on what part we want to 
> have Emacs and TexInfo play in the process.

See above: the existing communities don't need to solve the problems
that are central to Emacs in this area, they don't even come close.
So, while PO is definitely one alternative we should consider, it is
not necessarily the right one for our purposes, certainly when
translation of large and frequently-changing manuals is concerned.

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

[Eli Zaretskii]

> 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.

> * 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.  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.

> * 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.

> * 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.

> * information
> 
> We’d need a readme file to make all that explicit.

Yes.  Feel free to submit it.

> * 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.  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.

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

[Jean-Christophe Helary]

> 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?

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

[Eli Zaretskii]

> Date: Fri, 05 Jan 2024 14:07:12 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Stefan Kangas <stefankangas@gmail.com>, Po Lu <luangruo@yahoo.com>, Vincent Belaïche <vincent.b.1@hotmail.fr>, emacs-devel@gnu.org, rms@gnu.org
> 
> >> 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.

I don't care much about the names of these branches.  We could have
all of them under origin/translations/, for example, if that would
help.  The important thing is that the people who contribute know the
name and/or publish it when they need others to take a look.

Not everything needs to be codified in advance and rigidly.

> >> 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.

It isn't a job for translators, it's a job for the Emacs maintainers.
And it's already "on paper": see admin/make-tarball.txt.

> >  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?

No, I just gave an example how portions of the documentation that are
not in English are organically incorporated into the Emacs release
process.

Re: Translating Emacs manuals is of strategic importance

[Jean-Christophe Helary]

> On Jan 5, 2024, at 21:53, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Date: Fri, 05 Jan 2024 02:36:29 +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
>> 
>> We have little translations and translators on the horizons not because
>> they do not potentially exist, but because Emacs was always seen as a
>> closed English-only system.
>> 
>> Emacs is *the* free software movement flagship. There is no equivalent
>> in the history of the movement. Still, it is the one that has
>> historically shown the least interest in, or practical commitment to,
>> translation and localization.
> 
> This is at least inaccurate, and quite a bit unfair, I must say.  The
> fact that Emacs does not yet support localized translated messages is
> correct, of course, but explaining that by lack of interest and
> practical commitment is not.  I think even the response of the
> maintainers to Vincent's submission speaks volumes about the level of
> our interest and commitment.

The proof is in the pudding. In 40 years, the Emacs project has yet to 
publish an up-to-date manual in a non-English language.

It’s a fact. And I understand that it comes from the community at large 
not being interested in that aspect of Emacs.

But there are groups that worked on a Japanese manual if my memory is 
correct. There is mention of a Chinese manual, I know of the French 
attempt at working on the manuals 20 years ago, and there are probably 
many other language groups that tried too.

Where the people too shy to ask if their work could be included? Maybe. 
Was the “English is the language of computer development” general 
stance detrimental to considering these efforts as valuable then? I’d 
think that yes.

I’m glad that you are strongly stating that Emacs as a project does not 
support that view.

> Silly things people sometimes say here aside (and everyone who reads
> this list should be able to distinguish between wrong or even silly
> opinions of some and the official POV of the Emacs maintainers), the
> projects that have translations all do it using gettext and the
> related infrastructure.  All they need is to wrap strings in the
> various printf's with _(), and the rest is a matter of having a
> message catalog translated to the target language.  So it is quite
> simple for those programs to provide localized messages.

We are really talking manuals here. Not message strings.

man pages are translated. Web pages are translated. DocBook or other 
documentation is translated. Etc. There are millions of words in 
various documentation formats that are translated to dozens of 
languages in the free software world.

> So before you accuse the project as a whole in being "passively
> dismissive" wrt translations, a reality check is in order.  The real
> reasons are not the lack of interest or us being lazy.

I certainly never suggested that “you” (for any value of “you”) were 
being lazy.

>> I’m really glad that Vincent’s commit has actually started to stir the
>> pot, because the mere fact that we did not have a location within the
>> Emacs sources to put our translations was probably one of the major
>> show stoppers for all translation endeavours.
> 
> Nothing is farther from the truth.  There was no need to "stir the
> pot": as soon as Vincent came up with his translation, he was
> immediately asked whether adding that to Emacs would be possible.
> That alone should speak volumes of the attitude of the current (and
> past) maintainers wrt making Emacs friendlier to people whose first
> language is not English.

Maybe stirring the pot was not the appropriate expression and I am not 
criticizing maintainers at all. What is happening now is a very 
constructive discussion on how to move forward regarding translations. 

That has never happened in the past (as far as I remember, and checked 
in the archives), and I think that it is thanks to Vincent moving 
forward and committing his manual to a place that did not exist 
before.

> It is unreasonable
> to expect the Emacs project to solve problems that are common to all
> the GNU projects, and accuse us of lack of interest because those
> problems are not yet solved satisfactorily.

I’m not sure where that comes from. I’m trying to focus on Emacs 
manuals. You’re the one who mentioned that TexInfo should be involved.

But I’m not sure it is fair to expect translators to wait until 
somebody comes up with a “globally satisfactory solution to problems 
common to all the GNU projects”, whatever that means in practice.

> See above: the existing communities don't need to solve the problems
> that are central to Emacs in this area, they don't even come close.

I’m still not sure how documentation translation is so much harder to 
handle for Emacs than for other projects. Texi is just another plain text 
format that has nothing special to it.

> So, while PO is definitely one alternative we should consider, it is
> not necessarily the right one for our purposes, certainly when
> translation of large and frequently-changing manuals is concerned.

There are 2 intermediate formats in the industry and they work very 
well for any kind of documentation. It’s PO and XLIFF (side note: there 
is absolutely no technical need to use intermediate formats in 
translation.)

Maybe PO was not designed for documentation in the first place, but 
nothing keeps it from being used that way, and the fact is that it is 
being used that way.

I understand that you don’t think PO is a good solution because you 
want to do the translation in Emacs and translating PO in Emacs is not 
a good experience.

It’s OK if the Emacs project does not create infrastructure that offers 
PO as the intermediate translation format. Texi is a fine format and 
experienced translation teams know how to handle updates, even without 
IDs attached to paragraphs.

Re: Translating Emacs manuals is of strategic importance

[Eli Zaretskii]

> Date: Fri, 05 Jan 2024 15:20:49 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Stefan Kangas <stefankangas@gmail.com>, Vincent Belaïche <vincent.b.1@hotmail.fr>, emacs-devel@gnu.org, rms@gnu.org
> 
> >> Emacs is *the* free software movement flagship. There is no equivalent
> >> in the history of the movement. Still, it is the one that has
> >> historically shown the least interest in, or practical commitment to,
> >> translation and localization.
> > 
> > This is at least inaccurate, and quite a bit unfair, I must say.  The
> > fact that Emacs does not yet support localized translated messages is
> > correct, of course, but explaining that by lack of interest and
> > practical commitment is not.  I think even the response of the
> > maintainers to Vincent's submission speaks volumes about the level of
> > our interest and commitment.
> 
> The proof is in the pudding. In 40 years, the Emacs project has yet to 
> publish an up-to-date manual in a non-English language.
> 
> It’s a fact. And I understand that it comes from the community at large 
> not being interested in that aspect of Emacs.

I don't argue with facts.  My response was to the apparent denigration
of the project and its leadership based on incorrect interpretation of
the reasons which led to the fact.

> But there are groups that worked on a Japanese manual if my memory is 
> correct. There is mention of a Chinese manual, I know of the French 
> attempt at working on the manuals 20 years ago, and there are probably 
> many other language groups that tried too.
> 
> Where the people too shy to ask if their work could be included? Maybe. 
> Was the “English is the language of computer development” general 
> stance detrimental to considering these efforts as valuable then? I’d 
> think that yes.

I don't remember anyone suggesting to add a translated manual and
being rejected.  Did something like that actually happen?  If so, can
you point to the relevant discussion?

> > Silly things people sometimes say here aside (and everyone who reads
> > this list should be able to distinguish between wrong or even silly
> > opinions of some and the official POV of the Emacs maintainers), the
> > projects that have translations all do it using gettext and the
> > related infrastructure.  All they need is to wrap strings in the
> > various printf's with _(), and the rest is a matter of having a
> > message catalog translated to the target language.  So it is quite
> > simple for those programs to provide localized messages.
> 
> We are really talking manuals here. Not message strings.

Your original message indicated otherwise.  You talked about other
projects that have translations of high quality, and the "sad state"
of Emacs by comparison.  I can only understand this if you are
alluding to message catalogs.  Because if you are talking about
translations of the manuals, then please name free software projects
that have high-quality translations of their manuals, and the manuals
are of sufficient size to consider them anywhere near what Emacs has
to deal with.

If we limit this discussion to manuals, I submit that Emacs as a
project has nothing to be ashamed of.  We have tutorial translations
into 2 dozen languages, and we have refcards translations into 5
languages.  What other GNU projects can boast that?

> man pages are translated. Web pages are translated. DocBook or other 
> documentation is translated. Etc. There are millions of words in 
> various documentation formats that are translated to dozens of 
> languages in the free software world.

Not in my experience, not in the GNU Project anyway.

> > Nothing is farther from the truth.  There was no need to "stir the
> > pot": as soon as Vincent came up with his translation, he was
> > immediately asked whether adding that to Emacs would be possible.
> > That alone should speak volumes of the attitude of the current (and
> > past) maintainers wrt making Emacs friendlier to people whose first
> > language is not English.
> 
> Maybe stirring the pot was not the appropriate expression and I am not 
> criticizing maintainers at all. What is happening now is a very 
> constructive discussion on how to move forward regarding translations. 
> 
> That has never happened in the past (as far as I remember, and checked 
> in the archives), and I think that it is thanks to Vincent moving 
> forward and committing his manual to a place that did not exist 
> before.

It never happened in the past because no one submitted a translated
manual for inclusion.  We try not to discuss theoretical problems, I'm
sure you understand.

> > It is unreasonable
> > to expect the Emacs project to solve problems that are common to all
> > the GNU projects, and accuse us of lack of interest because those
> > problems are not yet solved satisfactorily.
> 
> I’m not sure where that comes from.

It comes from your apparent expectations that we solve the non-trivial
issues on our own and "yesterday", when all we have is a single
translation of a single manual.  This stuff takes time, so please be
patient and let us find the right tools and ways of dealing with this
as we go.  What you see now is as it is because we had no translations
to work with.  It's too early to raise complaints about this.

> But I’m not sure it is fair to expect translators to wait until 
> somebody comes up with a “globally satisfactory solution to problems 
> common to all the GNU projects”, whatever that means in practice.

They don't need to.  Each and every translated manual that is
submitted to us will be added, no questions asked.  Like it happened
with Vincent's translation.

> > See above: the existing communities don't need to solve the problems
> > that are central to Emacs in this area, they don't even come close.
> 
> I’m still not sure how documentation translation is so much harder to 
> handle for Emacs than for other projects. Texi is just another plain text 
> format that has nothing special to it.

I wasn't talking about the manuals.  But even for the manuals there
are some issues that need to be considered.  For example: what do we
do with the info/dir file for these translated manuals? what should be
@dircategory for them -- should it be a separate category, like
"Translated manuals", or should it be the same as in the original
English manuals?

Re: Translating Emacs manuals is of strategic importance

[Jean-Christophe Helary]

> On Jan 6, 2024, at 0:53, Eli Zaretskii <eliz@gnu.org> wrote:

>>> It is unreasonable
>>> to expect the Emacs project to solve problems that are common to all
>>> the GNU projects, and accuse us of lack of interest because those
>>> problems are not yet solved satisfactorily.
>> 
>> I’m not sure where that comes from.
> 
> It comes from your apparent expectations that we solve the non-trivial
> issues on our own and "yesterday", when all we have is a single
> translation of a single manual.

I don’t have any expectations. All this weird discussion is taking 
place because I was trying to understand what you did not like about PO 
while you (seemingly) were thinking I was trying to push PO down 
somebody’s throat.

Can we please move on?

> It's too early to raise complaints about this.

I have no complaint about anything. I proposed things based on my 
experience. You refused them because they don’t fit your idea of an 
ideal workflow in Emacs. And that’s OK. You’re the maintainer and you 
have a view of the project that I will never be able to have. I am fine 
with your decisions.

>>> See above: the existing communities don't need to solve the problems
>>> that are central to Emacs in this area, they don't even come close.
>> 
>> I’m still not sure how documentation translation is so much harder to
>> handle for Emacs than for other projects. Texi is just another plain text
>> format that has nothing special to it.
> 
> I wasn't talking about the manuals.  But even for the manuals there
> are some issues that need to be considered.  For example: what do we
> do with the info/dir file for these translated manuals? what should be
> @dircategory for them -- should it be a separate category, like
> "Translated manuals", or should it be the same as in the original
> English manuals?

Can we talk about that?

Re: Translating Emacs manuals is of strategic importance

[Eli Zaretskii]

> Date: Fri, 05 Jan 2024 16:10:53 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Stefan Kangas <stefankangas@gmail.com>, Vincent Belaïche <vincent.b.1@hotmail.fr>, emacs-devel@gnu.org, rms@gnu.org
> 
> > But even for the manuals there are some issues that need to be
> > considered.  For example: what do we do with the info/dir file for
> > these translated manuals? what should be @dircategory for them --
> > should it be a separate category, like "Translated manuals", or
> > should it be the same as in the original English manuals?
> 
> Can we talk about that?

Sure.

Re: Translation of manuals (was: SES manual French translation)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I understand now that you’d prefer to work in Emacs for all the 
  > translation work

This is not a mere personal preference.  We offer Emacs as the
solution for editing.  It would be self-defeating to adopt a format,
for ANY of the files we edit, which is ill-suited to editing with
Emacs!

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Translation of manuals (was: SES manual French translation)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > The stuff PO adds, before and after the text, is clutter that gets in
  > the way of reading.

I feel the same -- but the www.gnu.org teams use PO in a way that
avoids this drawback.  The files we normally edit, the HTML files
that appear on the web site, do not have any PO material.
Translators maintain PO versions of those files, which they alone use.
That way, they can take advantage of PO to aid their work
while not interfering with non-translators writing the English text.

Maybe the translators of manuals could so something like this too.
-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

@dircategory (Re: Translating Emacs manuals is of strategic importance)

[Jean-Christophe Helary]

> I wasn't talking about the manuals.  But even for the manuals there
> are some issues that need to be considered.  For example: what do we
> do with the info/dir file for these translated manuals? what should be
> @dircategory for them -- should it be a separate category, like
> "Translated manuals", or should it be the same as in the original
> English manuals?


I suppose the @dircategory is also what appears in the Emacs info top 
page under “*Menu:”?

If that’s the case, what about using “Translated manuals” for now, 
since the number of translated manuals is very low?

The day when we have a reasonable amount of translated manuals, it will 
make sense to have them under the original English manuals. I guess it 
won’t be too difficult to make the change.

So I guess the info/dir file would list the translated manuals in 
“Translated manuals” for now.


Other texinfo items that come to mind:

Would @author be also used for the translator?

For ex. emacs-gnutls.txi has
@author by Ted Zlatanov


In French that would be
@author par Ted Zlatanov
@author traduit en français par Achille Talon


(I see that Vincent has not mentioned his authorship of the SES French translation.)


Also, we will have to translate @node, because they appear in the 
Section index. I see that they were kept in English in the SES manual.

Are there other texi specific items that translators should be aware of?


-- 
Jean-Christophe Helary @jchelary@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 6, 2024, at 13:35, Richard Stallman <rms@gnu.org> wrote:
> 
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> 
>> I understand now that you’d prefer to work in Emacs for all the
>> translation work
> 
> This is not a mere personal preference.  We offer Emacs as the
> solution for editing.  It would be self-defeating to adopt a format,
> for ANY of the files we edit, which is ill-suited to editing with
> Emacs!

I understand that. But currently, the translation-editing functions 
offered by Emacs are not up to par with translation dedicated free 
software packages. So, translators tend to prefer such packages and 
thus the formats that such packages support.

But now that I understand why Eli as project maintainer does not favour 
PO, I am totally fine with the project’s position. We need to 
investigate what are the best ways to handle TeXinfo files for 
translation and propose guidelines to potential translators.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> Date: Sat, 06 Jan 2024 04:40:41 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Stefan Kangas <stefankangas@gmail.com>, Vincent Belaïche <vincent.b.1@hotmail.fr>, emacs-devel@gnu.org, Richard Stallman <rms@gnu.org>, help-texinfo@gnu.org
> 
> > I wasn't talking about the manuals.  But even for the manuals there
> > are some issues that need to be considered.  For example: what do we
> > do with the info/dir file for these translated manuals? what should be
> > @dircategory for them -- should it be a separate category, like
> > "Translated manuals", or should it be the same as in the original
> > English manuals?
> 
> 
> I suppose the @dircategory is also what appears in the Emacs info top 
> page under “*Menu:”?

The category headings there, yes.

> If that’s the case, what about using “Translated manuals” for now, 
> since the number of translated manuals is very low?

I'd say the other way around: as long as we have very few
translations, keeping them together with the English version is
better.

I wonder what Texinfo folks have to say about that.  Are there any
precedents for having such translations in DIR files?

> Other texinfo items that come to mind:
> 
> Would @author be also used for the translator?

@author is a TeX command and goes into the printed version.  For
translation, we'd need a separate directive, I think, since a
translator is not the author.  Again, this is something for the
Texinfo folks to handle.

> Also, we will have to translate @node, because they appear in the 
> Section index. I see that they were kept in English in the SES manual.

If we translate @node names, links from the doc strings and
cross-manual links will not work.  But, for such links to work, we
need a facility to tell the Info reader that when a link goes to a
manual named FOO.info, it should visit FOO-LANG.info instead.  Again,
something that involves a change in Texinfo and in all Info readers.

Re: Translation of manuals (was: SES manual French translation)

[Eli Zaretskii]

> Date: Sat, 06 Jan 2024 05:40:38 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: emacs-devel@gnu.org
> 
> > This is not a mere personal preference.  We offer Emacs as the
> > solution for editing.  It would be self-defeating to adopt a format,
> > for ANY of the files we edit, which is ill-suited to editing with
> > Emacs!
> 
> I understand that. But currently, the translation-editing functions 
> offered by Emacs are not up to par with translation dedicated free 
> software packages. So, translators tend to prefer such packages and 
> thus the formats that such packages support.
> 
> But now that I understand why Eli as project maintainer does not favour 
> PO, I am totally fine with the project’s position. We need to 
> investigate what are the best ways to handle TeXinfo files for 
> translation and propose guidelines to potential translators.

My personal preferences only matter when I do the translation.  It is
wrong to impose those preferences on others.  Of course, the
motivation to be able to work on translation in Emacs is high, but
whether what Emacs provides is good enough is up to each translator to
decide.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Jean-Christophe Helary]

> On Jan 6, 2024, at 17:36, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Date: Sat, 06 Jan 2024 04:40:41 +0000
>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> Cc: Stefan Kangas <stefankangas@gmail.com>, Vincent Belaïche <vincent.b.1@hotmail.fr>, emacs-devel@gnu.org, Richard Stallman <rms@gnu.org>, help-texinfo@gnu.org
>> 
>>> I wasn't talking about the manuals.  But even for the manuals there
>>> are some issues that need to be considered.  For example: what do we
>>> do with the info/dir file for these translated manuals? what should be
>>> @dircategory for them -- should it be a separate category, like
>>> "Translated manuals", or should it be the same as in the original
>>> English manuals?
>> 
>> 
>> I suppose the @dircategory is also what appears in the Emacs info top
>> page under “*Menu:”?
> 
> The category headings there, yes.
> 
>> If that’s the case, what about using “Translated manuals” for now,
>> since the number of translated manuals is very low?
> 
> I'd say the other way around: as long as we have very few
> translations, keeping them together with the English version is
> better.
> 
> I wonder what Texinfo folks have to say about that.  Are there any
> precedents for having such translations in DIR files?
> 
>> Other texinfo items that come to mind:
>> 
>> Would @author be also used for the translator?
> 
> @author is a TeX command and goes into the printed version.  For
> translation, we'd need a separate directive, I think, since a
> translator is not the author.  Again, this is something for the
> Texinfo folks to handle.

Legally speaking a translator is an author. Depending on the 
jurisdiction (Anglo-Saxon right vs EU right for ex.), the translator 
hold full copyright on the translation, unless it was a work for hire, 
etc. That’s why there are contracts between publishing houses and 
translators to allow or not the use of the translation is such and such 
format. I am not an IP lawyer, but I know what’s written in the 
contracts I’ve signed.

Creating another directive for the translation author seems like 
splitting hairs. But maybe not using @author at all and just adding a 
sentence in the text regarding the translation is the way to go.

>> Also, we will have to translate @node, because they appear in the
>> Section index. I see that they were kept in English in the SES manual.
> 
> If we translate @node names, links from the doc strings and
> cross-manual links will not work.

They will if they are translated in the other manuals. That’s what I’m 
doing in the Emacs manuals at the moment.

> But, for such links to work, we
> need a facility to tell the Info reader that when a link goes to a
> manual named FOO.info, it should visit FOO-LANG.info instead.  Again,
> something that involves a change in Texinfo and in all Info readers.

What are the practical cases where translating nodes would be a problem?

1. I read a manual in English, there is a link with a node in English, 
it directs to the other English manual.

It’s the expected behaviour.

2. I read a manual in French, there is a link with a node in English, 
it directs to the other English manual.

If the other manual exists in French, it is not the proper behaviour.

3. I read a manual in French, there is a link with a node in French, it 
directs to the other French manual.

If the other manual exists in French, it is the proper behaviour.

If it does not, we should have an error message that informs the reader 
that the manual is not translated.


So instead of a complex look up system, just an error message for links 
that don’t work should be sufficient. Don’t you think?

One issue seems to be that nodes have natural language IDs that also 
appear in the manual. If nodes were just arbitrary IDs associated to a 
string, like “2.1.2.fr” associated to “Ma section”, while “2.1.2.en” is 
“My section”, it would be easier to do the lookup and the manual would 
print the correct string.

In my current work on the Emacs manual, every time I find a node, I 
look for it in all the other chapters/manuals and adapt its translation.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> Date: Sat, 06 Jan 2024 09:37:03 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Stefan Kangas <stefankangas@gmail.com>, Vincent Belaïche <vincent.b.1@hotmail.fr>, emacs-devel@gnu.org, rms@gnu.org, help-texinfo@gnu.org
> 
> >> Would @author be also used for the translator?
> > 
> > @author is a TeX command and goes into the printed version.  For
> > translation, we'd need a separate directive, I think, since a
> > translator is not the author.  Again, this is something for the
> > Texinfo folks to handle.
> 
> Legally speaking a translator is an author. Depending on the 
> jurisdiction (Anglo-Saxon right vs EU right for ex.), the translator 
> hold full copyright on the translation, unless it was a work for hire, 
> etc. That’s why there are contracts between publishing houses and 
> translators to allow or not the use of the translation is such and such 
> format. I am not an IP lawyer, but I know what’s written in the 
> contracts I’ve signed.
> 
> Creating another directive for the translation author seems like 
> splitting hairs. But maybe not using @author at all and just adding a 
> sentence in the text regarding the translation is the way to go.

I don't know enough about this to have an opinion.  I still think this
is a GNU-wide decision that should be addressed by Texinfo folks.

> >> Also, we will have to translate @node, because they appear in the
> >> Section index. I see that they were kept in English in the SES manual.
> > 
> > If we translate @node names, links from the doc strings and
> > cross-manual links will not work.
> 
> They will if they are translated in the other manuals. That’s what I’m 
> doing in the Emacs manuals at the moment.

That means no fallback for when a translated manual doesn't exist to
which the link points.  Not sure this is better or what to do about
that.  Again, something Texinfo should address, I think.

> > But, for such links to work, we
> > need a facility to tell the Info reader that when a link goes to a
> > manual named FOO.info, it should visit FOO-LANG.info instead.  Again,
> > something that involves a change in Texinfo and in all Info readers.
> 
> What are the practical cases where translating nodes would be a problem?
> 
> 1. I read a manual in English, there is a link with a node in English, 
> it directs to the other English manual.
> 
> It’s the expected behaviour.
> 
> 2. I read a manual in French, there is a link with a node in English, 
> it directs to the other English manual.
> 
> If the other manual exists in French, it is not the proper behaviour.
> 
> 3. I read a manual in French, there is a link with a node in French, it 
> directs to the other French manual.
> 
> If the other manual exists in French, it is the proper behaviour.
> 
> If it does not, we should have an error message that informs the reader 
> that the manual is not translated.

I think case 3 should fall back to the English manual instead of
erroring out.  Having a manual without translation to an arbitrary
language will be the usual case for quite some time, so an error
message sounds like a harsh punishment to me.

Re: Translation of manuals (was: SES manual French translation)

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Sat, 06 Jan 2024 05:40:38 +0000
>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> Cc: emacs-devel@gnu.org
>>
>> But now that I understand why Eli as project maintainer does not favour
>> PO, I am totally fine with the project’s position. We need to
>> investigate what are the best ways to handle TeXinfo files for
>> translation and propose guidelines to potential translators.
>
> My personal preferences only matter when I do the translation.  It is
> wrong to impose those preferences on others.  Of course, the
> motivation to be able to work on translation in Emacs is high, but
> whether what Emacs provides is good enough is up to each translator to
> decide.

Since Jean-Christophe seems willing to volunteer for this work, let's
grab that opportunity with both hands.

To be a bit more practical, here's what I'd propose:

- Continue using PO for the translations for now, in particular the
  French one that is already using that format.

- Get the infrastructure in place for such translations in emacs.git.

- We can consider changing things later, if we can find or come up with
  a better alternative to PO.

Does that basic plan make sense?

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> If that’s the case, what about using “Translated manuals” for now,
>> since the number of translated manuals is very low?
>
> I'd say the other way around: as long as we have very few
> translations, keeping them together with the English version is
> better.

I'm concerned that they'd get in the way, even if there are only few of
them.

How about using something like `Info-streamline-headings' for this:

- Put manuals under "Translated manuals" for English locales.

- Move those relevant to the current locale to "Emacs".

I'd probably take it a step further and completely hide translations (by
default at least) outside of relevant locales.  We already do basically
that for the tutorial.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Stefan Kangas]

Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
writes:

>> @author is a TeX command and goes into the printed version.  For
>> translation, we'd need a separate directive, I think, since a
>> translator is not the author.  Again, this is something for the
>> Texinfo folks to handle.
>
> Legally speaking a translator is an author. Depending on the
> jurisdiction (Anglo-Saxon right vs EU right for ex.), the translator
> hold full copyright on the translation, unless it was a work for hire,
> etc. That’s why there are contracts between publishing houses and
> translators to allow or not the use of the translation is such and such
> format. I am not an IP lawyer, but I know what’s written in the
> contracts I’ve signed.

Legally, and morally too.  Translation work should be credited just the
same as we do other work.

But I think Eli's point was that we might need a separate directive like
@translator for that, and that this should be handled by the Texinfo
developers.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sat, 6 Jan 2024 03:57:24 -0800
> Cc: vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org, 
> 	help-texinfo@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> If that’s the case, what about using “Translated manuals” for now,
> >> since the number of translated manuals is very low?
> >
> > I'd say the other way around: as long as we have very few
> > translations, keeping them together with the English version is
> > better.
> 
> I'm concerned that they'd get in the way, even if there are only few of
> them.

How can a couple of manuals get in the way?  I think they will be
hardly even noticed.

> How about using something like `Info-streamline-headings' for this:
> 
> - Put manuals under "Translated manuals" for English locales.
> 
> - Move those relevant to the current locale to "Emacs".
> 
> I'd probably take it a step further and completely hide translations (by
> default at least) outside of relevant locales.  We already do basically
> that for the tutorial.

We could do something like that, indeed, but I tend to think this is a
matter of user preferences rather than the locale.  Why would we
assume that only users running in a French locale want to be able to
read the French translation?

In any case, my proposal was to do something simple as the first step.
IMO we should postpone more complicated stuff, like user preferences
and locale-dependent magic to later, when the way of handling
translations of the manuals is based on discussions and decisions that
are not private to Emacs.  I feel we are putting the cart ahead of the
horses by designing solutions for this at this time.

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 6, 2024, at 20:52, Stefan Kangas <stefankangas@gmail.com> wrote:
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
>>> Date: Sat, 06 Jan 2024 05:40:38 +0000
>>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>>> Cc: emacs-devel@gnu.org
>>> 
>>> But now that I understand why Eli as project maintainer does not favour
>>> PO, I am totally fine with the project’s position. We need to
>>> investigate what are the best ways to handle TeXinfo files for
>>> translation and propose guidelines to potential translators.
>> 
>> My personal preferences only matter when I do the translation.  It is
>> wrong to impose those preferences on others.  Of course, the
>> motivation to be able to work on translation in Emacs is high, but
>> whether what Emacs provides is good enough is up to each translator to
>> decide.
> 
> Since Jean-Christophe seems willing to volunteer for this work, let's
> grab that opportunity with both hands.
> 
> To be a bit more practical, here's what I'd propose:
> 
> - Continue using PO for the translations for now, in particular the
>  French one that is already using that format.

Well, I’m certainly not going to give up my setup because of the 
discussions we’ve had :), but I certainly won’t force Vincent (or 
any other person willing to work on a French translation) to follow my 
“lead”.

I know what’s good for me, but I won’t speak for others. Plus, it is 
not hard to incorporate pure texi translations into my workflow. I’m just a 
bit worried about potential diff noise between a texi to texi 
translation (Vincent’s) and a texi to po to texi one (mine). But that’s 
something I can deal with.

This discussion has prompted me to test building a short translated 
manual (GnuTLS Emacs integration). I’ve noticed a few texi things that 
need some tweaking and when I understand what it’s all about I’ll make 
suggestions.

The first one would be that all the current manuals should have the 
following directives by default:

@documentlanguage en
@documentencoding UTF-8

so that translators know that they only have to change the language, 
instead of checking which directive to add to their work.

> - Get the infrastructure in place for such translations in emacs.git.
> 
> - We can consider changing things later, if we can find or come up with
>  a better alternative to PO.

Just like I hate it when a client forces me to use a 
process/application to get a translation done, I’m sure that other 
translators have their own processes that may not involve PO. So maybe 
just indicating in a readme that there is the texi to texi route and 
also other routes like texi to po to texi for people who are already 
used to that process.

> Does that basic plan make sense?

If by “basic” you mean “let’s move on and translate” :) Yes, it does :)

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Jean-Christophe Helary]

> On Jan 6, 2024, at 20:38, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> 1. I read a manual in English, there is a link with a node in English,
>> it directs to the other English manual.
>> 
>> It’s the expected behaviour.
>> 
>> 2. I read a manual in French, there is a link with a node in English,
>> it directs to the other English manual.
>> 
>> If the other manual exists in French, it is not the proper behaviour.

I forgot. If I understand texinfo properly, if the manual name is 
translated (and if the manual is translated) it is enough that the node 
name is the same as in the target manual, so either both untranslated, 
or both translated. So here, the node name only being left in English 
is not so relevant. What matters most is whether the manual name is 
translated or not. Am I correct?

>> 3. I read a manual in French, there is a link with a node in French, it
>> directs to the other French manual.
>> 
>> If the other manual exists in French, it is the proper behaviour.
>> 
>> If it does not, we should have an error message that informs the reader
>> that the manual is not translated.
> 
> I think case 3 should fall back to the English manual instead of
> erroring out.  Having a manual without translation to an arbitrary
> language will be the usual case for quite some time, so an error
> message sounds like a harsh punishment to me.

Sure, but the situation where that would happen is indeed when there 
are too few translated manuals to create a “monolingual ecosystem” 
where manuals all link to each other.

Supposedly, the user has installed the manual independently and knows 
that there will be limitations. Just like all web sites have default 404 
pages and some have redirection, the error does not have to read like 
a punishment.

And that can be a first solution before something more elaborate is 
implemented. But indeed, that depends on how the TexInfo project wants 
to solve the issue.

Regarding the translation process, it seems like there are 2 steps here.

- The first is the translator who is conscious of the external nodes 
  limitations and keeps all the external nodes in English.

- The second is preparing the ground to link to her translation by 
  modifying external nodes in manuals that direct to it.

Little by little, the discrepancy will disappear and the translated 
manuals are all properly linked to each other.


Btw, does your comment indicate that you are currently not strongly 
opposed to translating the node names?

Re: Translation of manuals (was: SES manual French translation)

[Eli Zaretskii]

> Date: Sat, 06 Jan 2024 12:18:09 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Eli Zaretskii <eliz@gnu.org>, Richard Stallman <rms@gnu.org>, emacs-devel@gnu.org
> 
> The first one would be that all the current manuals should have the 
> following directives by default:
> 
> @documentlanguage en
> @documentencoding UTF-8

The second line is already there: see doc/emacs/docstyle.texi, which
all the manuals include.

As for @documentlanguage, it for now leaves no trace in the Info file,
so we didn't bother providing it.  Once makeinfo will do something
with it, we will probably ad it to docstyle.texi, and I think we
should add a LANG-docstyle.texi file, which will be included by all
the manuals for language LANG.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> Date: Sat, 06 Jan 2024 12:25:55 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Stefan Kangas <stefankangas@gmail.com>, Vincent Belaïche <vincent.b.1@hotmail.fr>, emacs-devel@gnu.org, Richard Stallman <rms@gnu.org>, help-texinfo@gnu.org
> 
> > On Jan 6, 2024, at 20:38, Eli Zaretskii <eliz@gnu.org> wrote:
> > 
> >> 1. I read a manual in English, there is a link with a node in English,
> >> it directs to the other English manual.
> >> 
> >> It’s the expected behaviour.
> >> 
> >> 2. I read a manual in French, there is a link with a node in English,
> >> it directs to the other English manual.
> >> 
> >> If the other manual exists in French, it is not the proper behaviour.
> 
> I forgot. If I understand texinfo properly, if the manual name is 
> translated (and if the manual is translated) it is enough that the node 
> name is the same as in the target manual, so either both untranslated, 
> or both translated. So here, the node name only being left in English 
> is not so relevant. What matters most is whether the manual name is 
> translated or not. Am I correct?

Yes, I think so.

> >> 3. I read a manual in French, there is a link with a node in French, it
> >> directs to the other French manual.
> >> 
> >> If the other manual exists in French, it is the proper behaviour.
> >> 
> >> If it does not, we should have an error message that informs the reader
> >> that the manual is not translated.
> > 
> > I think case 3 should fall back to the English manual instead of
> > erroring out.  Having a manual without translation to an arbitrary
> > language will be the usual case for quite some time, so an error
> > message sounds like a harsh punishment to me.
> 
> Sure, but the situation where that would happen is indeed when there 
> are too few translated manuals to create a “monolingual ecosystem” 
> where manuals all link to each other.

Which is where we are now, and will probably remain for at least a few
years to come.

> Supposedly, the user has installed the manual independently and knows 
> that there will be limitations. Just like all web sites have default 404 
> pages and some have redirection, the error does not have to read like 
> a punishment.

It is an annoyance.  gettext shows the original English message if
there's no translation, and I think we should try doing the same in
Info.

> Btw, does your comment indicate that you are currently not strongly 
> opposed to translating the node names?

I'm not opposed, but I tend to think we shouldn't translate them until
Texinfo developers figure out how to handle these cases.

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 6, 2024, at 22:02, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Date: Sat, 06 Jan 2024 12:18:09 +0000
>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> Cc: Eli Zaretskii <eliz@gnu.org>, Richard Stallman <rms@gnu.org>, emacs-devel@gnu.org
>> 
>> The first one would be that all the current manuals should have the
>> following directives by default:
>> 
>> @documentlanguage en
>> @documentencoding UTF-8
> 
> The second line is already there: see doc/emacs/docstyle.texi, which
> all the manuals include.

Ok. So I guess it's redundant in Vincent's manual.

> As for @documentlanguage, it for now leaves no trace in the Info file,
> so we didn't bother providing it.  Once makeinfo will do something
> with it, we will probably ad it to docstyle.texi, and I think we
> should add a LANG-docstyle.texi file, which will be included by all
> the manuals for language LANG.

Ok.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Jean-Christophe Helary]

> On Jan 6, 2024, at 22:05, Eli Zaretskii <eliz@gnu.org> wrote:

>> Supposedly, the user has installed the manual independently and knows
>> that there will be limitations. Just like all web sites have default 404
>> pages and some have redirection, the error does not have to read like
>> a punishment.
> 
> It is an annoyance.  gettext shows the original English message if
> there's no translation, and I think we should try doing the same in
> Info.

Ok. Fair enough.

>> Btw, does your comment indicate that you are currently not strongly
>> opposed to translating the node names?
> 
> I'm not opposed, but I tend to think we shouldn't translate them until
> Texinfo developers figure out how to handle these cases.

Ok. I guess it's also a matter of how much a manual is linked to from 
other manuals.


Thinking out loud here, but @node currently requires the node-name 
argument and has next/preious/up optional argument. It seems to me that 
most of the issues would be fixed by adding a fifth argument that acts 
like the cross-references' second argument (online-label). That way, 
node-name can stay as it is and act as the pointer but is displayed as 
"online-label", which is the translated part.

Same for the cross-references, if we generalize the use of 2 or 3 
arguments.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> Date: Sat, 06 Jan 2024 13:49:53 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: stefankangas@gmail.com, vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org, help-texinfo@gnu.org
> 
> Thinking out loud here, but @node currently requires the node-name 
> argument and has next/preious/up optional argument. It seems to me that 
> most of the issues would be fixed by adding a fifth argument that acts 
> like the cross-references' second argument (online-label). That way, 
> node-name can stay as it is and act as the pointer but is displayed as 
> "online-label", which is the translated part.

Maybe this will be a solution, I don't know.  (But note that the
next/preious/up arguments are basically obsolete and almost never used
nowadays.)

> Same for the cross-references, if we generalize the use of 2 or 3 
> arguments.

Cross-references already support 5 arguments.  I think we'd need
something more complex there.  One possibility could be some kind of
"translation table" inside an Info file, which maps English node names
to translated names.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Jean-Christophe Helary]

> On Jan 6, 2024, at 23:04, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Date: Sat, 06 Jan 2024 13:49:53 +0000
>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> Cc: stefankangas@gmail.com, vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org, help-texinfo@gnu.org
>> 
>> Thinking out loud here, but @node currently requires the node-name
>> argument and has next/preious/up optional argument. It seems to me that
>> most of the issues would be fixed by adding a fifth argument that acts
>> like the cross-references' second argument (online-label). That way,
>> node-name can stay as it is and act as the pointer but is displayed as
>> "online-label", which is the translated part.
> 
> Maybe this will be a solution, I don't know.  (But note that the
> next/preious/up arguments are basically obsolete and almost never used
> nowadays.)

Sure, but adding a 4th argument would be compatible with the current 
state of affairs.

>> Same for the cross-references, if we generalize the use of 2 or 3
>> arguments.
> 
> Cross-references already support 5 arguments.

I know. That's why I'm saying generalize their use.

> I think we'd need something more complex there.  One possibility could 
> be some kind of "translation table" inside an Info file, which maps 
> English node names to translated names.

Interesting. Is such a "translation" file already used in parts of 
Emacs (obviously not in relation to natural language translations)?

It seems to me that using things/concepts that already exist keeps the 
internal logic of the tool, while adding new processes adds to the 
complexity of things. But there are more things that I do not 
understand in Emacs/TexInfo than things I do, so I'll leave this 
consideration at that.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> Date: Sat, 06 Jan 2024 14:16:23 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Stefan Kangas <stefankangas@gmail.com>, Vincent Belaïche <vincent.b.1@hotmail.fr>, emacs-devel@gnu.org, Richard Stallman <rms@gnu.org>, help-texinfo@gnu.org
> 
> > I think we'd need something more complex there.  One possibility could 
> > be some kind of "translation table" inside an Info file, which maps 
> > English node names to translated names.
> 
> Interesting. Is such a "translation" file already used in parts of 
> Emacs (obviously not in relation to natural language translations)?

No.  But Info files have tag tables, which are something similar in
nature, so adding such a translation table is not as outlandish as it
might sound.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Gavin Smith]

On Sat, Jan 06, 2024 at 04:40:41AM +0000, Jean-Christophe Helary wrote:
> > I wasn't talking about the manuals.  But even for the manuals there
> > are some issues that need to be considered.  For example: what do we
> > do with the info/dir file for these translated manuals? what should be
> > @dircategory for them -- should it be a separate category, like
> > "Translated manuals", or should it be the same as in the original
> > English manuals?
> 
> 
> I suppose the @dircategory is also what appears in the Emacs info top 
> page under “*Menu:”?
> 
> If that’s the case, what about using “Translated manuals” for now, 
> since the number of translated manuals is very low?

(This is the first email that was CC-ed to help-texinfo@gnu.org and it's
not clear what the discussion is about or what if anything is being
asked, or what the context or history of the discussion is.  Hence,
I find this thread quite hard to follow based on the messages I have seen.)

It's up to people writing the Texinfo manuals what they put for
@dircategory.  In practice it seems that there aren't any well-followed
conventions for this so top-level dir files end up quite disorganised.

There are no conventions that I know of for the @dircategory of translated
manuals.  I think it is fine to translate the category.  For example,
on my system I have a manual "help2man-uk" which is listed with the
category of "Розробка програмного забезпечення", which Google Translate
tells me translates as "Software development".

If desired, users could have a directory containing solely Info manuals
in a certain language along with a dir file containing their dir entries.


> The day when we have a reasonable amount of translated manuals, it will 
> make sense to have them under the original English manuals. I guess it 
> won’t be too difficult to make the change.
> 
> So I guess the info/dir file would list the translated manuals in 
> “Translated manuals” for now.

I don't think that is the best category for non-English manuals as it
is too broad.

> In French that would be
> @author par Ted Zlatanov
> @author traduit en français par Achille Talon

That seems fine to me.

I will read through other messages in this thread and see if I have anything
to add.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Gavin Smith]

On Sat, Jan 06, 2024 at 10:36:28AM +0200, Eli Zaretskii wrote:
> > Would @author be also used for the translator?
> 
> @author is a TeX command and goes into the printed version.  For
> translation, we'd need a separate directive, I think, since a
> translator is not the author.  Again, this is something for the
> Texinfo folks to handle.

The Texinfo manual gives the example

     @author by Jane Smith and John Doe

The word "by" show that the argument of @author does not just have
to be the name of the author.  However, it may be confusing for some
output formats, such as DocBook.  The example in the Texinfo manual:

@titlepage
@title NAME-OF-MANUAL-WHEN-PRINTED
@subtitle SUBTITLE-IF-ANY
@subtitle SECOND-SUBTITLE
@author AUTHOR
@page
...
@end titlepage

yields, in DocBook:

<bookinfo><title>NAME-OF-MANUAL-WHEN-PRINTED</title>
<subtitle>SUBTITLE-IF-ANY
SECOND-SUBTITLE</subtitle>
<authorgroup>
<collab><collabname>AUTHOR</collabname></collab>
</authorgroup>
</bookinfo>

It's questionable whether this would be a correct use of <collabname>
and <authorgroup> or not.  The online DocBook documentation says,

"The AuthorGroup element is a wrapper around multiple authors or other
collaborators."

<https://tdg.docbook.org/tdg/4.5/authorgroup>

- and a translator is indeed a collaborator, although a word like "by"
is not part of their name.

In short I doubt it leads to practical problems putting a translator
in an @author line.  If they are clearly stated as a translator, and
not an author, there are no legal or moral problems.

If there are any real problems, these could of course be discussed.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> From: Gavin Smith <gavinsmith0123@gmail.com>
> Date: Sat, 6 Jan 2024 19:03:33 +0000
> Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Kangas <stefankangas@gmail.com>,
> 	Vincent Belaïche <vincent.b.1@hotmail.fr>,
> 	emacs-devel@gnu.org, Richard Stallman <rms@gnu.org>,
> 	help-texinfo@gnu.org
> 
> It's up to people writing the Texinfo manuals what they put for
> @dircategory.  In practice it seems that there aren't any well-followed
> conventions for this so top-level dir files end up quite disorganised.
> 
> There are no conventions that I know of for the @dircategory of translated
> manuals.

I always thought that utils/dir-example is the de-facto standard of
the categories which are "blessed" by the Texinfo project.

In this thread, we are raising the issue of some kind of
standardization of the categories for translated manuals.  If you are
saying that you don't think there should be such standardization, then
I guess we in the Emacs project will come up with our own solutions,
and the rest of the GNU Project will have to cope with that, since the
categories we use gets copied to the system-wide DIR files when Emacs
is installed.

> If desired, users could have a directory containing solely Info manuals
> in a certain language along with a dir file containing their dir entries.

That would mean INFOPATH will have to be amended to include such
directories.  It also means that INFOPATH will eventually include a
lot of directories, and search for Info manuals might become
significantly slower.  I'm not sure this is a scalable arrangement.

> I will read through other messages in this thread and see if I have anything
> to add.

Thanks.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Gavin Smith]

On Sat, Jan 06, 2024 at 09:37:03AM +0000, Jean-Christophe Helary wrote:
> >> Also, we will have to translate @node, because they appear in the
> >> Section index. I see that they were kept in English in the SES manual.
> > 
> > If we translate @node names, links from the doc strings and
> > cross-manual links will not work.
> 
> They will if they are translated in the other manuals. That’s what I’m 
> doing in the Emacs manuals at the moment.
> 
> > But, for such links to work, we
> > need a facility to tell the Info reader that when a link goes to a
> > manual named FOO.info, it should visit FOO-LANG.info instead.  Again,
> > something that involves a change in Texinfo and in all Info readers.
> 
> What are the practical cases where translating nodes would be a problem?
> 
> 1. I read a manual in English, there is a link with a node in English, 
> it directs to the other English manual.
> 
> It’s the expected behaviour.
> 
> 2. I read a manual in French, there is a link with a node in English, 
> it directs to the other English manual.
> 
> If the other manual exists in French, it is not the proper behaviour.

One option to account for this is use multiple infodirs, one for each
language.  Each of the infodirs would be on the INFOPATH, in order of
language preference.

Node names would not be translated, so that links to translated nodes
would work, if they became available.  Alternatively, the English node
name could be provided as an @anchor in addition to a non-English node
name.

> 
> 3. I read a manual in French, there is a link with a node in French, it 
> directs to the other French manual.
> 
> If the other manual exists in French, it is the proper behaviour.
> 
> If it does not, we should have an error message that informs the reader 
> that the manual is not translated.
> 
> 
> So instead of a complex look up system, just an error message for links 
> that don’t work should be sufficient. Don’t you think?

That word "just" implies it's easy and straightforward to implement,
which is a risky assumption.

One difficulty that comes to mind is how you tell the difference between
a manual that has not been translated yet, and one which just isn't
installed or or doesn't exist.

> 
> One issue seems to be that nodes have natural language IDs that also 
> appear in the manual. If nodes were just arbitrary IDs associated to a 
> string, like “2.1.2.fr” associated to “Ma section”, while “2.1.2.en” is 
> “My section”, it would be easier to do the lookup and the manual would 
> print the correct string.
> 
> In my current work on the Emacs manual, every time I find a node, I 
> look for it in all the other chapters/manuals and adapt its translation.
> 

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Gavin Smith]

On Sat, Jan 06, 2024 at 12:25:55PM +0000, Jean-Christophe Helary wrote:
> I forgot. If I understand texinfo properly, if the manual name is 
> translated (and if the manual is translated) it is enough that the node 
> name is the same as in the target manual, so either both untranslated, 
> or both translated. So here, the node name only being left in English 
> is not so relevant. What matters most is whether the manual name is 
> translated or not. Am I correct?

You could be translating node names in cross-references to other
manauls that aren't translated yet!  Then how would you know what
exactly the node name should be exactly?

In the case of mutually referrent manuals (a common case), this situation
is impossible to avoid, unless you take on the project of translating
every single referenced manual, and every manual those manuals reference,
and so on, as well as maintaining all of these translations indefinitely.
That is not going to happen.

> Sure, but the situation where that would happen is indeed when there 
> are too few translated manuals to create a “monolingual ecosystem” 
> where manuals all link to each other.
> 
> Supposedly, the user has installed the manual independently and knows 
> that there will be limitations. Just like all web sites have default 404 
> pages and some have redirection, the error does not have to read like 
> a punishment.
> 
> And that can be a first solution before something more elaborate is 
> implemented. But indeed, that depends on how the TexInfo project wants 
> to solve the issue.

What is the issue exactly?  I don't think it has been clearly stated.

> Regarding the translation process, it seems like there are 2 steps here.
> 
> - The first is the translator who is conscious of the external nodes 
>   limitations and keeps all the external nodes in English.
> 
> - The second is preparing the ground to link to her translation by 
>   modifying external nodes in manuals that direct to it.
> 
> Little by little, the discrepancy will disappear and the translated 
> manuals are all properly linked to each other.

More likely that they link to other nodes with their English names, and
then never change them.  You are assuming a consistency of purpose and
action across socially disparate actors that is very unlikely to exist.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Gavin Smith]

On Sat, Jan 06, 2024 at 01:49:53PM +0000, Jean-Christophe Helary wrote:
> Thinking out loud here, but @node currently requires the node-name 
> argument and has next/preious/up optional argument. It seems to me that 
> most of the issues would be fixed by adding a fifth argument that acts 
> like the cross-references' second argument (online-label). That way, 
> node-name can stay as it is and act as the pointer but is displayed as 
> "online-label", which is the translated part.

A document author can use @anchor to provide target text for a
cross-reference which does not appear in the reader-visible part
of the manual.  I don't see that extending the Texinfo language is
necessary.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Gavin Smith]

On Sat, Jan 06, 2024 at 03:57:24AM -0800, Stefan Kangas wrote:
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> If that’s the case, what about using “Translated manuals” for now,
> >> since the number of translated manuals is very low?
> >
> > I'd say the other way around: as long as we have very few
> > translations, keeping them together with the English version is
> > better.
> 
> I'm concerned that they'd get in the way, even if there are only few of
> them.
> 
> How about using something like `Info-streamline-headings' for this:
> 
> - Put manuals under "Translated manuals" for English locales.
> 
> - Move those relevant to the current locale to "Emacs".

> I'd probably take it a step further and completely hide translations (by
> default at least) outside of relevant locales.  We already do basically
> that for the tutorial.

I think it would be a good idea to hide them.  This could be dealt with
by installing translated manuals in a different location.

For example, in my top-level dir node, which I see by running "info",
I have the following lines:

Развој програма
* help2man-sr: (help2man-sr).   Самостално стварање 
                                  странице упутства.

Розробка програмного забезпечення
* help2man-uk: (help2man-uk).   Програма для 
                                  автоматичного створення сторінок 
                                  підручника (man).

软件开发
* help2man-zh_CN: (help2man-zh_CN).
                                自动手册页生成。

These are of no interest to me as I can't read the languages.  This
could potentially get worse if more manuals were translated and the
translations installed by default in the default Info directories.

Any support for supporting different installation directories for
different languages in Texinfo (or elsewhere, e.g. Automake) depends on
users of manuals in other languages explaining what exactly is needed
to support their use cases.

FWIW there is the following in the TODO file of Texinfo:

* Ideas that will not be implemented:

- Support installation of manuals in different languages, along these lines:
  . support a LINGUAS file or variable saying which subdirs LL in the
    source to descend into (under doc/).
  . within each subdir LL, install the info files into $infodir/LL,
    and run install-info on $infodir/LL/dir.
  . info (both emacs and standalone) should read $infodir/$LANG/dir
    as the first dir file, and likewise read info files first from
    $infodir/$LANG, before falling back to $infodir.
  . consider ways to avoid installing images in both places.
    In fact, images probably need to be installed in a subdir
    $infodir/MANUAL/ in the first place, to avoid conflicts of having
    the same image name in different manuals.
  For a test case, see texinfo cvs, with its one translated manual
  (info-fr.texi).
  From Wojciech Polak.
  ... Except, in practice, people just name their manuals with a
  suffix for the language, and that seems to work well enough.  There
  aren't that many manuals even in English, let alone other languages,
  and there are almost no manuals in multiple languages.

The $infodir/LL and $infodir/LL/dir part of this seem like a good idea
to me.  This would require changes in package build and installation
systems (Automake), not necessarily in Texinfo itself.  Since users
can set INFOPATH (or Emacs equivalent) themselves, it is not urgent to
implement special support for language directories per se in 'info'
or 'install-info'.  This could be done once it is clear that people
are actually using installation directories that way.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Gavin Smith]

On Sat, Jan 06, 2024 at 09:24:14PM +0200, Eli Zaretskii wrote:
> > It's up to people writing the Texinfo manuals what they put for
> > @dircategory.  In practice it seems that there aren't any well-followed
> > conventions for this so top-level dir files end up quite disorganised.
> > 
> > There are no conventions that I know of for the @dircategory of translated
> > manuals.
> 
> I always thought that utils/dir-example is the de-facto standard of
> the categories which are "blessed" by the Texinfo project.

It was "categories of the Free Software Directory" but that no longer
follows the same structure as it did when that recommendation
was first made.

The Texinfo manual under @dircategory lists a few example categories
which could be used (fairly consistent with what is in util/dir-example)
but at this point it is up to document authors to decide what categories
to use.  They could look at what other documents do or invent their own
categories if none are appropriate.

> In this thread, we are raising the issue of some kind of
> standardization of the categories for translated manuals.  If you are
> saying that you don't think there should be such standardization, then
> I guess we in the Emacs project will come up with our own solutions,
> and the rest of the GNU Project will have to cope with that, since the
> categories we use gets copied to the system-wide DIR files when Emacs
> is installed.

As I said, my personal preference is that categories should be translated,
although it is the decision of the translator in conjunction with the
user community of that language.

> > If desired, users could have a directory containing solely Info manuals
> > in a certain language along with a dir file containing their dir entries.
> 
> That would mean INFOPATH will have to be amended to include such
> directories.  It also means that INFOPATH will eventually include a
> lot of directories, and search for Info manuals might become
> significantly slower.  I'm not sure this is a scalable arrangement.

There's a limit to how many languages one person can read, so they won't
need dozens of such directories.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> From: Gavin Smith <gavinsmith0123@gmail.com>
> Date: Sat, 6 Jan 2024 19:41:27 +0000
> Cc: Eli Zaretskii <eliz@gnu.org>, stefankangas@gmail.com,
>  vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org,
>  help-texinfo@gnu.org
> 
> On Sat, Jan 06, 2024 at 01:49:53PM +0000, Jean-Christophe Helary wrote:
> > Thinking out loud here, but @node currently requires the node-name 
> > argument and has next/preious/up optional argument. It seems to me that 
> > most of the issues would be fixed by adding a fifth argument that acts 
> > like the cross-references' second argument (online-label). That way, 
> > node-name can stay as it is and act as the pointer but is displayed as 
> > "online-label", which is the translated part.
> 
> A document author can use @anchor to provide target text for a
> cross-reference which does not appear in the reader-visible part
> of the manual.  I don't see that extending the Texinfo language is
> necessary.

Do you mean that a translated manual should have an @anchor for each
@node, where nodes have translated names and the anchors give their
original names in English?

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Gavin Smith]

On Sat, Jan 06, 2024 at 10:26:29PM +0200, Eli Zaretskii wrote:
> > From: Gavin Smith <gavinsmith0123@gmail.com>
> > Date: Sat, 6 Jan 2024 19:41:27 +0000
> > Cc: Eli Zaretskii <eliz@gnu.org>, stefankangas@gmail.com,
> >  vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org,
> >  help-texinfo@gnu.org
> > 
> > On Sat, Jan 06, 2024 at 01:49:53PM +0000, Jean-Christophe Helary wrote:
> > > Thinking out loud here, but @node currently requires the node-name 
> > > argument and has next/preious/up optional argument. It seems to me that 
> > > most of the issues would be fixed by adding a fifth argument that acts 
> > > like the cross-references' second argument (online-label). That way, 
> > > node-name can stay as it is and act as the pointer but is displayed as 
> > > "online-label", which is the translated part.
> > 
> > A document author can use @anchor to provide target text for a
> > cross-reference which does not appear in the reader-visible part
> > of the manual.  I don't see that extending the Texinfo language is
> > necessary.
> 
> Do you mean that a translated manual should have an @anchor for each
> @node, where nodes have translated names and the anchors give their
> original names in English?

Yes, exactly.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> From: Gavin Smith <gavinsmith0123@gmail.com>
> Date: Sat, 6 Jan 2024 20:02:32 +0000
> Cc: Eli Zaretskii <eliz@gnu.org>,
> 	Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>,
> 	vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org,
> 	help-texinfo@gnu.org
> 
> > I'd probably take it a step further and completely hide translations (by
> > default at least) outside of relevant locales.  We already do basically
> > that for the tutorial.
> 
> I think it would be a good idea to hide them.  This could be dealt with
> by installing translated manuals in a different location.

This would be un-Emacsy, I think.  Emacs does not obey the locale so
completely, it changes the defaults to follow the locale, but allows
the user to request variants that are not the locale's defaults.  For
example, the command to show the tutorial by default shows the
tutorial for the locale's language, but it can optionally be requested
to show the tutorial in any other language specified by the user.

I would prefer to have something similar for translated manuals.

> For example, in my top-level dir node, which I see by running "info",
> I have the following lines:
> 
> Развој програма
> * help2man-sr: (help2man-sr).   Самостално стварање 
>                                   странице упутства.
> 
> Розробка програмного забезпечення
> * help2man-uk: (help2man-uk).   Програма для 
>                                   автоматичного створення сторінок 
>                                   підручника (man).
> 
> 软件开发
> * help2man-zh_CN: (help2man-zh_CN).
>                                 自动手册页生成。
> 
> These are of no interest to me as I can't read the languages.  This
> could potentially get worse if more manuals were translated and the
> translations installed by default in the default Info directories.

Whether to actually install those is a separate issue.  A downstream
distro could, for example, have separate installible components for
each language.  But if these _are_ installed, then why shouldn't they
be available?

> - Support installation of manuals in different languages, along these lines:
>   . support a LINGUAS file or variable saying which subdirs LL in the
>     source to descend into (under doc/).
>   . within each subdir LL, install the info files into $infodir/LL,
>     and run install-info on $infodir/LL/dir.
>   . info (both emacs and standalone) should read $infodir/$LANG/dir
>     as the first dir file, and likewise read info files first from
>     $infodir/$LANG, before falling back to $infodir.
>   . consider ways to avoid installing images in both places.
>     In fact, images probably need to be installed in a subdir
>     $infodir/MANUAL/ in the first place, to avoid conflicts of having
>     the same image name in different manuals.

I think this implicitly assumes that only a single LANG plus the
English manuals are ever installed.  If a user installs manuals for
many languages, this kind of arrangement will make INFOPATH have too
many directories, which will eventually slow down the search for
manuals.

I think a flat directory with FOO-LL.info files for language LL is a
better idea.

> The $infodir/LL and $infodir/LL/dir part of this seem like a good idea
> to me.  This would require changes in package build and installation
> systems (Automake), not necessarily in Texinfo itself.  Since users
> can set INFOPATH (or Emacs equivalent) themselves, it is not urgent to
> implement special support for language directories per se in 'info'
> or 'install-info'.  This could be done once it is clear that people
> are actually using installation directories that way.

Actually, the Emacs Info reader is designed to work OOTB without any
tweaking of its INFOPATH equivalent.  So asking users to add the LL
directories would be a nuisance, I think.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> From: Gavin Smith <gavinsmith0123@gmail.com>
> Date: Sat, 6 Jan 2024 20:16:54 +0000
> Cc: jean.christophe.helary@traductaire-libre.org, stefankangas@gmail.com,
> 	vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org,
> 	help-texinfo@gnu.org
> 
> > > If desired, users could have a directory containing solely Info manuals
> > > in a certain language along with a dir file containing their dir entries.
> > 
> > That would mean INFOPATH will have to be amended to include such
> > directories.  It also means that INFOPATH will eventually include a
> > lot of directories, and search for Info manuals might become
> > significantly slower.  I'm not sure this is a scalable arrangement.
> 
> There's a limit to how many languages one person can read, so they won't
> need dozens of such directories.

I was thinking about automatic computation of Info-directory-list, the
way we have in Emacs now.  That might need to account for directories
that _might_ exist, but aren't necessarily there on every system.  The
potential list of language-specific subdirectories _is_ long.

Having all of the manuals in a single directory with language-specific
suffixes completely avoids these problems, and will work with the
current standard Info directory trees without any changes.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Gavin Smith]

On Sat, Jan 06, 2024 at 10:41:11PM +0200, Eli Zaretskii wrote:
> > There's a limit to how many languages one person can read, so they won't
> > need dozens of such directories.
> 
> I was thinking about automatic computation of Info-directory-list, the
> way we have in Emacs now.  That might need to account for directories
> that _might_ exist, but aren't necessarily there on every system.  The
> potential list of language-specific subdirectories _is_ long.
> 
> Having all of the manuals in a single directory with language-specific
> suffixes completely avoids these problems, and will work with the
> current standard Info directory trees without any changes.

If using language suffixes for Info manuals becomes common practice,
in the future we could add support to the standalone Info program to
look for such manuals when following cross-references, dependent on
users' settings.

I'm not insisting that the language suffixes shouldn't be used in
preference to language-specific installation directories, if that's
more convenient or practical, even if the latter way seems to have
some possible advantages.

Re: Translating Emacs manuals is of strategic importance

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  >   Instead, we have to make it clear that
  > the translation teams (often: interested individuals) for the respective
  > languages will be responsible for the translations.

We can ask the FSF to consult lawyers about what (if anything) we need
to do.  (The lawyers we consult will be US lawyers.)  With luck, the measures
we use already to avoid being legally responsible for other kinds of errors
will apply to these too.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Jean-Christophe Helary]

> On Jan 7, 2024, at 5:31, Gavin Smith <gavinsmith0123@gmail.com> wrote:
> 
> On Sat, Jan 06, 2024 at 10:26:29PM +0200, Eli Zaretskii wrote:
>>> From: Gavin Smith <gavinsmith0123@gmail.com>
>>> Date: Sat, 6 Jan 2024 19:41:27 +0000
>>> Cc: Eli Zaretskii <eliz@gnu.org>, stefankangas@gmail.com,
>>> vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org,
>>> help-texinfo@gnu.org
>>> 
>>> On Sat, Jan 06, 2024 at 01:49:53PM +0000, Jean-Christophe Helary wrote:
>>>> Thinking out loud here, but @node currently requires the node-name
>>>> argument and has next/preious/up optional argument. It seems to me that
>>>> most of the issues would be fixed by adding a fifth argument that acts
>>>> like the cross-references' second argument (online-label). That way,
>>>> node-name can stay as it is and act as the pointer but is displayed as
>>>> "online-label", which is the translated part.
>>> 
>>> A document author can use @anchor to provide target text for a
>>> cross-reference which does not appear in the reader-visible part
>>> of the manual.  I don't see that extending the Texinfo language is
>>> necessary.
>> 
>> Do you mean that a translated manual should have an @anchor for each
>> @node, where nodes have translated names and the anchors give their
>> original names in English?
> 
> Yes, exactly.

As far as the Emacs manuals are concerned, could that be generalized to 
English manuals as well, so that translators don't have to add 
directives to the code and just have to modify the @node?

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> From: Gavin Smith <gavinsmith0123@gmail.com>
> Date: Sat, 6 Jan 2024 21:17:35 +0000
> Cc: jean.christophe.helary@traductaire-libre.org, stefankangas@gmail.com,
> 	vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org,
> 	help-texinfo@gnu.org
> 
> On Sat, Jan 06, 2024 at 10:41:11PM +0200, Eli Zaretskii wrote:
> > > There's a limit to how many languages one person can read, so they won't
> > > need dozens of such directories.
> > 
> > I was thinking about automatic computation of Info-directory-list, the
> > way we have in Emacs now.  That might need to account for directories
> > that _might_ exist, but aren't necessarily there on every system.  The
> > potential list of language-specific subdirectories _is_ long.
> > 
> > Having all of the manuals in a single directory with language-specific
> > suffixes completely avoids these problems, and will work with the
> > current standard Info directory trees without any changes.
> 
> If using language suffixes for Info manuals becomes common practice,
> in the future we could add support to the standalone Info program to
> look for such manuals when following cross-references, dependent on
> users' settings.
> 
> I'm not insisting that the language suffixes shouldn't be used in
> preference to language-specific installation directories, if that's
> more convenient or practical, even if the latter way seems to have
> some possible advantages.

I think it would be good if the GNU Project as a whole decided that
translated manuals should be called with language suffixes, as that
will allow cross-manual links to work across the project.  By
contrast, using special directories needs more tweaking.  Moreover,
even if eventually the decision will be to use language-specific
directories, I suggest that manuals in those directories will still be
named with language suffixes, so that the user who has both the
English and translated manuals could request the one they want
explicitly.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> IMO we should postpone more complicated stuff, like user preferences
> and locale-dependent magic to later, when the way of handling
> translations of the manuals is based on discussions and decisions that
> are not private to Emacs.  I feel we are putting the cart ahead of the
> horses by designing solutions for this at this time.

Yes, you're right.  Let's revisit this later.

Re: Translating Emacs manuals is of strategic importance

[Stefan Kangas]

Po Lu <luangruo@yahoo.com> writes:

> Are Jean-Christophe and Vincent capable of translating the Emacs user
> manual and maintaining it in an up-to-date condition, both now and a
> decade in the future,

I obviously can't answer that question, besides pointing out that we
don't usually place such high demands on people before accepting their
contributions.

> and would such efforts of theirs be impaired in any manner if they
> took place outside the Emacs repository, under their own supervision?

I tried to explain why I think this is true earlier in the thread.
I feel like I'm at risk of repeating my arguments at this point, which
to me is a sign that this subthread might have run its course.

That said, let me point out that I agree that we should avoid having
this work put an overly large burden on our regular Emacs maintenance.
Your conclusion is that we should not merge any translations.  Mine is
that we should make provisions to avoid the potential issues.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> Date: Sun, 07 Jan 2024 05:38:51 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: Eli Zaretskii <eliz@gnu.org>, stefankangas@gmail.com, vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org, help-texinfo@gnu.org
> 
> >> Do you mean that a translated manual should have an @anchor for each
> >> @node, where nodes have translated names and the anchors give their
> >> original names in English?
> > 
> > Yes, exactly.
> 
> As far as the Emacs manuals are concerned, could that be generalized to 
> English manuals as well, so that translators don't have to add 
> directives to the code and just have to modify the @node?

I'd object this.  Those anchors serve no purpose in the English
document, and adding them in a translation is almost trivial.  I also
don't know what would having a @node and an @anchor by the same name
cause to Info readers, and I'd rather not check.

Re: Translating Emacs manuals is of strategic importance

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sat, 6 Jan 2024 22:56:09 -0800
> Cc: Eli Zaretskii <eliz@gnu.org>, 
> 	Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>, vincent.b.1@hotmail.fr, 
> 	emacs-devel@gnu.org, rms@gnu.org
> 
> Po Lu <luangruo@yahoo.com> writes:
> 
> > and would such efforts of theirs be impaired in any manner if they
> > took place outside the Emacs repository, under their own supervision?
> 
> I tried to explain why I think this is true earlier in the thread.

From where I stand, stuff that's useful to Emacs users should be part
of Emacs.  Having to hunt additional sites to download useful stuff is
an annoyance we should strive to minimize.

> That said, let me point out that I agree that we should avoid having
> this work put an overly large burden on our regular Emacs maintenance.

FWIW, I see no significant maintenance burden added by these
translations.  If the translators don't update them, they will fall
behind, and if they eventually fall behind too much, we can decide
deleting them.

Re: Translation of manuals (was: SES manual French translation)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > It’s the only free software translation editor for professional (and 
  > committed amateur) translators. Since its first release in 2002, we 
  > managed to keep it free of “cloud versions for money” and other kinds of 
  > strings. As the current project coordinator, I insist on saying that it 
  > is “free software” and not “open source software”, and I introduced the 
  > 4 freedoms in the short help text that’s displayed when you launch 6.0.

I see it is listed in directory.fsf.org.  That is good.

  > I’m not holding my breath for such a “mode” to be developed. But it’s 
  > OK. I would not think of writing SVG images in Emacs, so I’m fine doing 
  > my translation work in OmegaT. I use Emacs for other things.

You, personally, would be free to use whatever you like.  We don't
have rules for what software a contributor can use -- not even against
nonfree programs, and certainly not a rule against using another free
program.

But when we choose a design for doing some editing job, we design it
so that Emacs is what we can recommend.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Translation of manuals (was: SES manual French translation)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > We have infrastructure on non-free systems (github for one),

Just to help clear up a widespread confusion, the distinction between
free and nonfree is defined for software packages.  It is not defined
for services.  Since github is a service, not a software package, it
is misleading to describe it as "free" or "nonfree".

The reason behind this is that the moral issues of how a service
treats users are much more complex than those of how a software
package treats its users.  With a software package, if it is free,
users can collaborate to change itt in any way.  By contrast, it is
never possible for the users of a service to modify that service.

We know of various ways a service can treat users unjustly -- we call
them "dis-services".  But we don't have a complete list of them.

We do have a list of them specifically for repo sites.
See https://www.gnu.org/software/repo-criteria-evaluation.html
for evaluations of several.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 8, 2024, at 12:44, Richard Stallman <rms@gnu.org> wrote:
> 
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> 
>> We have infrastructure on non-free systems (github for one),
> 
> Just to help clear up a widespread confusion, the distinction between
> free and nonfree is defined for software packages.  It is not defined
> for services.  Since github is a service, not a software package, it
> is misleading to describe it as "free" or "nonfree".
> 
> The reason behind this is that the moral issues of how a service
> treats users are much more complex than those of how a software
> package treats its users.  With a software package, if it is free,
> users can collaborate to change itt in any way.  By contrast, it is
> never possible for the users of a service to modify that service.
> 
> We know of various ways a service can treat users unjustly -- we call
> them "dis-services".  But we don't have a complete list of them.
> 
> We do have a list of them specifically for repo sites.
> See https://www.gnu.org/software/repo-criteria-evaluation.html
> for evaluations of several.

Thank you for the clarification.

Re: Translation of manuals (was: SES manual French translation)

[Jean-Christophe Helary]

> On Jan 8, 2024, at 12:44, Richard Stallman <rms@gnu.org> wrote:
> 
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> 
>> It’s the only free software translation editor for professional (and
>> committed amateur) translators. Since its first release in 2002, we
>> managed to keep it free of “cloud versions for money” and other kinds of
>> strings. As the current project coordinator, I insist on saying that it
>> is “free software” and not “open source software”, and I introduced the
>> 4 freedoms in the short help text that’s displayed when you launch 6.0.
> 
> I see it is listed in directory.fsf.org.  That is good.

Thank you.

I seem to remember that it's me who first registered it there. I just 
modified the entry to update it with current information.

Re: Translation of manuals (was: SES manual French translation)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > We know of various ways a service can treat users unjustly -- we call
  > them "dis-services".  But we don't have a complete list of them.

To clarify we use "dis-services" to refer to "services" that mistreat
users, but we don't have a full list of the bad things that a service
can do (twhich would make it a dis-service").  Coming up with that
is a hard problem.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Translation of manuals (was: SES manual French translation)

[Emanuel Berg]

Richard Stallman wrote:

>> We know of various ways a service can treat users unjustly
>> -- we call them "dis-services". But we don't have
>> a complete list of them.
>
> To clarify we use "dis-services" to refer to "services" that
> mistreat users, but we don't have a full list of the bad
> things that a service can do (twhich would make it
> a dis-service"). Coming up with that is a hard problem.

Maybe we can instead have a positive model that defines
a FOSS service?

To begin with it would run on free or open source
software, sure.

So people would be allowed to fork it, and run it on their own
servers, i.e. replicate and modify the service provided if
they saw reason to, be it to add something they wanted, or
remove something they didn't like? Or just do whatever they
liked to?

Wouldn't that be enough to say, this is a FOSS service?

-- 
underground experts united
https://dataswamp.org/~incal

Re: Translation of manuals (was: SES manual French translation)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Maybe we can instead have a positive model that defines
  > a FOSS service?

We would not call it "FOSS" -- we never use that term.  See
https://gnu.org/philosophy/floss-and-foss.html.  We say "free
software" instead of "FOSS", when talking about software.

That name issue is superficial, not hard to fix. But I don't see how
it makes sense to describe a service as a kind of software.  Those are
two different categories, and they raise different issuss.  See
https://gnu.org/philosophy/who-does-that-server-really-serve.html.

The deeper problem here is that defining what it means for services
that to users ethically is the same problem as defining what it
means for services to treat users unethically.  To figure out what
the moral rules should be for services is a hard problem.

We made a start on this around 20 years ago, producing the Franklin
Street Statement.  But that was only a start.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

free services (was: Re: Translation of manuals (was: SES manual French translation))

[Emanuel Berg]

Richard Stallman wrote:

> That name issue is superficial, not hard to fix. But I don't
> see how it makes sense to describe a service as a kind
> of software.

The service itself is not software, it is the result of the
work of software that runs on a server. The user interacts
with it with an interface and maybe there is an interface for
the result as well, depending on what service we are
talking about.

If all that software, including the interface(s), are free,
I don't see why not the whole thing is free as well.

> The deeper problem here is that defining what it means for
> services that to users ethically is the same problem as
> defining what it means for services to treat
> users unethically.

Indeed, it doesn't say anything about that.

But if anyone is displeased how users are treated that is
solvable, because the service is free, the whole thing can be
forked and setup on another server. Part of or all software
can be forked and modified and users can still use what is
basically the same service, only now whatever they were
displeased with can be fixed. (At least initially at least it
is basically the same. But of course it can grow from there to
what is ultimately more like two different things.)

Isn't it the same situation for any piece of free software?
Say it does something bad, it erases your disk. Instead of
having a long list what free software isn't allowed to do -
1. erase disk, 2. send spam e-mails, 3. ugh ... - we are
content the software is free. So those mistakes can be fixed,
however way they got there and for whatever reason.

So instead of having a long list of what a free service cannot
do - 1. treat the users unethically, 2. send spam e-mails,
3. ugh ... - we say if it runs entirely on free software, it
is a free service. Because everything unethically or otherwise
poorly-performing can be removed from it, just like a bug from
ordinary software.

-- 
underground experts united
https://dataswamp.org/~incal

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Patrice Dumas]

On Sat, Jan 06, 2024 at 09:37:03AM +0000, Jean-Christophe Helary wrote:
> 
> > But, for such links to work, we
> > need a facility to tell the Info reader that when a link goes to a
> > manual named FOO.info, it should visit FOO-LANG.info instead.  Again,
> > something that involves a change in Texinfo and in all Info readers.
> 
> What are the practical cases where translating nodes would be a problem?
> 
> 1. I read a manual in English, there is a link with a node in English, 
> it directs to the other English manual.
> 
> It’s the expected behaviour.
> 
> 2. I read a manual in French, there is a link with a node in English, 
> it directs to the other English manual.
> 
> If the other manual exists in French, it is not the proper behaviour.
> 
> 3. I read a manual in French, there is a link with a node in French, it 
> directs to the other French manual.
> 
> If the other manual exists in French, it is the proper behaviour.
> 
> If it does not, we should have an error message that informs the reader 
> that the manual is not translated.

This is already the current behaviour, though it is not possible to know
if the node name is incorrect or untranslated, and I do not think that
we should do something special here.

In any case, if a target manual is not yet translated, to me it is the
responsibility of the translator of amnual linking to it to either link
to the english manual, or to translate the node name in @ref even though
it won't lead to an existing manual and the name may need to be changed
later on to match with the actual name used in the translated manual.
To me both case could make sense depending on many criteria, such as
whether readers are likely to read english, whether manuals are
being translated...

In any case, I don't see any reason to do any automatic redirection in
the Info reader, it should remain simple and be the translators/writers
responsibilities.  Another reason is that it would not be possible to do
the same in HTML, as in HTML it is not possible to check if the target
exists.

-- 
Pat

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> Date: Wed, 10 Jan 2024 21:52:23 +0100
> From: Patrice Dumas <pertusus@free.fr>
> Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Kangas <stefankangas@gmail.com>,
> 	Vincent Belaïche <vincent.b.1@hotmail.fr>,
> 	emacs-devel@gnu.org, rms@gnu.org, help-texinfo@gnu.org
> 
> In any case, if a target manual is not yet translated, to me it is the
> responsibility of the translator of amnual linking to it to either link
> to the english manual, or to translate the node name in @ref even though
> it won't lead to an existing manual and the name may need to be changed
> later on to match with the actual name used in the translated manual.
> To me both case could make sense depending on many criteria, such as
> whether readers are likely to read english, whether manuals are
> being translated...

The translator doesn't always know whether a translated manual exists
when the translation is being written.  And even if a translated
manual does exist, there's no reason to be sure it will be installed
on the end-user's system.

So it would be good to have some Texinfo feature that would make the
behavior of Info readers more user-friendly in these cases.  Right
now, the Texinfo features that can help are @documentlanguage and the
suggestion by Gavin to have in the translated manual an @anchor for
each @node with the original English name of that @node.

> In any case, I don't see any reason to do any automatic redirection in
> the Info reader, it should remain simple and be the translators/writers
> responsibilities.

I don't think I agree, because leaving this completely to the
responsibilities of the translator could easily produce sub-optimal
results.

> Another reason is that it would not be possible to do the same in
> HTML, as in HTML it is not possible to check if the target exists.

Even if this cannot possibly be done in HTML (and I'm not yet sure),
it shouldn't stop us from doing that in Info.  After all, HTML output
lacks several features of Info output already, and it doesn't stop us.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Daniel Cerqueira]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Wed, 10 Jan 2024 21:52:23 +0100
>> From: Patrice Dumas <pertusus@free.fr>
>> Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Kangas <stefankangas@gmail.com>,
>> 	Vincent Belaïche <vincent.b.1@hotmail.fr>,
>> 	emacs-devel@gnu.org, rms@gnu.org, help-texinfo@gnu.org
>> 
>> In any case, if a target manual is not yet translated, to me it is the
>> responsibility of the translator of amnual linking to it to either link
>> to the english manual, or to translate the node name in @ref even though
>> it won't lead to an existing manual and the name may need to be changed
>> later on to match with the actual name used in the translated manual.
>> To me both case could make sense depending on many criteria, such as
>> whether readers are likely to read english, whether manuals are
>> being translated...
>
> The translator doesn't always know whether a translated manual exists
> when the translation is being written.  And even if a translated
> manual does exist, there's no reason to be sure it will be installed
> on the end-user's system.
>
> So it would be good to have some Texinfo feature that would make the
> behavior of Info readers more user-friendly in these cases.  Right
> now, the Texinfo features that can help are @documentlanguage and the
> suggestion by Gavin to have in the translated manual an @anchor for
> each @node with the original English name of that @node.
>
How come the translator doesn't always know whether a translated manual
exists?

That is ridiculous.

It is the same as saying that a translator just translated a whole
manual, without checking, and it was already translated. Ludacris.

>> In any case, I don't see any reason to do any automatic redirection in
>> the Info reader, it should remain simple and be the translators/writers
>> responsibilities.
>
> I don't think I agree, because leaving this completely to the
> responsibilities of the translator could easily produce sub-optimal
> results.

Sub-optimal? Like translators are deficient? We, translators, know what
we are doing. (I am the translator of GnuPG and Git).

>> Another reason is that it would not be possible to do the same in
>> HTML, as in HTML it is not possible to check if the target exists.
>
> Even if this cannot possibly be done in HTML (and I'm not yet sure),
> it shouldn't stop us from doing that in Info.  After all, HTML output
> lacks several features of Info output already, and it doesn't stop us.

I wholeheartedly disagree with Eli. In here I am nobody, but still I
don't like this complexity being added to a tool that I use to make
my books (texinfo).

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> From: Daniel Cerqueira <dan.list@brilhante.top>
> Cc: Patrice Dumas <pertusus@free.fr>,
>   jean.christophe.helary@traductaire-libre.org,  stefankangas@gmail.com,
>   vincent.b.1@hotmail.fr,  emacs-devel@gnu.org,  rms@gnu.org,
>   help-texinfo@gnu.org
> Date: Thu, 11 Jan 2024 12:48:46 +0000
> 
> > The translator doesn't always know whether a translated manual exists
> > when the translation is being written.  And even if a translated
> > manual does exist, there's no reason to be sure it will be installed
> > on the end-user's system.
> >
> > So it would be good to have some Texinfo feature that would make the
> > behavior of Info readers more user-friendly in these cases.  Right
> > now, the Texinfo features that can help are @documentlanguage and the
> > suggestion by Gavin to have in the translated manual an @anchor for
> > each @node with the original English name of that @node.
> >
> How come the translator doesn't always know whether a translated manual
> exists?
> 
> That is ridiculous.
> 
> It is the same as saying that a translator just translated a whole
> manual, without checking, and it was already translated. Ludacris.

This is a misunderstanding: I was talking about a manual other than
the one which is being translated by a translator.  A translator who
works on translating, say, the Emacs manual doesn't necessarily know
whether another manual, say, for Coreutils, to which the Emacs manual
has a cross-reference, has been translated to the same language, nor
whether such a translation of Coreutils will be installed on the
system where a user will read the translated Emacs manual.

> Sub-optimal? Like translators are deficient?

Granted, nothing like that was intended.  Sorry if what I wrote could
be even remotely hinting on something like that.

"Sub-optimal" in the sense that there will be situations where
clicking a cross-reference will show an error message instead of
taking me to another manual that I could read.

> (I am the translator of GnuPG and Git).

What do you do if you need to translate a cross reference from the
GnuPG manual to the Emacs manual?  Do you translate the node name to
which the cross-reference points?  If so, how do you know what is the
translation of that node's name in the Emacs manual?

> I wholeheartedly disagree with Eli. In here I am nobody, but still I
> don't like this complexity being added to a tool that I use to make
> my books (texinfo).

So you prefer that the Info reader shows an error message when the
user clicks a cross reference to another manual, and the translation
of that manual is not installed on the user's system, even if the
English version of that manual _is_ installed?  That's what I meant by
"sub-optimal".

I didn't suggest any solution, let alone a complex one.  I just said
that I think such a solution should exist.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Jean-Christophe Helary]

> On Jan 11, 2024, at 22:04, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Daniel Cerqueira <dan.list@brilhante.top>
>> Cc: Patrice Dumas <pertusus@free.fr>,
>>  jean.christophe.helary@traductaire-libre.org,  stefankangas@gmail.com,
>>  vincent.b.1@hotmail.fr,  emacs-devel@gnu.org,  rms@gnu.org,
>>  help-texinfo@gnu.org
>> Date: Thu, 11 Jan 2024 12:48:46 +0000
>> 
>>> The translator doesn't always know whether a translated manual exists
>>> when the translation is being written.  And even if a translated
>>> manual does exist, there's no reason to be sure it will be installed
>>> on the end-user's system.
>>> 
>>> So it would be good to have some Texinfo feature that would make the
>>> behavior of Info readers more user-friendly in these cases.  Right
>>> now, the Texinfo features that can help are @documentlanguage and the
>>> suggestion by Gavin to have in the translated manual an @anchor for
>>> each @node with the original English name of that @node.
>>> 
>> How come the translator doesn't always know whether a translated manual
>> exists?

Eli replied. But the discussion comes from an exchange on Emacs-devel 
where we raised the issue of incomplete manual “sets” where some 
manuals are translated but refer to manuals that may not yet be 
translated, etc. and that information may or may not be shared in the 
translators’ teams and may or may not be available to the end user, who 
may, or may not install all the translated manuals or only a number of 
them.

Hence the question of how we inform that user that the link she clicked 
on refers to something that may or may not be translated. The temporary 
conclusion is that it would be nice to have an error message that gives 
enough information in that regard, or provide a system that attempts to 
look up existing manuals, etc.

Manuals distributed with Emacs are not massively translated (yet), but 
since they are the place where most of the linking is taking place 
(think of the web of links between the Emacs manual and Emacs Lisp 
reference), it would be nice to find a solution that satisfies the need 
of the Emacs distribution but also of the other TexInfo based manual 
distributions. Hence the discussion being moved here.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Patrice Dumas]

On Thu, Jan 11, 2024 at 08:09:28AM +0200, Eli Zaretskii wrote:
> > Date: Wed, 10 Jan 2024 21:52:23 +0100
> > From: Patrice Dumas <pertusus@free.fr>
> > Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Kangas <stefankangas@gmail.com>,
> > 	Vincent Belaïche <vincent.b.1@hotmail.fr>,
> > 	emacs-devel@gnu.org, rms@gnu.org, help-texinfo@gnu.org
> > 
> > In any case, if a target manual is not yet translated, to me it is the
> > responsibility of the translator of amnual linking to it to either link
> > to the english manual, or to translate the node name in @ref even though
> > it won't lead to an existing manual and the name may need to be changed
> > later on to match with the actual name used in the translated manual.
> > To me both case could make sense depending on many criteria, such as
> > whether readers are likely to read english, whether manuals are
> > being translated...
> 
> The translator doesn't always know whether a translated manual exists
> when the translation is being written.  And even if a translated
> manual does exist, there's no reason to be sure it will be installed
> on the end-user's system.

Having nodes linking to non installed manuals is, in general, an issue.
But I do not think that defaulting to the english manual for non english
manuals is a good thing to do.  Instead, it could be confusing,
especially if the missing translated manual is not shown prominently and
an english manual is substituted without much information and would not
convey the intention of the manual writer.

In my opinion, it would be much better to design a way to help with
installing a manual that is not already installed but exists and is
linked to irrespective of the issue of translations and still leave the
responsibility to setup the cross reference to the translator.  Having
some way to check node links in Info through automatic downloading of
manuals and check of all the referencecs could be nice too, but without
any special treatments of manuals not in english.

> So it would be good to have some Texinfo feature that would make the
> behavior of Info readers more user-friendly in these cases.  Right
> now, the Texinfo features that can help are @documentlanguage and the
> suggestion by Gavin to have in the translated manual an @anchor for
> each @node with the original English name of that @node.

Having @anchor indeed can help if the translator wants to link to the
english manual with translated node names.  Still, in my opinion, it
should only happen if the translator has setup the @ref to link to the
english manual by using the english manual name as @ref manual argument.

> > In any case, I don't see any reason to do any automatic redirection in
> > the Info reader, it should remain simple and be the translators/writers
> > responsibilities.
> 
> I don't think I agree, because leaving this completely to the
> responsibilities of the translator could easily produce sub-optimal
> results.

On the contrary, I think that having translators be responsible of cross
manual references is the best possible solution.  It could mean a link
to an english or translated manual based on a choice and not on an
automatic rule.  In that case, a choice seems to be better to me.

It is different from gettext, I think.  When we use gettext having
something in english is, in most cases, better than having nothing.
For cross references between manuals I think that it is not true. Having
the information that the link does not point to an installed manual is
better than substituting an english manual. As I said above, even better
could be to have information on existing manuals (and node in them ?)
and propose to install the manual, but it is a separate issue.

> > Another reason is that it would not be possible to do the same in
> > HTML, as in HTML it is not possible to check if the target exists.
> 
> Even if this cannot possibly be done in HTML (and I'm not yet sure),
> it shouldn't stop us from doing that in Info.  After all, HTML output
> lacks several features of Info output already, and it doesn't stop us.

If we follow up the long term plan to have HTML on par with Info output
as outlined in TODO.HTML, we should think about that kind of feature and
its adaptation to HTML as early as possible in the design phase to make
things easier later on.

-- 
Pat

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> Date: Thu, 11 Jan 2024 14:49:12 +0100
> From: Patrice Dumas <pertusus@free.fr>
> Cc: jean.christophe.helary@traductaire-libre.org, stefankangas@gmail.com,
> 	vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org,
> 	help-texinfo@gnu.org
> 
> > The translator doesn't always know whether a translated manual exists
> > when the translation is being written.  And even if a translated
> > manual does exist, there's no reason to be sure it will be installed
> > on the end-user's system.
> 
> Having nodes linking to non installed manuals is, in general, an issue.
> But I do not think that defaulting to the english manual for non english
> manuals is a good thing to do.  Instead, it could be confusing,
> especially if the missing translated manual is not shown prominently and
> an english manual is substituted without much information and would not
> convey the intention of the manual writer.

I guess there are disagreements about the best course of action in
these cases: some think it is better to produce an error message,
while others think falling back to the English version of the manual
is better.  So this will most probably be a user option, so that each
one could customize what happens.

> In my opinion, it would be much better to design a way to help with
> installing a manual that is not already installed but exists and is
> linked to irrespective of the issue of translations and still leave the
> responsibility to setup the cross reference to the translator.  Having
> some way to check node links in Info through automatic downloading of
> manuals and check of all the referencecs could be nice too, but without
> any special treatments of manuals not in english.

This is a much more complex solution, and it has some problematic
aspects: it requires a network connection and some users consideer
such features an annoyance.

> Having @anchor indeed can help if the translator wants to link to the
> english manual with translated node names.  Still, in my opinion, it
> should only happen if the translator has setup the @ref to link to the
> english manual by using the english manual name as @ref manual argument.

Having @anchor with the English node name will allow cross-manual
links to go to a translated manual if it exists, falling back to the
English manual: all it takes is try to find manual-LANG.info (when the
user's language is LANG) before falling back to manual.info.  Whereas
cross-references with the translated manual could use the translated
node names instead.  This will also allow translators not to bother in
cross-references about translations of node names in other manuals:
they could simply use the English node names.

> On the contrary, I think that having translators be responsible of cross
> manual references is the best possible solution.  It could mean a link
> to an english or translated manual based on a choice and not on an
> automatic rule.  In that case, a choice seems to be better to me.

Yes, it will probably need to be a user option.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Patrice Dumas]

On Thu, Jan 11, 2024 at 05:08:28PM +0200, Eli Zaretskii wrote:
> This is a much more complex solution, and it has some problematic
> aspects: it requires a network connection and some users consideer
> such features an annoyance.

Of course, and not only that, it also requires a way to know which
manual exist, where they are, and possibly a way to install them or
point to a way to install.

> Having @anchor with the English node name will allow cross-manual
> links to go to a translated manual if it exists, falling back to the
> English manual: all it takes is try to find manual-LANG.info (when the
> user's language is LANG) before falling back to manual.info.  Whereas
> cross-references with the translated manual could use the translated
> node names instead.  This will also allow translators not to bother in
> cross-references about translations of node names in other manuals:
> they could simply use the English node names.

The node name may be visible in the output, so if English node names are
used they won't be in the translated manual language.  So I do not think
that is it correct, in general, to use the English node names even if
they link to the correct node in a translated manual with English node
names as anchors.

-- 
Pat

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> Date: Thu, 11 Jan 2024 16:56:15 +0100
> From: Patrice Dumas <pertusus@free.fr>
> Cc: jean.christophe.helary@traductaire-libre.org, stefankangas@gmail.com,
> 	vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org,
> 	help-texinfo@gnu.org
> 
> > Having @anchor with the English node name will allow cross-manual
> > links to go to a translated manual if it exists, falling back to the
> > English manual: all it takes is try to find manual-LANG.info (when the
> > user's language is LANG) before falling back to manual.info.  Whereas
> > cross-references with the translated manual could use the translated
> > node names instead.  This will also allow translators not to bother in
> > cross-references about translations of node names in other manuals:
> > they could simply use the English node names.
> 
> The node name may be visible in the output, so if English node names are
> used they won't be in the translated manual language.  So I do not think
> that is it correct, in general, to use the English node names even if
> they link to the correct node in a translated manual with English node
> names as anchors.

Sorry, I don't understand what you are saying.  What do you mean by
"visible in the output"? which output?

The idea is to have the node names translated in the translated
manual, but to also have an @anchor for each such node with the
original English node name.  There will be no other use of the English
node names in the translated manual.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Gavin Smith]

On Thu, Jan 11, 2024 at 06:09:20PM +0200, Eli Zaretskii wrote:
> > The node name may be visible in the output, so if English node names are
> > used they won't be in the translated manual language.  So I do not think
> > that is it correct, in general, to use the English node names even if
> > they link to the correct node in a translated manual with English node
> > names as anchors.
> 
> Sorry, I don't understand what you are saying.  What do you mean by
> "visible in the output"? which output?

The Info output, I believe.  Suppose there is a cross-reference to a node
in the Emacs manual, "Select Buffer".  This would appear in Info output
as "*note (emacs)Select Buffer::."  The English words "Select Buffer"
would appear incongruous surrounded by non-English text.

It's possible to supply a label for a cross-reference, so it could be
"*note Choisir Tampon:(emacs)Select Buffer.  (Apologies if this is bad
French.)  However, the English text is still visible.  It could be hidden
with Info-hide-note-references in Emacs or similar, but this is not an
ideal situation as the line lengths will be affected in a paragraph.

The problem with translating the node name is that a simple
cross-reference like "note (emacs)Choisir Tampon" would not work if
the manual and node did not exist.   First Info would have to know
the preferred language of the manual to find, and find a manual
"emacs-fr.info".  Then, if the manual does exist, the person
translating the manual may not have used that translation.  If they had
called it "Sélectionner buffer" instead it wouldn't be found.  Any manual
being translated would likely reference several others, many of which
will not have existing translations.  It's not right for a translator
just to make up their own translations of node names for manuals
which haven't been translated yet.

Although it's not ideal, using cross-reference labels may be the best
solution.  It would be a temporary solution if the targetted manual
obtained an English translation later.  Once that is the case, the
first manual could be updated with the translated node name, so
"*note Choisir Tampon:(emacs)Select Buffer." becomes
"*note (emacs)Choisir Tampon::", eliminating the English.

Automatic processing of other translated manuals could make node name
translations easily available.  You could imagine an Emacs command used
by a translator that would look up equivalent node and anchor names in
Texinfo documents, if they exist.  For example, if a translator translates
a file containing "@ref{Select Buffer,, emacs, The Emacs Editor}" and
supposing that emacs-fr.texi did exist with "@node Choisir Tampon" and
"@anchor{Select Buffer}" immediately after, the software could make
the @node name available to use in translating this @ref.  This would
require a translator to have the other translated manuals on their machines,
but you could imagine the same system working on an abbreviated version
of the manuals that solely had @node lines with following @anchor commands.

This all seems to me to be something to be worked out in software used
by translators as well as possibly processes to be followed by translation
teams.

Info download service

[Gavin Smith]

On Thu, Jan 11, 2024 at 02:49:12PM +0100, Patrice Dumas wrote:
> Having nodes linking to non installed manuals is, in general, an issue.
> But I do not think that defaulting to the english manual for non english
> manuals is a good thing to do.  Instead, it could be confusing,
> especially if the missing translated manual is not shown prominently and
> an english manual is substituted without much information and would not
> convey the intention of the manual writer.
> 
> In my opinion, it would be much better to design a way to help with
> installing a manual that is not already installed but exists and is
> linked to irrespective of the issue of translations and still leave the
> responsibility to setup the cross reference to the translator.

This would be great to have on GNU/Linux distributions that don't install
many Info manuals by default (such as Debian-derived distributions due to
GFDL woes).  Users could opt in to Info manual downloads once, and then
get many uninstalled manuals easily, rather than having to spend time
working out how to install them every time (usually finding the exact
package name needed in the distribution package manager).  Currently,
"info" is not very helpful for manuals that aren't installed, giving
no clue about how to get the manual or even if one exists.

I can imagine that implementing such a thing may have complications,
though.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Daniel Cerqueira]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Daniel Cerqueira <dan.list@brilhante.top>
>> Cc: Patrice Dumas <pertusus@free.fr>,
>>   jean.christophe.helary@traductaire-libre.org,  stefankangas@gmail.com,
>>   vincent.b.1@hotmail.fr,  emacs-devel@gnu.org,  rms@gnu.org,
>>   help-texinfo@gnu.org
>> Date: Thu, 11 Jan 2024 12:48:46 +0000
>> 
>
> What do you do if you need to translate a cross reference from the
> GnuPG manual to the Emacs manual?  Do you translate the node name to
> which the cross-reference points?  If so, how do you know what is the
> translation of that node's name in the Emacs manual?
>

Sorry Eli, I did let anger take over when replying to you.

Regarding GnuPG and Emacs manuals, those are not translated at GnuPG,
AFAIK. The translators mostly do the .po files. There is also another
file that needs translation.

>> I wholeheartedly disagree with Eli. In here I am nobody, but still I
>> don't like this complexity being added to a tool that I use to make
>> my books (texinfo).
>
> So you prefer that the Info reader shows an error message when the
> user clicks a cross reference to another manual, and the translation
> of that manual is not installed on the user's system, even if the
> English version of that manual _is_ installed?  That's what I meant by
> "sub-optimal".
>
> I didn't suggest any solution, let alone a complex one.  I just said
> that I think such a solution should exist.

Let me see. I think it would be best to show a standard error page, that
has links to the English manual, and a link or message to translate that
untranslated part, to our own language.

I would be ok with it automatically redirecting to the English manual,
but I know that, for example, Brazilian Portuguese speakers know very
little regarding English, and in that case, a English redirection might
not be suitable.

Requiring a internet connection is a no no.

Don't know if I am contradicting myself, I suppose this is a bit
complex.

The English node names should be the ones to be used
whole-languages-wide.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> From: Gavin Smith <gavinsmith0123@gmail.com>
> Date: Thu, 11 Jan 2024 18:22:03 +0000
> Cc: Patrice Dumas <pertusus@free.fr>,
> 	jean.christophe.helary@traductaire-libre.org,
> 	stefankangas@gmail.com, vincent.b.1@hotmail.fr, emacs-devel@gnu.org,
> 	rms@gnu.org, help-texinfo@gnu.org
> 
> On Thu, Jan 11, 2024 at 06:09:20PM +0200, Eli Zaretskii wrote:
> > > The node name may be visible in the output, so if English node names are
> > > used they won't be in the translated manual language.  So I do not think
> > > that is it correct, in general, to use the English node names even if
> > > they link to the correct node in a translated manual with English node
> > > names as anchors.
> > 
> > Sorry, I don't understand what you are saying.  What do you mean by
> > "visible in the output"? which output?
> 
> The Info output, I believe.  Suppose there is a cross-reference to a node
> in the Emacs manual, "Select Buffer".  This would appear in Info output
> as "*note (emacs)Select Buffer::."  The English words "Select Buffer"
> would appear incongruous surrounded by non-English text.

But so is "note", and you said we won't (and probably cannot) use
something else instead.  So English is already there.

> The problem with translating the node name is that a simple
> cross-reference like "note (emacs)Choisir Tampon" would not work if
> the manual and node did not exist.   First Info would have to know
> the preferred language of the manual to find, and find a manual
> "emacs-fr.info".  Then, if the manual does exist, the person
> translating the manual may not have used that translation.  If they had
> called it "Sélectionner buffer" instead it wouldn't be found.  Any manual
> being translated would likely reference several others, many of which
> will not have existing translations.  It's not right for a translator
> just to make up their own translations of node names for manuals
> which haven't been translated yet.

Right.

> Although it's not ideal, using cross-reference labels may be the best
> solution.  It would be a temporary solution if the targetted manual
> obtained an English translation later.  Once that is the case, the
> first manual could be updated with the translated node name, so
> "*note Choisir Tampon:(emacs)Select Buffer." becomes
> "*note (emacs)Choisir Tampon::", eliminating the English.

You mean, the Info reader should do that?  It would mean that the Info
reader will need to access all its cross-manual links in a node before
it can display the node with or without the English node names.

> Automatic processing of other translated manuals could make node name
> translations easily available.  You could imagine an Emacs command used
> by a translator that would look up equivalent node and anchor names in
> Texinfo documents, if they exist.  For example, if a translator translates
> a file containing "@ref{Select Buffer,, emacs, The Emacs Editor}" and
> supposing that emacs-fr.texi did exist with "@node Choisir Tampon" and
> "@anchor{Select Buffer}" immediately after, the software could make
> the @node name available to use in translating this @ref.  This would
> require a translator to have the other translated manuals on their machines,
> but you could imagine the same system working on an abbreviated version
> of the manuals that solely had @node lines with following @anchor commands.
> 
> This all seems to me to be something to be worked out in software used
> by translators as well as possibly processes to be followed by translation
> teams.

Right.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Gavin Smith]

On Thu, Jan 11, 2024 at 09:26:51PM +0200, Eli Zaretskii wrote:
> > The Info output, I believe.  Suppose there is a cross-reference to a node
> > in the Emacs manual, "Select Buffer".  This would appear in Info output
> > as "*note (emacs)Select Buffer::."  The English words "Select Buffer"
> > would appear incongruous surrounded by non-English text.
> 
> But so is "note", and you said we won't (and probably cannot) use
> something else instead.  So English is already there.

Readers of other languages can easily learn to recognize "*note" as a
marker of a cross-reference.  That is much different to a node name
which could be any English text.

> > Although it's not ideal, using cross-reference labels may be the best
> > solution.  It would be a temporary solution if the targetted manual
> > obtained an English translation later.  Once that is the case, the
> > first manual could be updated with the translated node name, so
> > "*note Choisir Tampon:(emacs)Select Buffer." becomes
> > "*note (emacs)Choisir Tampon::", eliminating the English.
> 
> You mean, the Info reader should do that?  It would mean that the Info
> reader will need to access all its cross-manual links in a node before
> it can display the node with or without the English node names.

I meant that the maintainers of the translated document would update it.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> From: Daniel Cerqueira <dan.list@brilhante.top>
> Cc: Daniel Cerqueira <dan.list@brilhante.top>,  pertusus@free.fr,
>   jean.christophe.helary@traductaire-libre.org,  stefankangas@gmail.com,
>   vincent.b.1@hotmail.fr,  emacs-devel@gnu.org,  rms@gnu.org,
>   help-texinfo@gnu.org
> Date: Thu, 11 Jan 2024 19:14:36 +0000
> 
> Sorry Eli, I did let anger take over when replying to you.

No sweat.

> Let me see. I think it would be best to show a standard error page, that
> has links to the English manual, and a link or message to translate that
> untranslated part, to our own language.

OK, so I guess you agree with Patrice, then.

> The English node names should be the ones to be used
> whole-languages-wide.

So you think the node names should not be translated in translated
manuals?  Or did I misunderstand you?

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> From: Gavin Smith <gavinsmith0123@gmail.com>
> Date: Thu, 11 Jan 2024 19:46:30 +0000
> Cc: pertusus@free.fr, jean.christophe.helary@traductaire-libre.org,
> 	stefankangas@gmail.com, vincent.b.1@hotmail.fr, emacs-devel@gnu.org,
> 	rms@gnu.org, help-texinfo@gnu.org
> 
> > > Although it's not ideal, using cross-reference labels may be the best
> > > solution.  It would be a temporary solution if the targetted manual
> > > obtained an English translation later.  Once that is the case, the
> > > first manual could be updated with the translated node name, so
> > > "*note Choisir Tampon:(emacs)Select Buffer." becomes
> > > "*note (emacs)Choisir Tampon::", eliminating the English.
> > 
> > You mean, the Info reader should do that?  It would mean that the Info
> > reader will need to access all its cross-manual links in a node before
> > it can display the node with or without the English node names.
> 
> I meant that the maintainers of the translated document would update it.

That'd mean whenever a new translated manual is released, the
translators will need to update all the manuals that cross-reference
to the newly-released one, and users will then need to update their
manuals.  Should be possible, of course, but quite a hassle, IMO.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Gavin Smith]

On Thu, Jan 11, 2024 at 10:03:29PM +0200, Eli Zaretskii wrote:
> > From: Gavin Smith <gavinsmith0123@gmail.com>
> > Date: Thu, 11 Jan 2024 19:46:30 +0000
> > Cc: pertusus@free.fr, jean.christophe.helary@traductaire-libre.org,
> > 	stefankangas@gmail.com, vincent.b.1@hotmail.fr, emacs-devel@gnu.org,
> > 	rms@gnu.org, help-texinfo@gnu.org
> > 
> > > > Although it's not ideal, using cross-reference labels may be the best
> > > > solution.  It would be a temporary solution if the targetted manual
> > > > obtained an English translation later.  Once that is the case, the
> > > > first manual could be updated with the translated node name, so
> > > > "*note Choisir Tampon:(emacs)Select Buffer." becomes
> > > > "*note (emacs)Choisir Tampon::", eliminating the English.
> > > 
> > > You mean, the Info reader should do that?  It would mean that the Info
> > > reader will need to access all its cross-manual links in a node before
> > > it can display the node with or without the English node names.
> > 
> > I meant that the maintainers of the translated document would update it.
> 
> That'd mean whenever a new translated manual is released, the
> translators will need to update all the manuals that cross-reference
> to the newly-released one, and users will then need to update their
> manuals.  Should be possible, of course, but quite a hassle, IMO.

Well, they wouldn't *need* to update the manuals.  The links to the
English node names would still work as long as the translated manual
has the @anchor commands with those node names.

RE: Where to contribute manual translations ?

[Vincent Belaïche]

[-- Attachment #1.1: Type: text/plain, Size: 1307 bytes --]

Please find it attached.

BR,
  V.
________________________________
De : emacs-devel-bounces+vincent.b.1=hotmail.fr@gnu.org <emacs-devel-bounces+vincent.b.1=hotmail.fr@gnu.org> de la part de Eli Zaretskii <eliz@gnu.org>
Envoyé : jeudi 4 janvier 2024 12:24
À : Vincent Belaïche <vincent.b.1@hotmail.fr>
Cc : jean.christophe.helary@traductaire-libre.org <jean.christophe.helary@traductaire-libre.org>; rrandresf@gmail.com <rrandresf@gmail.com>; rrandresf@hotmail.com <rrandresf@hotmail.com>; stefankangas@gmail.com <stefankangas@gmail.com>; emacs-devel@gnu.org <emacs-devel@gnu.org>; rms@gnu.org <rms@gnu.org>
Objet : Re: Where to contribute manual translations ?

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "emacs-devel@gnu.org" <emacs-devel@gnu.org>, Richard Stallman
>        <rms@gnu.org>
> Date: Mon, 1 Jan 2024 00:27:28 +0000
>
> I have pushed the French translation of SES manual to master, here is a patch to make the compilation :
>
> [https://res-h3.public.cdn.office.net/assets/mail/file-icon/png/generic_16x16.png]patch.diff<https://1drv.ms/u/s!AkDIBBjRAOVwg3y54YIxSCu3e2MI>
>
> Since I am not the maintainer of these Makefile.in scripts, I did not dare push this change.

Could you please post that patch here, either inline or as an
attachment?

Thanks.


[-- Attachment #1.2: Type: text/html, Size: 2959 bytes --]

[-- Attachment #2: patch 2.diff --]
[-- Type: application/octet-stream, Size: 9894 bytes --]

diff --git a/Makefile.in b/Makefile.in
index 45540d2742f..b076cccbe39 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -115,6 +115,8 @@ HAVE_GSETTINGS =
 
 ANDROID = @ANDROID@
 
+DOCLANGS=default fr
+
 # ==================== Where To Install Things ====================
 
 # Location to install Emacs.app under GNUstep / macOS.
@@ -800,7 +802,7 @@ install-info:
 	   [ -f "$(DESTDIR)${infodir}/dir" ] || \
 	      [ ! -f ${srcdir}/info/dir ] || \
 	      ${INSTALL_DATA} ${srcdir}/info/dir "$(DESTDIR)${infodir}/dir"; \
-	   info_misc=`MAKEFLAGS= $(MAKE) --no-print-directory -s -C doc/misc echo-info`; \
+	   info_misc="$(foreach lang,$(DOCLANGS),`MAKEFLAGS= $(MAKE) --no-print-directory -s -C doc/misc lang=$(lang) echo-info`)"; \
 	   cd ${srcdir}/info ; \
 	   for elt in ${INFO_NONMISC} $${info_misc}; do \
 	      for f in `ls $$elt $$elt-[1-9] $$elt-[1-9][0-9] 2>/dev/null`; do \
@@ -945,7 +947,7 @@ uninstall:
 	done
 	-rm -rf "$(DESTDIR)${libexecdir}/emacs/${version}"
 	thisdir=`pwd -P`; \
-	(info_misc=`MAKEFLAGS= $(MAKE) --no-print-directory -s -C doc/misc echo-info`; \
+	(info_misc="$(foreach LANG,$(DOCLANGS),`MAKEFLAGS= $(MAKE) --no-print-directory -s -C doc/misc LANG=$(LANG) echo-info`)"; \
 	 if cd "$(DESTDIR)${infodir}"; then \
 	   for elt in ${INFO_NONMISC} $${info_misc}; do \
 	     (cd "$${thisdir}"; \
@@ -1120,7 +1122,7 @@ TAGS tags:
 	$(MAKE) -C doc/emacs tags
 	$(MAKE) -C doc/lispintro tags
 	$(MAKE) -C doc/lispref tags
-	$(MAKE) -C doc/misc tags
+	$(foreach LANG,$(DOCLANGS),$(MAKE) -C doc/misc LANG=$(LANG) tags;)
 
 CHECK_TARGETS = check check-maybe check-expensive check-all check-byte-compile
 .PHONY: $(CHECK_TARGETS)
@@ -1142,7 +1144,7 @@ PSS   =
 
 DOCS = $(DVIS) $(HTMLS) $(INFOS) $(PDFS) $(PSS)
 $(DOCS):
-	$(MAKE) -C doc/$(subst -, ,$@)
+	$(foreach lang,$(DOCLANGS),$(MAKE) -C doc/$(subst -, LANG=$(lang) ,$@);)
 
 .PHONY: $(DOCS) docs pdf ps
 .PHONY: info dvi dist html info-dir check-info
@@ -1166,13 +1168,18 @@ misc-dvi misc-html misc-pdf misc-ps:
 
 info-dir: ${srcdir}/info/dir
 
-texi_misc = $(shell MAKEFLAGS= ${MAKE} --no-print-directory -s -C doc/misc echo-sources)
+define set_texi_misc
+texi_misc_$(1) = $$(shell MAKEFLAGS= $${MAKE} --no-print-directory -s -C doc/misc LANG=$(1) echo-sources)
+
+endef
+
+$(foreach lang,$(DOCLANGS),$(eval $(call set_texi_misc,$(lang))))
 
 srcdir_doc_info_dir_inputs = \
   ${srcdir}/doc/emacs/emacs.texi \
   ${srcdir}/doc/lispintro/emacs-lisp-intro.texi \
   ${srcdir}/doc/lispref/elisp.texi \
-  $(addprefix ${srcdir}/doc/misc/,${texi_misc})
+  $(foreach lang,$(DOCLANGS),$(addprefix ${srcdir}/doc/misc/$(filter-out ../lang/default/misc/,../lang/$(lang)/misc/),$(texi_misc_$(lang)) ))
 info_dir_inputs = \
   ../build-aux/dir_top \
   $(subst ${srcdir}/doc/,,${srcdir_doc_info_dir_inputs})
diff --git a/doc/lang/default/info_common.mk b/doc/lang/default/info_common.mk
new file mode 100644
index 00000000000..92b3f144019
--- /dev/null
+++ b/doc/lang/default/info_common.mk
@@ -0,0 +1,11 @@
+## Info files to build and install on all platforms.
+INFO_COMMON = auth autotype bovine calc ccmode cl dbus dired-x		\
+	ebrowse ede ediff edt efaq eglot eieio emacs-gnutls		\
+	emacs-mime epa erc ert eshell eudc eww flymake forms gnus	\
+	htmlfontify idlwave ido info.info mairix-el message mh-e	\
+	modus-themes newsticker nxml-mode octave-mode org pcl-cvs pgg	\
+	rcirc reftex remember sasl sc semantic ses sieve smtpmail	\
+	speedbar srecode todo-mode tramp transient url use-package	\
+	vhdl-mode vip viper vtable widget wisent woman
+
+DOCMISC_W32_TARGET = efaq-w32
diff --git a/doc/lang/fr/info_common.mk b/doc/lang/fr/info_common.mk
new file mode 100644
index 00000000000..e72440fe69a
--- /dev/null
+++ b/doc/lang/fr/info_common.mk
@@ -0,0 +1,8 @@
+## Info files to build and install on all platforms (onl ses has been
+## translated to Frenchj)
+INFO_COMMON = ses
+
+## efac-w32 has not been translated to French
+DOCMISC_W32:=#
+
+DOCMISC_W32_TARGET:=#
diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in
index 1831bbbb73f..b8ea16b554a 100644
--- a/doc/misc/Makefile.in
+++ b/doc/misc/Makefile.in
@@ -63,18 +63,18 @@ INSTALL_DATA =
 MAKEINFO = @MAKEINFO@
 MAKEINFO_OPTS = --force -I$(emacsdir)
 
+ifeq ($(LANG),)
+LANG:=default
+endif
+
+lang_suffix:=$(filter-out -default,-$(LANG))
+lang_subdir:=$(filter-out ../lang/default/misc/,../lang/$(LANG)/misc/)
+
 ## On MS Windows, efaq-w32; otherwise blank.
 DOCMISC_W32 = @DOCMISC_W32@
 
 ## Info files to build and install on all platforms.
-INFO_COMMON = auth autotype bovine calc ccmode cl dbus dired-x		\
-	ebrowse ede ediff edt efaq eglot eieio emacs-gnutls		\
-	emacs-mime epa erc ert eshell eudc eww flymake forms gnus	\
-	htmlfontify idlwave ido info.info mairix-el message mh-e	\
-	modus-themes newsticker nxml-mode octave-mode org pcl-cvs pgg	\
-	rcirc reftex remember sasl sc semantic ses sieve smtpmail	\
-	speedbar srecode todo-mode tramp transient url use-package	\
-	vhdl-mode vip viper vtable widget wisent woman
+include ../lang/$(LANG)/info_common.mk
 
 ## Info files to install on current platform.
 INFO_INSTALL = $(INFO_COMMON) $(DOCMISC_W32)
@@ -82,13 +82,13 @@ INFO_INSTALL =
 ## Info files to build on current platform.
 ## This is all of them, even though they might not all get installed,
 ## because the info files are pre-built in release tarfiles.
-INFO_TARGETS = $(INFO_COMMON) efaq-w32
+INFO_TARGETS = $(INFO_COMMON) $(DOCMISC_W32_TARGET)
 
 ## Some manuals have their source in .org format.
 ## This is discouraged because the .texi files it generates
 ## are not as well formatted as handwritten ones.
-ORG_SETUP = $(wildcard ${srcdir}/*-setup.org)
-ORG_SRC = $(filter-out ${ORG_SETUP},$(wildcard ${srcdir}/*.org))
+ORG_SETUP = $(wildcard ${srcdir}/$(lang_subdir)*-setup.org)
+ORG_SRC = $(filter-out ${ORG_SETUP},$(wildcard ${srcdir}/$(lang_subdir)*.org))
 TEXI_FROM_ORG = ${ORG_SRC:.org=.texi}
 
 # There are some naming differences between the info targets and the other
@@ -96,15 +96,18 @@ TEXI_FROM_ORG = ${ORG_SRC:
 TARGETS_1 = $(INFO_INSTALL:ccmode=cc-mode)
 TARGETS = $(TARGETS_1:info.info=info)
 
-texi_sources = $(addsuffix .texi,${TARGETS})
+# Sources are also suffixed, this is useless as they are in different
+# directories, but some people argued that there should not be
+# different files with same name in the repo.
+texi_sources = $(addsuffix $(lang_suffix).texi,${TARGETS})
 texi_notgen = $(filter-out $(notdir ${TEXI_FROM_ORG}),${texi_sources})
 texi_and_org = $(notdir ${ORG_SRC}) ${texi_notgen}
 SOURCES = $(sort ${texi_and_org})
 
-DVI_TARGETS  = $(TARGETS:=.dvi)
-HTML_TARGETS = $(TARGETS:=.html)
-PDF_TARGETS  = $(TARGETS:=.pdf)
-PS_TARGETS   = $(TARGETS:=.ps)
+DVI_TARGETS  = $(TARGETS:=$(lang_suffix).dvi)
+HTML_TARGETS = $(TARGETS:=$(lang_suffix).html)
+PDF_TARGETS  = $(TARGETS:=$(lang_suffix).pdf)
+PS_TARGETS   = $(TARGETS:=$(lang_suffix).ps)
 
 TEXI2DVI = texi2dvi
 TEXI2PDF = texi2pdf
@@ -132,7 +135,7 @@ info:
 ## Base file names of output info files.
 INFO_BASES = $(patsubst %.info,%,$(notdir $(INFO_INSTALL)))
 echo-info:
-	@: $(info $(addsuffix .info,$(INFO_BASES)))
+	@: $(info $(addsuffix $(lang_suffix).info,$(INFO_BASES)))
 
 echo-sources:
 	@: $(info $(SOURCES))
@@ -152,13 +155,13 @@ ${buildinfodir}:
 
 EXTRA_OPTS =
 
-${buildinfodir}/%.info: ${srcdir}/%.texi ${gfdl} ${style} | ${buildinfodir}
+${buildinfodir}/%$(lang_suffix).info: ${srcdir}/$(lang_subdir)%$(lang_suffix).texi ${gfdl} ${style} | ${buildinfodir}
 	$(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) $(EXTRA_OPTS) \
 	  -o $@ $<
 
 ## The short aliases, eg efaq = $(buildinfodir)/efaq.info.
 define info_template
- $(1): $$(buildinfodir)/$(1).info
+ $(1): $$(buildinfodir)/$(1)$(lang_suffix).info
 endef
 
 ## "info" is already taken.
@@ -167,17 +170,17 @@ info.info:
 $(foreach ifile,$(filter-out info.info,$(INFO_TARGETS)),$(eval $(call info_template,$(ifile))))
 
 
-%.dvi: ${srcdir}/%.texi ${gfdl} ${style}
+%$(lang_suffix).dvi: ${srcdir}/$(lang_subdir)%$(lang_suffix).texi ${gfdl} ${style}
 	$(ENVADD) $(TEXI2DVI) $<
 
-%.pdf: ${srcdir}/%.texi ${gfdl} ${style}
+%$(lang_suffix).pdf: ${srcdir}/$(lang_subdir)%$(lang_suffix).texi ${gfdl} ${style}
 	$(ENVADD) $(TEXI2PDF) $<
 
-%.html: ${srcdir}/%.texi ${gfdl} ${style}
+%$(lang_suffix).html: ${srcdir}/$(lang_subdir)%$(lang_suffix).texi ${gfdl} ${style}
 	$(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) $(EXTRA_OPTS) \
 	  -o $@ $<
 
-%.ps: %.dvi
+%$(lang_suffix).ps: %$(lang_suffix).dvi
 	$(DVIPS) -o $@ $<
 
 
@@ -204,16 +207,16 @@ ${buildinfodir}/ccmode.info:
 
 ## efaq, efaq_w32 do not depend on gfdl.
 ## Maybe we can use .SECONDEXPANSION for this.
-${buildinfodir}/efaq%.info: ${srcdir}/efaq%.texi ${style} | ${buildinfodir}
+${buildinfodir}/efaq%$(lang_suffix).info: ${srcdir}/efaq%$(lang_suffix).texi ${style} | ${buildinfodir}
 	$(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $<
 
-efaq%.dvi: ${srcdir}/efaq%.texi
+efaq%$(lang_suffix).dvi: ${srcdir}/efaq%$(lang_suffix).texi
 	$(ENVADD) $(TEXI2DVI) $<
 
-efaq%.pdf: ${srcdir}/efaq%.texi
+efaq%$(lang_suffix).pdf: ${srcdir}/efaq%$(lang_suffix).texi
 	$(ENVADD) $(TEXI2PDF) $<
 
-efaq%.html: ${srcdir}/efaq%.texi
+efaq%$(lang_suffix).html: ${srcdir}/efaq%$(lang_suffix).texi
 	$(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $<
 
 ${buildinfodir}/emacs-mime.info emacs-mime.html: EXTRA_OPTS = --enable-encoding
@@ -248,7 +251,10 @@ emacs =
 # things like org-setup's "version" macro work.  Sigh.
 define org_template
  $(1:.org=.texi): $(1) ${top_srcdir}/lisp/org/ox-texinfo.el
-	$${AM_V_GEN}cd "$${srcdir}" && $${emacs} -l ox-texinfo \
+	$${AM_V_GEN}cd "$${srcdir}" && $${emacs} \
+	  --eval '(add-to-list (quote load-path) "$(abspath ${top_srcdir}/lisp/org)")' \
+	  --eval '(setq org--inhibit-version-check t)' \
+	  -l ox-texinfo \
 	  --eval '(setq gc-cons-threshold 50000000)' \
 	  -f org-texinfo-export-to-texinfo-batch $$(notdir $$<) $$(notdir $$@)
 endef

RE: Translation of manuals (was: SES manual French translation)

[Vincent Belaïche]

[-- Attachment #1: Type: text/plain, Size: 2077 bytes --]

Somebody asked about my contribution to Emacs manual translations. Unfortunately, I am not able to contribute more than for SES. Since I maintain this program documenting it is part of the job, and since I am a native French speaker documenting it in French 1st and translating the additions to English when there are stable is just the easiest/laziest way to proceed.

  V.

PS : I will probably also push someday some documentation about 5x5 solver which explains how it works (I need to find again where I saved that file). This short document was quite fun to write as it is the first ever Texinfo document using macros with more than 10 args (I contributed to texinfo.tex for that ;-) ). This document will have to be transated to English, this is why I mention it here.
________________________________
De : emacs-devel-bounces+vincent.b.1=hotmail.fr@gnu.org <emacs-devel-bounces+vincent.b.1=hotmail.fr@gnu.org> de la part de Emanuel Berg <incal@dataswamp.org>
Envoyé : mardi 9 janvier 2024 04:08
À : emacs-devel@gnu.org <emacs-devel@gnu.org>
Objet : Re: Translation of manuals (was: SES manual French translation)

Richard Stallman wrote:

>> We know of various ways a service can treat users unjustly
>> -- we call them "dis-services". But we don't have
>> a complete list of them.
>
> To clarify we use "dis-services" to refer to "services" that
> mistreat users, but we don't have a full list of the bad
> things that a service can do (twhich would make it
> a dis-service"). Coming up with that is a hard problem.

Maybe we can instead have a positive model that defines
a FOSS service?

To begin with it would run on free or open source
software, sure.

So people would be allowed to fork it, and run it on their own
servers, i.e. replicate and modify the service provided if
they saw reason to, be it to add something they wanted, or
remove something they didn't like? Or just do whatever they
liked to?

Wouldn't that be enough to say, this is a FOSS service?

--
underground experts united
https://dataswamp.org/~incal



[-- Attachment #2: Type: text/html, Size: 3604 bytes --]

RE: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Vincent Belaïche]

[-- Attachment #1: Type: text/plain, Size: 2861 bytes --]

Just to react to this comment : I fully agree that a translation should keep exactly the same anchor & node names. So that switching the language is just a matter of replacing en by de, fr, ru, jp etc.

Emacs info viewer inserts the word « see », even in French, before links, fortunately « see » does not mean anything wrong in French, but still, this is a hassle. I wonder why this was done this way.

Also, a module like Calc finds function / command doc in the manual relying on some search, so this way of doing should be generalized, and made language independant if for other module than Calc people want to proceed this way, and if they want have translation of the manual.

   V.
________________________________
De : Gavin Smith <gavinsmith0123@gmail.com>
Envoyé : jeudi 11 janvier 2024 21:37
À : Eli Zaretskii <eliz@gnu.org>
Cc : pertusus@free.fr <pertusus@free.fr>; jean.christophe.helary@traductaire-libre.org <jean.christophe.helary@traductaire-libre.org>; stefankangas@gmail.com <stefankangas@gmail.com>; vincent.b.1@hotmail.fr <vincent.b.1@hotmail.fr>; emacs-devel@gnu.org <emacs-devel@gnu.org>; rms@gnu.org <rms@gnu.org>; help-texinfo@gnu.org <help-texinfo@gnu.org>
Objet : Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

On Thu, Jan 11, 2024 at 10:03:29PM +0200, Eli Zaretskii wrote:
> > From: Gavin Smith <gavinsmith0123@gmail.com>
> > Date: Thu, 11 Jan 2024 19:46:30 +0000
> > Cc: pertusus@free.fr, jean.christophe.helary@traductaire-libre.org,
> >      stefankangas@gmail.com, vincent.b.1@hotmail.fr, emacs-devel@gnu.org,
> >      rms@gnu.org, help-texinfo@gnu.org
> >
> > > > Although it's not ideal, using cross-reference labels may be the best
> > > > solution.  It would be a temporary solution if the targetted manual
> > > > obtained an English translation later.  Once that is the case, the
> > > > first manual could be updated with the translated node name, so
> > > > "*note Choisir Tampon:(emacs)Select Buffer." becomes
> > > > "*note (emacs)Choisir Tampon::", eliminating the English.
> > >
> > > You mean, the Info reader should do that?  It would mean that the Info
> > > reader will need to access all its cross-manual links in a node before
> > > it can display the node with or without the English node names.
> >
> > I meant that the maintainers of the translated document would update it.
>
> That'd mean whenever a new translated manual is released, the
> translators will need to update all the manuals that cross-reference
> to the newly-released one, and users will then need to update their
> manuals.  Should be possible, of course, but quite a hassle, IMO.

Well, they wouldn't *need* to update the manuals.  The links to the
English node names would still work as long as the translated manual
has the @anchor commands with those node names.

[-- Attachment #2: Type: text/html, Size: 4857 bytes --]

Re: Translating Emacs manuals is of strategic importance

[Gregory Heytings]

>
> Because if you are talking about translations of the manuals, then 
> please name free software projects that have high-quality translations 
> of their manuals, and the manuals are of sufficient size to consider 
> them anywhere near what Emacs has to deal with.
>

FYI, the LibreOffice manual ("Help") is more than twice the size of the 
Emacs manual, and has been translated in a few dozen languages.

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "pertusus@free.fr" <pertusus@free.fr>,
> 	"jean.christophe.helary@traductaire-libre.org"
> 	<jean.christophe.helary@traductaire-libre.org>, "stefankangas@gmail.com"
> 	<stefankangas@gmail.com>, "emacs-devel@gnu.org" <emacs-devel@gnu.org>,
> 	"rms@gnu.org" <rms@gnu.org>, "help-texinfo@gnu.org" <help-texinfo@gnu.org>
> Date: Thu, 11 Jan 2024 21:58:20 +0000
> 
> Emacs info viewer inserts the word « see », even in French, before links, fortunately « see » does
> not mean anything wrong in French, but still, this is a hassle. I wonder why this was done this way.

We can insert the equivalent of "see" in the document's language
(there's a TODO item for that), but to do it correctly we need to know
the language of the manual.  Up until now, makeinfo didn't leave any
trace of the @documentlanguage directive in the Info file it produces,
so Emacs couldn't DTRT there.  AFAIU the development version of
Texinfo has a change to propagate @documentlanguage into the Info
file, so now the TODO item is doable as soon as the new version of
Texinfo is released.

> Also, a module like Calc finds function / command doc in the manual relying on some search, so this
> way of doing should be generalized, and made language independant if for other module than Calc
> people want to proceed this way, and if they want have translation of the manual.

Not sure I understand this.  Could you please provide the details
about the search for functions in Calc?

Re: Translating Emacs manuals is of strategic importance

[Eli Zaretskii]

> Date: Fri, 12 Jan 2024 00:28:40 +0000
> From: Gregory Heytings <gregory@heytings.org>
> cc: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>, 
>     stefankangas@gmail.com, vincent.b.1@hotmail.fr, emacs-devel@gnu.org, 
>     rms@gnu.org
> 
> > Because if you are talking about translations of the manuals, then 
> > please name free software projects that have high-quality translations 
> > of their manuals, and the manuals are of sufficient size to consider 
> > them anywhere near what Emacs has to deal with.
> 
> FYI, the LibreOffice manual ("Help") is more than twice the size of the 
> Emacs manual, and has been translated in a few dozen languages.

Is it written in Texinfo?  Does it reference other manuals?  How does
LibreOffice decide in which language to display the manual?

Re: Translating Emacs manuals is of strategic importance

[Gregory Heytings]

>> FYI, the LibreOffice manual ("Help") is more than twice the size of the 
>> Emacs manual, and has been translated in a few dozen languages.
>
> Is it written in Texinfo?
>

Of course not.  The "master" (English) file is written in XML, and PO is 
used for the translations.

>
> Does it reference other manuals?
>

No, AFAIK it is self-contained.

>
> How does LibreOffice decide in which language to display the manual?
>

LibreOffice is fully localized.  Its UI elements and Help are displayed in 
the language specified in the LC_ALL or LANG environment variable.

Re: Translating Emacs manuals is of strategic importance

[Eli Zaretskii]

> Date: Fri, 12 Jan 2024 12:08:09 +0000
> From: Gregory Heytings <gregory@heytings.org>
> cc: jean.christophe.helary@traductaire-libre.org, stefankangas@gmail.com, 
>     vincent.b.1@hotmail.fr, emacs-devel@gnu.org, rms@gnu.org
> 
> 
> >> FYI, the LibreOffice manual ("Help") is more than twice the size of the 
> >> Emacs manual, and has been translated in a few dozen languages.
> >
> > Is it written in Texinfo?
> >
> 
> Of course not.  The "master" (English) file is written in XML, and PO is 
> used for the translations.
> 
> >
> > Does it reference other manuals?
> >
> 
> No, AFAIK it is self-contained.
> 
> >
> > How does LibreOffice decide in which language to display the manual?
> >
> 
> LibreOffice is fully localized.  Its UI elements and Help are displayed in 
> the language specified in the LC_ALL or LANG environment variable.

Thanks.

So I conclude that the LibreOffice manual cannot help us figure out
how to handle the issues raised in this discussion, viz.:

  . how to handle Texinfo cross-references to other manuals
  . how to decide which of the translated manuals to display by
    default, based on the information we have from the Info manual

Re: Info download service

[Daniel Cerqueira]

That is a Debian problem, not a Emacs problem.

My GNU/Linux-libre system does not have that problem. And that would
lead to centralization of manuals, and are we sick of centralization?

Also, it will begin as authors having to upload their manuals to a
central place, only to later that place having problems and having to
make some restrictions, and then new book places arise where you could
upload books with less restrictive policies than the central place,
resulting in people having to upload to various places, or else no one
will read their books. Also distributions stopped providing info books
(they only offer a link) since there is already a outside place that
hosts books for them. Leaving distributions without manuals, for a thing
that should have been dealt with at the Debian distribution level. Now
books can only be obtained by a JavaScript enabled web browser (for
security reasons) and those info book places are praised as an
"innovation of technology" by various magazines. The end.

:-) :-)

Things are good as they are. My best advice is to change from Debian to
Parabola.

Re: Info download service

[Eli Zaretskii]

> From: Daniel Cerqueira <dan.list@brilhante.top>
> Cc: Patrice Dumas <pertusus@free.fr>,  Eli Zaretskii <eliz@gnu.org>,
>   jean.christophe.helary@traductaire-libre.org,  stefankangas@gmail.com,
>   vincent.b.1@hotmail.fr,  emacs-devel@gnu.org,  rms@gnu.org,
>   help-texinfo@gnu.org
> Date: Fri, 12 Jan 2024 14:42:58 +0000
> 
> That is a Debian problem, not a Emacs problem.

What is?  (Since you haven't quoted the parts to which you are
replying, I cannot guess what problem you are alluding to.)

> My GNU/Linux-libre system does not have that problem. And that would
> lead to centralization of manuals, and are we sick of centralization?

The place of each manual is with the package it documents.  Translated
manuals should IMO also be part of the release tarball of the
corresponding packages.

> Also, it will begin as authors having to upload their manuals to a
> central place, only to later that place having problems and having to
> make some restrictions, and then new book places arise where you could
> upload books with less restrictive policies than the central place,
> resulting in people having to upload to various places, or else no one
> will read their books. Also distributions stopped providing info books
> (they only offer a link) since there is already a outside place that
> hosts books for them. Leaving distributions without manuals, for a thing
> that should have been dealt with at the Debian distribution level. Now
> books can only be obtained by a JavaScript enabled web browser (for
> security reasons) and those info book places are praised as an
> "innovation of technology" by various magazines. The end.
> 
> :-) :-)
> 
> Things are good as they are. My best advice is to change from Debian to
> Parabola.

Indeed, AFAIK Debian has problems with Info manual (and FSF manuals in
general), since they consider them to be non-free.

But other distros don't have this problem, AFAIK.

Re: Translating Emacs manuals is of strategic importance

[Gregory Heytings]

>
> So I conclude that the LibreOffice manual cannot help us figure out how 
> to handle the issues raised in this discussion, viz.:
>
>  . how to handle Texinfo cross-references to other manuals
>  . how to decide which of the translated manuals to display by
>    default, based on the information we have from the Info manual
>

I did not mean to address these two issues (which appeared later in the 
discussion), but only to answer your question, viz.:

>
> Because if you are talking about translations of the manuals, then 
> please name free software projects that have high-quality translations 
> of their manuals, and the manuals are of sufficient size to consider 
> them anywhere near what Emacs has to deal with.
>

And here's my opinion on these two issues:

About the first issue, ISTM that using an indirection table, as you 
suggested ("One possibility could be some kind of "translation table" 
inside an Info file, which maps English node names to translated names.") 
is TRT in the Texinfo framework.  Translated info files could contain such 
a table, linking the translated node names to the "master" node names (the 
English ones).  That would allow jumping from any node in any language to 
any node in any language.

About the second issue, ISTM that using the LANG environment variable is 
TRT (on GNU/Linux).

Re: free services (was: Re: Translation of manuals (was: SES manual French translation))

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > The service itself is not software, it is the result of the
  > work of software that runs on a server.

Yes, that's how computerized online services generally work.

  > If all that software, including the interface(s), are free,
  > I don't see why not the whole thing is free as well.

Because calling that server "free" would be misleading.  To avoid
misleading conclusions, we don't call servers "free" or "nonfree".  See
https://www.gnu.org/philosophy/network-services-arent-free-or-nonfree.html.

We call a program "free" if users have control what the program does
for them -- so if you install a copy on your computer, you have
control over what your copy will do.  If you don't like what it does,
you can change it.

If John's server runs that very same free program, John can change his
copy.  You can change your copy, too, if you have one.  But you cannot
change the copy in John's server. You have no control over what that
server does.

If "all the programs" that implement the service are free, you could
install the same programs on your own server.  But you may not be anle
to get the local changes made on that server.  Also, it may have
configurations, scripts, and surely some data.

But even if it is possible to set up a similar service, it will be a
lot of work and take a lot of time.

The conclusion is that no server is ever "free" in the sense that free
programs are free.



-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Info download service

[Patrice Dumas]

On Fri, Jan 12, 2024 at 02:42:58PM +0000, Daniel Cerqueira wrote:
> My GNU/Linux-libre system does not have that problem. And that would
> lead to centralization of manuals, and are we sick of centralization?

Not necessarily centralization of manuals, but maybe centralization of
manual locations, to know where to download from.  We already have
something like that for HTML cross references, actually, the htmlxref.cnf
file, which is maintained in Texinfo.
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Configuration.html

That being said, even if it is only centralization of where to find
manuals, any centralization is not ideal, but I can't see another way to
do it.

> Also, it will begin as authors having to upload their manuals to a
> central place, only to later that place having problems and having to
> make some restrictions, and then new book places arise where you could
> upload books with less restrictive policies than the central place,
> resulting in people having to upload to various places, or else no one
> will read their books. Also distributions stopped providing info books
> (they only offer a link) since there is already a outside place that
> hosts books for them.

This is already possible to do that, most of the info manuals are also
quite easily available from the web.  Of course there is still some work
to do before making it easier, as we are discussing here, but in any case, if
anybody wants to do that code, we cannot stop Distributions from using
it.  I do not believe that it would be a code hard to do, so I do not
think that whether we do it or not changes much the possibility of
having only online info manuals.  If we want Info manuals to keep being
installed, we must be convincing, as we cannot have any real control.
This is the same for HTML manuals, in the long term the plan is to have
HTML manuals used for local browsing, I think that we need to be
convincing here, such that Distributions install locally HTML manual.

> Things are good as they are. My best advice is to change from Debian to
> Parabola.

Even if this is an issue that is more pregnant with Debian because of
their policy regarding GFDL with invariant sections, this is an issue
that exists for any Distribution that do not install all the manuals
linked to from an installed Info manual.

-- 
Pat

Re: Info download service

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > That being said, even if it is only centralization of where to find
  > manuals, any centralization is not ideal, but I can't see another way to
  > do it.

Some centralization is important for reasons beyond convenience.  We
need to give the community a centralized method of finding the
official GNU manuals, and the translations whose translators we at
least are in contact with.

It would not be good to recommend that people search for anything that
says it is a translation of a GNU manual, and take that on faith.

  > This is already possible to do that, most of the info manuals are also
  > quite easily available from the web.  Of course there is still some work
  > to do before making it easier, as we are discussing here, but in any case, if
  > anybody wants to do that code, we cannot stop Distributions from using
  > it.  I do not believe that it would be a code hard to do, so I do not
  > think that whether we do it or not changes much the possibility of
  > having only online info manuals.

Those words are alarming but vague.  They seem to say that some
problems are impossible to prevent, but I can't tell what problems you
mean.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Info download service

[Patrice Dumas]

On Sun, Jan 14, 2024 at 10:13:14PM -0500, Richard Stallman wrote:
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> 
>   > That being said, even if it is only centralization of where to find
>   > manuals, any centralization is not ideal, but I can't see another way to
>   > do it.
> 
> Some centralization is important for reasons beyond convenience.  We
> need to give the community a centralized method of finding the
> official GNU manuals, and the translations whose translators we at
> least are in contact with.

Agreed.  But there should also be non-GNU manuals.  We can maintain a
list here in the Texinfo package, but I am not sure that it scales well.
Again, I do not have a good solution either.

>   > This is already possible to do that, most of the info manuals are also
>   > quite easily available from the web.  Of course there is still some work
>   > to do before making it easier, as we are discussing here, but in any case, if
>   > anybody wants to do that code, we cannot stop Distributions from using
>   > it.  I do not believe that it would be a code hard to do, so I do not
>   > think that whether we do it or not changes much the possibility of
>   > having only online info manuals.
> 
> Those words are alarming but vague.  They seem to say that some
> problems are impossible to prevent, but I can't tell what problems you
> mean.

I did not meant to be alarming.  I agree with Daniel that it is better
if manuals are installed locally (Info manuals today, maybe HTML manuals
with Info browsing capabilities tomorrow).  My point is that, if
Distributions do not want to have manuals installed locally, but provide
ways to download manuals instead, we can not do much against such
decision.  In particular, I do not believe that adding to Info readers the
possibility to download manuals to resolve links will particularly lead
to Distributions stop installing manuals locally and I do not think
either that refraining from providing this feature ourselves is a good
way to avoid Distributions stop installing manuals locally.

-- 
Pat

Re: Info download service

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Some centralization is important for reasons beyond convenience.  We
  > > need to give the community a centralized method of finding the
  > > official GNU manuals, and the translations whose translators we at
  > > least are in contact with.

  > Agreed.  But there should also be non-GNU manuals.

I think the question of qhat issue we are discussing has not been
entirely clarified.  I got the idea, a few days ago, that we were
talking about managing development and release of translations of GNU
manuals.  You seem to be bringing up a different issue.

Both issues are useful but we had better not mix them up.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Info download service

[Patrice Dumas]

On Wed, Jan 17, 2024 at 10:35:38PM -0500, Richard Stallman wrote:
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> 
>   > > Some centralization is important for reasons beyond convenience.  We
>   > > need to give the community a centralized method of finding the
>   > > official GNU manuals, and the translations whose translators we at
>   > > least are in contact with.
> 
>   > Agreed.  But there should also be non-GNU manuals.
> 
> I think the question of qhat issue we are discussing has not been
> entirely clarified.  I got the idea, a few days ago, that we were
> talking about managing development and release of translations of GNU
> manuals.  You seem to be bringing up a different issue.

We drifted somewhat from that discussion towards resolution of link to
non installed manuals, be them translated or not.  This issue of knowing
where the manuals are to resolve links is, in my opinion, better to
consider in that context.  It is particularly relevant for translated
manuals, but not only.

> Both issues are useful but we had better not mix them up.

It seems to me that they are necessarily mixed up to some extent, as the
code in the info readers and in the Texinfo processors will need to
handle in a similar way GNU and non-GNU manuals.  For GNU manuals, we
should probably set up some kind of "authoritative" information on where
they could be found, but the code that would handle getting manuals
should be the same, and would need to handle links to non-GNU manuals
too.  Even for the "authoritative" information, I think that it could
make sense to do the same for non-GNU manuals, possibly in the same
file, in particular for manuals that are linked to often from GNU
manuals.

-- 
Pat

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Jean-Christophe Helary]

> On Jan 7, 2024, at 4:18, Gavin Smith <gavinsmith0123@gmail.com> wrote:
> 
> On Sat, Jan 06, 2024 at 10:36:28AM +0200, Eli Zaretskii wrote:
>>> Would @author be also used for the translator?
>> 
>> @author is a TeX command and goes into the printed version.  For
>> translation, we'd need a separate directive, I think, since a
>> translator is not the author.  Again, this is something for the
>> Texinfo folks to handle.
> 
> The Texinfo manual gives the example
> 
>     @author by Jane Smith and John Doe
> 
> The word "by" show that the argument of @author does not just have
> to be the name of the author.  However, it may be confusing for some
> output formats, such as DocBook.  The example in the Texinfo manual:
> 
> @titlepage
> @title NAME-OF-MANUAL-WHEN-PRINTED
> @subtitle SUBTITLE-IF-ANY
> @subtitle SECOND-SUBTITLE
> @author AUTHOR
> @page
> ...
> @end titlepage
> 
> yields, in DocBook:
> 
> <bookinfo><title>NAME-OF-MANUAL-WHEN-PRINTED</title>
> <subtitle>SUBTITLE-IF-ANY
> SECOND-SUBTITLE</subtitle>
> <authorgroup>
> <collab><collabname>AUTHOR</collabname></collab>
> </authorgroup>
> </bookinfo>
> 
> It's questionable whether this would be a correct use of <collabname>
> and <authorgroup> or not.  The online DocBook documentation says,
> 
> "The AuthorGroup element is a wrapper around multiple authors or other
> collaborators."
> 
> <https://tdg.docbook.org/tdg/4.5/authorgroup>

I guess there is a reason why you refer to DocBook 4.5 and not DocBook 5.0?

https://tdg.docbook.org/tdg/5.0/ch01#introduction-whats-new

collabname and a few others have been merged into orgname.

collab now has the following children:  affiliation, org, orgname, person, personname.

https://tdg.docbook.org/tdg/5.0/collab

Re: @dircategory (Re: Translating Emacs manuals is of strategic importance)

[Patrice Dumas]

On Mon, Jan 22, 2024 at 08:48:03AM +0000, Jean-Christophe Helary wrote:
> > It's questionable whether this would be a correct use of <collabname>
> > and <authorgroup> or not.  The online DocBook documentation says,
> > 
> > "The AuthorGroup element is a wrapper around multiple authors or other
> > collaborators."
> > 
> > <https://tdg.docbook.org/tdg/4.5/authorgroup>
> 
> I guess there is a reason why you refer to DocBook 4.5 and not DocBook 5.0?

It is because texi2any generates DocBook 4.5.  I have no idea which
should be our target.  I do not want to maintain conversion to different
DocBook versions.  It seems that there is an xslt to convert 4.5 to 5,
this is in favor of outputing 4.5, but if nobody uses 4.5 anymore, it
may be right to switch to 5.0, I don't know.  If, however, there are
still many applications that prefer 4.5, we could stay with 4.5.

> https://tdg.docbook.org/tdg/5.0/ch01#introduction-whats-new
> 
> collabname and a few others have been merged into orgname.
> 
> collab now has the following children:  affiliation, org, orgname, person, personname.
> 
> https://tdg.docbook.org/tdg/5.0/collab

That's actually an issue for conversion from Texinfo, as it means that
the generic collabname is gone, we have to choose between org/orgname,
which is inadequate, and person/personname which is not usable, as it is
incorrect when @author corresponds to many authors, and even if there is
one author, in Texinfo there is no way to get the elements of a name
needed for personname.  I am not sure that we used collabname correctly,
but at least it was practical.

Ideas to convert te lax Texinfo @author to DocBook 5 are welcome...

-- 
Pat

Re: Translation of the Org mode manual (was: Translation of manuals (was: SES manual French translation))

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

> 1. Org mode manual itself, just like the other Emacs manuals may need to
>   be translated. However, Org mode manual source is written in Org mode
>   format, not texi. It is just transformed to texi as one of the export
>   options.

Using Org format for the source of a document, and converting it to
texi for processing (for instance, through TeX) would be a fine method
to use, if it worked.  But it doesn't actually work.

The problem is that it cannot work, given Org format as it exists now.
It cannot properly represent manuals that use the GNU standard style
because it does not have ways to represent all the distinctions that
are needed.

Texinfo implements semantic markup, and is designed for multiple
output formats, including Info, HTML, and DVI (whence also PDF).  Two
different markup constructs that look the same in one output format
may look different in another.  All these design decisions were the
result of long thought.

For instance, italic face can be the result of @dfn, @var, @emph,
@cite and @i.  Each of them has a meaning -- which one to use is not a
matter of taste.

@cite is used around the title of a book.
@dfn is used around the first use of a term, to say it is being defined.
@emph is used to indicate emphasis.
@var is used around a metasyntactic variable.

@i means "use italic for this" and does not say why.  It is a escape
for situations that Texinfo has no specific way to describe.

These five commands produce the same output in DVI/PDF, but different
output in Info.

I think there must be 15 different Texinfo commands to generate
fixed-width bold text in DVI/PDF.

To represent a manual source in Org format and do the job right is not
possible with Org format as it is now.  To make it possible requires
extending Org format so it can make all the distinctions Texinfo can
make.

I would like Org format to be extended in this way.

Texinfo format is often misunderstood.  People write GNU manuals
without knowing of all these constructs, so they use the wrong
construct.  If Org format were extended to do _the whole job_, we
could convert all manuals to Org format once and for all.

A few years ago I raised this idea, but nobody wanted to work on it.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Translation of the Org mode manual (was: Translation of manuals (was: SES manual French translation))

[Ihor Radchenko]

Richard Stallman <rms@gnu.org> writes:

> Using Org format for the source of a document, and converting it to
> texi for processing (for instance, through TeX) would be a fine method
> to use, if it worked.  But it doesn't actually work.
>
> The problem is that it cannot work, given Org format as it exists now.
> It cannot properly represent manuals that use the GNU standard style
> because it does not have ways to represent all the distinctions that
> are needed.
> ...

This is not true. We can generate a precise TeXinfo markup from Org
files even now using export snippets: @@texinfo:<direct texinfo code>@@

So, Org mode manual in particular can be adapted if absolutely
necessary.

Another question is that having native Org mode constructs for
manual-specific markup would make things less verbose and ad-hoc. But
that question is out of scope of this particular discussion, which is
focused on translation tools.

> I would like Org format to be extended in this way.
>
> Texinfo format is often misunderstood.  People write GNU manuals
> without knowing of all these constructs, so they use the wrong
> construct.  If Org format were extended to do _the whole job_, we
> could convert all manuals to Org format once and for all.
>
> A few years ago I raised this idea, but nobody wanted to work on it.

Your idea is not forgotten. But the resources for Org mode development
are limited. In particular, I am currently not prioritizing adding
brand-new features in favour of helping contributors, improving the
existing functionality, and fixing the existing problems.

If somebody is interested to work on adding new Org mode features like
custom inline markup, please contact Org mode mailing list. We can guide
the volunteers through the contribution process and help with any
questions when they arise.
See https://orgmode.org/worg/org-contribute.html

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Translation of the Org mode manual (was: Translation of manuals (was: SES manual French translation))

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > This is not true. We can generate a precise TeXinfo markup from Org
  > files even now using export snippets: @@texinfo:<direct texinfo code>@@

I know that it is possible to convert Org format to Texinfo.  I am
raising a different issue.  I think we are miscommunicating.

The question is not whether Org can be translated to Texingo.  The
question is whether Org format can represent all the distinctions that
Texinfo represents.  Or, equivalently, is it possible to translate
Texinfo text to Org format and then back to Texinfo format without
losing any information?

Last I looked, that was not possible, because of the issue I
explained in my previous message.

If things have improved and Org format is now capable of doing this, I
will consider that good news.

  > Another question is that having native Org mode constructs for
  > manual-specific markup would make things less verbose and ad-hoc.

To handle GNU manuals using Org format would not require a feature
like that.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Translating Emacs manuals is of strategic importance

[Jean-Christophe Helary]

> On Jan 12, 2024, at 9:28, Gregory Heytings <gregory@heytings.org> wrote:
> 
>> Because if you are talking about translations of the manuals, then
>> please name free software projects that have high-quality translations
>> of their manuals, and the manuals are of sufficient size to consider
>> them anywhere near what Emacs has to deal with.
> 
> FYI, the LibreOffice manual ("Help") is more than twice the size of the
> Emacs manual, and has been translated in a few dozen languages.

I wanted to answer that for a long time, but the LO Help translation 
started when StarOffice first published the software, was then handled 
by Sun Microsystem for a long time and when LibreOffice came into 
existence, the manual already existed as an ongoing international 
project with a stable infrastructure, accepted workflows, etc. I still 
remember vividly when we had “project managers” working on Sun side, and 
Sun was also working with translation vendors, had started working on 
mtpe, etc.

So comparing the two translation projects only based on their size when 
one is close to 4 decades old and extremely mature and the other 
barely starting does not seem to be a meaningful comparison.