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`
-declarations**.
-
-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]
- [LICENSE TEXT]
-
- Files: getopt.*
- Copyright: 2000, The Corporation Foundation, Inc.
- License: BSD
- [LICENSE TEXT]
+
+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.
+
+Example:
+
+ 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: