packaging pregenerated kdelibs-apidocs

[Rex Dieter]

For reference,
235M kdelibs-apidocs-4.7.4-1.fc16.noarch.rpm

So, in an effort to make releng/infra/mirrors happier, I was looking into 
the possibility of packaging pregenerated content from http://api.kde.org/, 
rather than respinning kdelibs-apidocs on every kdelibs pkg build.

So, here's my general take (please correct or confirm where appropriate):
* These -apidocs are generated via doxygen from lgpl sources, so, lgpl 
applies to -apidocs
* what source code requirements are there? is the -apidocs 'preferred form' 
of the source... the kdelibs source code? or is the pregenerated html docs 
themselves good enough?

if we need matching kdelibs source code, then...

One issue raised is that api.kde.org generates their content daily from scm 
branches, which likely doesn't match exactly the sources that we distribute 
(say in our kdelibs.src.rpm's).  In case we'd try to take scm source 
snapshots to satisfy source requirements, it not clear (at the moment 
anyway), which exactly branch/commits are used by upstream either.

So, how picky do we need to be, if at all, about satisfying lgpl source 
requirements to pursue trying to package pregenerated lgpl documentation 
from api.kde.org ?

-- rex

[Tom Callaway]

On 01/26/2012 03:30 PM, Rex Dieter wrote:
>  For reference,
>  235M kdelibs-apidocs-4.7.4-1.fc16.noarch.rpm 
Maybe this is a silly question, but is this package really valuable?
Does anyone really want 235MB of apidocs, especially given the legal
complexity/concerns, and the availability of these docs on the kde.org
website?

Perhaps killing this subpackage off entirely is a clever way of avoiding
this situation.

Additionally, I'm very uncomfortable with the idea of permitting
packaging this specific type of pregenerated content, especially when it
would not necessarily match the kdelibs it refers to.

That said, here is my initial thoughts on this situation:

LGPL is a VERY poor license for these documentation files. I'd be
happier if the kdelibs license had a case where the apidocs generated
from the kdelibs files were explicitly stated to be under a proper docs
license.

In fact, in my initial attempt to apply the LGPLv2 terms to the apidocs
case, I ran into 2a) "The modified work must itself be a software
library.", which the apidocs are not.

So, I'm not even convinced anyone aside from the copyright holders
actually has permission to redistribute the apidocs (as a "modified
work" of the LGPLv2 kdelibs). Just trying to figure out a way for this
to work under the LGPLv2 is giving me a migraine.

The simplest way to fix this would be to amend the kdelibs license to
say something like:

  As an exception to the LGPL, documentation generated from this
  library for the purposes of documenting the API of this library is
  licensed under the terms of the *INSERT_YOUR_DOC_LICENSE_HERE*.

That still leaves you with the particular compliance requirements of
whatever doc license you choose, but depending on the license chosen, it
is entirely possible that the apidocs would not have a requirement to be
accompanied with matching kdelibs source (my reading of GFDL for example
is such that the apidocs, assuming they are in a suitably Transparent
copy (as defined by the GFDL) can be distributed independently of the
kdelibs source they refer to).

~tom

==
Fedora Project

[Rex Dieter]

On 01/26/2012 03:40 PM, Tom Callaway wrote:
>  The simplest way to fix this would be to amend the kdelibs license
> to
>  say something like:
>
>     As an exception to the LGPL, documentation generated from this
>     library for the purposes of documenting the API of this library is
>     licensed under the terms of the*INSERT_YOUR_DOC_LICENSE_HERE*. 
Eww, sounds to me (again, correct me if I'm wrong) that the scope of 
your concerns and statement here applies to and/all self-documenting 
code (that uses doxygen or similar tools).  If so, doesn't that imply 
we've got big problems on our hands?

-- rex

[Tom Callaway]

On 01/27/2012 08:59 AM, Rex Dieter wrote:
>  On 01/26/2012 03:40 PM, Tom Callaway wrote:
> > The simplest way to fix this would be to amend the kdelibs license to
> > say something like:
> >
> >    As an exception to the LGPL, documentation generated from this
> >    library for the purposes of documenting the API of this library is
> >    licensed under the terms of the*INSERT_YOUR_DOC_LICENSE_HERE*.
>  
>  Eww, sounds to me (again, correct me if I'm wrong) that the scope of
>  your concerns and statement here applies to and/all self-documenting
>  code (that uses doxygen or similar tools).  If so, doesn't that imply
>  we've got big problems on our hands? 
It is a concern worth addressing.

~tom

==
Fedora Project

[Kevin Kofler]

Tom Callaway wrote:
>  LGPL is a VERY poor license for these documentation files. I'd
> be
>  happier if the kdelibs license had a case where the apidocs generated
>  from the kdelibs files were explicitly stated to be under a proper docs
>  license.
>  
>  In fact, in my initial attempt to apply the LGPLv2 terms to the apidocs
>  case, I ran into 2a) "The modified work must itself be a software
>  library.", which the apidocs are not.
>  
>  So, I'm not even convinced anyone aside from the copyright holders
>  actually has permission to redistribute the apidocs (as a "modified
>  work" of the LGPLv2 kdelibs). Just trying to figure out a way for this
>  to work under the LGPLv2 is giving me a migraine. 
But the LGPL allows converting to the GPL which does not have this
limitation, and in fact the FSF lists the GPL as a license which can be
applied to documentation, though it doesn't encourage that practice.

(In fact, I think that sentence is intended to make non-library uses of LGPL 
code always use GPL terms.)

I don't see how building this documentation as binaries from the LGPLed or 
GPLed source code is in any way a violation of the licenses. If the code 
files as a whole can be distributed (L)GPL, extracting the documentation 
portions from it is explicitly allowed by the GPL (and the LGPL allows 
converting to the GPL).

>  The simplest way to fix this would be to amend the kdelibs license
> to
>  say something like:
>  
>  As an exception to the LGPL, documentation generated from this
>  library for the purposes of documenting the API of this library is
>  licensed under the terms of the *INSERT_YOUR_DOC_LICENSE_HERE*. 
I don't think upstream can realistically change the license. There are 
dozens of contributors who all hold copyright.

        Kevin Kofler

[Tom Callaway]

On 01/27/2012 05:06 PM, Kevin Kofler wrote:

>  But the LGPL allows converting to the GPL which does not have this
>  limitation, and in fact the FSF lists the GPL as a license which can be
>  applied to documentation, though it doesn't encourage that practice. 
So, this is correct, and it does work past the problem of the LGPLv2 not
being a valid documentation license. If you convert the license on
kdelibs to GPL, then make the apidocs, then the apidocs are under the
terms of either GPLv2 or GPLv3, depending on which is specified by the
person implementing that change (doesn't have to be the copyright
holder, a distributor could do this as well).

So, in this case, we have to comply with the GPL's terms, which means
you have to do one of the following:

A) Accompany it with the complete corresponding machine-readable source
code [...]

B) Accompany it with a written offer, valid for at least three years, to
give any third party, for a charge no more than your cost of physically
performing source distribution, a complete machine-readable copy of the
corresponding source code [...]

C) Accompany it with the information you received as to the offer to
distribute corresponding source code.

