From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mathieu Lirzin Subject: Re: Texinfo in descriptions? Date: Tue, 21 Jul 2015 23:37:23 +0200 Message-ID: <874mkx8a5o.fsf@openmailbox.org> References: <87wpy0nygt.fsf@gmail.com> <87y4ige2ux.fsf@openmailbox.org> <87wpy0t83c.fsf@gnu.org> <87r3o7pz3h.fsf@openmailbox.org> <87y4ietrdz.fsf_-_@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:48933) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZHfG1-000732-KG for guix-devel@gnu.org; Tue, 21 Jul 2015 17:39:26 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZHfFx-00042C-Vb for guix-devel@gnu.org; Tue, 21 Jul 2015 17:39:25 -0400 Received: from smtp21.openmailbox.org ([62.4.1.55]:52072) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZHfFx-00041b-N1 for guix-devel@gnu.org; Tue, 21 Jul 2015 17:39:21 -0400 In-Reply-To: <87y4ietrdz.fsf_-_@gnu.org> ("Ludovic \=\?utf-8\?Q\?Court\=C3\=A8s\?\= \=\?utf-8\?Q\?\=22's\?\= message of "Fri, 17 Jul 2015 23:18:16 +0200") List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: Ludovic =?utf-8?Q?Court=C3=A8s?= Cc: guix-devel@gnu.org, Alex Kost ludo@gnu.org (Ludovic Court=C3=A8s) writes: > However, as I wrote, this would be an important change, and I wouldn=E2= =80=99t > know how to handle translations (basically =E2=80=98xgettext=E2=80=99 wou= ld 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 =E2=80=98xgettext= =E2=80=99 (though > we=E2=80=99d need to check with the TP whether adding Texinfo markup is O= K.) > > 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=20 (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 =E2=80=98|=E2=80=99 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=E2=80=99s probably ok to = use in translatable strings. But please bear in mind that the GNU gettext tools don=E2=80=99t 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 =E2=80=98--help=E2=80=99 output that extends ov= er 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 '=E2=80=A2') 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