update doc about README and LICENSE license scan

1 files changed, 28 insertions, 3 deletions

diff --git a/lib/Dpkg/Copyright/Scanner.pm b/lib/Dpkg/Copyright/Scanner.pm
index a51a87b3..b35af999 100644
--- a/lib/Dpkg/Copyright/Scanner.pm
+++ b/lib/Dpkg/Copyright/Scanner.pm
@@ -724,18 +724,43 @@ license information. Information are packed in a way to ease review and
 maintenance. Files information is grouped with wildcards ('*') to reduce
 the list of files.
 
+=head2 About LICENSE and README files
+
+Projects often store global copyright information, i.e. information
+that apply to all files of a project (unless specified otherwise in
+some files) in README or LICENSE or COPYING file.
+
+The information contained in these files id merged and applied to the
+directory entry that contain them.
+
+I.e files like:
+
+ foo_comp/README: (c) 2018 Joe, GPL-2
+ foo_comp/LICENSE: (c) 2017 Max, GPL-3
+
+Yield the following copyright entries:
+
+ foo_comp/*:
+ Copyright: 2018 Joe
+   2019 Max
+ License: GPL-2 or GPL-3
+
+ README:
+ Copyright: 2018 Joe
+ License: GPL-2
+
 =head1 Selecting or ignoring files to scan
 
 By default, scanner scans source files with known suffixes (like .c
 .pl ...), README, scripts and skip backup files.
 
-You can change this behavior in file
-C<debian/copyright-scan-patterns.yml>. This YAML file can contain a
+If needed, this behavior can tuned with
+C<debian/copyright-scan-patterns.yml> file. This YAML file contains a
 list of suffixes or patterns to scan or to ignore that are added to
 the default list. Any file that is not scanned or ignored will be
 shown as "skipped".
 
-The file must have the following structure (all fields are optional
+This file must have the following structure (all fields are optional
 and order does not matter):
 
  ---