From mboxrd@z Thu Jan 1 00:00:00 1970 From: Alex Kost Subject: Formatting lists in descriptions (was: [PATCH] gnu: Document xorg packages.) Date: Tue, 14 Jul 2015 11:32:45 +0300 Message-ID: <87wpy3xhoy.fsf_-_@gmail.com> References: <87wpy5uvd8.fsf@gmail.com> <877fq4yol1.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]:56018) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZEvdy-0008Ds-Cq for guix-devel@gnu.org; Tue, 14 Jul 2015 04:32:55 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZEvdv-0003Eo-6K for guix-devel@gnu.org; Tue, 14 Jul 2015 04:32:50 -0400 In-Reply-To: <877fq4yol1.fsf@gnu.org> ("Ludovic \=\?utf-8\?Q\?Court\=C3\=A8s\=22'\?\= \=\?utf-8\?Q\?s\?\= message of "Mon, 13 Jul 2015 19:06:18 +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 Ludovic Court=C3=A8s (2015-07-13 20:06 +0300) wrote: > Alex Kost skribis: [...] >> And one more thing: there are "windowswmproto" and "libwindowswm" >> packages that have something to do with MS Windows and Cygwin. Do we >> need them? > > If that=E2=80=99s really what they are, let=E2=80=99s remove them. OK, I'll sent a patch for that and it may be discussed there, if there will be objections. >> From 9b0d9bec0e1b1a3ce949f7d93a6598b75b050c86 Mon Sep 17 00:00:00 2001 >> From: Alex Kost >> Date: Sun, 12 Jul 2015 19:47:39 +0300 >> Subject: [PATCH] gnu: Document xorg packages. >> >> * gnu/packages/xorg.scm: Add/imrove 'synopsis'/'description' fields of >> many packages. > > OK! > >> + (description >> + "XExtProto provides the following extensions: >> + >> +DOUBLE-BUFFER >> +DPMS >> +Extended-Visual-Information >> +Generic Event Extension >> +LBX >> +MIT-SHM >> +MIT-SUNDRY-NONSTANDARD >> +Multi-Buffering >> +SECURITY >> +SHAPE >> +SYNC >> +TOG-CUP >> +XC-APPGROUP >> +XTEST") > > Formatting will be lost in UIs, so this should be a comma-separated list > instead. Currently the formatting is not lost in Emacs UI, but I agree on this one. >> + (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.") > > Likewise. What about separating such entries with newspaces as it is done in some other packages (e.g., 'signing-party') to prevent the format breaking?: + (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.") If this is acceptable, I can send a patch to fix the list formatting for other packages (guile-json, libotr, =E2=80=A6) And as I have an unhealthy desire to organize the same things in the same manner, what variant to choose for formatting lists? Should the list items begin with "-" or "+" or "*" or "=E2=80=A2" and should there be = spaces before the chosen symbol or maybe there should be just a couple of spaces without any marker? I think the following variant is more or less the standard way: --8<---------------cut here---------------start------------->8--- Our 'foobarbaz' consists of: - foo: does some fooing; - bar: bars everything; - baz: useless component. --8<---------------cut here---------------end--------------->8--- However I like how the description of 'libdaemon' looks (I would rather added periods in the end of all sentences), but someone probably wouldn't like using "=E2=80=A2" or other unusual symbols. --=20 Alex