Clarify the description of the Files control field

Reword a difficult sentence in the Files control field description and
add examples of the two versions of the field.  Thanks to Jeremiah
Foster for the report and wording discussion.

diff --git a/debian/changelog b/debian/changelog
index 675905df1c5ff16703efac44758108f5e04d1900..9dafa0edeb82f47acda47b689a0c48b0de87824a 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -60,6 +60,7 @@ debian-policy (3.8.3.0) UNRELEASED; urgency=low
   * Explain that the copyright dates are for the original Policy manual
     and that there is no updated list of copyright holders for subsequent
     revisions available.  (Partly addresses #47438)
+  * Clarify the description of the Files control field and add examples.
   * Merge the package name syntax requirements between the Package and
     Source field descriptions.
 

diff --git a/policy.sgml b/policy.sgml
index 27deaa70c31d0bb08b7f69746913ca55095cac8e..50d28dbd4a2549df0f27efccd6d0c7e45177e289 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -3308,20 +3308,30 @@ Package: libc6
          <p>
            This field contains a list of files with information about
            each one.  The exact information and syntax varies with
-           the context.  In all cases the part of the field
-           contents on the same line as the field name is empty.  The
-           remainder of the field is one line per file, each line
-           being indented by one space and containing a number of
-           sub-fields separated by spaces.
+           the context.
+         </p>
+
+         <p>
+           In all cases, Files is a multiline field.  The first line of
+           the field value (the part on the same line as <tt>Files:</tt>)
+           is always empty.  The content of the field is expressed as
+           continuation lines, one line per file.  Each line must be
+           indented by one space and contain a number of sub-fields,
+           separated by spaces, as described below.
          </p>
 
          <p>
            In the <file>.dsc</file> file, each line contains the MD5
-           checksum, size and filename of the tar file and (if applicable)
-           diff file which make up the remainder of the source
-           package<footnote>
-               That is, the parts which are not the <tt>.dsc</tt>.
-           </footnote>.
+           checksum, size and filename of the tar file and (if
+           applicable) diff file which make up the remainder of the
+           source package<footnote>
+             That is, the parts which are not the <tt>.dsc</tt>.
+           </footnote>.  For example:
+           <example>
+Files:
+ c6f698f19f2a2aa07dbb9bbda90a2754 571925 example_1.2.orig.tar.gz
+ 938512f08422f3509ff36f125f5873ba 6220 example_1.2-1.diff.gz
+           </example>
            The exact forms of the filenames are described
            in <ref id="pkg-sourcearchives">.
          </p>
@@ -3329,14 +3339,20 @@ Package: libc6
          <p>
            In the <file>.changes</file> file this contains one line per
            file being uploaded.  Each line contains the MD5 checksum,
-           size, section and priority and the filename.
+           size, section and priority and the filename.  For example:
+           <example>
+Files:
+ 4c31ab7bfc40d3cf49d7811987390357 1428 text extra example_1.2-1.dsc
+ c6f698f19f2a2aa07dbb9bbda90a2754 571925 text extra example_1.2.orig.tar.gz
+ 938512f08422f3509ff36f125f5873ba 6220 text extra example_1.2-1.diff.gz
+ 7c98fe853b3bbb47a00e5cd129b6cb56 703542 text extra example_1.2-1_i386.deb
+           </example>
            The <qref id="f-Section">section</qref>
-           and <qref id="f-Priority">priority</qref>
-           are the values of the corresponding fields in
-           the main source control file.  If no section or priority is
-           specified then <tt>-</tt> should be used, though section
-           and priority values must be specified for new packages to
-           be installed properly.
+           and <qref id="f-Priority">priority</qref> are the values of
+           the corresponding fields in the main source control file.  If
+           no section or priority is specified then <tt>-</tt> should be
+           used, though section and priority values must be specified for
+           new packages to be installed properly.
          </p>
 
          <p>