dpkg programmers' manual - chapter 7
Descriptions of packages - the Description field

The Description control file field is used by dselect when the user is selecting which packages to install and by dpkg when it displays information about the status of packages and so forth. It is included on the FTP site in the Packages files, and may also be used by the Debian WWW pages.

The description is intended to describe the program to a user who has never met it before so that they know whether they want to install it. It should also give information about the significant dependencies and conflicts between this package and others, so that the user knows why these dependencies and conflicts have been declared.

The field's format is as follows:

Description: single line synopsis
 extended description over several lines

The synopsis is often printed in lists of packages and so forth, and should be as informative as possible. Every package should also have an extended description.


7.1 Types of formatting line in the extended description


7.2 Notes about writing descriptions

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 message header fields are in RFC822. Forgetting the whitespace will cause dpkg-deb[20] 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 different packages in the debian/control file, and are forbidden in package 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. dselect displays between 25 and 49 characters without panning if you're using an 80-column terminal, depending on what display options are in effect.

Do not include the package name in the synopsis line. The display software knows how to display this already, and you do not need to state it. Remember that in many situations the user may only see the synopsis line - make it as informative as you can.

The extended description should describe what the package does and how it relates to the rest of the system (in terms of, for example, which subsystem it is which part of).

The blurb that comes with a program in its announcements and/or README files is rarely suitable for use in a description. It is usually aimed at people who are already in the community where the package is used. The description field needs to make sense to anyone, even people who have no idea about any of the things the package deals with.

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.

Do not use tab characters. Their effect is not predictable.

Do not try to linewrap the summary (the part on the same line as the field name Description) into the extended description. This will not work correctly when the full description is displayed, and makes no sense where only the summary is available.


7.3 Example description in control file for Smail

Package: smail
Version: 3.1.29.1-13
Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
Recommends: pine | mailx | elm | emacs | mail-user-agent
Suggests: metamail
Depends: cron, libc5
Conflicts: sendmail
Provides: mail-transport-agent
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.

dpkg programmers' manual - Copyright ©1996 Ian Jackson.
Contents; abstract; next; back.
version 2.1.2.2 (dpkg 1.4.0.5), 5 December 1996
Ian Jackson ijackson@gnu.ai.mit.edu
Revised: David A. Morris bweaver@debian.org