Note that all options refer to "corresponding source code", which means
"the source code used to make the binary", and in the context of the
apidocs, the matching kdelibs library code.

So, from a purely license compliance perspective, shipping the apidocs
without the matching sources in Fedora is a no-go. It's also a no-go
from a "everything must be built from source" rule.

> > The simplest way to fix this would be to amend the kdelibs
> license to
> > say something like:
> >
> > As an exception to the LGPL, documentation generated from this
> > library for the purposes of documenting the API of this library is
> > licensed under the terms of the *INSERT_YOUR_DOC_LICENSE_HERE*.
>  
>  I don't think upstream can realistically change the license. There are 
>  dozens of contributors who all hold copyright. 
Difficult, perhaps, but not impossible.

~tom

==
Fedora Project

[Kevin Kofler]

Tom Callaway wrote:
>  So, from a purely license compliance perspective, shipping the
> apidocs
>  without the matching sources in Fedora is a no-go. It's also a no-go
>  from a "everything must be built from source" rule. 
That (both parts) is what I already told Rex, too, he just wouldn't believe 
me. ;-)

Our current approach of building kdelibs-apidocs as a subpackage of kdelibs 
looks compliant to me though, isn't it?

        Kevin Kofler

[Tom Callaway]

On 01/31/2012 04:57 PM, Kevin Kofler wrote:
>  Tom Callaway wrote:
> > So, from a purely license compliance perspective, shipping the apidocs
> > without the matching sources in Fedora is a no-go. It's also a no-go
> > from a "everything must be built from source" rule.
>  
>  That (both parts) is what I already told Rex, too, he just wouldn't believe 
>  me. ;-)
>  
>  Our current approach of building kdelibs-apidocs as a subpackage of kdelibs 
>  looks compliant to me though, isn't it? 
Yes, but I circle back to the original question I posed:

Is this package really valuable?
Does anyone really want 235MB of apidocs, especially given the legal
complexity/concerns, and the availability of these docs on the kde.org
website?

~tom

==
Fedora Project

[Josh Boyer]

On Thu, Jan 26, 2012 at 4:40 PM, Tom Callaway <tcallawa(a)redhat.com&gt; wrote:
>  On 01/26/2012 03:30 PM, Rex Dieter wrote:
> > For reference,
> > 235M kdelibs-apidocs-4.7.4-1.fc16.noarch.rpm
>
>  Maybe this is a silly question, but is this package really valuable?
>  Does anyone really want 235MB of apidocs, especially given the legal
>  complexity/concerns, and the availability of these docs on the kde.org
>  website?
>
>  Perhaps killing this subpackage off entirely is a clever way of avoiding
>  this situation. 
Honestly, that sounds really desirable overall.  Rex, you kinda skipped this
part in your reply.

josh