[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Formatting lists in descriptions (was: [PATCH] gnu: Document xorg packag
From: |
Alex Kost |
Subject: |
Formatting lists in descriptions (was: [PATCH] gnu: Document xorg packages.) |
Date: |
Tue, 14 Jul 2015 11:32:45 +0300 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux) |
Ludovic Courtès (2015-07-13 20:06 +0300) wrote:
> Alex Kost <address@hidden> 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 <address@hidden>
>> 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