GFDL/GPL Issue

GFDL/GPL Issue

[Mark Mitchell]

As I mentioned last week, I've been talking to the SC and RMS about the
issue of automatically generating GFDL'd documentation from GPL'd code.

I will state explicitly up front a few topics I am not raising, because
I do not think they are either necessary, or likely to be productive:

* Whether or not the GFDL is a "free" license, or whether it's a good
license, or anything else about its merits or lack thereof

* Whether we can take things out of the current GFDL manuals and put
them into GPL'd code

The first is immaterial from the limited perspective of trying to figure
out how to make it possible for us to make better (in terms of content)
manuals more easily.  The second issue *is* relevant, in that we might
want to bring some of what's currently in manuals into the code, but I
think it's less important than the question of whether we can
auto-generate manuals from code on a going-forwards basis.  And, it's
simpler to work on one thing at a time.

At this point, RMS has said, answered this question from me:

"Can we take comments (not code) from FSF-owned GPL'd code and process
them in some way that results in them being included in a GFDL'd manual?"

by saying, in part:

"If Texinfo text is included the .h files specifically to be copied into
a manual, it is ok to for you copy that text into a manual and release
the manual under the GFDL."

In context, "you" means "the GCC maintainers" and the permission would
be limited only to changes contributed to the FSF.  This is specifically
not permission for random people to do even this outside the context of
the FSF repository.  RMS acknowledges that this is a problem, but he
says (and I agree) that we would need a GPL license exception to make
this a fully general permission, and he says that will take a long time.

This limited permission might be enough to solve some problems.  For
example, we could write TeXinfo in special comments for hooks, and have
some script that pulled out the comments and generated a TeXinfo
document listing all the hooks.  But, it doesn't help with things more
like Javadoc or Doxygen or Synopsis.  (Disclosure: Stefan Seefeld, one
of my fellow Sourcerers is the lead author of Synopsis.)  These tools
can parse the code, creating cross-references of various kinds, while
also extracting documentation intended for users of the API.

So, my question is this: is the permission above sufficient for what
people want to do at this point?  Or do we need more?  And if we need
more (as I suspect), can we be specific about what toolflow we want to
follow and what content will be generated?  It would help if I could
show RMS inputs and outputs, not just with some random example, but with
GCC itself.  Is someone willing to apply enough effort to produce at
least some fragments of documentation using some method, and document
that method for me, so that I can provide it to RMS.

(An obvious strategy generate these manuals under the GPL, rather than
the GFDL, thereby dodging the issue.  But, RMS does not want GCC having
GPL'd manuals.  Maybe if we show him what we want to do, he will
conclude that GPL'd manuals are an acceptable outcome, and easier than
trying to do license exceptions.)

Thanks,

-- 
Mark Mitchell
CodeSourcery
mark@codesourcery.com
(650) 331-3385 x713

Re: GFDL/GPL Issue

[Joern Rennecke]

Quoting Mark Mitchell <mark@codesourcery.com>:

> At this point, RMS has said, answered this question from me:
>
> "Can we take comments (not code) from FSF-owned GPL'd code and process
> them in some way that results in them being included in a GFDL'd manual?"

We also need struct member declarations.
I.e type and name.  In the case of function members - as is common with
hooks - that includes return type and the types of all arguments; moreover,
we also want the names of the function arguments.
As we move to C++, that might morph to class members / member functions.

> So, my question is this: is the permission above sufficient for what
> people want to do at this point?  Or do we need more?  And if we need
> more (as I suspect), can we be specific about what toolflow we want to
> follow and what content will be generated?  It would help if I could
> show RMS inputs and outputs, not just with some random example, but with
> GCC itself.  Is someone willing to apply enough effort to produce at
> least some fragments of documentation using some method, and document
> that method for me, so that I can provide it to RMS.

See:
http://gcc.gnu.org/ml/gcc-patches/2010-05/msg02255.html

Search for GPL and/or GFDL for a sample of things that we currently
can't fix due to licensing issues.

Re: GFDL/GPL Issue

[Mark Mitchell]

Joern Rennecke wrote:

>> And if we need
>> more (as I suspect), can we be specific about what toolflow we want to
>> follow and what content will be generated?  It would help if I could
>> show RMS inputs and outputs, not just with some random example, but with
>> GCC itself.  Is someone willing to apply enough effort to produce at
>> least some fragments of documentation using some method, and document
>> that method for me, so that I can provide it to RMS.
> 
> See:
> http://gcc.gnu.org/ml/gcc-patches/2010-05/msg02255.html

OK, I see what that is doing.  Why did you choose to use a .def file
rather than something more like Doxygen to generate the documentation?
Consistency with existing practice of .def files in GCC?  Or you don't
like Doxygen-like tools?  Or something else?  (I'm not making a judgment
here, but I need to understand why so that I can explain things to RMS.)

> Search for GPL and/or GFDL for a sample of things that we currently
> can't fix due to licensing issues.

I'm happy to act as an advocate, but I don't have the time to do a lot
of research.  Would you please describe the steps and provide the inputs
and outputs of the process for some of these issues?  I want to able to
show RMS an actual input file, an actual output file, and describe the
transformation process that leads from one to the other.

Thanks,

-- 
Mark Mitchell
CodeSourcery
mark@codesourcery.com
(650) 331-3385 x713

Re: GFDL/GPL Issue

[DJ Delorie]

Mark Mitchell <mark@codesourcery.com> writes:
> So, my question is this: is the permission above sufficient for what
> people want to do at this point?

This permission exactly covers what libiberty does for its
documentation, you can use that as an example to RMS.

Re: GFDL/GPL Issue

[Joern Rennecke]

Quoting Mark Mitchell <mark@codesourcery.com>:

>> http://gcc.gnu.org/ml/gcc-patches/2010-05/msg02255.html
>
> OK, I see what that is doing.  Why did you choose to use a .def file
> rather than something more like Doxygen to generate the documentation?

It is not only used to generate documenation, but also to generate
initializers for all the struct gcc_target members.  While at the same
time serving as an include file for target.h .

Also, the documentation generation allows the generation of @findex
statements by using @fcode instaed of @code, and places these @findex  
statements at the start of the enclosing paragraph; however, this part  
is
not really introducing any extra licensing issues, and describing the
operation in detail would probably be distracting.

>> Search for GPL and/or GFDL for a sample of things that we currently
>> can't fix due to licensing issues.
>
> I'm happy to act as an advocate, but I don't have the time to do a lot
> of research.  Would you please describe the steps and provide the inputs
> and outputs of the process for some of these issues?

For a typical hook member, we got the following macro:

DEFHOOK(NAME, DOC, TYPE, PARAMS, INIT)

TYPE and PARAMS is wrapped in @var as appropriate and prepended /  
appended to the capitalized NAME to give the target hook signature in  
the documentation.
Also, NAME usually gets prepended with a prefix; the current prefix is  
specified in separate macro in target.def.

E.g.:

DEFHOOK
(adjust_cost_2,
  "Given the current cost, @var{cost}, of an insn, @var{insn}, calculate and\
  return a new cost based on its relationship to @var{dep_insn} through the\
  dependence of weakness @var{dw}.  The default is to make no adjustment.",
  int, (rtx insn, int dep_type1, rtx dep_insn, int cost, int dw), NULL)

Gives:

@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST_2 (rtx  
@var{insn}, int @var{dep_type1}, rtx @var{dep_insn}, int @var{cost},  
int @var{dw})
Given the current cost, @var{cost}, of an insn, @var{insn}, calculate  
and return a new cost based on its relationship to @var{dep_insn}  
through the dependence of weakness @var{dw}.  The default is to make  
no adjustment.
@end deftypefn

Because of licensing issues, my patch so far uses DEFHOOK_UNDOC for  
adjust_cost_2 instead, so that the hook remains undocumented.

>  I want to able to
> show RMS an actual input file, an actual output file, and describe the
> transformation process that leads from one to the other.

target.def is a GPLed input file, and tm.texi.in is a GFDLed input file.
tm.texi is the GFDLed output file.

If you like, I can send you the complete files in non-patch form.

Re: GFDL/GPL Issue

[Dave Korn]

On 02/06/2010 00:31, Mark Mitchell wrote:

> At this point, RMS has said, answered this question from me:
> 
> "Can we take comments (not code) from FSF-owned GPL'd code and process
> them in some way that results in them being included in a GFDL'd manual?"
> 
> by saying, in part:
> 
> "If Texinfo text is included the .h files specifically to be copied into
> a manual, it is ok to for you copy that text into a manual and release
> the manual under the GFDL."
> 
> In context, "you" means "the GCC maintainers" and the permission would
> be limited only to changes contributed to the FSF.  This is specifically
> not permission for random people to do even this outside the context of
> the FSF repository.

  So to be clear: would redistributors be in breach if they were to ship the
