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

[Gavin Smith <gavinsmith0123@gmail.com>]

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