RFC: Better formatting for long descriptions
Hi,
I tried to find a clear advise how to reasonable format lists inside long
descriptions of packages. The only thing I know is that lines with two
leading spaces is considered verbose. This leaves a lot of freedom to
simulate for instance itemize lists. I'd like to give some examples for
package names starting with 'a' and stopped with the first package names
of 'b'. If you are bored by these examples continue reading below the
------ line.
Package: a2ps
- various encodings (all the Latins and others),
- various fonts (automatic font down loading),
- various medias,
^^ (two spaces)
Package: acerhk-source
* controlling LEDs (Mail, Wireless)
* enable/disable wireless hardware
^^^ (three spaces)
Package: acidlab
...
o Alert management by providing constructs to logically group alerts
to create incidents (alert groups), deleting the handled alerts or
false positives, exporting to email for collaboration, or archiving of
alerts to transfer them between alert databases.
.
o Chart and statistic generation based on time, sensor, signature, protocol,
IP address, TCP/UDP ports
.
ACID has the ability to analyze a wide variety of events which are
post-processed into its database. Tools exist for the following formats:
.
o using Snort (www.snort.org)
- Snort alerts
- tcpdump binary logs
o using logsnorter (www.snort.org/downloads/logsnorter-0.2.tar.gz)
- Cisco PIX
- ipchains
--> atempt to emulate a two level itemize list
==> The upper part has only one space which is most probably not intended.
Package: addresses-goodies-for-gnustep
adgnumailconverter
A tool that will merge your GNUMail address book into the Addresses
database.
adserver
A stand-alone Addresses network server.
adtool
A command-line tool for address database manipulation.
--> atempt to simulate a description list
Package: airport-utils
For the original Apple AirPort and the Lucent RG-1000 base stations only:
- airport-config: base station configurator
- airport-linkmon: wireless link monitor, gives information on the wireless
link quality between the base station and the associated hosts
.
For the Apple AirPort Extreme base stations only:
- airport2-config: base station configurator
- airport2-portinspector: port maps monitor
- airport2-ipinspector: WAN interface monitoring utility
.
For all:
- airport-modem: modem control utility, displays modem state, starts/stops
modem connections, displays the approximate connection time (Extreme only)
- airport-hostmon: wireless hosts monitor, lists wireless hosts connected
to the base station (see airport2-portinspector for the Snow)
--> sometimes two sometimes three spaces, broken indentation for continued lines
Package: alsa-utils
o amixer: command line mixer
o alsamixer: curses mixer
--> third type of marker (we had '*' and '-')
Package: altermime
* Insert disclaimers
* Insert arbitrary X-headers
^^^^ four spaces
Package: amanda-client
Features:
^^ useless verbose
* will back up multiple machines in parallel to a holding disk, blasting
finished dumps one by one to tape as fast as we can write files to
tape. For example, a ~2 Gb 8mm tape on a ~240K/s interface to a host
with a large holding disk can be filled by Amanda in under 4 hours.
* built on top of standard backup software: Unix dump/restore, and
later GNU Tar and others.
^^^ three spaces
Package: amaya
- eXtensible HyperText Markup Language (XHTML)
- Scalable Vector Graphics (SVG)
- Math Markup Language (MathML)
- Cascading Style Sheets (CSS)
^^^^^^^^ a lot of spaces
Package: amrita
* The template for amrita is a pure html/xhtml document without
special tags like <?...?> or <% .. %>
* The template can be written by designers using almost any html
editor.
^^^ continued line with 3 spaces instead of four as it would look nicer
Package: amsynth
* two analogue-style audio oscillators, featuring:
o sine wave
o saw/triangle wave with adjustable shape
o square/pulse wave with adjustable pulsewidth
o noise generation
o "random" wave (noise with sample & hold)
o oscillator sync
o of course, detune and range control
* mixer section with ring modulation
--> another atempt to simulate two level itemizing
Package: aoetools
* aoecfg - manipulate AoE configuration strings
* aoe-discover - trigger discovery of ATA over Ethernet devices
* aoe-flush - flush the down devices out of the aoe driver
--> a description list simulated as itemize + formating
Package: aolserver4-doc
(1) The AOLserver Administrator's Guide covers the setup options
and security issues relating to running the server.
(2) The AOLserver Tcl Developer's Guide covers the Tcl API which
can be used to add features to your web pages (similar in
some respects to PHP or Microsoft's ASP)
^^ enumerate list with more than needed spaces and numbers in ()
Package: apel
poe.el emulation module mainly for basic functions and special
forms/macros of latest emacsen
poem.el basic functions to write portable MULE programs
pces.el portable character encoding scheme (coding-system) features
--> another kind of description list
Package: apg
* Built-in ANSI X9.17 RNG (Random Number Generator)(CAST/SHA1)
* Built-in password quality checking system (now it has support for Bloom
filter for faster access)
* Two Password Generation Algorithms:
1. Pronounceable Password Generation Algorithm (according to NIST
FIPS 181)
2. Random Character Password Generation Algorithm with 35
configurable modes of operation
--> itemize list with enumeration list in second level (looks OK for me)
Package: balazar
...
.
Plot:
More than a thousand years ago, the three Gods that have created the
world became too powerful for the poor mortals. Then the Elves forged
three magical scepters to control the Gods, and the Gods were
imprisoned in the magical crystal of Arkanae (during Arkanae I).
.
Though the secret of the Elven blacksmiths has not been lost as time
goes on, monsters and powers are coming back. New scepters have been
reforged, giving birth to new Gods. But who can find the scepters and
imprison them in the Arkanae, or free them for ever by dropping the
scepters in the Abyss ? Who can judge the Gods ?
^^^ if this should be a description list I see no motivation for it
Package: bbmail
* All the colors an gradients can be changed.
* Support for multiple mail boxes and provides a menu showing
all of them (and their unread/total mail count)
^^^^^ five spaces
.... and many more - I spare you the other funny formatings
---------------------------------------------------------------------
I think we should try to implement some more strict formating rules
to our long descriptions. The rationale behind this is that with some
better standard formating some tools which display descriptions on web
pages might be enhanced to use <li>, <ol> and <dl> tags which finally
makes a better reading.
I do not propose drastic changes but a start for "Best practices" might
be reasonable and perhaps some lintian warnings might help to remind
developers to move to some standard. My proposal would be:
1. Itemize lists: (<li>)
------------------------
First line: "^ * \w+"
Continued line: "^ \w+"
First line of second level: "^ - \w+"
Cont. line of second level: "^ \w+"
Example:
* first line of text blabla
which is continued here. There is a second level itemizing
- second level item blabla
which is continued here
- another second level item
* back to first level
2. Enumerate lists: (<ol>)
--------------------------
First line: "^ ?1. \w+"
Continued line: "^ ? \w+"
If there are more than 9 items: "^ 10. \w+"
(that's the reason for the optional space - perhaps we should strictly
use three spaces for items < 10)
Example:
1. first line of text blabla
which is continued here
2. second line
...
10. tenth line
3. Description lists: (<dl>)
----------------------------
First descrition: "^ \w+: +\w+"
Continued line: "^ +\w+"
Example:
field1: description of field1 which is
continued here
field17: starting the description always in the same column might
look nicer
field4711: so wie might add extra space, but the separator ':'
between field name (<dt>) and description (<dd>) should
be mandatory.
This suggestion is far from complete and should be enhanced. I have even
heard suggestion to use some markup we might know from Wikis. I'm fine with
any suggestions which has two features:
1. Defines some kind of standard which can be parsed automatically.
2. Does not break any existing tool
Kind regards
Andreas.
--
http://fam-tille.de
Reply to: