Bug#1020241: debian-policy: copyright-format: Formatting improvements/changes
Russ Allbery <rra@debian.org> writes:
> The killer features of YAML for the purposes of the copyright format are
> the > and | symbols after a key, which let you write paragraphs of text
> afterwards with normal structural indentation and full editor support
> for wrapping and the like, and you can choose whether you want
> significant whitespace.
I said I wasn't going to get into this, but of course now I can't stop
thinking about it. For those who haven't done very much with YAML, an
example may help illustrate what I'm talking about.
Here's the copyright file for libpgp-sign-perl, which is fairly simple,
converted to a hypothetical YAML syntax. I moved the Expat license to a
separate license stanza to illustrate how that would work, and I also made
up some structure to represent a bunch of the things we put into a
copyright-format file as plain text right now that we could turn into less
ambiguous fields. The latter we can of course do in the current syntax,
so that's not the interesting part; the interesting part is to look at
what's required to represent the structure, how much nested structure you
can add, and how the text blocks are handled in the format. There is also
an illustration of how to handle long copyright lines in here.
Note that YAML syntax and schema checkers are also quite common, so we
can easily provide tools to validate these files without writing bespoke
parsers the way that I did for Lintian with the current syntax.
I'm erring on the side of very unambiguous nested structure here and
avoiding any implicit semantics, which may be overkill; we could tone that
down quite a bit if we wanted in the name of making the file less complex.
(Or we could go a step further and split the years from the holder in
copyright statements, but that feels like overkill even to me.)
Also try saving this as a file ending in .yaml in your favorite editor, if
you haven't done a lot of YAML work before, and see how well it handles it
for syntax highlighting, editing, etc. Emacs handles it extremely well
with elpa-yaml-mode installed. vim, at least without any add-ons
installed, does some syntax highlighting but is still a bit confused by
the text blocks and thinks colons are significant in them. (There's
apparently a vim-yaml plugin that I don't have installed that might help
there.)
format: https://www.debian.org/doc/packaging-manuals/copyright-format/x.x/
upstream:
contact: Russ Allbery <rra@cpan.org>
source:
urls:
- https://www.eyrie.org/~eagle/software/pgp-sign/
files:
- paths: [*]
copyrights:
- 1997-2002, 2004, 2007, 2018, 2020 Russ Allbery <rra@cpan.org>
license:
identifier: Perl
grant: |
This program is free software; you may redistribute it and/or
modify it under the same terms as Perl itself. This means that
you may choose between the two licenses that Perl is released
under: the GNU GPL and the Artistic License. Please see your
Perl distribution for the details and copies of the licenses.
pointers:
- /usr/share/common-licenses/GPL-1
- /usr/share/common-licenses/Artistic
- paths:
- t/data/perlcriticrc
- t/docs/pod-coverage.t
- t/docs/pod-spelling.t
- t/docs/pod.t
- t/docs/spdx-license.t
- t/docs/synopsis.t
- t/lib/Test/RRA.pm
- t/lib/Test/RRA/Config.pm
- t/style/coverage.t
- t/style/critic.t
- t/style/minimum-version.t
- t/style/obsolete-strings.t
- t/style/strict.t
copyrights:
- >-
2011-2014 The Board of Trustees of the Leland Stanford Junior
University
- 2015-2016, 2018-2020 Russ Allbery <eagle@eyrie.org>
license:
identifier: Expat
- paths: [t/data/perltidyrc]
copyrights:
- >-
2012-2013 The Board of Trustees of the Leland Stanford Junior
University
license:
identifier: all-permissive
text: |
Copying and distribution of this file, with or without
modification, are permitted in any medium without royalty provided
the copyright notice and this notice are preserved. This file is
offered as-is, without any warranty.
licenses:
- identifier: Expat
text: |
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation files
(the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
--
Russ Allbery (rra@debian.org) <https://www.eyrie.org/~eagle/>
Reply to: