Texinfo in descriptions?

[ludo@gnu.org (Ludovic Courtès)]

Mathieu Lirzin <mthl@openmailbox.org> skribis:

> ludo@gnu.org (Ludovic Courtès) writes:
>
>> What are your concerns and what would you prefer?  (I was left with the
>> impression that there was a rough consensus in the other thread, but
>> surely there’s a bias.)
>>
>> In Emacs it’s quite easily typed (C-x 8 RET etc.), and at worst people
>> can copy/paste it.
>
> My concerns are about the translators, who will have to care about more
> formatting (formatted variables are enough :)) and about my impression
> that keeping unformatted text can be more easily rendered in different
> contexts (guix package, guix web, guix.el and beyond!) but maybe I'm
> wrong.

Oh, sure.  We’re talking about very lightweight formatting though, not
very different from what we already have (bullets instead of dashes.)

> The first (probably stupid) idea that comes to my mind is to transform
> the description field into a list of multiple (unformatted) strings and
> sexps, where the responsability of the formatting is delegated to the
> program that actually displays the descriptions.  For the translator,
> the description will appear as 4 independent strings with no special
> formatting to take care.
>
>        (description
>         "XKBUtils is a collection of small utilities for X Keyboard (XKB)
>  extension to the X11 protocol.  It includes:"
>         '(unordered-list        ; Or a better symbol
>           "xkbbell: generate XKB bell events;"
>           "xkbvleds: display the state of LEDs on an XKB keyboard in a window;"
>           "xkbwatch: reports changes in the XKB keyboard state."))
>
> or with just nested lists
>
>        (description
>         "XKBUtils is a collection of small utilities for X Keyboard (XKB)
>  extension to the X11 protocol.  It includes:"
>         '("xkbbell: generate XKB bell events;"
>           "xkbvleds: display the state of LEDs on an XKB keyboard in a window;"
>           "xkbwatch: reports changes in the XKB keyboard state."))

No it’s not a stupid idea at all; it’s even “the right thing.”

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.

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?

(Anyway, that shouldn’t influence much the review of Alex’s patches.)

Ludo’.