dpkg/doc/descriptions.txt

To: Debian developers list <debian-devel@pixar.com>
Subject: Package maintainers please look at your Description fields.

dselect will be much more useful when more packages are more
informative in the Description they provide in their control file.

So, when you next release a package, could you please check whether
the `control' file has a good description of the package, formatted as
described below ?

A small amount of effort here on the part of package maintainers will
improve the looks of things quite a bit, I think.

BTW, a number of packages have been indenting continuation lines in
their Description fields thus:
  Description: gnomovision
         Gnomovision is ....
         further blurb ...
Please don't do this.  According to the scheme described below (which
I've now implemented), dselect interprets the extra indentation to
mean `preformatted' text, and doesn't wordwrap it.

Ian.


The format of the Description field is as follows:

Description: <single line synopsis>
 <extended description over several lines>

The extended description has several kinds of line:

 - those starting with a single space are part of a paragraph.
Successive lines of this form will be word-wrapped when displayed.
The leading space will usually be stripped off.

 - those starting with two or more spaces.  These will be displayed
verbatim.  If the display cannot be panned horizontally the displaying
program will linewrap them `hard' (ie, without taking account of word
breaks).  If it can they will be allowed to trail off to the right.
None, one or two initial spaces may be deleted, but the number of
spaces deleted from each line will be the same (so that you can have
indenting work right, for example).

 - those containing a single space followed by a single full stop
character.  These are rendered as blank lines.  This is the ONLY way
to get a blank line - see below.

 - those containing a space, a full stop and some more characters.
These are for future expansion.  Don't use them.

IMPORTANT and not so important TIPS:

* ALWAYS START EXTENDED DESCRIPTION LINES WITH AT LEAST ONE WHITESPACE
CHARACTER.  Fields in the control file and in the Packages file are
separated by field names starting in the first column, just as in
RFC822.  Forgetting the whitespace will cause dpkg-deb (>=0.93.23) to
produce a syntax error when trying to build the package.  If you force
it to build anyway dpkg will refuse to install the resulting mess.

* DO NOT INCLUDE ANY COMPLETELY EMPTY LINES.  These separate different
records in the Packages file, and are forbidden in control files.  See
the previous paragraph for what happens if you get this wrong.

* The single line synopsis should be kept brief - certainly under 80
characters.  My current working half-dselect displays the first 49
characters if you're using an 80-column terminal.

* Don't include the package name in the synopsis line.  The display
software knows how to display this already, and you don't need to
state it.

* The extended description should describe what the package does, and
what component it forms of any larger subsystem of which it is a part.

* Put important information first, both in the synopis and extended
description.  Sometimes only the first part of the synopsis or of the
description will be displayed.  You can assume that there will usually
be a way to see the whole extended description.

* You may include information about dependencies and so forth in the
extended description, if you wish.

* Don't use tab characters.  Their effect is not predictable.

Example control file for Smail:

Package: smail
Version: 3.1.29.1
Package_Revision: 8
Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
Recommended: pine | elm | emacs | mh | mailx
Optional: metamail
Depends: cron
Conflicts: sendmail
Description: Electronic mail transport system.
 Smail is the recommended mail transport agent (MTA) for Debian.
 .
 An MTA is the innards of the mail system - it takes messages from
 user-friendly mailer programs and arranges for them to be delivered
 locally or passed on to other systems as required.
 .
 In order to make use of it you must have one or more user level
 mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
 and VM as mailreaders) installed.  If you wish to send messages other
 than just to other users of your system you must also have appropriate
 networking support, in the form of IP or UUCP.

-- 
Ian Jackson, at home.         ijackson@nyx.cs.du.edu or iwj10@cus.cam.ac.uk
+44 1223 575512    Escoerea on IRC.   http://www.cl.cam.ac.uk/users/iwj10/
2 Lexington Close, Cambridge, CB4 3LS, England.   Urgent: iwj@cam-orl.co.uk