[libconfig-model-dpkg-perl] 04/05: Dpkg::Copyright: added explanation on merge mechanism in pod doc

[dod at debian.org]

This is an automated email from the git hooks/post-receive script.

dod pushed a commit to branch master
in repository libconfig-model-dpkg-perl.

commit 1edeb8e670a6d9718ee9c331ea7f20e291f2b9f5
Author: Dominique Dumont <dod at debian.org>
Date:   Sun Jun 14 11:02:00 2015 +0200

    Dpkg::Copyright: added explanation on merge mechanism in pod doc
---
 lib/Config/Model/Dpkg/Copyright.pm | 66 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/lib/Config/Model/Dpkg/Copyright.pm b/lib/Config/Model/Dpkg/Copyright.pm
index 86ca0d9..862e59d 100644
--- a/lib/Config/Model/Dpkg/Copyright.pm
+++ b/lib/Config/Model/Dpkg/Copyright.pm
@@ -225,6 +225,7 @@ sub fill_global_license ($self, $l, $text) {
 
 __END__
 
+=encoding utf8
 
 =head1 NAME
 
@@ -298,6 +299,71 @@ Here's another more complex example:
  ! copyright   Files:~/.*/     Copyright=~s/all\s*rights\s*reserved//i
 
 
+=head1 Under the hood
+
+This section explains how cme merges the information from the existing
+C<debian/copyright> file (the "old" information) with the information
+extracted by I<licensecheck> (the "new" information):
+
+=over
+
+=item *
+
+The old and new information are compared in the form of file lists:
+
+=over
+
+=item *
+
+New file entries are kept as is in the new list.
+
+=item *
+
+When a file entry is found in both old and new lists, the new © and
+license short names are checked. If they are unknown, the information
+from the old list is copied in the new list.
+
+=item *
+
+Old files entries not found in the new list are deleted.
+
+=back
+
+=item *
+
+File entries are coalesced in the new list to reduce redundancies (this mechanism is explained in this L<blog|https://ddumont.wordpress.com/2015/04/05/improving-creation-of-debian-copyright-file>)
+
+=item *
+
+License entries are created, either attached to Files specification or as global licenses. License text is added for known license (actually known by L<Software::License>)
+
+=item *
+
+Directories (path ending with C</*>) from old list then checked:
+
+=over
+
+=item *
+
+Directory is found in the new list: the old information is clobbered by new information.
+
+=item *
+
+Directory not found in new list but exists: the old information is copied in the new list.
+
+=item *
+
+Directory is not found: the old information is discarded
+
+=back
+
+=item *
+
+Files entries are sorted and the new C<debian/copyright> is generated.
+
+=back
+
+
 =head1 AUTHOR
 
 Dominique Dumont <dod at debian.org>

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libconfig-model-dpkg-perl.git