FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > Debian > Debian Development

 
 
LinkBack Thread Tools
 
Old 03-20-2009, 12:45 PM
Andreas Tille
 
Default 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


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 03-20-2009, 01:07 PM
martin f krafft
 
Default RFC: Better formatting for long descriptions

also sprach Andreas Tille <tillea@rki.de> [2009.03.20.1445 +0100]:
> 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.

What we really should do, instead of clinging to the NIH-behaviour,
reinventing the wheel, and polishing it over and over again is ditch
the pseudo-RFC822 format we have and use Yaml instead.

http://www.yaml.org/start.html
http://yaml.org/spec/1.2/

--
.'`. martin f. krafft <madduck@d.o> Related projects:
: :' : proud Debian developer http://debiansystem.info
`. `'` http://people.debian.org/~madduck http://vcs-pkg.org
`- Debian - when you have better things to do than fixing systems

"den stil verbessern, das heißt den gedanken verbessern."
- friedrich nietzsche
 
Old 03-20-2009, 01:21 PM
Andreas Tille
 
Default RFC: Better formatting for long descriptions

On Fri, 20 Mar 2009, martin f krafft wrote:


What we really should do, instead of clinging to the NIH-behaviour,
reinventing the wheel, and polishing it over and over again is ditch
the pseudo-RFC822 format we have and use Yaml instead.

http://www.yaml.org/start.html
http://yaml.org/spec/1.2/


And most probably somebody else will revive the "switch to XML" suggestion.
I know the pros and cons for different formats but I want a solution *now*
and that's the reason why I wrote:


> 2. Does not break any existing tool


Kind regards

Andreas.

--
http://fam-tille.de


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 03-20-2009, 03:36 PM
Michael Banck
 
Default RFC: Better formatting for long descriptions

On Fri, Mar 20, 2009 at 02:45:09PM +0100, Andreas Tille wrote:
> 1. Itemize lists: (<li>)
> ------------------------
>
> 2. Enumerate lists: (<ol>)
> --------------------------
>
> 3. Description lists: (<dl>)
> ----------------------------
>
> This suggestion is far from complete and should be enhanced.

Well, not sure this should be over-engineered; I guess itemize lists
already cover most of the cases (most enumerations could probably be
changed to itemizations I guess).

So a +1 from me.


Michael


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 03-20-2009, 06:03 PM
Neil Williams
 
Default RFC: Better formatting for long descriptions

On Fri, 20 Mar 2009 14:45:09 +0100 (CET)
Andreas Tille <tillea@rki.de> wrote:

> 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.

Packages.gz is already 26Mb - I'd like to find ways to shorten the
package descriptions, not lengthen it. :-(

> 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.
> ---------------------------------------------------------------------
>
> I think we should try to implement some more strict formating rules
> to our long descriptions.

Maybe starting with a way to provide extra long descriptions by some
means *other* than Packages.gz - which in turn means maintainers
deciding which bits of the long description *really* need to be visible
before download and which can wait until the user has decided to
download the package.

Can the long description be trimmed to only such data necessary to
identify the package compared to similar packages? We have debtags for
lots of other facets of a package description, maybe it is time that
the long description itself is trimmed so that it does not repeat any
information already encoded as debtags?

> 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.

Oh no, please don't let Packages.gz get to 40Mb or 50Mb or more. There
has to be a limit somewhere.

What about a way of having a really long, detailed, nicely formatted
description on packages.debian.org but a much shorter, more basic
version in the Packages.gz file?

> This suggestion is far from complete and should be enhanced.

I think the entire suggestion should be redirected away from the
Packages.gz file.

--


Neil Williams
=============
http://www.data-freedom.org/
http://www.nosoftwarepatents.com/
http://www.linux.codehelp.co.uk/
 
Old 03-20-2009, 06:08 PM
Julien Cristau
 
Default RFC: Better formatting for long descriptions

On Fri, 2009-03-20 at 19:03 +0000, Neil Williams wrote:
> On Fri, 20 Mar 2009 14:45:09 +0100 (CET)
> Andreas Tille <tillea@rki.de> wrote:
>
> > 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.
>
> Packages.gz is already 26Mb - I'd like to find ways to shorten the
> package descriptions, not lengthen it. :-(

Yeah, I'm sure being consistent about whether we use 2 or 3 spaces for
indented lists in descriptions is going to make that file a lot harder
to compress.

Cheers,
Julien


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 03-20-2009, 06:10 PM
Emilio Pozuelo Monfort
 
Default RFC: Better formatting for long descriptions

Neil Williams wrote:
> On Fri, 20 Mar 2009 14:45:09 +0100 (CET)
> Andreas Tille <tillea@rki.de> wrote:
>
>> 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.
>
> Packages.gz is already 26Mb - I'd like to find ways to shorten the
> package descriptions, not lengthen it. :-(

AFAICS he's not talking about lengthen the descriptions at all, but to
standardize the way lists are formatted in long descriptions. That is, formalize
whether we should be using 2 or 3 spaces, dashes or plus signs for items in the
lists...

Cheers,
Emilio
 
Old 03-20-2009, 06:20 PM
Neil Williams
 
Default RFC: Better formatting for long descriptions

On Fri, 20 Mar 2009 20:08:43 +0100
Julien Cristau <jcristau@debian.org> wrote:

> On Fri, 2009-03-20 at 19:03 +0000, Neil Williams wrote:
> > On Fri, 20 Mar 2009 14:45:09 +0100 (CET)
> > Andreas Tille <tillea@rki.de> wrote:
> >
> > > 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.
> >
> > Packages.gz is already 26Mb - I'd like to find ways to shorten the
> > package descriptions, not lengthen it. :-(
>
> Yeah, I'm sure being consistent about whether we use 2 or 3 spaces for
> indented lists in descriptions is going to make that file a lot harder
> to compress.

I'd like to get the longest descriptions out of Packages.gz completely,
so encouraging their retention it not ideal. It's not about whether 2
or 3 spaces should be used, it's about whether such detailed content
deserves to be in Packages.gz in the first place.

If there is going to be discussion on standardising on some form of
indentation, it's worth considering whether there isn't a better way of
providing the data itself to achieve other benefits. Indents would need
changes in all affected packages - it might be easier to provide a
different means that also reduces the size of the Packages.gz file
at the same time so that packages only need to be changed once.

My comment for this RFC is, therefore, that better formatting for long
descriptions should include a review of whether the long description
deserves to be that long in the first place, whether the long
description merely duplicates data already available via debtags and
whether the long description should be trimmed for the package in
question *as well as* standardising the formatting of what remains.

Better can be construed to mean more - I merely want maintainers to
consider whether better actually means less.

--


Neil Williams
=============
http://www.data-freedom.org/
http://www.nosoftwarepatents.com/
http://www.linux.codehelp.co.uk/
 
Old 03-20-2009, 09:32 PM
Michael Banck
 
Default RFC: Better formatting for long descriptions

On Fri, Mar 20, 2009 at 07:20:43PM +0000, Neil Williams wrote:
> I'd like to get the longest descriptions out of Packages.gz completely,
> so encouraging their retention it not ideal. It's not about whether 2
> or 3 spaces should be used, it's about whether such detailed content
> deserves to be in Packages.gz in the first place.

Then I wonder why you hijacked this thread and did not rather start a
new one?


Michael


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 03-20-2009, 10:44 PM
Filipus Klutiero
 
Default RFC: Better formatting for long descriptions

On Fri, 20 Mar 2009, martin f krafft wrote:




What we really should do, instead of clinging to the NIH-behaviour,
reinventing the wheel, and polishing it over and over again is ditch
the pseudo-RFC822 format we have and use Yaml instead.

http://www.yaml.org/start.html
http://yaml.org/spec/1.2/



And most probably somebody else will revive the "switch to XML" suggestion.
I know the pros and cons for different formats but I want a solution *now*
and that's the reason why I wrote:




> 2. Does not break any existing tool


I tend to agree with Martin. Do you have a particular reason making this
change urge? At worst, a format for extended descriptions could be
usable by Debian 7.
I noticed while checking if packages.debian.org rendered the current
descriptions decently that acidlab's description is rendered pretty
badly, but AFAICS that's just a packages.d.o bug. FWIW, I had never
noticed such an issue.

Kind regards

Andreas.




--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 

Thread Tools




All times are GMT. The time now is 09:29 PM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright ©2007 - 2008, www.linux-archive.org