Re: Texinfo in descriptions?

[Mathieu Lirzin <mthl@openmailbox.org>]

ludo@gnu.org (Ludovic Courtès) writes:
> However, as I wrote, this would be an important change, and I wouldn’t
> know how to handle translations (basically ‘xgettext’ would not work
> here.)  That also entails quite some work on the UI side: rendering,
> --search handling, etc.

Yeah, I don't know how to make that work too.

> That said, it just occurred to me that we have one solution that could
> work without too much work: Texinfo.  The (texinfo) modules in Guile are
> good enough for our purposes (parsing, plain-text rendering, etc.), so
> we could use simple markup like @code, @itemize, etc.  Descriptions
> would remain plain strings, amenable to extraction by ‘xgettext’ (though
> we’d need to check with the TP whether adding Texinfo markup is OK.)
>
> What do people think?  Anyone willing to give it a try?

As much as I would appreciate texinfo markup in that context, I think it
will still confuse our translator friends.  In 
(info "(gettext)Preparing Strings") we can found this:

--8<---------------cut here---------------start------------->8---
   Unusual markup or control characters should not be used in
translatable strings.  Translators will likely not understand the
particular meaning of the markup or control characters.

   For example, if you have a convention that ‘|’ delimits the left-hand
and right-hand part of some GUI elements, translators will often not
understand it without specific comments.  It might be better to have the
translator translate the left-hand and right-hand part separately.

[...]

   HTML markup, however, is common enough that it’s probably ok to use
in translatable strings.  But please bear in mind that the GNU gettext
tools don’t verify that the translations are well-formed HTML.
--8<---------------cut here---------------end--------------->8---

Sure HTML markup will not be pretty, but at least it will not encourage
people to put lists everywhere (for example for listing features instead
of describing what the package is doing).

On the same info node we can find this ...

--8<---------------cut here---------------start------------->8---
   Many GNU programs have a ‘--help’ output that extends over several
screen pages.  It is a courtesy towards the translators to split such a
message into several ones of five to ten lines each.  While doing that,
you can also attempt to split the documented options into groups, such
as the input options, the output options, and the informative output
options.  This will help every user to find the option he is looking
for.
--8<---------------cut here---------------end--------------->8---

... which can give the idea that formatting in a translatable string is
acceptable.  So eventually I don't know what to think of all of
this. (except that I'm not in favour of using '•')

My secret dream is that descriptions (and their translation) would be
managed directly in the FSD (Free Software Directory) so that we can
import those directly and care only about the building and deployment
process ;).

--
Mathieu Lirzin