Debian Bug report logs - #647570
convert Chapter 5 to RFC 2119 language

version graph

Package: debian-policy; Maintainer for debian-policy is Debian Policy List <debian-policy@lists.debian.org>; Source for debian-policy is src:debian-policy.

Reported by: Charles Plessy <plessy@debian.org>

Date: Fri, 4 Nov 2011 00:57:01 UTC

Severity: wishlist

Found in version debian-policy/3.9.2.0

Blocking fix for 661417: Policy document cleanups

Reply or subscribe to this bug.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, plessy@debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#647570; Package debian-policy. (Fri, 04 Nov 2011 00:57:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
New Bug report received and forwarded. Copy sent to plessy@debian.org, Debian Policy List <debian-policy@lists.debian.org>. (Fri, 04 Nov 2011 00:57:04 GMT) Full text and rfc822 format available.

Message #5 received at submit@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: debian-policy: Conformance of Chapter 5 to RFC 2119.
Date: Fri, 04 Nov 2011 09:55:45 +0900
Package: debian-policy
Version: 3.9.2.0
Severity: wishlist

Dear all,

following our discussion at the end of October about the vocabulary used in the
Policy, (20111025143614.GB14464@merveille.plessy.net), here is a first pass on
Chapter 5, to use the vocabulary of RFC 2119 (http://www.ietf.org/rfc/rfc2119.txt)
where applicable.

I am presenting my proposition as a patch for the words that change, and as a
serie of extracts centered on the words that do not change.

In most cases the change is a capitalisation, but in a few cases the words
themselves change, where for instance ‘may (not)’ becomes ‘MUST (NOT)’.  I
focused on the key words defined by the RFC, with the exception of ‘mandatory’,
which I propose to change to ‘REQUIRED’ as it was used in the context other
‘RECOMMENDED’ key words.  I also propose to change a ‘must never’ to ‘MUST NOT’.

I also made sure that ‘MUST NOT’ and ‘SHOULD NOT’ are never interrupted by a
new line, to facilitate searches in the source document.


@@ -2479,9 +2479,9 @@ endif
 	  fields<footnote>
 		The paragraphs are also sometimes referred to as stanzas.
 	  </footnote>.
-	  The paragraphs are separated by empty lines.  Parsers may accept
+	  The paragraphs are separated by empty lines.  Parsers MAY accept
 	  lines consisting solely of spaces and tabs as paragraph
-	  separators, but control files should use empty lines.  Some control
+	  separators, but control files SHOULD use empty lines.  Some control
 	  files allow only one paragraph; others allow several, in
 	  which case each paragraph usually refers to a different
 	  package.  (For example, in source packages, the first
@@ -2496,10 +2496,10 @@ endif
 	  then the data/value associated with that field.  The field
 	  name is composed of printable ASCII characters (i.e.,
 	  characters that have values between 33 and 126, inclusive)
-	  except colon and must not with a begin with #.  The
+	  except colon and MUST NOT with a begin with #.  The
 	  field ends at the end of the line or at the end of the
 	  last continuation line (see below).  Horizontal whitespace
-	  (spaces and tabs) may occur immediately before or after the
+	  (spaces and tabs) MAY occur immediately before or after the
 	  value and is ignored there; it is conventional to put a
 	  single space after the colon.  For example, a field might
 	  be:
@@ -2511,7 +2511,7 @@ Package: libc6
 	</p>
 
 	<p>
-	  A paragraph must not contain more than one instance of a
+	  A paragraph MUST NOT contain more than one instance of a
 	  particular field name.
 	</p>
 
@@ -2520,16 +2520,16 @@ Package: libc6
 	  <taglist>
 	    <tag>simple</tag>
 	    <item>
-	      The field, including its value, must be a single line.  Folding
+	      The field, including its value, MUST be a single line.  Folding
 	      of the field is not permitted.  This is the default field type
 	      if the definition of the field does not specify a different
 	      type.
 	    </item>
 	    <tag>folded</tag>
 	    <item>
-	      The value of a folded field is a logical line that may span
+	      The value of a folded field is a logical line that MAY span
 	      several lines.  The lines after the first are called
-	      continuation lines and must start with a space or a tab.
+	      continuation lines and MUST start with a space or a tab.
 	      Whitespace, including any newlines, is not significant in the
 	      field values of folded fields.<footnote>
 	        This folding method is similar to RFC 5322, allowing control
@@ -2539,7 +2539,7 @@ Package: libc6
 	    </item>
 	    <tag>multiline</tag>
 	    <item>
-	      The value of a multiline field may comprise multiple continuation
+	      The value of a multiline field MAY comprise multiple continuation
 	      lines.  The first line of the value, the part on the same line as
 	      the field name, often has special significance or may have to be
 	      empty.  Other lines are added following the same syntax as the
@@ -2550,7 +2550,7 @@ Package: libc6
 	</p>
 
 	<p>
-	  Whitespace must not appear
+	  Whitespace MUST NOT appear
           inside names (of packages, architectures, files or anything
           else) or version numbers, or between the characters of
           multi-character version relationships.
@@ -2583,7 +2583,7 @@ Package: libc6
 	</p>
 
 	<p>
-	  All control files must be encoded in UTF-8.
+	  All control files MUST be encoded in UTF-8.
 	</p>
       </sect>
 
@@ -2607,15 +2607,15 @@ Package: libc6
 	  package) are:
 
 	  <list compact="compact">
-	    <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
-	    <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
-	    <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
-	    <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
-	    <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
-	    <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
-	    <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+	    <item><qref id="f-Source"><tt>Source</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref> (OPTIONAL)</item>
+	    <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref> (OPTIONAL)</item>
+	    <item><qref id="f-Section"><tt>Section</tt></qref> (RECOMMENDED)</item>
+	    <item><qref id="f-Priority"><tt>Priority</tt></qref> (RECOMMENDED)</item>
+	    <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref> (OPTIONAL)</item>
+	    <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (RECOMMENDED)</item>
+	    <item><qref id="f-Homepage"><tt>Homepage</tt></qref> (OPTIONAL)</item>
 	  </list>
 	</p>
 
@@ -2623,14 +2623,14 @@ Package: libc6
 	  The fields in the binary package paragraphs are:
 
 	  <list compact="compact">
-	    <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
-	    <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
-	    <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
-	    <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
-	    <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+	    <item><qref id="f-Package"><tt>Package</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Section"><tt>Section</tt></qref> (RECOMMENDED)</item>
+	    <item><qref id="f-Priority"><tt>Priority</tt></qref> (RECOMMENDED)</item>
+	    <item><qref id="f-Essential"><tt>Essential</tt></qref> (OPTIONAL)</item>
+	    <item><qref id="binarydeps"><tt>Depends</tt> et al</qref> (OPTIONAL)</item>
+	    <item><qref id="f-Description"><tt>Description</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Homepage"><tt>Homepage</tt></qref> (OPTIONAL)</item>
 	  </list>
 	</p>
 
@@ -2653,7 +2653,7 @@ Package: libc6
 	</p>
 
 	<p>
-	  The fields here may contain variable references - their
+	  The fields here MAY contain variable references - their
 	  values will be substituted by <prgn>dpkg-gencontrol</prgn>,
 	  <prgn>dpkg-genchanges</prgn> or <prgn>dpkg-source</prgn>
 	  when they generate output control files.
@@ -2674,18 +2674,18 @@ Package: libc6
 	  The fields in this file are:
 
 	  <list compact="compact">
-	    <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Source"><tt>Source</tt></qref></item>
-	    <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
-	    <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
-	    <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
-	    <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
-	    <item><qref id="f-Installed-Size"><tt>Installed-Size</tt></qref></item>
-	    <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+	    <item><qref id="f-Package"><tt>Package</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Source"><tt>Source</tt></qref> (OPTIONAL)</item>
+	    <item><qref id="f-Version"><tt>Version</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Section"><tt>Section</tt></qref> (RECOMMENDED)</item>
+	    <item><qref id="f-Priority"><tt>Priority</tt></qref> (RECOMMENDED)</item>
+	    <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Essential"><tt>Essential</tt></qref> (OPTIONAL)</item>
+	    <item><qref id="binarydeps"><tt>Depends</tt> et al</qref> (OPTIONAL)</item>
+	    <item><qref id="f-Installed-Size"><tt>Installed-Size</tt></qref> (OPTIONAL)</item>
+	    <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Description"><tt>Description</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Homepage"><tt>Homepage</tt></qref> (OPTIONAL)</item>
 	  </list>
 	</p>
       </sect>
@@ -2699,20 +2699,20 @@ Package: libc6
 	  Their syntax is described above, in <ref id="pkg-controlfields">.
 
 	<list compact="compact">
-	  <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
-	  <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
-	  <item><qref id="f-Binary"><tt>Binary</tt></qref></item>
-	  <item><qref id="f-Architecture"><tt>Architecture</tt></qref></item>
-	  <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
-	  <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
-	  <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
-	  <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
-	  <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
-	  <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
-	  <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
+	  <item><qref id="f-Format"><tt>Format</tt></qref> (REQUIRED)</item>
+	  <item><qref id="f-Source"><tt>Source</tt></qref> (REQUIRED)</item>
+	  <item><qref id="f-Binary"><tt>Binary</tt></qref> (OPTIONAL)</item>
+	  <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (OPTIONAL)</item>
+	  <item><qref id="f-Version"><tt>Version</tt></qref> (REQUIRED)</item>
+	  <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (REQUIRED)</item>
+	  <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref> (OPTIONAL)</item>
+	  <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref> (OPTIONAL)</item>
+	  <item><qref id="f-Homepage"><tt>Homepage</tt></qref> (OPTIONAL)</item>
+	  <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (RECOMMENDED)</item>
+	  <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref> (OPTIONAL)</item>
 	  <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
-	      and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
-	  <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
+	      and <tt>Checksums-Sha256</tt></qref> (RECOMMENDED)</item>
+	  <item><qref id="f-Files"><tt>Files</tt></qref> (REQUIRED)</item>
 	</list>
 	</p>
 
@@ -2750,22 +2750,22 @@ Package: libc6
 	  The fields in this file are:
 
 	  <list compact="compact">
-	    <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Date"><tt>Date</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Binary"><tt>Binary</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (recommended)</item>
-	    <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Changed-By"><tt>Changed-By</tt></qref></item>
-	    <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Closes"><tt>Closes</tt></qref></item>
-	    <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
+	    <item><qref id="f-Format"><tt>Format</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Date"><tt>Date</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Source"><tt>Source</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Binary"><tt>Binary</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Version"><tt>Version</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (RECOMMENDED)</item>
+	    <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Changed-By"><tt>Changed-By</tt></qref> (OPTIONAL)</item>
+	    <item><qref id="f-Description"><tt>Description</tt></qref> (REQUIRED)</item>
+	    <item><qref id="f-Closes"><tt>Closes</tt></qref> (OPTIONAL)</item>
+	    <item><qref id="f-Changes"><tt>Changes</tt></qref> (REQUIRED)</item>
 	    <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
-		and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
-	    <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
+		and <tt>Checksums-Sha256</tt></qref> (RECOMMENDED)</item>
+	    <item><qref id="f-Files"><tt>Files</tt></qref> (REQUIRED)</item>
 	  </list>
 	</p>
       </sect>
@@ -2782,31 +2782,31 @@ Package: libc6
 
 	  <p>
 	    In <file>debian/control</file> or a <file>.dsc</file> file,
-	    this field must contain only the name of the source package.
+	    this field MUST contain only the name of the source package.
 	  </p>
 
 	  <p>
 	    In a binary package control file or a <file>.changes</file>
-	    file, the source package name may be followed by a version
+	    file, the source package name MAY be followed by a version
 	    number in parentheses<footnote>
 		It is customary to leave a space after the package name
 		if a version number is specified.
 	    </footnote>.
-	    This version number may be omitted (and is, by
+	    This version number MAY be omitted (and is, by
 	    <prgn>dpkg-gencontrol</prgn>) if it has the same value as
 	    the <tt>Version</tt> field of the binary package in
-	    question.  The field itself may be omitted from a binary
+	    question.  The field itself MAY be omitted from a binary
 	    package control file when the source package has the same
 	    name and version as the binary package.
 	  </p>
 
 	  <p>
 	    Package names (both source and binary,
-	    see <ref id="f-Package">) must consist only of lower case
+	    see <ref id="f-Package">) MUST consist only of lower case
 	    letters (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus
 	    (<tt>+</tt>) and minus (<tt>-</tt>) signs, and periods
-	    (<tt>.</tt>).  They must be at least two characters long and
-	    must start with an alphanumeric character.
+	    (<tt>.</tt>).  They MUST be at least two characters long and
+	    MUST start with an alphanumeric character.
 	  </p>
 	</sect1>
 
@@ -2815,7 +2815,7 @@ Package: libc6
 
 	  <p>
 	    The package maintainer's name and email address.  The name
-	    must come first, then the email address inside angle
+	    MUST come first, then the email address inside angle
 	    brackets <tt>&lt;&gt;</tt> (in RFC822 format).
 	  </p>
 
@@ -2844,15 +2844,15 @@ Package: libc6
 	    the one named in the <qref id="f-Maintainer">Maintainer
 	    field</qref>, their names and email addresses should be listed
 	    here. The format of each entry is the same as that of the
-	    Maintainer field, and multiple entries must be comma
+	    Maintainer field, and multiple entries MUST be comma
 	    separated.
 	  </p>
 
 	  <p>
-	    This is normally an optional field, but if
+	    This is normally an OPTIONAL field, but if
 	    the <tt>Maintainer</tt> control field names a group of people
-	    and a shared email address, the <tt>Uploaders</tt> field must
-	    be present and must contain at least one human with their
+	    and a shared email address, the <tt>Uploaders</tt> field MUST
+	    be present and MUST contain at least one human with their
 	    personal email address.
 	  </p>
 
@@ -2914,7 +2914,7 @@ Package: libc6
 	  </p>
 
 	  <p>
-	    Binary package names must follow the same syntax and
+	    Binary package names MUST follow the same syntax and
 	    restrictions as source package names.  See <ref id="f-Source">
 	    for the details.
 	  </p>
@@ -2954,7 +2954,7 @@ Package: libc6
 	    value <tt>all</tt>, the special architecture
 	    wildcard <tt>any</tt>, or a list of specific and wildcard
 	    architectures separated by spaces.  If <tt>all</tt>
-	    or <tt>any</tt> appears, that value must be the entire
+	    or <tt>any</tt> appears, that value MUST be the entire
 	    contents of the field.  Most packages will use
 	    either <tt>all</tt> or <tt>any</tt>.
 	  </p>
@@ -3028,8 +3028,8 @@ Package: libc6
 	    package is also being uploaded, the special
 	    entry <tt>source</tt> is also present.  <tt>all</tt> will be
 	    present if any architecture-independent packages are being
-	    uploaded.  Architecture wildcards such as <tt>any</tt> must
-	    never occur in the <tt>Architecture</tt> field in
+	    uploaded.  Architecture wildcards such as <tt>any</tt>
+	    MUST NOT occur in the <tt>Architecture</tt> field in
 	    the <file>.changes</file> file.
 	  </p>
 
@@ -3043,7 +3043,7 @@ Package: libc6
 	  <heading><tt>Essential</tt></heading>
 
 	  <p>
-	    This is a boolean field which may occur only in the
+	    This is a boolean field which MAY occur only in the
 	    control file of a binary package or in a per-package fields
 	    paragraph of a source package control file.
 	  </p>
@@ -3097,7 +3097,7 @@ Package: libc6
 	    Thus only the first three components of the policy version
 	    are significant in the <em>Standards-Version</em> control
 	    field, and so either these three components or all four
-	    components may be specified.<footnote>
+	    components MAY be specified.<footnote>
 	  	In the past, people specified the full version number
 	  	in the Standards-Version field, for example "2.3.0.0".
 	  	Since minor patch-level changes don't introduce new
@@ -3125,8 +3125,8 @@ Package: libc6
 	      <item>
 	        <p>
 	          This is a single (generally small) unsigned integer.  It
-	          may be omitted, in which case zero is assumed.  If it is
-	          omitted then the <var>upstream_version</var> may not
+	          MAY be omitted, in which case zero is assumed.  If it is
+	          omitted then the <var>upstream_version</var> MUST NOT
 	          contain any colons.
 	        </p>
 
@@ -3154,17 +3154,17 @@ Package: libc6
 	          The comparison behavior of the package management system
 	          with respect to the <var>upstream_version</var> is
 	          described below.  The <var>upstream_version</var>
-	          portion of the version number is mandatory.
+	          portion of the version number is REQUIRED.
 	        </p>
 
 	        <p>
-	          The <var>upstream_version</var> may contain only
+	          The <var>upstream_version</var> MUST contain only
 	          alphanumerics<footnote>
 			Alphanumerics are <tt>A-Za-z0-9</tt> only.
 	          </footnote>
 	          and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
 	          <tt>:</tt> <tt>~</tt> (full stop, plus, hyphen, colon,
-	          tilde) and should start with a digit.  If there is no
+	          tilde) and SHOULD start with a digit.  If there is no
 	          <var>debian_revision</var> then hyphens are not allowed;
 	          if there is no <var>epoch</var> then colons are not
 	          allowed.
@@ -3176,7 +3176,7 @@ Package: libc6
 	        <p>
 	          This part of the version number specifies the version of
 	          the Debian package based on the upstream version.  It
-	          may contain only alphanumerics and the characters
+	          MUST contain only alphanumerics and the characters
 	          <tt>+</tt> <tt>.</tt> <tt>~</tt> (plus, full stop,
 	          tilde) and is compared in the same way as the
 	          <var>upstream_version</var> is.
@@ -3184,7 +3184,7 @@ Package: libc6
 
 	        <p>
 	          It is optional; if it isn't present then the
-	          <var>upstream_version</var> may not contain a hyphen.
+	          <var>upstream_version</var> MUST NOT contain a hyphen.
 	          This format represents the case where a piece of
 	          software was written specifically to be a Debian
 	          package, where the Debian package source must always
@@ -3310,7 +3310,7 @@ Package: libc6
 	      horizontally, the displaying program will line wrap 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
+	      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>
@@ -3404,7 +3404,7 @@ Package: libc6
 
 	  <p>
 	    This field includes the date the package was built or last
-	    edited.  It must be in the same format as the <var>date</var>
+	    edited.  It MUST be in the same format as the <var>date</var>
 	    in a <file>debian/changelog</file> entry.
 	  </p>
 
@@ -3462,7 +3462,7 @@ Package: libc6
 	      gives an indication of the importance of any fixes included
 	      in the upload.  <tt>Emergency</tt> and <tt>critical</tt> are
 	      treated as synonymous.
-	    </footnote> (not case-sensitive) followed by an optional
+	    </footnote> (not case-sensitive) followed by an OPTIONAL
 	    commentary (separated by a space) which is usually in
 	    parentheses.  For example:
 
@@ -3491,7 +3491,7 @@ Package: libc6
 	    The first line of the field value (the part on the same line
 	    as <tt>Changes:</tt>) is always empty.  The content of the
 	    field is expressed as continuation lines, with each line
-	    indented by at least one space.  Blank lines must be
+	    indented by at least one space.  Blank lines MUST be
 	    represented by a line consisting only of a space and a full
 	    stop (<tt>.</tt>).
 	  </p>
@@ -3503,15 +3503,15 @@ Package: libc6
 	  </p>
 
 	  <p>
-	    Each version's change information should be preceded by a
+	    Each version's change information SHOULD be preceded by a
 	    "title" line giving at least the version, distribution(s)
 	    and urgency, in a human-readable way.
 	  </p>
 
 	  <p>
 	    If data from several versions is being returned the entry
-	    for the most recent version should be returned first, and
-	    entries should be separated by the representation of a
+	    for the most recent version SHOULD be returned first, and
+	    entries SHOULD be separated by the representation of a
 	    blank line (the "title" line may also be followed by the
 	    representation of a blank line).
 	  </p>
@@ -3576,7 +3576,7 @@ Package: libc6
 	    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
+	    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>
@@ -3611,7 +3611,7 @@ Files:
 	    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
+	    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>
@@ -3621,18 +3621,18 @@ Files:
 	    <tt>.changes</tt> file indicates that the file in question
 	    is not an ordinary package file and must by installed by
 	    hand by the distribution maintainers.  If the section is
-	    <tt>byhand</tt> the priority should be <tt>-</tt>.
+	    <tt>byhand</tt> the priority SHOULD be <tt>-</tt>.
 	  </p>
 
 	  <p>
 	    If a new Debian revision of a package is being shipped and
 	    no new original source archive is being distributed the
-	    <tt>.dsc</tt> must still contain the <tt>Files</tt> field
+	    <tt>.dsc</tt> MUST still contain the <tt>Files</tt> field
 	    entry for the original source archive
 	    <file><var>package</var>_<var>upstream-version</var>.orig.tar.gz</file>,
-	    but the <file>.changes</file> file should leave it out.  In
+	    but the <file>.changes</file> file SHOULD leave it out.  In
 	    this case the original source archive on the distribution
-	    site must match exactly, byte-for-byte, the original
+	    site MUST match exactly, byte-for-byte, the original
 	    source archive which was used to generate the
 	    <file>.dsc</file> file and diff which are being uploaded.</p>
 	</sect1>
@@ -3696,11 +3696,11 @@ Checksums-Sha256:
 	  </p>
 
 	  <p>
-	    In the <file>.dsc</file> file, these fields should list all
+	    In the <file>.dsc</file> file, these fields SHOULD list all
 	    files that make up the source package.  In
-	    the <file>.changes</file> file, these fields should list all
+	    the <file>.changes</file> file, these fields SHOULD list all
 	    files being uploaded.  The list of files in these fields
-	    must match the list of files in the <tt>Files</tt> field.
+	    MUST match the list of files in the <tt>Files</tt> field.
 	  </p>
 	</sect1>
 
@@ -3709,7 +3709,7 @@ Checksums-Sha256:
 
 	  <p>
 	    The most recent version of a package uploaded to unstable or
-	    experimental must include the field <tt>DM-Upload-Allowed:
+	    experimental MUST include the field <tt>DM-Upload-Allowed:
 	    yes</tt> in the source section of its source control file for
 	    the Debian archive to accept uploads signed with a key in the
 	    Debian Maintainer keyring.  See the General
@@ -3724,7 +3724,7 @@ Checksums-Sha256:
 	<heading>User-defined fields</heading>
 
 	<p>
-	  Additional user-defined fields may be added to the
+	  Additional user-defined fields MAY be added to the
 	  source package control file.  Such fields will be
 	  ignored, and not copied to (for example) binary or
 	  Debian source control files or upload control files.


Here are the occurences of ‘must’ that I did not feel like or was unsure about
changing to upper case.


	  <p>
	    If the maintainer's name contains a full stop then the
	    whole field will not work directly as an email address due
	    to a misfeature in the syntax specified in RFC822; a
	    program using this field as an address must check for this
	    and correct the problem if necessary (for example by
	    putting the name in round brackets and moving it to the
	    end, and bringing the email address forward).
	  </p>

--
	        <p>
	          It is optional; if it isn't present then the
	          <var>upstream_version</var> MUST NOT contain a hyphen.
	          This format represents the case where a piece of
	          software was written specifically to be a Debian
	          package, where the Debian package source must always
	          be identical to the pristine source and therefore no
	          revision indication is required.
	        </p>

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

	  <p>
	    The special value <tt>byhand</tt> for the section in a
	    <tt>.changes</tt> file indicates that the file in question
	    is not an ordinary package file and must by installed by
	    hand by the distribution maintainers.  If the section is
	    <tt>byhand</tt> the priority SHOULD be <tt>-</tt>.
	  </p>

For ‘should’:


	  <p>
	    List of the names and email addresses of co-maintainers of the
	    package, if any. If the package has other maintainers besides
	    the one named in the <qref id="f-Maintainer">Maintainer
	    field</qref>, their names and email addresses should be listed
	    here. The format of each entry is the same as that of the
	    Maintainer field, and multiple entries MUST be comma
	    separated.
	  </p>

--
	    architecture-dependent package on only those architectures
	    that match any of the specified architecture wildcards.
	    Specifying a list of architectures or architecture wildcards
	    other than <tt>any</tt> is for the minority of cases where a
	    program is not portable or is not useful on some
	    architectures.  Where possible, the program should be made
	    portable instead.
	  </p>

	  <p>
	    In the Debian source control file <file>.dsc</file>, this
--
	    the <file>debian/control</file> in the source package.
	  </p>

	  <p>
	    Specifying only <tt>any</tt> indicates that the source package
	    isn't dependent on any particular architecture and should
	    compile fine on any one. The produced binary package(s)
	    will be specific to whatever the current build architecture is.
	  </p>

	  <p>
--
	  <heading><tt>Distribution</tt></heading>

	  <p>
	    In a <file>.changes</file> file or parsed changelog output
	    this contains the (space-separated) name(s) of the
	    distribution(s) where this version of the package should
	    be installed.  Valid distributions are determined by the
	    archive maintainers.<footnote>
	      Example distribution names in the Debian archive used in
	      <file>.changes</file> files are:
		<taglist compact="compact">
--
	  Debian source control files or upload control files.
	</p>

	<p>
	  If you wish to add additional unsupported fields to
	  these output files you should use the mechanism
	  described here.
	</p>

	<p>
	  Fields in the main source control information file with

For ‘may’:


	    </item>
	    <tag>multiline</tag>
	    <item>
	      The value of a multiline field MAY comprise multiple continuation
	      lines.  The first line of the value, the part on the same line as
	      the field name, often has special significance or may have to be
	      empty.  Other lines are added following the same syntax as the
	      continuation lines of the folded fields.  Whitespace, including newlines,
	      is significant in the values of multiline fields.
	    </item>
	  </taglist>
--
          multi-character version relationships.
	</p>

	<p>
	  The presence and purpose of a field, and the syntax of its
	  value may differ between types of control files.
	</p>

	<p>
	  Field names are not case-sensitive, but it is usual to
	  capitalize the field names using mixed case as shown below.
--
	    </list>
	  </p>

	  <p>
	    In the main <file>debian/control</file> file in the source
	    package, this field may contain the special
	    value <tt>all</tt>, the special architecture
	    wildcard <tt>any</tt>, or a list of specific and wildcard
	    architectures separated by spaces.  If <tt>all</tt>
	    or <tt>any</tt> appears, that value MUST be the entire
	    contents of the field.  Most packages will use
--
	    architecture wildcard <tt>any</tt>, the only other value
	    allowed in the list is <tt>all</tt>.
	  </p>

	  <p>
	    The list may include (or consist solely of) the special
	    value <tt>all</tt>.  In other words, in <file>.dsc</file>
	    files unlike the <file>debian/control</file>, <tt>all</tt> may
	    occur in combination with specific architectures.
	    The <tt>Architecture</tt> field in the Debian source control
	    file <file>.dsc</file> is generally constructed from
	    the <tt>Architecture</tt> fields in
	    the <file>debian/control</file> in the source package.
--
	  	in the Standards-Version field, for example "2.3.0.0".
	  	Since minor patch-level changes don't introduce new
	  	policy, it was thought it would be better to relax
	  	policy and only require the first 3 components to be
	  	specified, in this example "2.3.0".  All four
	  	components may still be used if someone wishes to do so.
	    </footnote>
	  </p>

	</sect1>

--
	          This is the main part of the version number.  It is
	          usually the version number of the original ("upstream")
	          package from which the <file>.deb</file> file has been made,
	          if this is applicable.  Usually this will be in the same
	          format as that specified by the upstream author(s);
	          however, it may need to be reformatted to fit into the
	          package management system's format and comparison
	          scheme.
	        </p>

	        <p>
--
	  </p>

	  <p>
	    First the initial part of each string consisting entirely of
	    non-digit characters is determined.  These two parts (one of
	    which may be empty) are compared lexically.  If a difference
	    is found it is returned.  The lexical comparison is a
	    comparison of ASCII values modified so that all the letters
	    sort earlier than all the non-letters and so that a tilde
	    sorts before anything, even the end of a part.  For example,
	    the following parts are in sorted order from earliest to
--
	    programs acting on a source package to interpret the list of
	    files in the source package and determine how to unpack it.
	    The syntax of the field value is a numeric major revision, a
	    period, a numeric minor revision, and then an optional subtype
	    after whitespace, which if specified is an alphanumeric word
	    in parentheses.  The subtype is optional in the syntax but may
	    be mandatory for particular source format revisions.
	    <footnote>
	      The source formats currently supported by the Debian archive
	      software are <tt>1.0</tt>, <tt>3.0 (native)</tt>,
	      and <tt>3.0 (quilt)</tt>.
--

	  <p>
	    If data from several versions is being returned the entry
	    for the most recent version SHOULD be returned first, and
	    entries SHOULD be separated by the representation of a
	    blank line (the "title" line may also be followed by the
	    representation of a blank line).
	  </p>
	</sect1>

	<sect1 id="f-Binary">
--

	  <p>
	    This field appears in the control files of binary packages,
	    and in the <file>Packages</file> files.  It gives an estimate
	    of the total amount of disk space required to install the
	    named package.  Actual installed size may vary based on block
	    size, file system properties, or actions taken by package
	    maintainer scripts.
	  </p>

	  <p>
--

	  <p>
	    The URL of the web site for this package, preferably (when
	    applicable) the site from which the original source can be
	    obtained and any additional upstream documentation or
	    information may be found.  The content of this field is a
	    simple URL without any surrounding characters such as
	    <tt>&lt;&gt;</tt>.
	  </p>
	</sect1>


For ‘required’:


	          <var>upstream_version</var> MUST NOT contain a hyphen.
	          This format represents the case where a piece of
	          software was written specifically to be a Debian
	          package, where the Debian package source must always
	          be identical to the pristine source and therefore no
	          revision indication is required.
	        </p>

	        <p>
	          It is conventional to restart the
	          <var>debian_revision</var> at <tt>1</tt> each time the
--
	  <heading><tt>Installed-Size</tt></heading>

	  <p>
	    This field appears in the control files of binary packages,
	    and in the <file>Packages</file> files.  It gives an estimate
	    of the total amount of disk space required to install the
	    named package.  Actual installed size may vary based on block
	    size, file system properties, or actions taken by package
	    maintainer scripts.
	  </p>


For ‘optional’:


	          tilde) and is compared in the same way as the
	          <var>upstream_version</var> is.
	        </p>

	        <p>
	          It is optional; if it isn't present then the
	          <var>upstream_version</var> MUST NOT contain a hyphen.
	          This format represents the case where a piece of
	          software was written specifically to be a Debian
	          package, where the Debian package source must always
	          be identical to the pristine source and therefore no
--
	    Debian source control</qref> files, this field declares the
	    format of the source package.  The field value is used by
	    programs acting on a source package to interpret the list of
	    files in the source package and determine how to unpack it.
	    The syntax of the field value is a numeric major revision, a
	    period, a numeric minor revision, and then an optional subtype
	    after whitespace, which if specified is an alphanumeric word
	    in parentheses.  The subtype is optional in the syntax but may
	    be mandatory for particular source format revisions.
	    <footnote>
	      The source formats currently supported by the Debian archive
	      software are <tt>1.0</tt>, <tt>3.0 (native)</tt>,
	      and <tt>3.0 (quilt)</tt>.


I did my best, but I would be surprised to have been completely accurate on the
first attempt, so your critical comments are more than welcome.

Have a nice day,

-- 
Charles




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#647570; Package debian-policy. (Fri, 04 Nov 2011 13:30:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Bill Allombert <Bill.Allombert@math.u-bordeaux1.fr>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Fri, 04 Nov 2011 13:30:03 GMT) Full text and rfc822 format available.

Message #10 received at 647570@bugs.debian.org (full text, mbox):

From: Bill Allombert <Bill.Allombert@math.u-bordeaux1.fr>
To: Charles Plessy <plessy@debian.org>, 647570@bugs.debian.org
Subject: Re: Bug#647570: debian-policy: Conformance of Chapter 5 to RFC 2119.
Date: Fri, 4 Nov 2011 14:28:14 +0100
On Fri, Nov 04, 2011 at 09:55:45AM +0900, Charles Plessy wrote:
> Package: debian-policy
> Version: 3.9.2.0
> Severity: wishlist
> 
> Dear all,
> 
> following our discussion at the end of October about the vocabulary used in the
> Policy, (20111025143614.GB14464@merveille.plessy.net), here is a first pass on
> Chapter 5, to use the vocabulary of RFC 2119 (http://www.ietf.org/rfc/rfc2119.txt)
> where applicable.
> 
> I am presenting my proposition as a patch for the words that change, and as a
> serie of extracts centered on the words that do not change.
> 
> In most cases the change is a capitalisation, but in a few cases the words
> themselves change, where for instance ‘may (not)’ becomes ‘MUST (NOT)’.  I
> focused on the key words defined by the RFC, with the exception of ‘mandatory’,
> which I propose to change to ‘REQUIRED’ as it was used in the context other
> ‘RECOMMENDED’ key words.  I also propose to change a ‘must never’ to ‘MUST NOT’.
> 
> I also made sure that ‘MUST NOT’ and ‘SHOULD NOT’ are never interrupted by a
> new line, to facilitate searches in the source document.

I would suggest we use entities instead of hard-coding 'MUST NOT/SHOULD NOT'.
This way it will be easier to generate policy document with the lower case
variant for people who cannot read uppercase words.

Cheers,
-- 
Bill. <ballombe@debian.org>

Imagine a large red swirl here. 




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#647570; Package debian-policy. (Fri, 04 Nov 2011 13:57:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Fri, 04 Nov 2011 13:57:03 GMT) Full text and rfc822 format available.

Message #15 received at 647570@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Bill Allombert <Bill.Allombert@math.u-bordeaux1.fr>, 647570@bugs.debian.org
Cc: Charles Plessy <plessy@debian.org>
Subject: Re: Bug#647570: debian-policy: Conformance of Chapter 5 to RFC 2119.
Date: Fri, 4 Nov 2011 14:52:34 +0100
On Fri, 04 Nov 2011, Bill Allombert wrote:
> I would suggest we use entities instead of hard-coding 'MUST NOT/SHOULD NOT'.
> This way it will be easier to generate policy document with the lower case
> variant for people who cannot read uppercase words.

Entities are not translatable. Even if there's no current translation of
the policy, I believe we should not use entities for english words
that ought to be translatable.

Cheers,
-- 
Raphaël Hertzog ◈ Debian Developer

Pre-order a copy of the Debian Administrator's Handbook and help
liberate it: http://debian-handbook.info/go/ulule-rh/




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#647570; Package debian-policy. (Sat, 05 Nov 2011 11:15:16 GMT) Full text and rfc822 format available.

Acknowledgement sent to Bill Allombert <Bill.Allombert@math.u-bordeaux1.fr>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 05 Nov 2011 11:15:22 GMT) Full text and rfc822 format available.

Message #20 received at 647570@bugs.debian.org (full text, mbox):

From: Bill Allombert <Bill.Allombert@math.u-bordeaux1.fr>
To: Raphael Hertzog <hertzog@debian.org>, 647570@bugs.debian.org
Subject: Re: Bug#647570: debian-policy: Conformance of Chapter 5 to RFC 2119.
Date: Sat, 5 Nov 2011 12:10:41 +0100
On Fri, Nov 04, 2011 at 02:52:34PM +0100, Raphael Hertzog wrote:
> On Fri, 04 Nov 2011, Bill Allombert wrote:
> > I would suggest we use entities instead of hard-coding 'MUST NOT/SHOULD NOT'.
> > This way it will be easier to generate policy document with the lower case
> > variant for people who cannot read uppercase words.
> 
> Entities are not translatable. Even if there's no current translation of
> the policy, I believe we should not use entities for english words
> that ought to be translatable.

Of course entities are translatable. What are you actually wanting to say ?

Cheers,
-- 
Bill. <ballombe@debian.org>

Imagine a large red swirl here. 




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#647570; Package debian-policy. (Sat, 05 Nov 2011 21:30:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sat, 05 Nov 2011 21:30:04 GMT) Full text and rfc822 format available.

Message #25 received at 647570@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Bill Allombert <Bill.Allombert@math.u-bordeaux1.fr>
Cc: 647570@bugs.debian.org
Subject: Re: Bug#647570: debian-policy: Conformance of Chapter 5 to RFC 2119.
Date: Sat, 5 Nov 2011 22:27:05 +0100
On Sat, 05 Nov 2011, Bill Allombert wrote:
> Of course entities are translatable. What are you actually wanting to say ?

Well, nowadays we expect to handle translations just with PO files. And in
this context, you're expected to keep an entity between the original
string and the translated one.

"a package &must; have a version"
"un paquet &must; avoir une version"

This won't work, so the translators would have to use "un paquet DOIT
avoir une version" (i.e. replacing the entity with its translated value).
Or we would have to add entities for all translations... or we would have
to have localized definitions of all entities (likely without using PO
files but some custom mechanism).

None of this is really clean IMO and it's really abusing entities
for a weird goal ("allowing people to generate a version of the policy
without uppercase").

Cheers,
-- 
Raphaël Hertzog ◈ Debian Developer

Pre-order a copy of the Debian Administrator's Handbook and help
liberate it: http://debian-handbook.info/go/ulule-rh/




Changed Bug title to 'convert Chapter 5 to RFC 2119 language' from 'debian-policy: Conformance of Chapter 5 to RFC 2119.' Request was from Russ Allbery <rra@debian.org> to control@bugs.debian.org. (Sun, 25 Dec 2011 18:33:05 GMT) Full text and rfc822 format available.

Added indication that bug 647570 blocks 661417 Request was from Russ Allbery <rra@debian.org> to control@bugs.debian.org. (Mon, 27 Feb 2012 02:15:06 GMT) Full text and rfc822 format available.

Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Thu Apr 17 07:53:50 2014; Machine Name: buxtehude.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.