#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

diff --git a/policy.sgml b/policy.sgml
index 5ed8ed7f33e7363969f92cdb8f0c1a3340b8624f..71d9fe9387eefd358f219f40a3ae260257af70a8 100644 (file)
--- 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).
          </p>
            statements and other administrivia should not be included
            either (that is what the copyright file is for).
          </p>

+
+         <p>
+           Please refer to <ref id="descriptions"> for more information.
+         </p>
+

        </sect1>
 
 
        </sect1>
 
 


@@ -2369,8 +2374,20 @@ Package: libc6
          </footnote>
        </p>
       </sect>
          </footnote>
        </p>
       </sect>

+

       <sect id="descriptions"><heading>Descriptions of packages - the
       <sect id="descriptions"><heading>Descriptions of packages - the

-         <tt>Description</tt> field </heading>
+         <tt>Description</tt> field</heading>
+
+       <p>
+         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:
+       </p>
+
+       <p><example>
+       Description: &lt;single line synopsis&gt;
+        &lt;extended description over several lines&gt;
+</example></p>

 
        <p>
          The description is intended to describe the program to a user
 
        <p>
          The description is intended to describe the program to a user


@@ -2381,8 +2398,15 @@ Package: libc6
          conflicts have been declared.
        </p>
 
          conflicts have been declared.
        </p>
 

-       <sect1><heading>Notes about writing descriptions
-         </heading>
+       <p>
+         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.
+       </p>
+
+        <sect1 id="synopsis"><heading>The single line synopsis</heading>

 
          <p>
            The single line synopsis should be kept brief - certainly
 
          <p>
            The single line synopsis should be kept brief - certainly


@@ -2397,6 +2421,10 @@ Package: libc6
            informative as you can.
          </p>
 
            informative as you can.
          </p>
 

+       </sect1>
+
+        <sect1 id="extendeddesc"><heading>The extended description</heading>
+

          <p>
            Do not try to continue the single line synopsis into the
            extended description.  This will not work correctly when
          <p>
            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.<footnote>
            The description field needs to make sense to anyone, even
            people who have no idea about any of the things the
            package deals with.<footnote>

-             <p>

                The blurb that comes with a program in its
                announcements and/or <prgn>README</prgn> 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 blurb that comes with a program in its
                announcements and/or <prgn>README</prgn> 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.

-             </p>

            </footnote>
          </p>
 
          <p>
            </footnote>
          </p>
 
          <p>

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

          </p>
 
          </p>
 

-         <p>
-           You may include information about dependencies and so forth
-           in the extended description, if you wish.
-         </p>
+         <p><list>
+
+           <item>
+             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.
+           </item>
+
+           <item>
+             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).
+           </item>
+
+           <item>
+             Those containing a single space followed by a single full stop
+             character. These are rendered as blank lines. This is the
+             <em>only</em> way to get a blank line<footnote>
+               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.
+             </footnote>.
+           </item>
+
+           <item>
+             Those containing a space, a full stop and some more characters.
+             These are for future expansion. Do not use them.
+           </item>
+
+         </list></p>

 
          <p>
            Do not use tab characters.  Their effect is not predictable.
          </p>
 
        </sect1>
 
          <p>
            Do not use tab characters.  Their effect is not predictable.
          </p>
 
        </sect1>

+

       </sect>
       </sect>

+

     </chapt>
 
 
     </chapt>
 
 


@@ -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 <prgn>debian-devel</prgn> and checking
          that a dynamically allocated id can be used.  In this case
          you should choose an appropriate user or group name,
          discussing this on <prgn>debian-devel</prgn> and checking

-         with the base system maintainer that it is unique and that
+         with the <package/base-passwd/ maintainer that it is unique and that

          they do not wish you to use a statically allocated id
          instead.  When this has been checked you must arrange for
          your package to create the user or group if necessary using
          they do not wish you to use a statically allocated id
          instead.  When this has been checked you must arrange for
          your package to create the user or group if necessary using