generated docs in their binary packages?

    cheers,
      DaveK

Re: GFDL/GPL Issue

[Matthias Klose]

On 02.06.2010 01:31, Mark Mitchell wrote:
> I will state explicitly up front a few topics I am not raising, because
> I do not think they are either necessary, or likely to be productive:
>
> * Whether or not the GFDL is a "free" license, or whether it's a good
> license, or anything else about its merits or lack thereof

Maybe, but GFDL is not GFDL.  Please could you clarify if such documentation is 
licensed under a GFDL with frontcover/backcover texts and/or invariant sections? 
  Would any of these clauses even make sense for this kind of documentation?

   Matthias

Re: GFDL/GPL Issue

[Mark Mitchell]

Dave Korn wrote:

>> "If Texinfo text is included the .h files specifically to be copied into
>> a manual, it is ok to for you copy that text into a manual and release
>> the manual under the GFDL."
>>
>> In context, "you" means "the GCC maintainers" and the permission would
>> be limited only to changes contributed to the FSF.  This is specifically
>> not permission for random people to do even this outside the context of
>> the FSF repository.
> 
>   So to be clear: would redistributors be in breach if they were to ship the
> generated docs in their binary packages?

No, not if they ship the docs unmodified from the version from the FSF.
 They would also not be in breach if they themselves added some new text
and regenerated the docs, since they can license their changes as they
see fit (provided, of course, that's compatible with the GPL and GFDL).

However, if I changed the code, but did not regenerate the docs, and you
then picked up my changes, possibly made more of your own, and then
regenerated the docs, *you* would be in breach.  (Because my changes are
only available to you under the GPL; you do not have the right to
relicense my changes under the GFDL.)

I find that consequence undesirable.  In particular, what I did is OK in
that scenario, but suddenly, now, you, are a possibly unwitting
violator.  (Yes, I have confirmed the above interpretation is correct
directly with RMS.)

Because this scheme depends not on a general license exception, but
rather on particular power that the FSF has by virtue of owning the
code, the ultimate downstream recipient cannot be guaranteed that they
can rebuild the documentation.

-- 
Mark Mitchell
CodeSourcery
mark@codesourcery.com
(650) 331-3385 x713

Re: GFDL/GPL Issue

[Richard Kenner]

> However, if I changed the code, but did not regenerate the docs, and you
> then picked up my changes, possibly made more of your own, and then
> regenerated the docs, *you* would be in breach.  (Because my changes are
> only available to you under the GPL; you do not have the right to
> relicense my changes under the GFDL.)

Just to be clear, I don't believe that regenerating the docs itself would
be a breach since NOTHING you do internally can be a GPL or GFDL breach).
What would be a breach would be *distributing* those regenerated docs.

Re: GFDL/GPL Issue

[Mark Mitchell]

Richard Kenner wrote:

>> However, if I changed the code, but did not regenerate the docs, and you
>> then picked up my changes, possibly made more of your own, and then
>> regenerated the docs, *you* would be in breach.  (Because my changes are
>> only available to you under the GPL; you do not have the right to
>> relicense my changes under the GFDL.)
> 
> Just to be clear, I don't believe that regenerating the docs itself would
> be a breach since NOTHING you do internally can be a GPL or GFDL breach).
> What would be a breach would be *distributing* those regenerated docs.

Indeed; I was too casual in my description.  Dave can regenerate the
docs, and even pass them around his company, but he can't distribute them.

-- 
Mark Mitchell
CodeSourcery
mark@codesourcery.com
(650) 331-3385 x713

Re: GFDL/GPL Issue

[Mark Mitchell]

Matthias Klose wrote:

>> I will state explicitly up front a few topics I am not raising, because
>> I do not think they are either necessary, or likely to be productive:
>>
>> * Whether or not the GFDL is a "free" license, or whether it's a good
>> license, or anything else about its merits or lack thereof
> 
> Maybe, but GFDL is not GFDL.  Please could you clarify if such
> documentation is licensed under a GFDL with frontcover/backcover texts
> and/or invariant sections? 

