[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: [DEP-5] [re-patch] Syntax of the files.



Le Sat, Aug 14, 2010 at 09:39:32PM -0700, Russ Allbery a écrit :
> Charles Plessy <plessy@debian.org> writes:
> > 2) The Policy does not describe the DEP syntax for escaping empty lines.
> 
> > Policy §5.1 does not describe the mechanism of using a space plus a dot
> > to escape empty lines in field values, but we can not refer simply to
> > §5.6.13 (Description) because the DEP-5 License field is verbatim,
> > whereas the debian/control Description filed requires an additional
> > space to signal verbatim sections.
> 
> Yes, this should be described in DEP-5.
[…] 
> DEP-5 can certainly say that the leading
> spaces are not part of the field value.

I attached three consecutive patches, that I think reflect our current
discussion.

 - The first one is just a re-iteration of Lars' patch, in
   which I added the title of §5.1, and the version of the current Policy.

 - The second replaces stanza by paragraph.

 - The third explains how empty lines are escaped in field values.

Currently, all multi-line fields are verbatim; this is not changed from before.

-- 
Charles
>From cdc3e8826eabcdb17cc3ff5a4e3109e823bfc67e Mon Sep 17 00:00:00 2001
From: Charles Plessy <plessy@debian.org>
Date: Sat, 14 Aug 2010 15:45:25 +0900
Subject: [PATCH 1/3]  # Use the same syntax as Debian control files, indicating the version of the Policy.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comment: |
 Similar to Lars' patch, but indicating the Policy version, §5.1's title,
 and providing URL.
Message-ID: <1281815038.5840.101.camel@havelock>
---
 dep5.mdwn |   12 ++++++------
 1 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/dep5.mdwn b/dep5.mdwn
index d12c3a3..327f995 100644
--- a/dep5.mdwn
+++ b/dep5.mdwn
@@ -54,17 +54,17 @@ A user might want to have a way to avoid software with certain licenses
 they have a problem with, even if the licenses are DFSG-free. For
 example, the Affero GPL.
 
-# Compatibility and Human-Readability
-The file must be encoded as UTF-8 and strictly formatted as a superset
-of RFC2822 including significant newlines. Free-form text is not
-allowed.
+# File syntax
 
 The `debian/copyright` file must be machine-interpretable, yet
 human-readable, while communicating all mandated upstream information,
 copyright notices and licensing details.
 
-For the sake of human-readability this proposal avoids any complex field
-names or syntax rules.
+The syntax of the file is the same as for other Debian control files, as
+specified in section 5.1 ([Syntax of control files][]) of the Debian Policy
+Manual, version 3.9.1.
+
+[Syntax of control files]: http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-controlsyntax
 
 # Implementation
 ## Sections
-- 
1.6.5.7

>From 1bed647d90b44fc9b9d0b2f3005c519675a5adab Mon Sep 17 00:00:00 2001
From: Charles Plessy <plessy@debian.org>
Date: Sun, 15 Aug 2010 09:00:40 +0900
Subject: [PATCH 2/3] =?UTF-8?q?=20#=20Replaced=20=E2=80=98Stanza=E2=80=99=20with=20=E2=80=98Paragraph=E2=80=99.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Message-ID: <87vd7dp11p.fsf@windlord.stanford.edu>
---
 dep5.mdwn |   10 +++++-----
 1 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/dep5.mdwn b/dep5.mdwn
index 327f995..b0be016 100644
--- a/dep5.mdwn
+++ b/dep5.mdwn
@@ -114,10 +114,10 @@ Examples:
 ### Files Section (Repeatable)
 
 The declaration of copyright and license for files is done in one or
-more stanzas.
+more paragraphs.
 
  * **`Files`**
-   * Required for all but the first stanza.  If omitted from the first stanza, this is equivalent to a value of '*'.
+   * Required for all but the first paragraph.  If omitted from the first paragraph, this is equivalent to a value of '*'.
    * Syntax: List of patterns indicating files having the same license and sharing copyright holders. See "File patterns" below
 
  * **`Copyright`**
@@ -144,7 +144,7 @@ Example:
 ### Standalone License Section
 Where a set of files are dual (tri, etc) licensed, or when the same license
 occurs multiple times, you can use a single line **`License`** field and
-standalone **`License`** stanzas to expand the license short names.
+standalone **`License`** paragraphs to expand the license short names.
 
 Example 1 (tri-licensed files).
 
@@ -214,7 +214,7 @@ For the first example, the equivalent `find` command would be:
 
 It is quite common for a work to have files with copyright held by
 different parties and received under different licenses. To accommodate
-this, **multiple stanzas are allowed with different `Files`
+this, **multiple paragraphs are allowed with different `Files`
 declarations**.
 
 However it makes for easier reading if the copyright file lists the
@@ -223,7 +223,7 @@ others listed as exceptions. To allow this, the following precedence
 rule applies for matching files: **If multiple `Files` declarations
 match the same file, then only the last match counts.**
 
-As a result, it is recommended for clarity that the stanzas appear in
+As a result, it is recommended for clarity that the paragraphs appear in
 order from most general (e.g. `Files: *`) first, through to most
 specific. In the following example, the file `getopt.c` matches both
 `Files: *` and `Files: getopt.*`; only the last match counts, so
-- 
1.6.5.7

>From 4026456f46724efdd3b0feb1db13111fc7dd7a79 Mon Sep 17 00:00:00 2001
From: Charles Plessy <plessy@debian.org>
Date: Sun, 15 Aug 2010 15:47:54 +0900
Subject: [PATCH 3/3]  # Details on the multi-line fields.

Message-ID: <87d3tko5ff.fsf@windlord.stanford.edu>
---
 dep5.mdwn |    4 ++++
 1 files changed, 4 insertions(+), 0 deletions(-)

diff --git a/dep5.mdwn b/dep5.mdwn
index b0be016..06ec284 100644
--- a/dep5.mdwn
+++ b/dep5.mdwn
@@ -64,6 +64,10 @@ The syntax of the file is the same as for other Debian control files, as
 specified in section 5.1 ([Syntax of control files][]) of the Debian Policy
 Manual, version 3.9.1.
 
+In field values, lines containing a single space followed by a single full stop
+character are replaced by an empty line. The first space or tabulation is
+ignored.
+
 [Syntax of control files]: http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-controlsyntax
 
 # Implementation
-- 
1.6.5.7


Reply to: