.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Config::Model::Dpkg::Copyright 3pm" .TH Config::Model::Dpkg::Copyright 3pm "2021-06-06" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Config::Model::Dpkg::Copyright \- Fill the File sections of debian/copyright file .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # this modules is used by cme when invoked with this command \& $ cme update dpkg\-copyright .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This commands helps with the tedious task of maintening \&\f(CW\*(C`debian/copyright\*(C'\fR file. When you package a new release of a software, you can run \f(CW\*(C`cme update dpkg\-copyright\*(C'\fR to update the content of the copyright file. .PP This command scans current package directory to extract copyright and license information and store them in the Files sections of debian/copyright file. .PP In debian package directory: .PP * run 'cme update dpkg\-copyright' or 'cme update dpkg' * check the result with your favorite \s-1VCS\s0 diff tool. (you do use a \s-1VCS\s0 for your package files, do you ?) .PP Note: this command is experimental. .SH "Debian copyright data" .IX Header "Debian copyright data" The \f(CW\*(C`Files: debian/*\*(C'\fR section from \f(CW\*(C`debian/copyright\*(C'\fR is often the only place containing copyright information for the files created by Debian maintainer. So all \f(CW\*(C`Files\*(C'\fR entries beginning with \f(CW\*(C`debian/\*(C'\fR are preserved during update. However, entries not matching an existing file or directory are removed. .SH "Tweak results" .IX Header "Tweak results" Results can be tweaked either by: .IP "\(bu" 4 Changing the list of files to scan or ignore. (By default, licensecheck will decide which file to scan or not.) .IP "\(bu" 4 Specifying information for individual files .IP "\(bu" 4 Tweaking the copyright entries created by grouping and coaslescing information. .PP The first 2 ways are described in \&\*(L"Selecting or ignoring files to scan\*(R" in Dpkg::Copyright::Scanner and \*(L"Filling the blanks\*(R" in Dpkg::Copyright::Scanner. .PP The last way is described below: .SS "Tweak copyright entries" .IX Subsection "Tweak copyright entries" Since the extraction of copyright information from source file is based on comments, the result is sometimes lackluster. Your may specify instruction to alter or set specific copyright entries in \&\f(CW\*(C`debian/fix.scanned.copyright\*(C'\fR file (or \f(CW\*(C`debian/.fix.scanned.copyright\*(C'\fR). .PP cme stores the copyright information in a tree. Entries in \&\f(CW\*(C`fix.scanned.copyright\*(C'\fR provide instructions for traversing the cme tree and modifying entries. You can have a view of \f(CW\*(C`debian/copyright\*(C'\fR file translated in this syntax by running \f(CW\*(C`cme dump \-\-format cml dpkg\-copyright\*(C'\fR. Each line of this file will be handled by Config::Model::Loader to modify copyright information; the full syntax is documented in \*(L"load string syntax\*(R" in Config::Model::Loader section. .SS "Example" .IX Subsection "Example" If the extracted copyright contains: .PP .Vb 3 \& Files: * \& Copyright: 2014\-2015, Adam Kennedy "foobar \& License: Artistic or GPL\-1+ .Ve .PP You may add this line in \f(CW\*(C`debian/fix.copyright\*(C'\fR file: .PP .Vb 1 \& ! Files:\*(Aq*\*(Aq Copyright=~s/\es*".*// .Ve .PP This way, the copyright information will be updated from the file content but the extra \f(CW\*(C`"foobar\*(C'\fR will always be removed during updates. .PP Comments are accepted in Perl and \*(C+ style from the beginning of the line. Lines breaks are ignored. .PP Here's another more complex example: .PP .Vb 2 \& // added a global license, MIT license text is filled by Config::Model \& ! copyright License:MIT \& \& # don\*(Aqt forget \*(Aq!\*(Aq to go back to tree root \& ! copyright Files:"pan/general/map\-vector.h" Copyright="2001,Andrei Alexandrescu" \& License short_name=MIT \& # delete license text since short_name points to global MIT license \& full_license~ \& \& # use a loop there vvvvvv to clean up that vvvvvvvvvvvvvvvvvvvvvvv in all copyrights \& ! copyright Files:~/.*/ Copyright=~s/all\es*rights\es*reserved//i \& \& # defeat spammer by replacing all \*(Aq@\*(Aq in emails of 3rdparty files \& # the operation :~/^3party/ loops over all Files entries that match ^3rdparty \& # and modify the copyright entry with a Perl substitution \& ! Files:~/^3rdparty/ Copyright=~s/@/(at)/ .Ve .PP Sometimes, you might want to find an entry that spans multiple lines. You can do this by double quoting the whole value: .PP .Vb 2 \& ! Files:"uulib/crc32.h \& uulib/uustring.h" Copyright="2019 John Doe" .Ve .SH "Under the hood" .IX Header "Under the hood" This section explains how cme merges the information from the existing \&\f(CW\*(C`debian/copyright\*(C'\fR file (the \*(L"old\*(R" information) with the information extracted by \fIlicensecheck\fR (the \*(L"new\*(R" information): .IP "\(bu" 4 The old and new information are compared in the form of file lists: .RS 4 .IP "\(bu" 4 New file entries are kept as is in the new list. .IP "\(bu" 4 When a file entry is found in both old and new lists, the new X and license short names are checked. If they are unknown, the information from the old list is copied in the new list. .IP "\(bu" 4 Old files entries not found in the new list are deleted. .RE .RS 4 .RE .IP "\(bu" 4 File entries are coalesced in the new list to reduce redundancies (this mechanism is explained in this blog ) .IP "\(bu" 4 License entries are created, either attached to Files specification or as global licenses. License text is added for known license (actually known by Software::License) .IP "\(bu" 4 Directories (path ending with \f(CW\*(C`/*\*(C'\fR) from old list then checked: .RS 4 .IP "\(bu" 4 Directory is found in the new list: the old information is clobbered by new information. .IP "\(bu" 4 Directory not found in new list but exists: the old information is copied in the new list. .IP "\(bu" 4 Directory is not found: the old information is discarded .RE .RS 4 .RE .IP "\(bu" 4 Files entries are sorted and the new \f(CW\*(C`debian/copyright\*(C'\fR is generated. .SH "update" .IX Header "update" Updates data using the output \&\*(L"scan_files\*(R"" in Dpkg::Copyright::Scanner. .PP Parameters in \f(CW%args\fR: .IP "quiet" 4 .IX Item "quiet" set to 1 to suppress progress messages. Should be used only in tests. .PP Otherwise, \f(CW%args\fR is passed to \f(CW\*(C`scan_files\*(C'\fR .SH "AUTHOR" .IX Header "AUTHOR" Dominique Dumont