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: