From mboxrd@z Thu Jan 1 00:00:00 1970 From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Texinfo in descriptions? Date: Fri, 17 Jul 2015 23:18:16 +0200 Message-ID: <87y4ietrdz.fsf_-_@gnu.org> References: <87wpy0nygt.fsf@gmail.com> <87y4ige2ux.fsf@openmailbox.org> <87wpy0t83c.fsf@gnu.org> <87r3o7pz3h.fsf@openmailbox.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]:48873) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZGD1U-0006nH-7G for guix-devel@gnu.org; Fri, 17 Jul 2015 17:18:25 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZGD1Q-0004D2-3G for guix-devel@gnu.org; Fri, 17 Jul 2015 17:18:24 -0400 In-Reply-To: <87r3o7pz3h.fsf@openmailbox.org> (Mathieu Lirzin's message of "Thu, 16 Jul 2015 23:33:06 +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: Mathieu Lirzin Cc: guix-devel@gnu.org, Alex Kost Mathieu Lirzin skribis: > ludo@gnu.org (Ludovic Court=C3=A8s) 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=E2=80=99s a bias.) >> >> In Emacs it=E2=80=99s 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=E2=80=99re 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 wi= ndow;" > "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 wi= ndow;" > "xkbwatch: reports changes in the XKB keyboard state.")) No it=E2=80=99s not a stupid idea at all; it=E2=80=99s even =E2=80=9Cthe ri= ght thing.=E2=80=9D 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 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 =E2=80=98xgettext=E2= =80=99 (though we=E2=80=99d 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=E2=80=99t influence much the review of Alex=E2=80=99s= patches.) Ludo=E2=80=99.