From 3c3b7e1523f841c51f230d772d0379fb2954840a Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:35:38 +0000 Subject: [PATCH] #172022, and #174927 while i'm at it Author: joy Date: 2003/01/01 17:59:54 #172022, and #174927 while i'm at it git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-165 --- policy.sgml | 86 +++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 71 insertions(+), 15 deletions(-) diff --git a/policy.sgml b/policy.sgml index 5ed8ed7..71d9fe9 100644 --- a/policy.sgml +++ b/policy.sgml @@ -877,6 +877,11 @@ statements and other administrivia should not be included either (that is what the copyright file is for).

+ +

+ Please refer to for more information. +

+ @@ -2369,8 +2374,20 @@ Package: libc6

+ Descriptions of packages - the - Description field + Description field + +

+ The "Description" control file field consists of two parts, + the synopsis or the short description, and the long description. + The field's format is as follows: +

+ +

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

The description is intended to describe the program to a user @@ -2381,8 +2398,15 @@ Package: libc6 conflicts have been declared.

- Notes about writing descriptions - +

+ Put important information first, both in the synopsis 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. +

+ + The single line synopsis

The single line synopsis should be kept brief - certainly @@ -2397,6 +2421,10 @@ Package: libc6 informative as you can.

+ + + The extended description +

Do not try to continue the single line synopsis into the extended description. This will not work correctly when @@ -2415,35 +2443,63 @@ Package: libc6 The description field needs to make sense to anyone, even people who have no idea about any of the things the package deals with. -

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

- Put important information first, both in the synopsis 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. + The lines in the extended description can have these formats:

-

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

+

+ + + 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" + (i.e., 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 + Completely empty lines will not be rendered as blank lines. + Instead, they will cause the parser to think you're starting + a whole new record in the control file, and will therefore + likely abort with an error. + . + + + + Those containing a space, a full stop and some more characters. + These are for future expansion. Do not use them. + + +

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

+ + @@ -6421,7 +6477,7 @@ endscript that a dynamically allocated id can be used. In this case you should choose an appropriate user or group name, discussing this on debian-devel and checking - with the base system maintainer that it is unique and that + with the