GCC's current documentation does have some of these things on at least
some manuals.

> Would any of these clauses even make sense
> for this kind of documentation?

To the extent that we'd be auto-generating parts of existing manuals, I
think such sections make as much sense as they do now.  For example,
were we to auto-generate a list of command-line options for the main GCC
manual, replacing the current hand-generated list, there would be no
reason to change any of the invariant sections, etc.

For API documentation, or, in general, for new manuals, I have no
opinion.  My guess, though, is that the FSF would want the same
invariant sections and such as are on the existing manuals.

(If it were up to me, manuals would just be GPL, whether or not that's a
great license for documentation.  But, it's not up to me.)

-- 
Mark Mitchell
CodeSourcery
mark@codesourcery.com
(650) 331-3385 x713

Re: GFDL/GPL Issue

[Dave Korn]

On 02/06/2010 15:07, Mark Mitchell wrote:
> Richard Kenner wrote:
> 
>>> However, if I changed the code, but did not regenerate the docs, and you
>>> then picked up my changes, possibly made more of your own, and then
>>> regenerated the docs, *you* would be in breach.  (Because my changes are
>>> only available to you under the GPL; you do not have the right to
>>> relicense my changes under the GFDL.)
>> Just to be clear, I don't believe that regenerating the docs itself would
>> be a breach since NOTHING you do internally can be a GPL or GFDL breach).
>> What would be a breach would be *distributing* those regenerated docs.
> 
> Indeed; I was too casual in my description.  Dave can regenerate the
> docs, and even pass them around his company, but he can't distribute them.

  (Indeed, that's why I asked specifically "would redistributors be in breach".)

  Well, I can't say I like this idea.  The whole scheme seems laden with
unforeseen potential booby-traps.  And this is just for the simple case where
we're only doing verbatim copying of texinfo chunks from the source files to
the manual, it doesn't even let us use any kind of advanced generator or
processing en route (let alone something like doxygen).  I'm not sure how
intrinsically worthwhile scattering the docs into fragments all through the
source is in the first place, and with these proposed limitations it seems
pretty pointless to me.  I'd rather stick with just manually writing texinfo
chunks direct into a documentation-specific texinfo source file.

    cheers,
      DaveK

Re: GFDL/GPL Issue

[Mark Mitchell]

Dave Korn wrote:

>>> Just to be clear, I don't believe that regenerating the docs itself would
>>> be a breach since NOTHING you do internally can be a GPL or GFDL breach).
>>> What would be a breach would be *distributing* those regenerated docs.

>> Indeed; I was too casual in my description.  Dave can regenerate the
>> docs, and even pass them around his company, but he can't distribute them.

>   Well, I can't say I like this idea.  The whole scheme seems laden with
> unforeseen potential booby-traps.

I agree.  However, to convince RMS that this isn't sufficient, I need to
explain this is in a way that shows that this "solution" is a problem
*for the FSF*.

(The fact that the FSF has special superpowers that other parties don't
isn't something the FSF considers a problem; the FSF wants people to
assign code to them in part precisely so that it can change the licenses
at will.  I think RMS does recognize that this issue for distributors is
a problem in this situation, though.  He also doesn't feel that he can
get a license exception very quickly, though, if at all.)

-- 
Mark Mitchell
CodeSourcery
mark@codesourcery.com
(650) 331-3385 x713

Re: GFDL/GPL Issue

[Joseph S. Myers]

On Wed, 2 Jun 2010, Mark Mitchell wrote:

> For API documentation, or, in general, for new manuals, I have no
> opinion.  My guess, though, is that the FSF would want the same
> invariant sections and such as are on the existing manuals.

The standard rules for Cover Texts and inclusion of Invariant Sections (at 
least as regards inclusion of the GPL in manuals) are 
<http://www.gnu.org/prep/maintain/html_node/License-Notices-for-Documentation.html>.  
There are various ways in which the GCC manuals do not follow this (e.g. 
having Cover Texts on manuals the FSF does not print that are only meant 
to be on printed manuals, or including the GPL in manuals under 400 
pages).  But getting approval to fix those issues might also require 
adding the "Free Software and Free Manuals" invariant section (see 
comments in PR 13573), which in general those who don't like invariant 
sections aren't going to like.

-- 
Joseph S. Myers
joseph@codesourcery.com