Package: debian-policy
The dropping of the packaging manual seems increasinly hasty and
ill-thought-out, when important documentation like this turns out to
have been dropped from debian in the process. This should probably go
into the policy manual's appendices.
----- Forwarded message from John Hasler <john@dhh.gt.org> -----
From: John Hasler <john@dhh.gt.org>
Date: 05 Dec 2002 18:21:01 -0600
To: debian-devel@lists.debian.org
Subject: Re: description writing guide
X-Spam-Status: No, hits=-12.6 required=5.0
tests=AWL,IN_REP_TO,MAILTO_TO_SPAM_ADDR,REFERENCES,
SIGNATURE_LONG_SPARSE,SPAM_PHRASE_03_05,USER_AGENT,X_LOOP,
X_MAILING_LIST
version=2.41
David B Harris writes:
> Could you point me at the documentation in question?
Debian Packaging Manual
-----------------------
Ian Jackson <ijackson@gnu.ai.mit.edu>
Revised: David A. Morris <bweaver@debian.org>
Maintainer: Christian Schwarz <schwarz@debian.org>
Maintainer: Manoj Srivastava <srivasta@debian.org>
Maintainer: The Debian Policy group <debian-policy@lists.debian.org>
version 3.1.1.1, 1999-11-22
...
...
...
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
---------------------------------------------------------
* 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 correctly, 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. Do not use them.
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' [1] 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.
[1] Version 0.93.23 or later.
_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.
--
John Hasler
john@dhh.gt.org (John Hasler)
Dancing Horse Hill
Elmwood, WI
--
To UNSUBSCRIBE, email to debian-devel-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
----- End forwarded message -----
--
see shy jo
Attachment:
pgpMMK1J3eizc.pgp
Description: PGP signature