Re: [boost] [inspect] Contents in XML <legalnotice> sections not checked for L & C issues?

From: Andreas Huber (ahd6974-spamgroupstrap_at_[hidden])
Date: 2006-11-27 14:30:13

Rene Rivera wrote:
> Andreas Huber wrote:
[snip]
>> Ok, please have a look at:
>>
>> http://www.boost-consulting.com/boost/libs/thread/doc/thread.xml
>>
>> What if someone removes the <legalnotice> section in this file (or
>> rewords it to whatever he pleases)? My guess is that inspect will not
>> report a failure then because there's still the XML comment. I've not
>> actually found an example for such a problem but then again I haven't
>> looked that hard.
>
> Yea, that's a correct guess. This is certainly a problem, read that as
> bug, in such documents. There should only be *one* license statement
> per file.

For boostbook root xml files (like the one above) you'd also need to 
check that the license appears in the <legalnotice> section.

> I think the best approach would be to add a check to the
> inspect program that complains when it finds multiple license
> instances in a file.

That's quite a hard problem to solve, especially when a license can 
appear in arbitrary places (like the XML comment as in the example 
above). Except of course when you assume that all licenses have some 
magic words in common.

>> This problem, together with the broken license propagation of the doc
>> tools, seems to suggest that inspect would best also check the
>> generated HTML.
>
> Strange, it suggest something different to me :-) I find it better to
> detect errors close to the source of the problem, rather than the
> farther away point of after generation.

I assume you suggest to keep checking the boostbook source xml only as 
opposed to also/only check the generated HTML. While I agree with the 
general statement, in this case, by checking the sources only, you 
cannot detect when the doctools do something wrong. That's why I 
suggested to check the generated HTML.

BTW, I do see that L & C checking is tricky business in general and can 
never be made completely foolproof. All I'm saying is that the current 
checks can be tightened with relatively little additional effort, either 
by checking the presence and contents of <legalnotice> sections and/or 
by checking the generated HTML. Then again, I don't know much about 
boostbook or inspect so I could well be wrong.

-- 
Andreas Huber
When replying by private email, please remove the words spam and trap
from the address shown in the header.