[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

RFC: Better formatting for long descriptions


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
   A tool that will merge your GNUMail address book into the Addresses
   A stand-alone Addresses network server.
   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
^^ 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
^^^ 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
   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+"


  * 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)


   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+"


  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



Reply to: