Re: texinfo-6.7.90 pretest

[Benno Schulenberg]

Hello Gavin,

Op 23-02-2021 om 22:12 schreef Gavin Smith:
> The first pretest for the next Texinfo release has been uploaded to
> 
> https://alpha.gnu.org/gnu/texinfo/texinfo-6.7.90.tar.xz

In the POT file I see a large new string (pasted at the end of this email).
Such enormous pieces of text are annoying to translate: 1) the translator
cannot see msgid and msgstr in a single, small movement of the eye, and 2)
translation memory is not of any help.  What's more: if ever an option is
added or removed or changed, the /whole/ translation of this message is
invalidated, wasting a bunch of work.  And, in such a changed big message,
it is hard for the translator to find out /what/ was changed.

So, it's much better to split large pieces of text into small, sensible
elements.  In this case: synopsis, first paragraph, second paragraph,
"Options:\n", option, option... option, last paragraph.  It's best to
not include the blank lines in the translatable strings -- it's awkward
to have an extra \n at the start or end of a message.

(Of course, please do not change the existing msgids that cover several
options or paragraphs, as that would invalidate translators' work.  But
if ever you change such a longer string, please take the opportunity to
split it into small, sensible elements.)

Also, typographically it is incorrect to have a period at the end of
the option descriptions when these descriptions do not start with a
capital letter.  I know that the POT file already contains many such
option descriptions that end in a period, but... the output of
'info --help' does not.  Please follow that model.

Also, when an option description takes multiple lines, the other pograms
in texinfo give the continuation lines an extra indent of two spaces.
Please continue with that custom (that also many other programs use).


This is the large piece of text I am referring to:

msgid ""
"Usage: pod2texi [OPTION]... POD...\n"
"\n"
"Translate Perl pod documentation file(s) to Texinfo.  There are two\n"
"basic modes of operation.  First, by default, each pod is translated to\n"
"a standalone Texinfo manual.\n"
"\n"
"Second, if C<--base-level> is set higher than 0, each pod is translated\n"
"to a file suitable for C<@include>, and one more file with all the\n"
"C<@include>s is generated, intended to be C<@include>d in turn within\n"
"a hand-written top-level file.\n"
"\n"
"Options:\n"
"  --appendix-sections     use appendix-like sections.\n"
"  --base-level=NUM|NAME   level of the head1 commands; default 0.\n"
"  --debug=NUM             set debugging level.\n"
"  --help                  display this help and exit.\n"
"  --no-fill-section-gaps  do not fill sectioning gaps.\n"
"  --no-section-nodes      use anchors for sections instead of nodes.\n"
"  --output=NAME           output to NAME for the first or main manual\n"
"                          instead of standard output.\n"
"  --preamble=STR          insert STR as beginning boilerplate.\n"
"  --subdir=NAME           put files included in the main manual in NAME.\n"
"  --top                   top for the main manual.\n"
"  --unnumbered-sections   use unumbered sections.\n"
"  --version               display version information and exit.\n"
"\n"
"Email bug reports to bug-texinfo@gnu.org,\n"
"general questions and discussion to help-texinfo@gnu.org.\n"
"Texinfo home page: http://www.gnu.org/software/texinfo/\n";

-- 

Benno