Bug#172022: marked as done (FWD: Re: description writing guide)
Your message dated Mon, 10 Mar 2003 14:11:39 -0500
with message-id <E18sSgV-0005me-00@auric.debian.org>
and subject line Bug#172022: fixed in debian-policy 3.5.9.0
has caused the attached Bug report to be marked as done.
This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.
(NB: If you are a system administrator and have no idea what I am
talking about this indicates a serious mail system misconfiguration
somewhere. Please contact me immediately.)
Debian bug tracking system administrator
(administrator, Debian Bugs database)
--------------------------------------
Received: (at submit) by bugs.debian.org; 6 Dec 2002 17:38:33 +0000
>From joey@kitenet.net Fri Dec 06 11:38:32 2002
Return-path: <joey@kitenet.net>
Received: from gluck.debian.org [192.25.206.10]
by master.debian.org with esmtp (Exim 3.12 1 (Debian))
id 18KMQq-0002NP-00; Fri, 06 Dec 2002 11:38:32 -0600
Received: from (kitenet.net) [208.27.22.224] (postfix)
by gluck.debian.org with esmtp (Exim 3.35 1 (Debian))
id 18KMQn-0006L8-00; Fri, 06 Dec 2002 10:38:29 -0700
Received: from dragon.kitenet.net (as5800-82-166.access.naxs.com [216.98.82.166])
(using TLSv1 with cipher EDH-RSA-DES-CBC3-SHA (168/168 bits))
(Client CN "Joey Hess", Issuer "Joey Hess" (verified OK))
by kitenet.net (Postfix) with ESMTP id 4CDAFBC003
for <submit@bugs.debian.org>; Fri, 6 Dec 2002 12:32:27 -0500 (EST)
Received: from joey by dragon.kitenet.net with local (Exim 3.35 #1 (Debian))
id 18KMLa-0004iD-00
for <submit@bugs.debian.org>; Fri, 06 Dec 2002 12:33:06 -0500
Date: Fri, 6 Dec 2002 12:33:06 -0500
From: Joey Hess <joeyh@debian.org>
To: submit@bugs.debian.org
Subject: FWD: Re: description writing guide
Message-ID: <20021206173306.GC16820@dragon.kitenet.net>
Mime-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha1;
protocol="application/pgp-signature"; boundary="8X7/QrJGcKSMr1RN"
Content-Disposition: inline
User-Agent: Mutt/1.4i
Sender: Joey Hess <joey@dragon.kitenet.net>
Delivered-To: submit@bugs.debian.org
X-Spam-Status: No, hits=-5.9 required=5.0
tests=MAILTO_TO_SPAM_ADDR,PGP_SIGNATURE_2,SPAM_PHRASE_03_05,
USER_AGENT,USER_AGENT_MUTT
version=2.41
X-Spam-Level:
--8X7/QrJGcKSMr1RN
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
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=3D-12.6 required=3D5.0
tests=3DAWL,IN_REP_TO,MAILTO_TO_SPAM_ADDR,REFERENCES,
SIGNATURE_LONG_SPARSE,SPAM_PHRASE_03_05,USER_AGENT,X_LOOP,
X_MAILING_LIST
version=3D2.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
=2E..
=2E..
=2E..
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.
--=20
John Hasler
john@dhh.gt.org (John Hasler)
Dancing Horse Hill
Elmwood, WI
--=20
To UNSUBSCRIBE, email to debian-devel-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.o=
rg
----- End forwarded message -----
--=20
see shy jo
--8X7/QrJGcKSMr1RN
Content-Type: application/pgp-signature
Content-Disposition: inline
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.1 (GNU/Linux)
iD8DBQE98N9S3xwsXJZQhyMRAkmoAJsEPhj5QprMzH4odHBk8LZpGBWydwCgowim
Ay7QPXYTYMsCK784Fo5jgdk=
=ZwxV
-----END PGP SIGNATURE-----
--8X7/QrJGcKSMr1RN--
---------------------------------------
Received: (at 172022-close) by bugs.debian.org; 10 Mar 2003 19:33:11 +0000
>From troup@auric.debian.org Mon Mar 10 13:33:11 2003
Return-path: <troup@auric.debian.org>
Received: from auric.debian.org [206.246.226.45] (mail)
by master.debian.org with esmtp (Exim 3.12 1 (Debian))
id 18sT1K-0006SC-00; Mon, 10 Mar 2003 13:33:10 -0600
Received: from troup by auric.debian.org with local (Exim 3.35 1 (Debian))
id 18sSgV-0005me-00; Mon, 10 Mar 2003 14:11:39 -0500
From: Manoj Srivastava <srivasta@acm.org>
To: 172022-close@bugs.debian.org
X-Katie: lisa $Revision: 1.21 $
Subject: Bug#172022: fixed in debian-policy 3.5.9.0
Message-Id: <E18sSgV-0005me-00@auric.debian.org>
Sender: James Troup <troup@auric.debian.org>
Date: Mon, 10 Mar 2003 14:11:39 -0500
Delivered-To: 172022-close@bugs.debian.org
We believe that the bug you reported is fixed in the latest version of
debian-policy, which is due to be installed in the Debian FTP archive:
debian-policy_3.5.9.0.dsc
to pool/main/d/debian-policy/debian-policy_3.5.9.0.dsc
debian-policy_3.5.9.0.tar.gz
to pool/main/d/debian-policy/debian-policy_3.5.9.0.tar.gz
debian-policy_3.5.9.0_all.deb
to pool/main/d/debian-policy/debian-policy_3.5.9.0_all.deb
A summary of the changes between this version and the previous one is
attached.
Thank you for reporting the bug, which will now be closed. If you
have further comments please address them to 172022@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.
Debian distribution maintenance software
pp.
Manoj Srivastava <srivasta@acm.org> (supplier of updated debian-policy package)
(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@debian.org)
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Format: 1.7
Date: Fri, 7 Mar 2003 12:35:16 -0600
Source: debian-policy
Binary: debian-policy
Architecture: source all
Version: 3.5.9.0
Distribution: unstable
Urgency: low
Maintainer: Debian Policy List <debian-policy@lists.debian.org>
Changed-By: Manoj Srivastava <srivasta@acm.org>
Description:
debian-policy - Debian Policy Manual and related documents
Closes: 60979 69864 87510 93975 103459 109166 170019 172022 174048 174927 177205 177206 177207 177208 177209 178455 181923 183544
Changes:
debian-policy (3.5.9.0) unstable; urgency=low
.
Josip:
* Added missing bits of information about Description: fields from
the old Packaging manual, closes: #172022
* Fixed a stale reference to the "base system maintainer" to
base-passwd maintainer, closes: #174927
* Fixed an accidental change from /usr/share/package to /usr/share/doc in
the paragraph about not depending on /usr/share/doc/package,
closes: #174048
* Fixed several errors reported by Guenther Palfinger, with some help from
Richard Braakman, closes: #177205, #177206, #177207, #177208, #177209
* Added versions to links and docbook-xml source-dependencies, hopefully
fixes the bug with potato, and even if it doesn't, I don't care :)
closes: #103459
* Fixed typos in the debconf spec noticed by Jay Bonci, closes: #178455
* Clarified that using Build-Depends for build-dependencies is not a "may"
but a "should", added proper linking among various sections dealing with
the dependencies so that there is no confusion, closes: #87510
If any one of those poor, misguided people ;) still thinks that the
requirement should be a "must" (in _our_ meaning, not RFC "MUST"),
please file a new bug, as it's quite unproductive to have to sift
through a 152-page bug log which mostly goes back-and-forth with
explanations how policy should work, occasionally sprinkled with
offtopic stuff, too.
* When asked to restart a service that isn't already running, the init
script should start it, closes: #60979
* Rephrased section on configuration files to remove confusing use of
"should", closes: #170019
* Rearranged the shared library information properly, closes: #109166
This change also centralizes the info on how to ship static libraries
in one place (hopefully not too ambiguous), closes: #93975
* Allow examples to be placed in /usr/share/doc/package/ in packages
that are meant to provide examples, closes: #69864
* Removed several references to the Policy manual etc in the stuff
imported from old packaging manual, closes: #181923
* Fixed too greedy wildcard match in the logrotate example,
closes: #183544
Files:
c681573847ca95f0a8290957aaea7a36 833 doc optional debian-policy_3.5.9.0.dsc
7111f544864e257532b3ed1bca84ee0f 572699 doc optional debian-policy_3.5.9.0.tar.gz
40a7998a2cd2a7450562e7043fefadb0 609728 doc optional debian-policy_3.5.9.0_all.deb
6d3fe9ffc9bdddd1950b5949ecf7fc86 95043 byhand - policy.txt.gz
bf03d5508abc7273970e3fe2d5edcbbc 2118 byhand - menu-policy.txt.gz
e2515b142d71ad7841f2a44cfe15cc22 1560 byhand - mime-policy.txt.gz
3b2b8b544f7c1d0b700b5f0638ad023c 4496 byhand - policy-process.txt.gz
53d59d382f2cca63440a7cb88d945da2 4424 byhand - perl-policy.txt.gz
8f37c6c419260b2502e8d8ab5fce3ea9 105217 byhand - policy.html.tar.gz
2ccd5b318e61304a1afc07d5a1cd01be 2724 byhand - menu-policy.html.tar.gz
f9f5ac8b0239f8fead8f6b26640c65ea 2143 byhand - mime-policy.html.tar.gz
892413f781d93a366ef22508c2e4102b 5191 byhand - policy-process.html.tar.gz
d7b73a28044fa30aa5facb232dc002f6 5794 byhand - perl-policy.html.tar.gz
aab901eeedcd23ae6d56c91ede2649eb 6363 byhand - debconf_specification.txt.gz
a2c4b60651949b84c4ad2b8f74df3cc2 35535 byhand - debconf_specification.html
3ed7aa5a489834b24bb28ff377a34aa9 10982 byhand - libc6-migration.txt
7c6c1d1be799f750ad8085e0d3eecad8 9288 byhand - virtual-package-names-list.txt
3079b137ed179f5ceb8dd845867621c5 210466 byhand - policy.ps.gz
8a54af210e6cff6c85c98e7f84a1a3f0 435238 byhand - policy.pdf.gz
58e0adf3c1aff158d12b1d686b82ebee 18890 byhand - upgrading-checklist.txt
93679f707ec4cbc94b6f667afb1f2600 34997 byhand - fhs-2.1.html.tar.gz
02153a8048e28d94dd72c0cbcf0c1816 98312 byhand - fhs.txt
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.1 (GNU/Linux)
iD8DBQE+aPbEIbrau78kQkwRAqEEAJ0VPXWeSlp7ARD3N/hX5WjVuW2hfwCfVeP0
XZ3hFwBOUsv1vHlj6C4O8Yc=
=g488
-----END PGP SIGNATURE-----
Reply to: