Formatting lists in descriptions (was: [PATCH] gnu: Document xorg packages.)

[Alex Kost <alezost@gmail.com>]

Ludovic Courtès (2015-07-13 20:06 +0300) wrote:

> Alex Kost <alezost@gmail.com> 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’s really what they are, let’s 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 <alezost@gmail.com>
>> 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, …)

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 "•" 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 "•" or other unusual symbols.

-- 
Alex