Bug#942756: cme: please provide more description of the format of d/fix.scanned.copyright

[Dominique Dumont]

Hello

On Monday, 21 October 2019 04:35:47 CEST you wrote:
> I started to use cme to maintain d/copyright today.  It'll be a big help, so
> thanks!

Thanks for the feedback :-)

> But I ran into a few snags.

Which is to be expected with complex software :-p

> I'm not sure how d/fix.scanned.copyright is supposed to work.  Some examples
> in Config::Model::Dpkg::Copyright(3pm) are clear but trivial. 

Yes, I failed to come up with more complex but realistic examples. I hope 
you'll help me there.

> They allude
> to some complex capabilities without any explanation ("don't forget '!' to
> go back to tree root": but what tree is there?  This is a text file with a
> few lines.).

The data contained in debian/copyright is mapped to a tree structure inside 
cme. You can have a view of this structure by running 'cme dump dpkg-
copyright' or get a graphical view with 'cme edit dpkg-copyright'

The instructions specified in fix.scanned.copyright are steps to walk in that 
tree and alter the values when specified.

> I think I need some more help from the point of view of
> someone trying to automate management of d/copyright.

Sure. Note that this automation cannot be bulletproof because the copyright 
extraction process relies on unstructured data so it's somewhat fuzzy.

> Things that I'd find helpful:
> - what is the general form of these lines?  If that's too complex, examples
>   covering more use-cases would be helpful.

In fact, I've found that tweaking debian/fill.copyright.blanks.yml often 
provide better results. All in all, I've found very few cases where tweaking 
d/fix.scanned.copyright provided better results than tweaking debian/
fill.copyright.blanks.yml 

Note that debian/fill.copyright.blanks.yml can also be edited with 'cme edit 
dpkg'

> - how should I handle stanzas with multiple lines in Files, Copyright, etc.?

Right. That's a realistic example I did not think of.. :-}

Please put the multiline stanza between double quotes. For instance:

Files:"uulib/crc32.h
 uulib/uustring.h"

You can have a view of debian/copyright file translated in this syntax by 
running 'cme dump --format cml dpkg-copyright'

> - there appears to be a few ways to modify d/copyright stanzas.  What are
> the possibilities?

Mostly assignment and using regular expression on value. These are detailed on 
Config::Model::Loader man page. I'd rather fix this man page than repeat the 
instructions.

> I found Config::Model::Loader(3pm) but it was overwhelming.  Documenting the
> data structures doesn't help much since I'm not a perl programmer and I'd
> rather avoid learning about the generic serialization described there.

I understand that Config::Model::Loader synopsis is for only for Perl 
programmer. 

On the other hand, the "load string syntax" section was intended to provide 
instructions usable for non-perl programmers. Was that section overwhelming as 
well ?

In any case, I may need to split this man page... What do you think ?

All the best

Dod