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

Re: DEP-5: Files field and filename patterns

On la, 2010-08-28 at 19:51 +1200, Lars Wirzenius wrote:
> To make this go forward, I suggest that we adopt Charles's suggestion of
> very simple globbing, since that's going to be compatible with more
> powerful syntaxes if we want to adopt those later. Further, I suggest we
> not treat the slash character specially when matching, so that
> */Makefile.in will match Makefile.in at any depth. All patterns are
> anchored to the root of the source tree; thus a plain Makefile.in will
> match only at the root of the source tree. I suggest we not add
> exclusions at this time. In a year or two, we can re-visit this part of
> the spec and see if it needs to be improved.
> Is this proposal acceptable?

Nobody has commented on this in any way, so I assume I am still perfect
and everything I say is flawless. I am attaching a proposed patch to
rewrite the filename pattern section. Unless there are objections within
a couple of days, I will push it out.
=== modified file 'dep5.mdwn'
--- dep5.mdwn	2010-08-31 21:08:28 +0000
+++ dep5.mdwn	2010-09-07 05:22:34 +0000
@@ -276,62 +276,59 @@
 Extra fields can be added to any section. Their name starts by **`X-`**.
 ## Fields Detail
 ### Files
-#### Format
-The **`Files`** field contains a list of comma-separated patterns
-	Files: foo.c, bar.*, baz.[ch]
-File names containing spaces or commas should be put within double
-quotes. The backslash character is an escaping character, be it inside
-or outside double quotes:
-	Files: "Program Files/*", manual[english].txt
-#### Syntax
-Patterns are handled as by the `find` utility's `-name` option.  Patterns
-containing a path separator ("/") are handled as by the `find` utility's
-`-path` option.
-The following matches all `Makefile.am` files in the tree and all
-Python scripts:
-	Files: */Makefile.am, *.py
-But this will only match the top-level `Makefile.am`:
-	Files: ./Makefile.am
-For the first example, the equivalent `find` command would be:
-	find . -path "*/Makefile.am" -o -name "*.py"
-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 paragraphs are allowed with different `Files`
-However it makes for easier reading if the copyright file lists the
-"main" license first: the one matching the "top level" of the work, with
-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 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
-the file `getopt.c` has the license declaration `License: BSD`.
-	Files: *
-	Copyright: 2003-2005, John Doe <jdoe@xample.com>
-	License: [the main work's license]
-	Files: getopt.*
-	Copyright: 2000, The Corporation Foundation, Inc.
-	License: BSD
+Filename patterns in the `Files` field are specified using a
+simplified shell glob syntax. Patterns are separated by
+white space.
+* Only the wildcards `*` and `?` apply; the former matches any number
+  of characters (including none), the latter a single character. Both
+  match a slash ("`/`") and a leading dot.
+* The backslash ("`\\`") is used to remove the magic from the next
+  character; see table below.
+* Patterns match pathnames that start at the root of the source tree.
+  Thus, "`Makefile.in`" matches only the file at the root of the tree,
+  but "`*/Makefile.in`" matches at any depth.
+Backslash escape sequences:
+    \*          match star (asterisk)
+    \?          match question mark
+    \\          match backslash
+Any other character following a backslash is an error.
+Multiple `Files` paragraphs are allowed. The last paragraph that
+matches a particular file applies to it.
+Exclusions are done by having multiple `Files` paragraphs.
+    Files: *
+    Copyright: 1975-2010 Ulla Upstream
+    License: GPL2+
+    Files: debian/*
+    Copyright: 2010 Daniela Debianizer
+    License: GPL2+
+    Files: debian/patches/fancy-feature
+    Copyright: 2010 Daniela Debianizer
+    License: GPL3+
+    Files: */*.1
+    Copyright: 2010 Manuela Manpager
+    License: GPL2+
+In this example, all files are copyright by the upstream and licensed
+under the GPL, version 2 or later, with three exceptions. 
+All the Debian packaging files are copyright by the packager,
+and further one specific file providing a new feature is licensed
+differently. Finally, there are some manual pages added to the package,
+written by a third person.
 ### License
 #### Short name

Reply to: