Many errors while converting the emacs manuals

[brandelune]

I have 3 manuals that fail to build and a number of other that generate seemingly irrelevant errors.

https://lists.gnu.org/archive/html/emacs-devel/2018-04/msg00406.html

[mquinson]

Indeed, our support for the texi format is far from being robust. I wish someone with actual interest in that format could investigate the problems. I have the feeling that some of these errors are easy to fix, but I won't find the time to investiguate myself, unfortunately.

[roptat]

Hi, I've successfully used po4a to generate the translation of the Guix manual. The only issue I had was with translating chapter titles, because they are referenced by name. I've written a script to take care of these, in case that is useful to someone else: http://git.savannah.gnu.org/cgit/guix.git/tree/doc/local.mk (the xref_command procedure).

A smaller issue I have is when definitions span multiple lines, such as in:

@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
  @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
  [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
…

I get the following to translate:

{Scheme Procedure} derivation @var{store} @var{name} @var{builder} @

and

@var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @ …

It should instead preserve line breaks and either ask for the complete block or separate the procedure synopsis from its description.

[mquinson]

Thanks for this feedback, and sorry for the delay.

It's a good news that you managed to translate a non-trivial texi document with po4a. I'd appreciate if you could contribute some test cases experiencing some parts the language, for our test suite.

I must confess that I don't really understand the xref_command procedure that you are pointing to. I did not even knew that it was possible to have functions in make! After 20 years of use, that's quite a shock to me :) Could you please enlight me by being more verbose on what's the problem and how you solve it? Do you think it'd be doable in the perl code of po4a directly? A broken test case that would guide me to implement this would be really welcome, please.

Likewise, I'm not sure I understand what's going wrong with the deffn line. Please be patient with me, I've never approached TexInfo before. Is it because the line ends with @ that the line break should be preserved? Or because of the indentation of the next lines? Or am I off track again?

[roptat]

So, to explain the issue with xref, suppose my document has this node:

@node Some Node

And a reference to it (the info manual will contain the text See Some Node):

@xref{Some Node}

Po4a creates the following entries:

msgid "Some Node"
msgstr ""

msgid "@xref{Some Node}"
msgstr ""

Which I think is correct. I can translate that and po4a will happily create a translated manual. The issue arises when the translation is incomplete. For instance when the English manual is updated with a new reference to Some Node, the po file will not have a translation for it. In this example, the translated manual will contain a reference to a non-existing node "Some Node". Texinfo will refuse to generate the document.

The purpose of the small script in the Makefile is to ensure that every reference is translated correctly. For each reference in the translated .texi file, it gets the node name (in a clever way because there may be more than one reference per line, and a reference can span two lines). Then, it tries to find it in the .po file and replace the reference with its proper translation.

For the deffn line, line breaks are not preserved in the msgid, but must be present in the msgstr, which is a bit confusing. Po4a can still find the correct lines to trantlate even though it contains line breaks when the msgid doesn't.

Another issue is the way it is split in the .po file. I would expect to have a msgstr containing the whole definition and then its explanation, but I get the first line of the definition and the rest of the definition with the explanation. For instance :

@deffn {Scheme Procedure} some-procedure @var{foo} @
@var {bar} @var{baz} @
@var{foobar}
Returns a random value
@end deffn

This will produce these entries:

msgid ""
"{Scheme Procedure} some-procedure @var{foo} @"
msgstr ""

msgid ""
"@var {bar} @var{baz} @ @var{foobar} Returns "
"a random value"
msgstr ""

When this is what would make more sense:

"{Scheme Procedure} some-procedure @var{foo} @\n"
"@var {bar} @var{baz} @\n"
"@var{foobar}"
msgstr ""

msgid ""
"Returns a random value"
msgstr ""

I hope it's more clear now! If not please ask more questions, I'll be happy to answer :)