GFDL/GPL issues

GFDL/GPL issues

[Mark Mitchell]

In a biweekly call with the other GCC Release Managers, I was asked
today on the status of the SC/FSF discussions re. GFDL/GPL issues.  In
particular, the question of whether or not we can use "literate
programming" techniques to extract documentation from code and take bits
of what is currently in GCC manuals and put that into comments in code
and so forth and so on.

I have raised this issue directly with RMS, with a copy to the GCC SC.
I will report any significant changes in status here.  If I don't report
anything, then it's probably because there's nothing to report.  It's
typical for these kinds of license issues to take a long time (months,
or even years) to be resolved -- unless the FSF decides very quickly
that it will not grant whatever request it is that we are making.

Therefore, if I don't have an update "soon" (within a week or two), I'd
suggest that we operate under the assumption that it will not be
possible to combine GFDL manuals and GPL code in the near future.

Thanks,

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

Re: GFDL/GPL issues

[Basile Starynkevitch]

On Tue, 2010-05-25 at 17:44 -0700, Mark Mitchell wrote:
> In a biweekly call with the other GCC Release Managers, I was asked
> today on the status of the SC/FSF discussions re. GFDL/GPL issues.  In
> particular, the question of whether or not we can use "literate
> programming" techniques to extract documentation from code and take bits
> of what is currently in GCC manuals and put that into comments in code
> and so forth and so on.
[...]
> 
> Therefore, if I don't have an update "soon" (within a week or two), I'd
> suggest that we operate under the assumption that it will not be
> possible to combine GFDL manuals and GPL code in the near future.

I am already doing that within the GCC MELT branch. Detailed
explanations have been given in my email of May 7th
http://gcc.gnu.org/ml/gcc/2010-05/msg00125.html

To be more precise

* all the MELT documentation have been written only by me (Basile).

* There is a chapter melt.texi devoted to MELT. It is hand written.

* The MELT infrastructure provides a syntax (:doc annotation) to add
documentation into definitions (of MELT functions, classes, primitives,
matchers, ...). The MELT infrastructure also provides a mode (a way of
running GCC MELT) to generate this documentation (from gcc/melt/*melt
source files) as a meltgendoc.texi in the build dir. So this generated
doc is another chapter of the documentation: gccint.texi has both
@include melt.texi & @include meltgendoc.texi

Actually, I believe that for MELT as a gcc-4.5 plugin, the two files
melt.texi (handwritten) & meltgendoc.texi (generated from *.melt source
files) constitute the documentation.

So what should I do?

a. ignore Mark Mitchell suggestion since GCC MELT is a branch, not the
official trunk.

b. scrap all the documentation & the documentation generator. This is
not good news - even if the documentation is incomplete, I did put a lot
of efforts inside... And MELT cannot be used without any documentation
(and this documentation, even imperfect & incomplete, is the best I have
today)

c. change the licenses of the melt*texi files [I certainly won't do that
without explicit approval] to something compatible. Perhaps the fact
that I am the only contributor to these files might help.

BTW, I intend to make a first release of MELT as a plugin in a few
weeks, not in a few years. This mostly means for me publishing the .tgz
file of all the MELT files as collected by the existing
contrib/make-melt-source-tar.sh script.

Cheers.




-- 
Basile STARYNKEVITCH         http://starynkevitch.net/Basile/
email: basile<at>starynkevitch<dot>net mobile: +33 6 8501 2359
8, rue de la Faiencerie, 92340 Bourg La Reine, France
*** opinions {are only mines, sont seulement les miennes} ***

Re: GFDL/GPL issues

[Joern Rennecke]

Quoting Mark Mitchell <mark@codesourcery.com>:

> Therefore, if I don't have an update "soon" (within a week or two), I'd
> suggest that we operate under the assumption that it will not be
> possible to combine GFDL manuals and GPL code in the near future.

We still can, to some degree, as long as we make sure that the
source code is GPL (generating GPLed code from GFDL source is not
compatible with the GPL provision of distributing the source under
the GPL), and that all patches include GPLed source and GFDLed
documentation from the start.
I.e. the original contributor grants GPL license to the source and
GFDL license to the generated documentation, and then with the
contribution the assignment to the FSF somes into effect.
What we can't do under this scheme is retroactively re-use code
as documentation or vice versa; we'd need the appropriate license
grant from the FSF for each bit of code/documentation that we want
to re-use in that manner.
Which should be even more motivation to get the initial licenses
right.

In this spirit, my patch:
http://gcc.gnu.org/ml/gcc-patches/2010-05/msg00788.html
should help to keep target hook code and documentation in
lock-step and properly licensed in the future, even though it
can't fix any of the pre-existing issues.

It's slightly out-of-date because three more changes have been
made to the target hooks in the meantime, two of which have introduced
new code/documentation inconsistencies; I'll post an updated patch
shortly after verifying regression test results.  However, it's
just mechanical changes where the new code / documentation bits
are added into the appropriate places.

Re: GFDL/GPL issues

[Frank Ch. Eigler]

Basile Starynkevitch <basile@starynkevitch.net> writes:

> [...]
> So what should I do?
> [...]
> c. change the licenses of the melt*texi files [I certainly won't do that
> without explicit approval] to something compatible. Perhaps the fact
> that I am the only contributor to these files might help.

Would dual-licensing the .texi files (GFDL + GPL3) solve these problems?


- FChE

Re: GFDL/GPL issues

[Mark Mitchell]

Frank Ch. Eigler wrote:

>> c. change the licenses of the melt*texi files [I certainly won't do that
>> without explicit approval] to something compatible. Perhaps the fact
>> that I am the only contributor to these files might help.
> 
> Would dual-licensing the .texi files (GFDL + GPL3) solve these problems?

Presumably so, but we cannot unilaterally do that with source code that
has been assigned to the FSF.  The FSF assignment agreement generally
allows the original contributor to relicense his/her own work under
different terms, so Basile could (if he is the sole contributor)
dual-license the MELT .texi documentation -- but it's not clear to me
that this permits us to then take advantage of that in the context of
FSF GCC.

In the context of FSF GCC, there is both a legal question and a policy
question; even if we can do it legally, is that what the FSF wants?
That last consideration, of course, does not apply to not-FSF GCC, e.g.,
 to a release that Basile does himself.

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

Re: GFDL/GPL issues

[Joern Rennecke]

Quoting "Frank Ch. Eigler" <fche@redhat.com>:

>
> Basile Starynkevitch <basile@starynkevitch.net> writes:
>
>> [...]
>> So what should I do?
>> [...]
>> c. change the licenses of the melt*texi files [I certainly won't do that
>> without explicit approval] to something compatible. Perhaps the fact
>> that I am the only contributor to these files might help.
>
> Would dual-licensing the .texi files (GFDL + GPL3) solve these problems?

Are you talking about the melt .texi files or the general GCC and texinfo
infrastructure texi files?  Unless you dual-license the latter, all
.texi files that use them must be GFDL.  I.e. if you autogenerate .texi files
from melt source files, these source files would have to have a
GFDL-compatible license, or you have to distribute & check-in the generated
.texi files under the GFDL together with the GPLed sources.

Re: GFDL/GPL issues

[Basile Starynkevitch]

On Wed, 2010-05-26 at 11:36 -0400, Frank Ch. Eigler wrote:
> Basile Starynkevitch <basile@starynkevitch.net> writes:
> 
> > [...]
> > So what should I do?
> > [...]
> > c. change the licenses of the melt*texi files [I certainly won't do that
> > without explicit approval] to something compatible. Perhaps the fact
> > that I am the only contributor to these files might help.
> 
> Would dual-licensing the .texi files (GFDL + GPL3) solve these problems?


Maybe (but one of them is generated from *.melt source files), but I
have absolutely no idea of who can permit me to change the licenses of
the files. In my understanding, their copyright belongs to FSF (not to
my employer CEA or me), and I would imagine that getting the FSF to
accept such a license change might be as difficult and as long-lasting
as having FSF solve the "global" issue.

Besides, GCC MELT is a branch that I would imagine is not the prime
interest of the FSF. To be more rude, I am probably the only one who
really cares about that branch, and I have no influence on the FSF.

My dream [I'm not sure it can happen] would be that some GCC steering
committee member would just say here to me that dual-licensing such and
such files is permitted and would solve any issue. If I had such a
informal "blessing" I would be ok.

Cheers.

-- 
Basile STARYNKEVITCH         http://starynkevitch.net/Basile/
email: basile<at>starynkevitch<dot>net mobile: +33 6 8501 2359
8, rue de la Faiencerie, 92340 Bourg La Reine, France
*** opinions {are only mines, sont seulement les miennes} ***

Re: GFDL/GPL issues

[Basile Starynkevitch]

On Wed, 2010-05-26 at 08:56 -0700, Mark Mitchell wrote:
> 
> In the context of FSF GCC, there is both a legal question and a policy
> question; even if we can do it legally, is that what the FSF wants?

Does the FSF want anything about GCC? AFAIK, the plugin exception to the
runtime license was not wanted by the FSF. It was only wanted by the GCC
community (and probably the FSF was reluctant to any changes). 

> That last consideration, of course, does not apply to not-FSF GCC, e.g.,
>  to a release that Basile does himself.

So what should I do concretely? What is the current status of the pdf
file generated inside GCC MELT, an old version of which is on
http://gcc.gnu.org/wiki/MELT%
20tutorial?action=AttachFile&do=view&target=GCC-MELT--gcc-internals-snapshot.pdf
Is it completely illegal? 

Does that means that the only time when such a file could be
redistributed is in a couple of years (2012, 2015?) [*] when at long
last the FSF will have make an official change in some license or
exception?

Does that mean that even if a MELT plugin package appears in Debian, it
could not contain any documentation? Or is there a mean (e.g. splitting
the chapters of the documentation...) to avoid such trouble...


Note [*]: I am quite pessimistic in the actual delay for an FSF official
decision. I remember too well how long it took to have a runtime license
compatible with plugins (even after it was drafted, it took much more
time than anyone expected). And no, I cannot fund American lawyers to
help (except at most by a *personal* donation of a few dozens euros,
which won't help at all; I imagine that american lawyers cost nearly a
million euros; any amount I could personally give is totally
insignificant.).


Any concrete & practical advice is welcome.

Cheers.
-- 
Basile STARYNKEVITCH         http://starynkevitch.net/Basile/
email: basile<at>starynkevitch<dot>net mobile: +33 6 8501 2359
8, rue de la Faiencerie, 92340 Bourg La Reine, France
*** opinions {are only mines, sont seulement les miennes} ***

Re: GFDL/GPL issues

[Mark Mitchell]

Basile Starynkevitch wrote:

> My dream [I'm not sure it can happen] would be that some GCC steering
> committee member would just say here to me that dual-licensing such and
> such files is permitted and would solve any issue. If I had such a
> informal "blessing" I would be ok.

The SC cannot do that in the context of FSF GCC, and, of course, the SC
has no control of any other GCC.  This is the downside of copyright
assignment; it gives the FSF a lot control over licensing issues.  If
you don't want to give the FSF that control, you can't assign copyright
to the FSF.  But, that also means you can't contribute to FSF GCC.

Of course, in the context of plug-ins, you'd have more options, in that
you could develop and independently distribute a plug-in where you had
more control of licensing.  The plug-in would have to be
GPLv3-compatible, but you'd be able to dual-license the code in the
plug-in if you chose to do that.

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

Re: GFDL/GPL issues

[Richard Kenner]

> Does the FSF want anything about GCC? AFAIK, the plugin exception to the
> runtime license was not wanted by the FSF. It was only wanted by the GCC
> community (and probably the FSF was reluctant to any changes). 

For good reason.  Check out the mess that results from allowing plugins
in the Asterisk system: it makes many of the advantages of it being
Free Software go away.

Minor technical advantages shouldn't have been enough to create that
situation.  I hope it never happens to GCC, but I'm not optimistic.

Re: GFDL/GPL issues

[Mark Mitchell]

Basile Starynkevitch wrote:

> Does the FSF want anything about GCC? AFAIK, the plugin exception to the
> runtime license was not wanted by the FSF. It was only wanted by the GCC
> community (and probably the FSF was reluctant to any changes). 

I don't speak for the FSF.  I don't know what the FSF wants, other than
what it's said in public.

> So what should I do concretely? What is the current status of the pdf
> file generated inside GCC MELT, an old version of which is on
> http://gcc.gnu.org/wiki/MELT%
> 20tutorial?action=AttachFile&do=view&target=GCC-MELT--gcc-internals-snapshot.pdf
> Is it completely illegal? 

I don't know.  I don't know enough about Melt to give an answer, even an
informal one.  (And I'm not a lawyer, so I certainly couldn't give you
good legal advice.)

> Does that mean that even if a MELT plugin package appears in Debian, it
> could not contain any documentation?

I thought Debian didn't like the GFDL at all.  But, in any case, that's
really a question for the Debian folks; I don't have any involvement in
Debian.

As for practical advice regarding getting quicker decisions from the FSF
on licensing issues, I have none.  I've worked on several such issues
with the FSF over the years, and they've all been lengthy processes.  If
I knew how to do it faster, I certainly would.  The best way to work
with the FSF on license issues is always to explain how whatever request
you are making furthers the FSF's goals.

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

Re: GFDL/GPL issues

[Joern Rennecke]

Quoting Basile Starynkevitch <basile@starynkevitch.net>:

> So what should I do concretely? What is the current status of the pdf
> file generated inside GCC MELT, an old version of which is on
> http://gcc.gnu.org/wiki/MELT%
> 20tutorial?action=AttachFile&do=view&target=GCC-MELT--gcc-internals-snapshot.pdf
> Is it completely illegal?
>
> Does that means that the only time when such a file could be
> redistributed is in a couple of years (2012, 2015?) [*] when at long
> last the FSF will have make an official change in some license or
> exception?

IIRC, when you do a Copyright Assignment to the FSF, you get the right
granted back to use the code you contributed in other projects, subject
to some notice  period (3 weeks?).
You best check your assignment confirmation papers.

So I would suggest that you inform the FSF that you want to use the
MELT code that you contributed previously (to the GCC project)
for the project 'MELT documentation';
wait for the notice period to pass, and then AFAIU you are free to
use your MELT code under a different License, like the GFDL.
(Ask a lawyer if there is any doubt.)
To assure users that they may use the documentation, you then have to
actually grant a GFDL license to the documentation.
E.g. you could include the auto-generated documentation with GFDL
license in your branchand/or release.  Of course you'd have to make
sure that you don't drag in copyrightable material for which you
don't have GFDL rights (e.g. pieces of GPL-only code from GCC proper).

Re: GFDL/GPL issues

[Basile Starynkevitch]

On Wed, 2010-05-26 at 11:19 -0700, Mark Mitchell wrote:
> 
> As for practical advice regarding getting quicker decisions from the FSF
> on licensing issues, I have none.  I've worked on several such issues
> with the FSF over the years, and they've all been lengthy processes.  If
> I knew how to do it faster, I certainly would.  The best way to work
> with the FSF on license issues is always to explain how whatever request
> you are making furthers the FSF's goals.

[not being a native english speaker, I had lots of trouble understanding
the last sentence above; apparently, according to my Robert&Collins
english<->french dictionnary applied twice, "to further" means "to
favour" in that context; is that understanding the right one?].

First, I have no idea of who the FSF really means (except RMS). Who
should I contact by email? What should I tell? What do I risk? What are
the *technical* background I can assume? Do FSF people know what coding
is about? (RMS certainly does, but is he most of FSF?).

Second, I believe I tried hard to explain what MELT is doing w.r.t.
documentation in an email (dated May 07th)
http://gcc.gnu.org/ml/gcc/2010-05/msg00125.html to which *nobody*
responded. Or was gcc@ the wrong list to ask?

Are there any reason for which I should expect more attention now? I
don't understand why a question nobody cared about on May 7th should
become interesting on May 27th of the same year (2010).

And all this is not really MELT related, and perhaps even not even GCC
related. Several GNU projects (notably GTK) generates documentation from
code. Not understanding at all any internal (& personal) factors from my
far continent (I am European, and I am not a lawyer!), I cannot imagine
why any "policy" defined for GTK would not be ok for GCC? Or are not all
GNU projects equal? Is GTK less important to the FSF than GCC? Or maybe
GTK is not an FSF project, (this implying that GNU software is not FSF
software)? Or are there still no FSF copyrighted software generating
some small documentation from code! (we are in 2010, and it is common
practice; I could imagine that bash or binutils have similar issues.).
And for GTK at least, the header files only mention LGPL license, and
apparently not any additional exception related to documentation...

And there is one even more basic thing I don't understand. Why are GFDL
& GPL incompatible? Apparently, both allow at least redistribution,
under the same license, of human written textual material -documentation
for GFDL, & source code for GPL- (the GPL probably allows more, like
compilation of a source code & some use of the resultant binary). Why
the probably non-empty intersection of rights (probably the right to
read textual material & to redistribute it verbatim at least) is not
usable?

Also, some official GCC documentation contains substantial chunks of
code (e.g. plugins.texi). Does that mere fact legally invalidate
something?

In practice, should I have to erase all the :doc annotations in MELT
source code? I would be very sad to do that. And even if I did that, I
am not sure to be able to claim that these :doc annotations never
existed (they did). I am not willing to falsely (= lyingly) claim that I
never wrote these :doc annotations. I did wrote them and I don't want to
deny that I did wrote them.

The most important for me is that MELT continues to be a GCC branch. If
I have to reduce or remove the documentation & comments inside the MELT
code for that, I probably would accept that (with great sadness). But
removing explanations -addressed to human readers- from inside source
code is in my naive technical view against the goals of free software.

Cheers.

Re: GFDL/GPL issues

[Mark Mitchell]

Basile Starynkevitch wrote:

>> The best way to work
>> with the FSF on license issues is always to explain how whatever request
>> you are making furthers the FSF's goals.

> [not being a native english speaker, I had lots of trouble understanding
> the last sentence above; apparently, according to my Robert&Collins
> english<->french dictionnary applied twice, "to further" means "to
> favour" in that context; is that understanding the right one?].

I would that "to further" in this context means "to advance".  If you
show the FSF how some change will help the FSF achieve its goals, then
they will generally consider it.

> First, I have no idea of who the FSF really means (except RMS). 

Me neither.  I usually contact RMS directly because ultimately he seems
to make most of the decisions about these things, often after getting
input from the SFLC and probably other people I don't know about.

> Are there any reason for which I should expect more attention now? I
> don't understand why a question nobody cared about on May 7th should
> become interesting on May 27th of the same year (2010).

If you can't explain to the FSF why a license change will help the FSF
achieve its goals, I'd expect that your request will be ignored.  The
discussion I started with RMS at Joseph's behest was not about MELT.  It
was about the general issue of generating documentation from code.  I
wasn't aware it had anything to do with MELT.

> And there is one even more basic thing I don't understand. Why are GFDL
> & GPL incompatible? 

I suggest you search the internet for the answer; there's a lot of
discussion about this out there.

I don't understand the full situation with MELT.  But, you cannot
combine GPL'd and GFDL's stuff, so I don't think you can auto-generate
GFDL documentation from GPL'd code on the MELT branch.  You could
generate GPL'd documentation, though.

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

Re: GFDL/GPL issues

[Matthias Klose]

On 26.05.2010 02:44, Mark Mitchell wrote:
> In a biweekly call with the other GCC Release Managers, I was asked
> today on the status of the SC/FSF discussions re. GFDL/GPL issues.  In
> particular, the question of whether or not we can use "literate
> programming" techniques to extract documentation from code and take bits
> of what is currently in GCC manuals and put that into comments in code
> and so forth and so on.

there is another issue with the manual pages.  Debian considers GFDL licensed 
files with invariant sections and/or cover texts as non-free.  You may agree or 
disagree with this, but the outcome is that Debian has to ship the gcc 
documentation and the manual pages in its non-free section.  The issue was 
raised with the FSF some years ago, but issues with the GFDL seem to be low 
priority within the FSF (Mako may correct me).  It would be nice to know if the 
files used to generate the manual pages (gcc/doc/invoke.texi, 
gcc/fortran/gfortran.texi, gcc/java/gcj.texi) could be dual-licensed as well, so 
that is possible to provide basic documentation in Debian as well.

   Matthias

Re: GFDL/GPL issues

[Joern Rennecke]

Quoting Basile Starynkevitch <basile@starynkevitch.net>:

> On Wed, 2010-05-26 at 11:19 -0700, Mark Mitchell wrote:
>>
>> As for practical advice regarding getting quicker decisions from the FSF
>> on licensing issues, I have none.  I've worked on several such issues
>> with the FSF over the years, and they've all been lengthy processes.  If
>> I knew how to do it faster, I certainly would.  The best way to work
>> with the FSF on license issues is always to explain how whatever request
>> you are making furthers the FSF's goals.
>
> [not being a native english speaker, I had lots of trouble understanding
> the last sentence above; apparently, according to my Robert&Collins
> english<->french dictionnary applied twice, "to further" means "to
> favour" in that context; is that understanding the right one?].

To a first order of approximation.  Pedantically speaking, you could be said
to favour the goals of the FSF over the goals of some other organization if
do less damage to the  goals of the FSF than to that of that other
organization.  OTOH 'further' in the context above does not allow such
a nefarious interpretation, it means that you are actually helping to
archieve/promote the goals of the FSF.

> First, I have no idea of who the FSF really means (except RMS). Who
> should I contact by email? What should I tell? What do I risk? What are
> the *technical* background I can assume? Do FSF people know what coding
> is about? (RMS certainly does, but is he most of FSF?).

There is some information on the fsf.org site.  You could also try
that question on gnu.misc.discuss .

> Second, I believe I tried hard to explain what MELT is doing w.r.t.
> documentation in an email (dated May 07th)
> http://gcc.gnu.org/ml/gcc/2010-05/msg00125.html to which *nobody*
> responded. Or was gcc@ the wrong list to ask?
>
> Are there any reason for which I should expect more attention now? I
> don't understand why a question nobody cared about on May 7th should
> become interesting on May 27th of the same year (2010).

Well, then we were still kind of hoping the FSF would come up with a
useful policy that allows using copyrightable elements from the code
to be used in its documentation, and vice versa.
However, now it doesn't look like that such a policy is forthcoming in
a timeframe relevant to current GCC development.

> And all this is not really MELT related, and perhaps even not even GCC
> related. Several GNU projects (notably GTK) generates documentation from
> code. Not understanding at all any internal (& personal) factors from my
> far continent (I am European, and I am not a lawyer!), I cannot imagine
> why any "policy" defined for GTK would not be ok for GCC? Or are not all
> GNU projects equal? Is GTK less important to the FSF than GCC? Or maybe
> GTK is not an FSF project, (this implying that GNU software is not FSF
> software)? Or are there still no FSF copyrighted software generating
> some small documentation from code! (we are in 2010, and it is common
> practice; I could imagine that bash or binutils have similar issues.).
> And for GTK at least, the header files only mention LGPL license, and
> apparently not any additional exception related to documentation...

I'm also at a loss why the GNU package maintainers, who are charged with
selecting which contributions to accept or reject, making sure each
relevant file has a license notice and that the program is properly documented
(http://www.gnu.org/prep/maintain/maintain.html,
  http://www.gnu.org/prep/standards/standards.html),
cannot authorize to put pieces of GPLed code/documentation under the GFDL,
or pieces of GFDLed code under the GPL, as long this is done in order to
pursue the goals set out in the above documents.

> And there is one even more basic thing I don't understand. Why are GFDL
> & GPL incompatible?

That one is easy.  The GPL, unlike the  GFDL, has a concept of source code,
which is relevant for the operation of the license.
I.e. I can auto-generate GFDL documentation from differently licensed source,
and distribute the result under the GFDL, and am free to mix it with other
GFDL documentation.  The same is not true for GPLed code.
The GPL does only grant redistribution rights under the GPL.  Since the
GFDL does not have a source code concept, it is not the GPL, so redistribution
rights under the GFDL are not granted by the GPL.
Likewise, the GFDL only grants redistribution rights under
'precisely this License', thus no redistribution rights under the GPL
are granted.

> Also, some official GCC documentation contains substantial chunks of
> code (e.g. plugins.texi). Does that mere fact legally invalidate
> something?

Ask a lawyer.  Or maybe more than one... the answer probably varies
with the jurisdiction.
Prima facie, it is unsafe to use any GFDLed documentation to write
GPLed code; see PR other/44032.

> In practice, should I have to erase all the :doc annotations in MELT
> source code?

I don't see how the annotations would be a problem; the problem only
arises when you have auto-generating scripts that use these annotations
and transform them into something whose sole purpose is to interface
with non-GPL (texinfo) code.
Moreover, if you wrote all these annotations yourself, under your own
Copyright Assignment to the FSF, then you should be able to get a GFDL
license in place for the generated file after giving the FSF notice
(see my previous post).

Re: GFDL/GPL issues

[Mark Mitchell]

Joern Rennecke wrote:

> Well, then we were still kind of hoping the FSF would come up with a
> useful policy that allows using copyrightable elements from the code
> to be used in its documentation, and vice versa.
> However, now it doesn't look like that such a policy is forthcoming in
> a timeframe relevant to current GCC development.

I did get a response from RMS today, within about 24 hours of the mail I
sent him yesterday.  But, the response was a request for more
information, not a commitment to doing anything.

> I'm also at a loss why the GNU package maintainers

...

> cannot authorize to put pieces of GPLed code/documentation under the GFDL,
> or pieces of GFDLed code under the GPL, as long this is done in order to
> pursue the goals set out in the above documents.

AFAIK, as a GNU maintainer, I don't have the right to bind the FSF in
any legal manner.  I don't think I have the right to dual-license GPL'd
code under the GFDL any more than I have the right to license it under
the BSD license or the CodeSourcery Super-Sekrit Proprietary License o'
Doom.

Allowing dual-license of GPL'd code under GFDL might further the
interests of the FSF (and, in fact, I've argued to RMS that at least in
the context of GCC it would do so), but I don't think any of us have the
right to do that without the FSF's permission.

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

Re: GFDL/GPL issues

[Joseph S. Myers]

On Wed, 26 May 2010, Basile Starynkevitch wrote:

> why any "policy" defined for GTK would not be ok for GCC? Or are not all
> GNU projects equal? Is GTK less important to the FSF than GCC? Or maybe

Not all GNU projects assign their code to the FSF, and if they don't 
assign their code to the FSF then the question is what permissions the 
copyright holders of the code grant and what wording they permit to be 
used in license notices (subject of course to the FSF not accepting e.g. 
non-free licenses for anything in GNU projects).  Of course, if a project 
does not have copyright assignments and wishes to start using existing GPL 
code in GFDL manuals, or vice versa, they may then need to get permission 
for this from many different copyright holders, which could be at least as 
hard as getting permission from the FSF.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: GFDL/GPL issues

[Joseph S. Myers]

On Wed, 26 May 2010, Matthias Klose wrote:

> there is another issue with the manual pages.  Debian considers GFDL licensed
> files with invariant sections and/or cover texts as non-free.  You may agree
> or disagree with this, but the outcome is that Debian has to ship the gcc
> documentation and the manual pages in its non-free section.  The issue was
> raised with the FSF some years ago, but issues with the GFDL seem to be low
> priority within the FSF (Mako may correct me).  It would be nice to know if
> the files used to generate the manual pages (gcc/doc/invoke.texi,
> gcc/fortran/gfortran.texi, gcc/java/gcj.texi) could be dual-licensed as well,
> so that is possible to provide basic documentation in Debian as well.

Just as Joern has worked on putting target hook information in one place, 
if we can get suitable permission from the FSF it should allow putting the 
Texinfo descriptions of individual options in the GPL (plus whatever GFDL 
permission wording the FSF approves) .opt files (which I think would be 
good for similar reasons - making it more likely that people write and 
update the documentation).  This is not all the documentation that goes in 
the manpages, but a large proportion of it.  I would hope that the 
permission will not require us to go back to the FSF for each individual 
case where we wish to do something like that.

I have no plans to work on that, but do intend to make it so that all the 
options are actually in the .opt files in the first place - at present 
options that are purely handled by the gcc.c driver do not appear there 
(and many such options are undocumented).

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: GFDL/GPL issues

[Joern Rennecke]

Quoting Mark Mitchell <mark@codesourcery.com>:

> I don't understand the full situation with MELT.  But, you cannot
> combine GPL'd and GFDL's stuff, so I don't think you can auto-generate
> GFDL documentation from GPL'd code on the MELT branch.

I don't see a problem if the auto-generated GFDL documentation is
identical to documentation that has been previously released under the GFDL.
Or if the only portions not covered by the above are generated from content
for which the user of the autogeneration machinery has full authorship
rights.

> You could
> generate GPL'd documentation, though.

But then it must not rely on GFDL files; the GCC documentation generally
uses some texinfo infrastructure.

Re: GFDL/GPL issues

[Mark Mitchell]

Matthias Klose wrote:

> there is another issue with the manual pages.

> It would be nice to know if the files used to generate the manual
> pages (gcc/doc/invoke.texi, gcc/fortran/gfortran.texi,
> gcc/java/gcj.texi) could be dual-licensed as well, so that is possible
> to provide basic documentation in Debian as well.

I could ask that question, but I don't know how to do so in a way that
is likely to get the desired answer.  The FSF considers the GFDL
meritorious, and, as far as I can tell, doesn't care whether that
inconveniences Debian.  So, I don't know how to make the argument that
this change helps the FSF.

I've argued that allowing GFDL documentation to be extracted from GPL'd
code, and allowing the current GFDL text in the manuals to be placed
into comments in GPL'd code, is a win in that it reduces developer
effort and improves the quality of the product -- but I can't argue that
this is true for the manual pages.

But, if we could get the documentation for command-line options into
GPL'd code in a structured way, then I think you could probably generate
 GPL'd manual pages from that.

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

Re: GFDL/GPL issues

[Steven Bosscher]

On Wed, May 26, 2010 at 11:22 PM, Mark Mitchell <mark@codesourcery.com> wrote:
> Joern Rennecke wrote:
>
>> Well, then we were still kind of hoping the FSF would come up with a
>> useful policy that allows using copyrightable elements from the code
>> to be used in its documentation, and vice versa.
>> However, now it doesn't look like that such a policy is forthcoming in
>> a timeframe relevant to current GCC development.
>
> I did get a response from RMS today, within about 24 hours of the mail I
> sent him yesterday.  But, the response was a request for more
> information, not a commitment to doing anything.

Still good news.

Would it help to include in this "more information" to emphasize that
the issue is especially urgent for internals documentation?  IMHO the
problems Debian has with GFDL are important too, but for the FSF I
think the "internals documentation" argument carries more weight.

Ciao!
Steven

Re: GFDL/GPL issues

[Mark Mitchell]

Steven Bosscher wrote:

> Would it help to include in this "more information" to emphasize that
> the issue is especially urgent for internals documentation? 

I think I've expressed that reasonably well, with help from Jason Merill
and Toon Moene.  I gave examples involving both the internals manuals
(e.g., target hooks) and the user manual (e.g., command-line options).

I've not raised any of the Debian issues with RMS and don't intend to do
so; I will not convince the FSF by making this into an argument about
whether the GFDL is a good license.  I'm trying to focus on use of the
GPL'd code in GFDL manuals and vice versa, particularly in the context
of GCC's manuals, as a way of reducing developer effort and improving
the documentation.

Thanks,

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

Re: GFDL/GPL issues

[Alfred M. Szmidt]

I suggest you raise this with license@gnu.org.

Re: GFDL/GPL issues

[Hans-Peter Nilsson]

> Date: Tue, 25 May 2010 17:44:32 -0700
> From: Mark Mitchell <mark@codesourcery.com>

> In a biweekly call with the other GCC Release Managers, I was asked
> today on the status of the SC/FSF discussions re. GFDL/GPL issues.  In
> particular, the question of whether or not we can use "literate
> programming" techniques to extract documentation from code and take bits
> of what is currently in GCC manuals and put that into comments in code
> and so forth and so on.

FWIW, there's some hope, as licensing@gnu.org recommended
solving the similar issue regarding doxygenerated documentation
for a (to-be-released) non-FSF LGPLv3 w/GFDL docs library, by
dual-licensing the comments and mentioning the dual-licensing in
the licensing info.  Right, preaching is not the same as
practicing, but still.

brgds, H-P

Re: GFDL/GPL issues

[Russ Allbery]

Mark Mitchell <mark@codesourcery.com> writes:
> Basile Starynkevitch wrote:

>> Does that mean that even if a MELT plugin package appears in Debian, it
>> could not contain any documentation?

> I thought Debian didn't like the GFDL at all.  But, in any case, that's
> really a question for the Debian folks; I don't have any involvement in
> Debian.

This is not the place to discuss this in any further detail, obviously,
but just to clarify for those watching this part of the discussion: Debian
is not horribly happy with the GFDL, but does consider it to be a free
license provided that there are no Front Cover or Back Cover texts and no
Invariant Sections.  Debian judges all licenses for all material by the
same DFSG standards as software licenses and considers the presence of
texts covered by those three provisions of the GFDL to be unmodifiable
sections, hence non-free, and not permitted in the Debian distribution.
But as long as that aspect of the license is not used, the GFDL is a
DFSG-free license.

Provided that the software does not conflict with the terms of the GPL or
GFDL by combining things with conflicting terms in such a way as to make
them unredistributable (and dual-licensing would resolve that, obviously),
I don't believe Debian would have a problem with the situation that you
describe.

-- 
Russ Allbery (rra@stanford.edu)             <http://www.eyrie.org/~eagle/>

Re: GFDL/GPL issues

[Basile Starynkevitch]

On Tue, 2010-05-25 at 17:44 -0700, Mark Mitchell wrote:
> 
> Therefore, if I don't have an update "soon" (within a week or two), I'd
> suggest that we operate under the assumption that it will not be
> possible to combine GFDL manuals and GPL code in the near future.


Thanks for the feedback.

However, could you (or some other well informed person) elaborate on
that incompatibility. What exactly is incompatible? Is it some paragraph
of GPLv3 versus another paragraph of GFDL1.2 - which ones? Or why is it
incompatible?

My feeling is that the main thing affected is perhaps the right to
redistribute a modification of such generated documentation. But very
sincerely, I don't understand the issue, except that the generated
documentation will be both GPL & GFDL licensed.

Apparently, it should be either specific to GPL (not to LGPL), to GFDL,
or should be an *interpretation* of the FSF. (A contrario, GTK headers
do contain comments which produce documentation, and these GTK headers
seems to be stricto LGPLv2+. At least, file <gtk/gtkwidget.h> only
mentions LGPLv2 and does not mention any exception and that same file is
used to generate the
http://library.gnome.org/devel/gtk/2.21/GtkWidget.html page).

Assuming it won't be solved in a few weeks, do you imagine that it could
be solved by : a change of the GPL (so we have to wait for an
hypothetical GPLv4), a change of the GCC runtime license, something
else?

This matters practically for timescale reasons. Waiting for GPLv4 means
waiting probably nearly twenty years (and by that time, GCC will
probably cease to be relevant, and perhaps even to be actively be
developed). Waiting for a change of the GCC runtime might mean waiting
for 2 or 4 years.

Cheers.
-- 
Basile STARYNKEVITCH         http://starynkevitch.net/Basile/
email: basile<at>starynkevitch<dot>net mobile: +33 6 8501 2359
8, rue de la Faiencerie, 92340 Bourg La Reine, France
*** opinions {are only mines, sont seulement les miennes} ***

Re: GFDL/GPL issues

[Paolo Bonzini]

On 05/26/2010 09:25 AM, Joern Rennecke wrote:
> What we can't do under this scheme is retroactively re-use code
> as documentation or vice versa; we'd need the appropriate license
> grant from the FSF for each bit of code/documentation that we want
> to re-use in that manner.

Does it help that large parts of the internals manual were copied into 
config/*/*.h files pre-GFDL?  Certainly it would reduce the number of 
people that will have to be contacted to relicense under the GPL their 
contribution to the internals manual.

Paolo

Re: GFDL/GPL issues

[Joern Rennecke]

Quoting Paolo Bonzini <bonzini@gnu.org>:

> On 05/26/2010 09:25 AM, Joern Rennecke wrote:
>> What we can't do under this scheme is retroactively re-use code
>> as documentation or vice versa; we'd need the appropriate license
>> grant from the FSF for each bit of code/documentation that we want
>> to re-use in that manner.
>
> Does it help that large parts of the internals manual were copied into
> config/*/*.h files pre-GFDL?  Certainly it would reduce the number of
> people that will have to be contacted to relicense under the GPL their
> contribution to the internals manual.

If the manual was distributed pre-GFDL, doesn't that mean that previous
version is available under the GPL in the first place?
AFAICT copies into config/*/*.h files are only relevant if they have been
updated more recently then the last GPL (or GPL compatible) manual version.
Or if manual somehow was only GPLv2 and not GPLv2+.

Re: GFDL/GPL issues

[Paolo Bonzini]

On 05/27/2010 10:02 AM, Joern Rennecke wrote:
> Quoting Paolo Bonzini <bonzini@gnu.org>:
>
>> On 05/26/2010 09:25 AM, Joern Rennecke wrote:
>>> What we can't do under this scheme is retroactively re-use code
>>> as documentation or vice versa; we'd need the appropriate license
>>> grant from the FSF for each bit of code/documentation that we want
>>> to re-use in that manner.
>>
>> Does it help that large parts of the internals manual were copied into
>> config/*/*.h files pre-GFDL? Certainly it would reduce the number of
>> people that will have to be contacted to relicense under the GPL their
>> contribution to the internals manual.
>
> If the manual was distributed pre-GFDL, doesn't that mean that previous
> version is available under the GPL in the first place?

Yes, that's right.  But then that would also help. :-)

Paolo

Re: GFDL/GPL issues

[Joseph S. Myers]

On Thu, 27 May 2010, Basile Starynkevitch wrote:

> However, could you (or some other well informed person) elaborate on
> that incompatibility. What exactly is incompatible? Is it some paragraph
> of GPLv3 versus another paragraph of GFDL1.2 - which ones? Or why is it
> incompatible?

Any two non-identical copyleft licenses are generally incompatible with 
each other, since a copyleft license permits distribution only under the 
terms of exactly that license and not under some other license with 
similar terms.  (The LGPL achieves compatibility with the GPL by allowing 
you to remove the additional permissions the LGPL grants and distribute 
the result under the GPL alone.  Similarly, the FSF could grant 
permissions on documentation and code it owns to allow them to be 
distributed under both the GPL and the GFDL, and that is what we want 
them to do.)

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: GFDL/GPL issues

[Alfred M. Szmidt]

   > Therefore, if I don't have an update "soon" (within a week or two), I'd
   > suggest that we operate under the assumption that it will not be
   > possible to combine GFDL manuals and GPL code in the near future.

I think it should be possible, Emacs does something similar I think.

   However, could you (or some other well informed person) elaborate on
   that incompatibility. What exactly is incompatible? Is it some paragraph
   of GPLv3 versus another paragraph of GFDL1.2 - which ones? Or why is it
   incompatible?

The GFDL contains terms that do not exist in the GPL, which is why it
is not compatible

It should be noted that Debian considers the GFDL a non-free
/software/ license; which it is, but then the GFDL is not a software
license to begin with.  The term `non-free license' is very ambiguous.

Re: GFDL/GPL issues

[Russ Allbery]

"Alfred M. Szmidt" <ams@gnu.org> writes:

> It should be noted that Debian considers the GFDL a non-free
> /software/ license; which it is, but then the GFDL is not a software
> license to begin with.

The official Debian position is that the distinction between a software
license and a non-software license for the sort of material distributed in
Debian is an artificial and meaningless distinction because of, among
other reasons, exactly the use case being discussed in this thread.

-- 
Russ Allbery (rra@stanford.edu)             <http://www.eyrie.org/~eagle/>

Re: GFDL/GPL issues

[Joern Rennecke]

Quoting Russ Allbery <rra@stanford.edu>:

> "Alfred M. Szmidt" <ams@gnu.org> writes:
>
>> It should be noted that Debian considers the GFDL a non-free
>> /software/ license; which it is, but then the GFDL is not a software
>> license to begin with.
>
> The official Debian position is that the distinction between a software
> license and a non-software license for the sort of material distributed in
> Debian is an artificial and meaningless distinction because of, among
> other reasons, exactly the use case being discussed in this thread.

It is relevant that the invariant sections are not executable code;
since they do not affect the execution of the program, they are only
one step further from an author attribution notice that may not be
removed.
The latter are allowed under GPLv3 as an Additional Term
under 7 b - does that make GPLv3 w/ author attribution similarly
non-free in the eyes of Debian?

Re: GFDL/GPL issues

[Ian Lance Taylor]

Joern Rennecke <joern.rennecke@embecosm.com> writes:

> Quoting Russ Allbery <rra@stanford.edu>:
>
>> "Alfred M. Szmidt" <ams@gnu.org> writes:
>>
>>> It should be noted that Debian considers the GFDL a non-free
>>> /software/ license; which it is, but then the GFDL is not a software
>>> license to begin with.
>>
>> The official Debian position is that the distinction between a software
>> license and a non-software license for the sort of material distributed in
>> Debian is an artificial and meaningless distinction because of, among
>> other reasons, exactly the use case being discussed in this thread.
>
> It is relevant that the invariant sections are not executable code;
> since they do not affect the execution of the program, they are only
> one step further from an author attribution notice that may not be
> removed.
> The latter are allowed under GPLv3 as an Additional Term
> under 7 b - does that make GPLv3 w/ author attribution similarly
> non-free in the eyes of Debian?

I know it's awfully tempting, but please: no arguments about whether
GFDL is a free license on the gcc mailing list.

Ian

Re: GFDL/GPL issues

[Benjamin Kosnik]

> In a biweekly call with the other GCC Release Managers, I was asked
> today on the status of the SC/FSF discussions re. GFDL/GPL issues.  In
> particular, the question of whether or not we can use "literate
> programming" techniques to extract documentation from code and take
> bits of what is currently in GCC manuals and put that into comments
> in code and so forth and so on.

Hey Mark. Sorry, I was just pointed at this thread.

Is there a separate issue for libstdc++ doxygen? This situation is
subtly different from the one outlined above: it is the application of
a GPL'd tool over GPL'd sources, which the FSF + Red Hat legal have
both told me for years results in GPL'd docs (and is clearly noted as
such in the libstdc++ manual under Licensing.)  I consider this sane,
actually, and would be most unhappily surprised if the act of generating
the HTML changed the license to GFDL.

It would be my preference to keep this, and then have Debian/Eclipse
use dual GPL/GFDL or GFDL exclusive docs for specified releases of GCC,
ie

gcc-4.5.0-manual.gfdl.html.tar.bz2

etc.

Anyway. Not trying to be controversial here, just trying to make
existing (and hoped-for) usage clear.

-benjamin

Re: GFDL/GPL issues

[Mark Mitchell]

Benjamin Kosnik wrote:

> Is there a separate issue for libstdc++ doxygen? This situation is
> subtly different from the one outlined above: it is the application of
> a GPL'd tool over GPL'd sources, which the FSF + Red Hat legal have
> both told me for years results in GPL'd docs (and is clearly noted as
> such in the libstdc++ manual under Licensing.)  I consider this sane,
> actually, and would be most unhappily surprised if the act of generating
> the HTML changed the license to GFDL.

As far as I know, everything you say above is correct; the documentation
you're generating is GPL'd.  (IANAL, of course.)

In any case, that wasn't what the discussion with RMS was about.  It was
about two things:

1. What license should "manuals" have?

The FSF wants them to be GFDL.  However, RMS agreed that it's OK for
"cross-reference" information (as opposed to "manuals"), auto-generated
from source code, such as the documentation you're generating with
doxygen to be GPL'd.  So, the procedure you're using is fine, not just
from a "is this legal" point of view, but also from an FSF policy point
of view.

2. Can we move GPL'd code into GFDL'd manuals, or copy text from GFDL's
manuals into GPL'd code, or auto-generated GFDL's manuals from GPL'd code?

This got complicated; see previous postings.  But, it's not relevant to
your question, since you're not trying to do that.

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

Re: GFDL/GPL issues

[Steven Bosscher]

On Fri, Jul 23, 2010 at 1:22 AM, Mark Mitchell <mark@codesourcery.com> wrote:
> 2. Can we move GPL'd code into GFDL'd manuals, or copy text from GFDL's
> manuals into GPL'd code, or auto-generated GFDL's manuals from GPL'd code?
>
> This got complicated; see previous postings.  But, it's not relevant to
> your question, since you're not trying to do that.

I would like to do this for the constraints.md files, but it's not
clear to me right now whether this is allowed or not. What do you
think?

Ciao!
Steven

Re: GFDL/GPL issues

[Mark Mitchell]

Steven Bosscher wrote:

>> 2. Can we move GPL'd code into GFDL'd manuals, or copy text from GFDL's
>> manuals into GPL'd code, or auto-generated GFDL's manuals from GPL'd code?
>>
>> This got complicated; see previous postings.  But, it's not relevant to
>> your question, since you're not trying to do that.
> 
> I would like to do this for the constraints.md files, but it's not
> clear to me right now whether this is allowed or not. What do you
> think?

I think it's allowed, but not a good idea, due to the fact that I think
it creates a "trap" for people.

The FSF has said that it's OK for *us* to do it, in the FSF repository,
because the FSF can itself relicense code.  But, it's said that it's not
OK for third parties to do it, because they can't.  And, the natural way
for us to do it is via generator programs.  This creates a situation
where a third party could rerun the generator program and end up with
something they couldn't distribute.  That seems very tricky to me.

I believe that the only real fix here is (a) for the FSF to abandon the
GFDL, and relicense manuals under the GPL, or (b) for the FSF to add an
exception to the GFDL, making it compatible with the GPL in some way.
However, I have no evidence that the FSF is considering either of these
ideas; RMS didn't provide encouraging feedback when I made such suggestions.

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

Re: GFDL/GPL issues

[Joe Buck]

On Thu, Jul 22, 2010 at 04:36:46PM -0700, Mark Mitchell wrote:
> Steven Bosscher wrote:
> 
> >> 2. Can we move GPL'd code into GFDL'd manuals, or copy text from GFDL's
> >> manuals into GPL'd code, or auto-generated GFDL's manuals from GPL'd code?
> >>
> >> This got complicated; see previous postings.  But, it's not relevant to
> >> your question, since you're not trying to do that.
> > 
> > I would like to do this for the constraints.md files, but it's not
> > clear to me right now whether this is allowed or not. What do you
> > think?
> 
> I think it's allowed, but not a good idea, due to the fact that I think
> it creates a "trap" for people.
> 
> The FSF has said that it's OK for *us* to do it, in the FSF repository,
> because the FSF can itself relicense code.  But, it's said that it's not
> OK for third parties to do it, because they can't.  And, the natural way
> for us to do it is via generator programs.  This creates a situation
> where a third party could rerun the generator program and end up with
> something they couldn't distribute.  That seems very tricky to me.
> 
> I believe that the only real fix here is (a) for the FSF to abandon the
> GFDL, and relicense manuals under the GPL, or (b) for the FSF to add an
> exception to the GFDL, making it compatible with the GPL in some way.
> However, I have no evidence that the FSF is considering either of these
> ideas; RMS didn't provide encouraging feedback when I made such suggestions.

RMS is unlikely to abandon the GFDL because the features that many object
to as non-free are intentionally chosen, in part to make sure that he can
get his message out even in situations where a distributor would not agree
with that message.  I think he hasn't gotten over ESR's attempts in the
late 90s to write him out of history, so he thinks he has to force people
to carry his message along with the GNU tools.

However, if we have text that is entirely generated from a GPL program
by some kind of generator program, that text can be distributed under
the GPL.  It just can't be combined with GFDL text, except by "mere
aggregation" (you can print the two "manuals" one after the other as
chapters, or publish them both from the same web site).

RMS didn't object to what he called a "cross reference" or an "index",
generated this way, to be distributed under the GPL.

Not a great solution, but perhaps it can be made to work for a while.

Re: GFDL/GPL issues

[Joern Rennecke]

Quoting Joe Buck <Joe.Buck@synopsys.COM>:

> RMS is unlikely to abandon the GFDL because the features that many object
> to as non-free are intentionally chosen, in part to make sure that he can
> get his message out even in situations where a distributor would not agree
> with that message.  I think he hasn't gotten over ESR's attempts in the
> late 90s to write him out of history, so he thinks he has to force people
> to carry his message along with the GNU tools.

What about extending the allowed additional Terms of the GPL under clause
7 (7b is closest right now) to allow an author / Copyright holder to have
his soapbox in the software (i.e. preserve designated comments /
documentation in source and printed form), and then implement the GFDL on
top of that.

Re: GFDL/GPL issues

[Mark Mitchell]

Joe Buck wrote:

> However, if we have text that is entirely generated from a GPL program
> by some kind of generator program, that text can be distributed under
> the GPL.  

As a license statement, that's accurate.  As a policy statement, the FSF
seems to object if the output is a "manual", but not if it is a "cross
reference".  If we had a useful manual generated in this way, I'd argue
very strongly to the FSF that we should permit its distribution under
the GPL, but we don't have such a case, so there's no need for the
argument at this time.

> RMS didn't object to what he called a "cross reference" or an "index",
> generated this way, to be distributed under the GPL.

Right.

> Not a great solution, but perhaps it can be made to work for a while.

Certainly, for the purposes of libstdc++, we're OK.  Nothing has to
change to keep distributing the doxygen-generated cross-reference for
libstdc++.

I agree with you that RMS is unlikely to shift his position regarding
the GFDL.  However, I think it's goofy that we cannot auto-generate
parts of the internals manual, or the user's manual, from GPL'd source
code.  If the FSF's policy of using the GFDL on manuals means that we
can't have as good a user's manual as we would otherwise, then --
whatever its purported benefits -- the GFDL is not serving us well, and
we should continue making that case to the FSF.

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

Re: GFDL/GPL issues

[Ian Lance Taylor]

Mark Mitchell <mark@codesourcery.com> writes:

> I believe that the only real fix here is (a) for the FSF to abandon the
> GFDL, and relicense manuals under the GPL, or (b) for the FSF to add an
> exception to the GFDL, making it compatible with the GPL in some way.
> However, I have no evidence that the FSF is considering either of these
> ideas; RMS didn't provide encouraging feedback when I made such suggestions.

What if we ask the FSF if we can dual license the constraints.md files
under both the GPL and the GFDL?

Ian

Re: GFDL/GPL issues

[Mark Mitchell]

Ian Lance Taylor wrote:

>> I believe that the only real fix here is (a) for the FSF to abandon the
>> GFDL, and relicense manuals under the GPL, or (b) for the FSF to add an
>> exception to the GFDL, making it compatible with the GPL in some way.
>> However, I have no evidence that the FSF is considering either of these
>> ideas; RMS didn't provide encouraging feedback when I made such suggestions.
> 
> What if we ask the FSF if we can dual license the constraints.md files
> under both the GPL and the GFDL?

We could do that.  It's a hack, but it might be an acceptable hack.

I've been thinking about this from the perspective of "how can we get
the FSF to put an exception into the GFDL to allow inclusion/generation
from GPL'd code?"; your clever idea is that if all the code is also
GFDL'd then you don't have a problem.  I call this is a hack, because
we're changing the code license to deal with a problem created by the
FSF's insistence on a separate license for documentation, but, hey, it
might work.

Do you think we should just ask the FSF to dual-license all of GCC?

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

Re: GFDL/GPL issues

[Ian Lance Taylor]

Mark Mitchell <mark@codesourcery.com> writes:

> Do you think we should just ask the FSF to dual-license all of GCC?

Sure, it might at least be worth finding out whether they think there is
any problem with that.

Ian

Re: GFDL/GPL issues

[Mark Mitchell]

Ian Lance Taylor wrote:

>> Do you think we should just ask the FSF to dual-license all of GCC?
> 
> Sure, it might at least be worth finding out whether they think there is
> any problem with that.

I've asked on the SC list.

Thanks,

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

Re: GFDL/GPL issues

[Benjamin Kosnik]

> What if we ask the FSF if we can dual license the constraints.md files
> under both the GPL and the GFDL?

Thanks for the update Mark.

I agree that we are likely to get more traction with a request to dual
license as opposed to re-license.

Although I confess to lingering doubts as to the big picture.

This implied documentation license algebra is quite weak and the
imagined documentation production toolchains and procedures quite
tortured. GPL indexes, but no GFDL direct linkages? Please. 

Not for the first time I find myself wishing the FSF spent more mental
effort on documentation for free software, at every level. 

-benjamin

Re: GFDL/GPL issues

[Mark Mitchell]

Benjamin Kosnik wrote:
>> What if we ask the FSF if we can dual license the constraints.md files
>> under both the GPL and the GFDL?

> I agree that we are likely to get more traction with a request to dual
> license as opposed to re-license.

Well, I've asked -- but RMS shot down that idea.

> Not for the first time I find myself wishing the FSF spent more mental
> effort on documentation for free software, at every level. 

I (and I speak here not for the FSF, the SC, CodeSourcery, or anybody
else) wish the FSF spent less time "improving" licenses and more time
focused on making FSF software attractive to end users.

I'm disappointed that a license "improvement" (changing GPL to GFDL on
manuals) has made it impossible to do something that we, as developers,
used to be able to do (when documentation was under the GPL we could
move things back and forth between code and documentation at will), and
which benefited users (by making it easier for us to generate better
documentation).

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

Re: GFDL/GPL issues

[Robert Dewar]

Mark Mitchell wrote:

> I'm disappointed that a license "improvement" (changing GPL to GFDL on
> manuals) has made it impossible to do something that we, as developers,
> used to be able to do (when documentation was under the GPL we could
> move things back and forth between code and documentation at will), and
> which benefited users (by making it easier for us to generate better
> documentation).

I agree that it is essential to be able to do this kind of movement
backwards and forwards.

Re: GFDL/GPL issues

[Miles Bader]

Mark Mitchell <mark@codesourcery.com> writes:
>> I agree that we are likely to get more traction with a request to dual
>> license as opposed to re-license.
>
> Well, I've asked -- but RMS shot down that idea.

Did he give reasons, and/or indicate any other possible methods to use?

-Miles

-- 
`Suppose Korea goes to the World Cup final against Japan and wins,' Moon said.
`All the past could be forgiven.'   [NYT]

Re: GFDL/GPL issues

[Mark Mitchell]

Robert Dewar wrote:

>> I'm disappointed that a license "improvement" (changing GPL to GFDL on
>> manuals) has made it impossible to do something that we, as developers,
>> used to be able to do (when documentation was under the GPL we could
>> move things back and forth between code and documentation at will), and
>> which benefited users (by making it easier for us to generate better
>> documentation).
> 
> I agree that it is essential to be able to do this kind of movement
> backwards and forwards.

Would you like to contact RMS about this?  He doesn't seem to think that
it's important, let alone essential.

His suggestion is that we do this in the FSF repository (where we can
explicitly make such license changes), but of course that denies that
same freedom to third parties.  RMS has proposed a script that
regenerates GFDL'd documentation from GPL'd code.  But, that is not
sufficient because I can regenerate the GFDL'd manual after I change
GPL'd code (my changes can be licensed as I see fit), but I cannot
regenerate the GFDL'd manual after *you* change GPL'd code if you have
not regenerated the GFDL'd manual.

I believe that the right fix (short of simply abandoning the GFDL, which
would be fine with me, but is presumably not going to pass muster with
RMS) is a revision to the GPL that explicitly permits relicensing GPL'd
content under the GFDL, by anyone.  Movement in that direction should
not be of concern to the FSF; the point of the GFDL was to prevent
people removing the FSF's philosophical statements in its manuals, not
to prevent GPL'd content from being used in manuals.

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

Re: GFDL/GPL issues

[Benjamin Kosnik]

> I believe that the right fix (short of simply abandoning the GFDL,
> which would be fine with me, but is presumably not going to pass
> muster with RMS) is a revision to the GPL that explicitly permits
> relicensing GPL'd content under the GFDL, by anyone.  Movement in
> that direction should not be of concern to the FSF; the point of the
> GFDL was to prevent people removing the FSF's philosophical
> statements in its manuals, not to prevent GPL'd content from being
> used in manuals.

I like the sound of this proposed solution and agree fully with your
intent to get back to a more workable state for documentation
production and creation.

The simple plan as outlined above is frankly much easier to explain
and understand than these autogen GPL-index + GFDL content
machinations. That is unworkable IMHO.

Please, members of the SC, make this case.

-benjamin

Re: GFDL/GPL issues

[Mark Mitchell]

Benjamin Kosnik wrote:

>> I believe that the right fix (short of simply abandoning the GFDL,
>> which would be fine with me, but is presumably not going to pass
>> muster with RMS) is a revision to the GPL that explicitly permits
>> relicensing GPL'd content under the GFDL, by anyone.

> I like the sound of this proposed solution and agree fully with your
> intent to get back to a more workable state for documentation
> production and creation.

I've made the case on the SC list.  RMS has thus far not responded
directly to this suggestion, but thus far has not seemed terribly
concerned about the inability to move things between code and documentation.

A few of the other SC members have weighed in, but it would certainly be
helpful if more would do so.

Thanks,

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

Re: GFDL/GPL issues

[Joe Buck]

On Tue, Jul 27, 2010 at 08:53:48AM -0700, Mark Mitchell wrote:
> I believe that the right fix (short of simply abandoning the GFDL, which
> would be fine with me, but is presumably not going to pass muster with
> RMS) is a revision to the GPL that explicitly permits relicensing GPL'd
> content under the GFDL, by anyone.  Movement in that direction should
> not be of concern to the FSF; the point of the GFDL was to prevent
> people removing the FSF's philosophical statements in its manuals, not
> to prevent GPL'd content from being used in manuals.

RMS already rejected the idea of dual-licensing just GCC (GPL/GFDL) to
deal with this problem, now you're asking to effectively dual-license all
GCC (v3.1?) code that way.  Even if he would be willing to consider it
(which I doubt), he'd want to have attorneys examine all the legal
consequences so another year will go by.

We might need to go in the other direction (less radical, but enough to
solve the immediate problem).  What if only constraints files are
dual-licensed (GPL3+ or GFDL) for now?  Then documentation can be
generated from them and we've at least solved that problem.  If RMS agrees
to that and sees that the world doesn't end, maybe he'll be open later on
to opening this door wider.

Re: GFDL/GPL issues

[Mark Mitchell]

Joe Buck wrote:

> We might need to go in the other direction (less radical, but enough to
> solve the immediate problem).  What if only constraints files are
> dual-licensed (GPL3+ or GFDL) for now?  Then documentation can be
> generated from them and we've at least solved that problem.  If RMS agrees
> to that and sees that the world doesn't end, maybe he'll be open later on
> to opening this door wider.

It would be a bit frustrating to have to do this piecemeal, but half a
loaf is better than nothing.  It's certainly fine with me if you want to
suggest that on the SC list -- not that you need my permission!

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

Re: GFDL/GPL issues

[Richard Guenther]

On Tue, Jul 27, 2010 at 8:09 PM, Mark Mitchell <mark@codesourcery.com> wrote:
> Joe Buck wrote:
>
>> We might need to go in the other direction (less radical, but enough to
>> solve the immediate problem).  What if only constraints files are
>> dual-licensed (GPL3+ or GFDL) for now?  Then documentation can be
>> generated from them and we've at least solved that problem.  If RMS agrees
>> to that and sees that the world doesn't end, maybe he'll be open later on
>> to opening this door wider.
>
> It would be a bit frustrating to have to do this piecemeal, but half a
> loaf is better than nothing.  It's certainly fine with me if you want to
> suggest that on the SC list -- not that you need my permission!

Why not just ignore RMS and the license issues and simply do what we
think suits us and the project.  Let the FSF deal with the legal consequences,
they put us in this messy situation, they deal with it.

Richard.

Re: GFDL/GPL issues

[Gerald Pfeifer]

On Tue, 27 Jul 2010, Benjamin Kosnik wrote:
> Please, members of the SC, make this case.

Done.  I, too, find the removal of freedoms that the incompatible GNU 
licenses (GPLv2 vs GPLv3, GPL vs GFDL,...) create rather unacceptable.

Gerald

Re: GFDL/GPL issues

[Mark Mitchell]

Richard Guenther wrote:

> Why not just ignore RMS and the license issues and simply do what we
> think suits us and the project.  Let the FSF deal with the legal consequences,
> they put us in this messy situation, they deal with it.

We should not distribute things in violation of their licenses; that
would be both unethical and legally actionable.  And, worse yet, we
should not induce third parties to take that kind of legal risk.

At this point, the manuals are GFDL and the code is GPL; we can't mix
them.  I suppose we could ask contributors to expressly permit their
GPL'd contributions to be licensed under the GFDL, but that's not
terribly useful unless we can get some dispensation for the existing code.

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

Re: GFDL/GPL issues

[Steven Bosscher]

On Tue, Jul 27, 2010 at 10:25 PM, Richard Guenther
<richard.guenther@gmail.com> wrote:
> Why not just ignore RMS and the license issues and simply do what we
> think suits us and the project.  Let the FSF deal with the legal consequences,
> they put us in this messy situation, they deal with it.

It seems to me that escalating the issue is more helpful. GCC is not
the only project with this problem.

Ciao!
Steven

Re: GFDL/GPL issues

[Mark Mitchell]

Steven Bosscher wrote:

>> Why not just ignore RMS and the license issues and simply do what we
>> think suits us and the project.  Let the FSF deal with the legal consequences,
>> they put us in this messy situation, they deal with it.
> 
> It seems to me that escalating the issue is more helpful. GCC is not
> the only project with this problem.

Sadly, at this point, RMS is simply taking the position that this is not
a problem worth solving.

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

Re: GFDL/GPL issues

[Steven Bosscher]

On Wed, Jul 28, 2010 at 11:17 PM, Mark Mitchell <mark@codesourcery.com> wrote:
> Steven Bosscher wrote:
>
>>> Why not just ignore RMS and the license issues and simply do what we
>>> think suits us and the project.  Let the FSF deal with the legal consequences,
>>> they put us in this messy situation, they deal with it.
>>
>> It seems to me that escalating the issue is more helpful. GCC is not
>> the only project with this problem.
>
> Sadly, at this point, RMS is simply taking the position that this is not
> a problem worth solving.

Ah, how the "free" in Free Software Foundation takes a whole different
meaning when it comes to actual freedom...

Ciao!
Steven

Re: GFDL/GPL issues

[Richard Guenther]

On Thu, Jul 29, 2010 at 12:08 AM, Steven Bosscher <stevenb.gcc@gmail.com> wrote:
> On Wed, Jul 28, 2010 at 11:17 PM, Mark Mitchell <mark@codesourcery.com> wrote:
>> Steven Bosscher wrote:
>>
>>>> Why not just ignore RMS and the license issues and simply do what we
>>>> think suits us and the project.  Let the FSF deal with the legal consequences,
>>>> they put us in this messy situation, they deal with it.
>>>
>>> It seems to me that escalating the issue is more helpful. GCC is not
>>> the only project with this problem.
>>
>> Sadly, at this point, RMS is simply taking the position that this is not
>> a problem worth solving.
>
> Ah, how the "free" in Free Software Foundation takes a whole different
> meaning when it comes to actual freedom...

Ha!  Sounds like time to overturn the (benevolent?) dictator!

Richard.

Re: GFDL/GPL issues

[Alfred M. Szmidt]

Please move such unconstructive arguments elsewhere.

Re: GFDL/GPL issues

[Ian Lance Taylor]

"Alfred M. Szmidt" <ams@gnu.org> writes:

> Please move such unconstructive arguments elsewhere.

Wait.  Steven's comment was on the snarky side, but coming from a
long-time gcc contributor I don't think it was over the line or even
near it.  I think he was expressing a perfectly valid point of view
considering the constraints that the FSF places on gcc developers.  For
certain aspects of gcc, generating documentation from code makes all
kinds of sense.  The fact that the FSF is preventing us from doing that
is a real problem.  It's not a critical problem, but it's one in a line
of real problems.

Ian

Re: GFDL/GPL issues

[Miles Bader]

Ian Lance Taylor <iant@google.com> writes:
>> Please move such unconstructive arguments elsewhere.
>
> Wait.  Steven's comment was on the snarky side, but coming from a
> long-time gcc contributor I don't think it was over the line or even
> near it.  I think he was expressing a perfectly valid point of view
> considering the constraints that the FSF places on gcc developers.  For
> certain aspects of gcc, generating documentation from code makes all
> kinds of sense.  The fact that the FSF is preventing us from doing that
> is a real problem.  It's not a critical problem, but it's one in a line
> of real problems.

I think it'd be a lot more palatable if there were at least some
justification given for ignoring the request -- but at least the way
Mark stated it, rms was just dismissive.

-Miles

-- 
Do not taunt Happy Fun Ball.

Re: GFDL/GPL issues

[Toon Moene]

Ian Lance Taylor wrote:
> "Alfred M. Szmidt" <ams@gnu.org> writes:
> 
>> Please move such unconstructive arguments elsewhere.
> 
> Wait.  Steven's comment was on the snarky side, but coming from a
> long-time gcc contributor I don't think it was over the line or even
> near it.  I think he was expressing a perfectly valid point of view
> considering the constraints that the FSF places on gcc developers.  For
> certain aspects of gcc, generating documentation from code makes all
> kinds of sense.  The fact that the FSF is preventing us from doing that
> is a real problem.  It's not a critical problem, but it's one in a line
> of real problems.

Especially if he is right about more projects having this problem.

He wrote:

"GCC is not the only project with this problem."

If that is true, and if those projects are also under the umbrella of 
the FSF, we (those projects together) might take the step to "escalate" 
this issue to the board of the FSF.

Kind regards,

-- 
Toon Moene - e-mail: toon@moene.org - phone: +31 346 214290
Saturnushof 14, 3738 XG  Maartensdijk, The Netherlands
At home: http://moene.org/~toon/; weather: http://moene.org/~hirlam/
Progress of GNU Fortran: http://gcc.gnu.org/gcc-4.5/changes.html#Fortran

Re: GFDL/GPL issues

[Richard Kenner]

> Wait.  Steven's comment was on the snarky side, but coming from a
> long-time gcc contributor I don't think it was over the line or even
> near it.  I think he was expressing a perfectly valid point of view
> considering the constraints that the FSF places on gcc developers.  For
> certain aspects of gcc, generating documentation from code makes all
> kinds of sense.  The fact that the FSF is preventing us from doing that
> is a real problem.  It's not a critical problem, but it's one in a line
> of real problems.

Could part of the problem here be that RMS's view on "documentation" is
that it's meant to be a creative process, somewhat akin to writing a book,
and that mechanically creating "documentation" will produce something of
much lower quality than what's done by hand?  Back when he and I spoke
regularly, I know that he cared a lot about the "literary" quality of the
documentation and I think that part of this might be due to a "why would
you want to do that anyway?" position on automaticaly-generated stuff.

But we've heard that he indeed has no problem creating something that's in
the form of documentation and calling it a "function index" or something
similar.  And I think we ought to seriously consider going in that
direction, where there are two separate things: a MANUAL, written manually,
which is meant to be high-quality language and is under the GFDL, and
a separate document which is under the GPL and is generated automatically.

This may also produce more of a split between the user and internal
documentation.  The user manual is the one that (I suspect), he's mostly
concerned about that that needs to be produced manually to get appropriate
quality.  Then there's another GFDL'ed document that's an overview of the
internals and references the third (GPL'ed) document that's automatically
generated.

Re: GFDL/GPL issues

[Joern Rennecke]

Quoting Richard Kenner <kenner@vlsi1.ultra.nyu.edu>:

> Could part of the problem here be that RMS's view on "documentation" is
> that it's meant to be a creative process, somewhat akin to writing a book,
> and that mechanically creating "documentation" will produce something of
> much lower quality than what's done by hand?  Back when he and I spoke
> regularly, I know that he cared a lot about the "literary" quality of the
> documentation and I think that part of this might be due to a "why would
> you want to do that anyway?" position on automaticaly-generated stuff.

But even for documentation written by hand, often I find that I'd like to
start out with some comment or example from the actual code.  The GPL / GFDL
dichotomy doesn't allow me to do that, so some documentation just won't get
written.

Re: GFDL/GPL issues

[Richard Kenner]

> But even for documentation written by hand, often I find that I'd like to
> start out with some comment or example from the actual code.  The GPL / GFDL
> dichotomy doesn't allow me to do that, so some documentation just won't get
> written.

Taking an example from actual code would be "fair use" and not a violation
of the GPL.  I don't see a problem there.  Taking large pieces of code
in a mechanical way is completely different from the type of manual
copying you're talking about.

Re: GFDL/GPL issues

[Jeff Law]

  On 07/29/10 08:26, Richard Kenner wrote:
>> But even for documentation written by hand, often I find that I'd like to
>> start out with some comment or example from the actual code.  The GPL / GFDL
>> dichotomy doesn't allow me to do that, so some documentation just won't get
>> written.
> Taking an example from actual code would be "fair use" and not a violation
> of the GPL.  I don't see a problem there.  Taking large pieces of code
> in a mechanical way is completely different from the type of manual
> copying you're talking about.
Isn't one of the specific instances of this issue the desire to copy 
some of the constraints information from the source, which would need to 
go into the user manual rather than internals documentation?

And in some cases a function index with documentation may be precisely 
what the end-user needs -- think runtime libraries.


What's concerning is how much time we've got to spend discussing this 
kind of issue rather than getting real work done, all due to a license 
that is insanely controversial.

Jeff

Re: GFDL/GPL issues

[Richard Kenner]

> Isn't one of the specific instances of this issue the desire to copy 
> some of the constraints information from the source, which would need to 
> go into the user manual rather than internals documentation?
> 
> And in some cases a function index with documentation may be precisely 
> what the end-user needs -- think runtime libraries.

But in both of these cases, there are basically two separate things: a
prose description (in these cases of what constraints do and an overview of
the library) and a separate list of details.  The first would be a
well-written document and the latter would be automatically generated.

So I can see the argument that having two separate documents here may be
valuable from OTHER than a licensing viewpoint.  (I'm not sure whether I
AGREE with it or not, but that may be partly where RMS is coming from.)

Re: GFDL/GPL issues

[Mark Mitchell]

Richard Kenner wrote:

> Could part of the problem here be that RMS's view on "documentation" is
> that it's meant to be a creative process, somewhat akin to writing a book,
> and that mechanically creating "documentation" will produce something of
> much lower quality than what's done by hand?  Back when he and I spoke
> regularly, I know that he cared a lot about the "literary" quality of the
> documentation and I think that part of this might be due to a "why would
> you want to do that anyway?" position on automaticaly-generated stuff.

Yes, that is part of his thinking.  And, yes, we can split our manuals
up into GPL and GFDL pieces, and in some cases that will work fine.
But, documentation of constraints (important to users for writing inline
assembly), or documentation of command-line options (important to all
users), or documentation of built-in functions (important to users to
understand the dialect of C we support) are all things that belong in
the manual, not in separate GPL documents.

FSF policy is making it impossible for us to do something useful to
users, that poses no real risk to the FSF's objectives (manuals were
under the GPL for ages without the world ending), and which GCC's
competitors can do.  That's a suboptimal policy.

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

Re: GFDL/GPL issues

[Robert Dewar]

Richard Kenner wrote:
>> But even for documentation written by hand, often I find that I'd like to
>> start out with some comment or example from the actual code.  The GPL / GFDL
>> dichotomy doesn't allow me to do that, so some documentation just won't get
>> written.
> 
> Taking an example from actual code would be "fair use" and not a violation
> of the GPL.  I don't see a problem there.  Taking large pieces of code
> in a mechanical way is completely different from the type of manual
> copying you're talking about.

I agree with this, taking examples also seems like fair use to me.

Re: GFDL/GPL issues

[Robert Dewar]

Jeff Law wrote:

> Isn't one of the specific instances of this issue the desire to copy 
> some of the constraints information from the source, which would need to 
> go into the user manual rather than internals documentation?
> 
> And in some cases a function index with documentation may be precisely 
> what the end-user needs -- think runtime libraries.

These cases both seem to fall within the four-test fair use guidlines
to me, and I can't imagine any of the relevant copyright holders seeing
otherwise.

> What's concerning is how much time we've got to spend discussing this 
> kind of issue rather than getting real work done, all due to a license 
> that is insanely controversial.

I would not worry about that, people like to spend time on this kind of
discussion, or they would not do it :-)

Re: GFDL/GPL issues

[Robert Dewar]

Mark Mitchell wrote:

> Yes, that is part of his thinking.  And, yes, we can split our manuals
> up into GPL and GFDL pieces, and in some cases that will work fine.
> But, documentation of constraints (important to users for writing inline
> assembly), or documentation of command-line options (important to all
> users), or documentation of built-in functions (important to users to
> understand the dialect of C we support) are all things that belong in
> the manual, not in separate GPL documents.
> 
> FSF policy is making it impossible for us to do something useful to
> users, that poses no real risk to the FSF's objectives (manuals were
> under the GPL for ages without the world ending), and which GCC's
> competitors can do.  That's a suboptimal policy.

I don't think it is making this impossible, my advice is simply to
consider this fair use and steam ahead, then worry if someone objects.
> 

Re: GFDL/GPL issues

[Mark Mitchell]

Robert Dewar wrote:

> I don't think it is making this impossible, my advice is simply to
> consider this fair use and steam ahead, then worry if someone objects.

Despite the copyright holder (well, RMS, but he certainly can be
interpreted as speaking for the FSF) saying plainly and clearly that he
thinks that you *cannot* do this?

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

Re: GFDL/GPL issues

[Joern Rennecke]

Quoting Mark Mitchell <mark@codesourcery.com>:

> Robert Dewar wrote:
>
>> I don't think it is making this impossible, my advice is simply to
>> consider this fair use and steam ahead, then worry if someone objects.
>
> Despite the copyright holder (well, RMS, but he certainly can be
> interpreted as speaking for the FSF) saying plainly and clearly that he
> thinks that you *cannot* do this?

Actually, the legal definition of fair use / fair dealing that might or might
not apply depends on the country of residence of the contributer, but if
RMS says you shouldn't do this, ignoring him is not proper in the context of
a GNU project - and if you are doing a fork to get away from FSF policies,
you might as well write your documentation GPLed.

Re: GFDL/GPL issues

[Toon Moene]

Richard Kenner wrote:

>> But even for documentation written by hand, often I find that I'd like to
>> start out with some comment or example from the actual code.  The GPL / GFDL
>> dichotomy doesn't allow me to do that, so some documentation just won't get
>> written.
> 
> Taking an example from actual code would be "fair use" and not a violation
> of the GPL.  I don't see a problem there.  Taking large pieces of code
> in a mechanical way is completely different from the type of manual
> copying you're talking about.

Not so fast - I know I got mighty suspicious of claims by non-lawyers 
about copyright issues by reading groklaw.net for over five years, but 
consider the following:

If you point your browser at:

http://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/Table-of-Intrinsic-Functions.html#Table-of-Intrinsic-Functions

you'll see literally up to a hundred entries of documentation that were 
generated in the following way:

1. There is a definition file that documents the interfaces to Fortran
    run time libraries (a GPL'd file).

2. There is a program (GPL'd) that generates:

    a. texinfo documentation from them, that ultimately leads to the web
       pages you view (GPL'd - in the old days).

    b. in addition, it generates the interfaces to the Fortran run-time
       libraries (which were LGPL'd, if I recall correctly).

In this way, we were sure that the documentation of the g77 run time 
library was commensurate with its implementation - more than once it has 
saved us from expensive debugging exercises to conclude that *yes* the 
implementation didn't match the documentation (or the standard, if the 
docs deviate from the standard).

The GFDL/GPL dichotomy makes this scheme impossible.

-- 
Toon Moene - e-mail: toon@moene.org - phone: +31 346 214290
Saturnushof 14, 3738 XG  Maartensdijk, The Netherlands
At home: http://moene.org/~toon/; weather: http://moene.org/~hirlam/
Progress of GNU Fortran: http://gcc.gnu.org/gcc-4.5/changes.html#Fortran

Re: GFDL/GPL issues

[Robert Dewar]

Mark Mitchell wrote:
> Robert Dewar wrote:
> 
>> I don't think it is making this impossible, my advice is simply to
>> consider this fair use and steam ahead, then worry if someone objects.
> 
> Despite the copyright holder (well, RMS, but he certainly can be
> interpreted as speaking for the FSF) saying plainly and clearly that he
> thinks that you *cannot* do this?

Whether something is fair use has to be judged on the very specific
instance in question, not clear to me that RMS has opined on a very
specific issue, if so, I missed it.

BTW, the copyright holder has in general nothing to say about whether
something is or is not fair use, that is a statutory issue, based on
the four tests, none of which involves copyright holder input.
> 

Re: GFDL/GPL issues

[Robert Dewar]

Joern Rennecke wrote:

> Actually, the legal definition of fair use / fair dealing that might or might
> not apply depends on the country of residence of the contributer

Not true in the US for sure.

, but if
> RMS says you shouldn't do this, ignoring him is not proper in the context of
> a GNU project 

I agree with that, but as I said in my previous note, it is not clear 
that RMS has given input on the fair use issue in the context of a very
specific case ...

Re: GFDL/GPL issues

[Mark Mitchell]

Robert Dewar wrote:

> Whether something is fair use has to be judged on the very specific
> instance in question, not clear to me that RMS has opined on a very
> specific issue, if so, I missed it.

We don't want to ask RMS every time we want to do this.  RMS has opined
on some of the specific cases, such as generating documentation for
command-line options from comments in the code.  He hasn't specifically
said whether he thinks it's a GPL/GFDL violation -- but nothing in what
he's said would suggest to me that he thinks it's not a violation.  In
fact, the statement that we can only run such generation scripts in the
FSF repository, since only the FSF can relicense the code, would seem to
suggest that he believes that, in general, you can't do this.

In any case, you're suggesting we go against the express wishes of the
FSF.  Would you suggest that we do that in the context of FSF GCC?

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

Re: GFDL/GPL issues

[Joern Rennecke]

Quoting Robert Dewar <dewar@adacore.com>:

> Joern Rennecke wrote:
>
>> Actually, the legal definition of fair use / fair dealing that   
>> might or might
>> not apply depends on the country of residence of the contributer
>
> Not true in the US for sure.

Are you saying that the USA is a solipsist nation that denies the existence
of people (or at least of Free Software developers) in other places?

That would be a rather odd regression, considering that other parts of the
GPL - and in particular v3 - were specifically written so as to to make
its meaning uniform irrespective of differences in national laws.

If you want to make the point that the FSF would have to consider fair
use if it were to sue in an US court - well, AFAICT it wouldn't have to,
it could sue in the court of the contributor's country of residence /
incorporation, as is common in patent cases where the patent might be
invalid in the patent holders's country of incorporation.

Re: GFDL/GPL issues

[Robert Dewar]

Joern Rennecke wrote:

> If you want to make the point that the FSF would have to consider fair
> use if it were to sue in an US court - well, AFAICT it wouldn't have to,
> it could sue in the court of the contributor's country of residence /
> incorporation, as is common in patent cases where the patent might be
> invalid in the patent holders's country of incorporation.

I think this has gone beyond what is appropriate for the gcc list, I am
happy to take it offline if you like.

Re: GFDL/GPL issues

[Diego Novillo]

On Sat, Jul 31, 2010 at 00:16, Mark Mitchell <mark@codesourcery.com> wrote:

> In any case, you're suggesting we go against the express wishes of the
> FSF.  Would you suggest that we do that in the context of FSF GCC?

Well, this issue is another one in a long series of roadblocks that
we've had to struggle with over the years.  So, eventually, we should
seriously consider not being an FSF project anymore.

We are already having trouble keeping our documentation up-to-date.
Some of it is in such a poor shape as to be laughable.  Yes, it's
mostly our fault, but if we were able to generate documentation by
simply extracting it from the code.  Tools exist for this, and
properly maintained, they are very useful.

SC folks, please find some way of convincing the FSF to stop being
unreasonable about this.  We are already having a hard time generating
good documentation.  Why make it harder than it is?


Diego.

Re: GFDL/GPL issues

[Richard Kenner]

> We are already having trouble keeping our documentation up-to-date.
> Some of it is in such a poor shape as to be laughable.  Yes, it's
> mostly our fault, but if we were able to generate documentation by
> simply extracting it from the code.  Tools exist for this, and
> properly maintained, they are very useful.

I disagree and think that's backwards.  To get good quality
documentation, we have to WRITE good quality documentation.  Using
tools to generate it from sources will DECREASE its quality, in my
opinion.  The best measure of quality of a document is how much time
people spend writing and editing it.

Re: GFDL/GPL issues

[Diego Novillo]

On 10-08-02 19:17 , Richard Kenner wrote:
>> We are already having trouble keeping our documentation up-to-date.
>> Some of it is in such a poor shape as to be laughable.  Yes, it's
>> mostly our fault, but if we were able to generate documentation by
>> simply extracting it from the code.  Tools exist for this, and
>> properly maintained, they are very useful.
>
> I disagree and think that's backwards.  To get good quality
> documentation, we have to WRITE good quality documentation.  Using
> tools to generate it from sources will DECREASE its quality, in my
> opinion.  The best measure of quality of a document is how much time
> people spend writing and editing it.

We'll have to agree to disagree in this respect, then.

Notwithstanding our difference of opinions here, the big issue that 
irritates me is our inability to even attract contributions in this area.


Diego.

Re: GFDL/GPL issues

[Steven Bosscher]

On Tue, Aug 3, 2010 at 1:17 AM, Richard Kenner
<kenner@vlsi1.ultra.nyu.edu> wrote:
>> We are already having trouble keeping our documentation up-to-date.
>> Some of it is in such a poor shape as to be laughable.  Yes, it's
>> mostly our fault, but if we were able to generate documentation by
>> simply extracting it from the code.  Tools exist for this, and
>> properly maintained, they are very useful.
>
> I disagree and think that's backwards.  To get good quality
> documentation, we have to WRITE good quality documentation.

That is true, but very often the documentation is needed in two
places: in the code and in the manual. Especially for things like
machine constraints, flags and options. And even if the documentation
isn't needed in two places to, well, document something, it may still
be useful to automatically generate parts of manual to avoid
divergence between the manual and the compiler.

But as it is, the good quality documentation cannot be written in the code...

Ciao!
Steven

Re: GFDL/GPL issues

[Richard Kenner]

> That is true, but very often the documentation is needed in two
> places: in the code and in the manual. Especially for things like
> machine constraints, flags and options. 

Yes, but the audiences are different between users who read the manual and
developers who read the code.  For the best quality, the two descriptions
may well be quite different, in emphasis, tone and other areas.  If the
emphasis is on finding text that's acceptable for BOTH purposes, you create
documentation that's not ideal for EITHER.

> And even if the documentation isn't needed in two places to, well,
> document something, it may still be useful to automatically generate
> parts of manual to avoid divergence between the manual and the compiler.

That's indeed a worthwhile goal, but doing it at the expense of the quality
of the documentation is a very bad idea, in my opinion.

The quality of documentation in the industry, and even in the Free Software
community is pretty poor.  GCC is known for a very high standard of
documentation.  Let's not lower it by substiting automated tools for
quality handwritten documentation.

I believe that tools have their purpose for such things as functions
lists and detailed ABI documentation, but not in things like user
manuals.

Re: GFDL/GPL issues

[Mark Mitchell]

Richard Kenner wrote:
>> That is true, but very often the documentation is needed in two
>> places: in the code and in the manual. Especially for things like
>> machine constraints, flags and options. 
> 
> Yes, but the audiences are different between users who read the manual and
> developers who read the code. 

Richard, your argument is a distraction from the important issue at
hand.  Unless you posit that there is no useful way in which to generate
documentation from code (and comments therein), which seems an extreme
statement, then it is desirable that we have the ability to do that.
Right now we don't.  That's bad.

I certainly don't disagree that it might be desirable for documentation
for constraints might be different for end users and for GCC developers.
 But, there is nothing that says that both kinds of documentation might
not be located physically in the code, so that when you
add/delete/modify a constraint you can also easily update the
documentation.

And, furthermore, just because it might be desirable for the
documentation to be different for end-users and compiler developers
doesn't mean that it's practical for them to be different.  I don't see
a mob of people beating down the doors to write GCC documentation.  So,
I'm not inclined to let perfect be the enemy of good.  If we only get
one "flavor" of documentation, that's a lot better than none at all!

In any case, the key issue here isn't how we should write documentation.
 It's whether we can use a technological measure to generate
documentation if we find cases where that is desirable.  It makes no
sense for the FSF to artificially erect legal barriers to using a given
technical approach to creating documentation.  If this is really about
documentation quality, the FSF could simply have a policy saying that
GNU maintainers should not do this -- there is no reason to have a legal
prohibition preventing people from doing it!

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

Re: GFDL/GPL issues

[Paul Koning]

On Aug 2, 2010, at 7:17 PM, Richard Kenner wrote:

>> We are already having trouble keeping our documentation up-to-date.
>> Some of it is in such a poor shape as to be laughable.  Yes, it's
>> mostly our fault, but if we were able to generate documentation by
>> simply extracting it from the code.  Tools exist for this, and
>> properly maintained, they are very useful.
> 
> I disagree and think that's backwards.  To get good quality
> documentation, we have to WRITE good quality documentation.  Using
> tools to generate it from sources will DECREASE its quality, in my
> opinion.  The best measure of quality of a document is how much time
> people spend writing and editing it.

I agree.

gcc and gccint docs are actually pretty reasonable.  (Certainly gccint is vastly better than some of its siblings, like gdbint.)  But very little of it is generated and very little of what comes to mind as possible subject matter is suitable for being generated.

Even when things have been set up from the start for generating documentation (like embedded documentation strings in Python code) such "documentation" rarely captures more than trivial information about calling conventions.  Nothing of substance ever comes from documentation of that kind.

	paul

Re: GFDL/GPL issues

[Richard Kenner]

> Richard, your argument is a distraction from the important issue at
> hand.  Unless you posit that there is no useful way in which to generate
> documentation from code (and comments therein), which seems an extreme
> statement, then it is desirable that we have the ability to do that.
> Right now we don't.  That's bad.

"bad" isn't very precise.  The claim was made that a reason that it's "bad"
is that not being able to automatically generate documentation lowers
the quality of the documentation.   That's what I disagree with.

> But, there is nothing that says that both kinds of documentation might
> not be located physically in the code, so that when you
> add/delete/modify a constraint you can also easily update the
> documentation.

In that case, wouldn't we have two distinctly different kinds of material
in the same file: an extract from a manual and code.  So why couldn't
the file have a license that says "this part is GFDL and this part is GPL"?

Re: GFDL/GPL issues

[Mark Mitchell]

Richard Kenner wrote:

> "bad" isn't very precise.  The claim was made that a reason that it's "bad"
> is that not being able to automatically generate documentation lowers
> the quality of the documentation.   That's what I disagree with.

OK, fine; that's a reasonably debatable point.  But, we currently can't
automatically generate manuals -- which is something we used to be able
to do -- and that's bad.  In general, a policy that prevents us from
being able to use a particular technical method to achieve a goal is silly.

>> But, there is nothing that says that both kinds of documentation might
>> not be located physically in the code, so that when you
>> add/delete/modify a constraint you can also easily update the
>> documentation.
> 
> In that case, wouldn't we have two distinctly different kinds of material
> in the same file: an extract from a manual and code.  So why couldn't
> the file have a license that says "this part is GFDL and this part is GPL"?

Maybe it could.  But, maybe it can't.  It depends on how closely you can
weave the documents together before you end up with something that is
more than mere aggregation.

None of this really answers the key question, which is, in my opinion,
what is the GFDL actually buying us?  And, if all it's buying us is that
people can't remove the FSF's philosophical statements in manuals, is
that worth having to split hairs about exactly what parts of what
documentation can be generated in what exact manner?

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

Re: GFDL/GPL issues

[Paolo Bonzini]

On 08/03/2010 01:35 AM, Richard Kenner wrote:
>> That is true, but very often the documentation is needed in two
>> places: in the code and in the manual. Especially for things like
>> machine constraints, flags and options.
>
> Yes, but the audiences are different between users who read the manual and
> developers who read the code.  For the best quality, the two descriptions
> may well be quite different, in emphasis, tone and other areas.  If the
> emphasis is on finding text that's acceptable for BOTH purposes, you create
> documentation that's not ideal for EITHER.

The amount of comments copied tout-court from gccint to the target files 
(especially with respect to target macro definitions) seems to 
contradict this.

Paolo

Re: GFDL/GPL issues

[Joe Buck]

On Mon, Aug 02, 2010 at 05:51:13PM -0700, Paul Koning wrote:
> gcc and gccint docs are actually pretty reasonable.  (Certainly gccint is vastly better than some of its siblings, like gdbint.)  But very little of it is generated and very little of what comes to mind as possible subject matter is suitable for being generated.

RMS explicitly blessed generated cross-references and the like under the
GPL.

So one way to move forward is to effectively have two manuals, one
containing traditional user-written text (GFDL), the other containing
generated text (GPL).  If you print it out as a book, the generated
part would just appear as an appendix to the manual, it's "mere
aggregation".

Re: GFDL/GPL issues

[Robert Dewar]

Diego Novillo wrote:

> We are already having trouble keeping our documentation up-to-date.
> Some of it is in such a poor shape as to be laughable.  Yes, it's
> mostly our fault, but if we were able to generate documentation by
> simply extracting it from the code.  Tools exist for this, and
> properly maintained, they are very useful.

I am actually a bit dubious about automatic extraction of documentation
from code. The kind of thing you can get this way is in any case easily
obtained by browsing the code. All too often this kind of automatic
generation is just a way of satisfying the need for quantity of
documentation without enough attention to quality.

There are certainly exceptions to this, some of which have been
mentioned in this thread, but as a general mechanism, it is dangerous
in my opinion.

Ultimately the proper path to excellent documentation is to have
programmers who are as interested in generating documentation as
they are in writing code. If you don't have that, you will never
get really good documentation.

Re: GFDL/GPL issues

[Robert Dewar]

It's interesting to note that in the case of GNAT, we have no
licensing constraints on the documentation that would restrict
automatic generation, but we just don't do it.

The GNAT documentation is pretty complete, and certainly
gets a lot of attention and constant improvement, since
we regard it as being as important as the code.

In the case of interfaces to library routines, what we do
is to have fully commented Ada package specs that act as
both the documentation of the implementation interface and
as the user documentation (for an example, look at g-spipat.ads).
I can't see any value in duplicating this information elsewhere.

Re: GFDL/GPL issues

[Robert Dewar]

Joe Buck wrote:

> So one way to move forward is to effectively have two manuals, one
> containing traditional user-written text (GFDL), the other containing
> generated text (GPL).  If you print it out as a book, the generated
> part would just appear as an appendix to the manual, it's "mere
> aggregation".

Does *anyone* print documentation "out as a book", this seems to me
to be a completely obsolete concept. We used to print GNAT manuals
for our customers, and ship them out in fancy boxes, and they looked
nice, but were in reality useless, since they got so quickly outdated.

We still format everything so that it can be printed out as books, but
I doubt anyone does it, we certainly don't.

Re: GFDL/GPL issues

[Joseph S. Myers]

On Tue, 3 Aug 2010, Joe Buck wrote:

> On Mon, Aug 02, 2010 at 05:51:13PM -0700, Paul Koning wrote:
> > gcc and gccint docs are actually pretty reasonable.  (Certainly gccint is vastly better than some of its siblings, like gdbint.)  But very little of it is generated and very little of what comes to mind as possible subject matter is suitable for being generated.
> 
> RMS explicitly blessed generated cross-references and the like under the
> GPL.
> 
> So one way to move forward is to effectively have two manuals, one
> containing traditional user-written text (GFDL), the other containing
> generated text (GPL).  If you print it out as a book, the generated
> part would just appear as an appendix to the manual, it's "mere
> aggregation".

The following is my personal opinion.

We want to move forward with the transition of target macros to hooks, we 
want to be able to convert each macro's documentation to hook 
documentation in target.def, we want to be able to move existing 
documentation for target hooks there, we want this to be possible for 
people maintaining their own non-FSF versions of GCC, we want to be able 
to do similar things with other sorts of documentation based solely on the 
technical judgement of relevant maintainers while keeping it properly 
integrated with related documentation, and we do not want this to need 
approval from RMS or the FSF for each patch.  Though it would probably be 
better for people doing hook conversion patches to include doc conversion 
and send them all to RMS rather than not including doc conversion and not 
pointing out to RMS every time such a patch runs into a legal issue.

The FSF's responsibility for legal matters under the Mission Statement 
comes with a duty to the developers not to get in the way of the "Patches 
will be considered equally based on their technical merits." principle 
from the Mission Statement.  The FSF is failing in its duty to what was 
traditionally considered one of its flagship projects.  If this has not 
been brought up with the full board of directors of the FSF, it is time 
that it was so brought up.  Richard may have the right point in 
<http://gcc.gnu.org/ml/gcc/2010-07/msg00411.html> regarding problems with 
FSF leadership.  I support the FSF's various campaigns for freedom and 
against closed devices and systems, but I get the impression that they 
have been losing sight of the needs of their traditional flagship projects 
lately.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: GFDL/GPL issues

[Steven Bosscher]

On Tue, Aug 3, 2010 at 8:48 PM, Robert Dewar <dewar@adacore.com> wrote:
> Joe Buck wrote:
>
>> So one way to move forward is to effectively have two manuals, one
>> containing traditional user-written text (GFDL), the other containing
>> generated text (GPL).  If you print it out as a book, the generated
>> part would just appear as an appendix to the manual, it's "mere
>> aggregation".
>
> Does *anyone* print documentation "out as a book", this seems to me
> to be a completely obsolete concept. We used to print GNAT manuals
> for our customers, and ship them out in fancy boxes, and they looked
> nice, but were in reality useless, since they got so quickly outdated.
>
> We still format everything so that it can be printed out as books, but
> I doubt anyone does it, we certainly don't.

So perhaps the solution is to only make the manual available as
separate, linked HTML pages from now on?

The HTML pages would exist under different licenses. There is nothing
against pointing from GFDL-licensed web pages to GPL-ed web pages,
right? So we could have a GFDL "wrapper" manual, and parts of the
manual generated from GPL code as separate pages. There are
interesting problems (generating the index, for example, and a small
maintenance problem for the links between parts of the manual under
different license), but it would work around the license problems.

Feels like reductio ad absurdum, but that's really sort-of the point...

Ciao!
Steven

Re: GFDL/GPL issues

[Miles Bader]

Robert Dewar <dewar@adacore.com> writes:
> I am actually a bit dubious about automatic extraction of documentation
> from code. The kind of thing you can get this way is in any case easily
> obtained by browsing the code.

Presumably it saves the effort of browsing the code, which is not a
small thing... (If I'm learning about an interface, I want a concise
introduction to the functions in it, and the work of finding the
appropriate functions in the appropriate location in the appropriate
file can be pretty annoying).

Moreover, it such extraction can to improve the source code for browsing
too:  if a function's header-comment were actually included in the
documentation (suitably massaged), that's all the more incentive to
write really good and clear function header-comments...

-Miles

-- 
The car has become... an article of dress without which we feel uncertain,
unclad, and incomplete.  [Marshall McLuhan, Understanding Media, 1964]

Re: GFDL/GPL issues

[Benjamin Kosnik]

> So one way to move forward is to effectively have two manuals, one
> containing traditional user-written text (GFDL), the other containing
> generated text (GPL).  If you print it out as a book, the generated
> part would just appear as an appendix to the manual, it's "mere
> aggregation".

This is not acceptable to me. 

You have just described the status quo,
what we are already doing. It is very difficult to link api
references to manual references in two separate documents. What I want
to do is full integration, and not be forced into these aggregations.

And I am being denied. 

I am very disheartened by this conversation. I'm actually incredulous,
exactly as expressed by Diego, that this is even an issue. These ivory
tower replies about awesome docs written by programmer-scribe-monks
for simple C interfaces that none of the email authors is in fact
writing are incredibly annoying to me, as somebody who is actually
doing this work. Let's at least give weight to the people in the gcc
community who are doing this work, ok? Or else I will stop doing it.

This should be a minor detail, not a month long thread. All we are
asking is for the permission to render GPL code as GFDL in addion to
GPL. No freedoms are being lost here dudes.

-benjamin

Re: GFDL/GPL issues

[Benjamin Kosnik]

> The FSF's responsibility for legal matters under the Mission
> Statement comes with a duty to the developers not to get in the way
> of the "Patches will be considered equally based on their technical
> merits." principle from the Mission Statement.  The FSF is failing in
> its duty to what was traditionally considered one of its flagship
> projects.  If this has not been brought up with the full board of
> directors of the FSF, it is time that it was so brought up.  Richard
> may have the right point in
> <http://gcc.gnu.org/ml/gcc/2010-07/msg00411.html> regarding problems
> with FSF leadership.  I support the FSF's various campaigns for
> freedom and against closed devices and systems, but I get the
> impression that they have been losing sight of the needs of their
> traditional flagship projects lately.

I agree. SC, please escalate.

-benjamin

Re: GFDL/GPL issues

[Diego Novillo]

On 10-08-04 03:22 , Benjamin Kosnik wrote:
>
>> The FSF's responsibility for legal matters under the Mission
>> Statement comes with a duty to the developers not to get in the way
>> of the "Patches will be considered equally based on their technical
>> merits." principle from the Mission Statement.  The FSF is failing in
>> its duty to what was traditionally considered one of its flagship
>> projects.  If this has not been brought up with the full board of
>> directors of the FSF, it is time that it was so brought up.  Richard
>> may have the right point in
>> <http://gcc.gnu.org/ml/gcc/2010-07/msg00411.html>  regarding problems
>> with FSF leadership.  I support the FSF's various campaigns for
>> freedom and against closed devices and systems, but I get the
>> impression that they have been losing sight of the needs of their
>> traditional flagship projects lately.
>
> I agree. SC, please escalate.

Agreed.  This is surreal and counterproductive.


Diego.

Re: GFDL/GPL issues

[Joe Buck]

On Wed, Aug 04, 2010 at 12:21:05AM -0700, Benjamin Kosnik wrote:
> 
> > So one way to move forward is to effectively have two manuals, one
> > containing traditional user-written text (GFDL), the other containing
> > generated text (GPL).  If you print it out as a book, the generated
> > part would just appear as an appendix to the manual, it's "mere
> > aggregation".
> 
> This is not acceptable to me. 
> 
> You have just described the status quo,
> what we are already doing. It is very difficult to link api
> references to manual references in two separate documents. What I want
> to do is full integration, and not be forced into these aggregations.
> 
> And I am being denied. 

You are being denied by RMS.  He controls the copyright, the SC has no
legal say, and he's stubborn as hell.

Re: GFDL/GPL issues

[Alfred M. Szmidt]

   > > So one way to move forward is to effectively have two manuals,
   > > one containing traditional user-written text (GFDL), the other
   > > containing generated text (GPL).  If you print it out as a
   > > book, the generated part would just appear as an appendix to
   > > the manual, it's "mere aggregation".
   > 
   > This is not acceptable to me. 
   > 
   > You have just described the status quo, what we are already
   > doing. It is very difficult to link api references to manual
   > references in two separate documents. What I want to do is full
   > integration, and not be forced into these aggregations.
   > 
   > And I am being denied.

   You are being denied by RMS.  He controls the copyright, the SC has
   no legal say, and he's stubborn as hell.

When presented with weak arguments, then yes he will be stubborn but
rightly so.  

I don't see what the problem is with two manuals, from a users
perspective I actually prefer that and doing cross referencing between
manuals in texinfo is easy.

Re: GFDL/GPL issues

[Paolo Bonzini]

On 08/04/2010 07:34 PM, Alfred M. Szmidt wrote:
>     >  >  So one way to move forward is to effectively have two manuals,
>     >  >  one containing traditional user-written text (GFDL), the other
>     >  >  containing generated text (GPL).  If you print it out as a
>     >  >  book, the generated part would just appear as an appendix to
>     >  >  the manual, it's "mere aggregation".
>     >
>     >  This is not acceptable to me.
>     >
>     >  You have just described the status quo, what we are already
>     >  doing. It is very difficult to link api references to manual
>     >  references in two separate documents. What I want to do is full
>     >  integration, and not be forced into these aggregations.
>     >
>     >  And I am being denied.
>
>     You are being denied by RMS.  He controls the copyright, the SC has
>     no legal say, and he's stubborn as hell.
>
> When presented with weak arguments, then yes he will be stubborn but
> rightly so.
>
> I don't see what the problem is with two manuals, from a users
> perspective I actually prefer that and doing cross referencing between
> manuals in texinfo is easy.

You probably haven't read this thread fully, or you wouldn't imply that 
GCC should have an "options manual" separate from the user's manual.

By the way, it's not an insult to qualify RMS's attitude as "stubborn". 
  And even if it was, he doesn't need a public defender.

Paolo

Re: GFDL/GPL issues

[Paolo Bonzini]

On 08/04/2010 07:34 PM, Alfred M. Szmidt wrote:
>     >  >  So one way to move forward is to effectively have two manuals,
>     >  >  one containing traditional user-written text (GFDL), the other
>     >  >  containing generated text (GPL).  If you print it out as a
>     >  >  book, the generated part would just appear as an appendix to
>     >  >  the manual, it's "mere aggregation".
>     >
>     >  This is not acceptable to me.
>     >
>     >  You have just described the status quo, what we are already
>     >  doing. It is very difficult to link api references to manual
>     >  references in two separate documents. What I want to do is full
>     >  integration, and not be forced into these aggregations.
>     >
>     >  And I am being denied.
>
>     You are being denied by RMS.  He controls the copyright, the SC has
>     no legal say, and he's stubborn as hell.
>
> When presented with weak arguments, then yes he will be stubborn but
> rightly so.
>
> I don't see what the problem is with two manuals, from a users
> perspective I actually prefer that and doing cross referencing between
> manuals in texinfo is easy.

You probably haven't read this thread fully, or you wouldn't imply that 
GCC should have an "options manual" separate from the user's manual.

By the way, it's not an insult to qualify RMS's attitude as "stubborn". 
  And even if it was, he doesn't need a public defender.

Paolo

Re: GFDL/GPL issues

[Joe Buck]

On Wed, Aug 04, 2010 at 10:34:51AM -0700, Alfred M. Szmidt wrote:
>    You are being denied by RMS.  He controls the copyright, the SC has
>    no legal say, and he's stubborn as hell.
> 
> When presented with weak arguments, then yes he will be stubborn but
> rightly so.  
> 
> I don't see what the problem is with two manuals, from a users
> perspective I actually prefer that and doing cross referencing between
> manuals in texinfo is easy.

OK, let's say Don Knuth decides he wants to spend his retirement
contributing to GNU.  RMS is effectively saying that "literate
programming" is banned from the GNU project and Knuth can just go away if
he doesn't like it (and yes, requiring GFDL for documentation and GPL for
code is equivalent to banning literate programming).  This is an
anti-software-freedom argument, an attempt by one man to impose his
personal taste.

For a class library, documentation generators are really the only
reasonable way to provide a maintainable manual.  You need to make
sure that every inheritance relationship is described correctly, and
you need to make sure that, as interfaces change, they are described
consistently and accurately.  The best way to achieve that is to
auto-generate the information.  Sure, as a *user* it works equally
well for you if the maintainers have worked three times as hard to
do by hand what could be done by computer, but there's a high cost.

Re: GFDL/GPL issues

[Alfred M. Szmidt]

   You probably haven't read this thread fully, or you wouldn't imply
   that GCC should have an "options manual" separate from the user's
   manual.

I have read the thread in full, and I do not see the problem with
keeping that info in a seperate manual; GCC has so many options for
various architectures and systems that I think it makes technical
sense to have a "Invoking GCC" manual.

Re: GFDL/GPL issues

[Paolo Bonzini]

On 08/04/2010 08:48 PM, Alfred M. Szmidt wrote:
>     You probably haven't read this thread fully, or you wouldn't imply
>     that GCC should have an "options manual" separate from the user's
>     manual.
>
> I have read the thread in full, and I do not see the problem with
> keeping that info in a seperate manual; GCC has so many options for
> various architectures and systems that I think it makes technical
> sense to have a "Invoking GCC" manual.

The limitation would also apply to target-independent options.

Paolo

Re: GFDL/GPL issues

[Paolo Bonzini]

On 08/04/2010 08:48 PM, Alfred M. Szmidt wrote:
>     You probably haven't read this thread fully, or you wouldn't imply
>     that GCC should have an "options manual" separate from the user's
>     manual.
>
> I have read the thread in full, and I do not see the problem with
> keeping that info in a seperate manual; GCC has so many options for
> various architectures and systems that I think it makes technical
> sense to have a "Invoking GCC" manual.

The limitation would also apply to target-independent options.

Paolo

Re: GFDL/GPL issues

[Jonathan Wakely]

On 4 August 2010 19:48, Alfred M. Szmidt wrote:
>
> I have read the thread in full, and I do not see the problem with
> keeping that info in a seperate manual; GCC has so many options for
> various architectures and systems that I think it makes technical
> sense to have a "Invoking GCC" manual.

And what about libstdc++ API docs, which are currently quite difficult
to cross-reference with the libstdc++ manual, and cannot be included
in it?  The API docs come from C++ sources and the manual from docbook
sources, so texinfo has nothing to do with it.

Re: GFDL/GPL issues

[Alfred M. Szmidt]

   > I have read the thread in full, and I do not see the problem with
   > keeping that info in a seperate manual; GCC has so many options
   > for various architectures and systems that I think it makes
   > technical sense to have a "Invoking GCC" manual.

   And what about libstdc++ API docs, which are currently quite
   difficult to cross-reference with the libstdc++ manual, and cannot
   be included in it?  The API docs come from C++ sources and the
   manual from docbook sources, so texinfo has nothing to do with it.

For a API reference listing document, it would make more sense to
license the work under the GPL, is that possible?  

There is no rule in the GNU project that all types of documentation
must be licensed under the GFDL.  Sometimes it makes sense, good
examples are the gccint, gcc and the emacs manual, and sometimes it
might not like for API reference listings.

Re: GFDL/GPL issues

[Alfred M. Szmidt]

   >    You are being denied by RMS.  He controls the copyright, the SC has
   >    no legal say, and he's stubborn as hell.
   > 
   > When presented with weak arguments, then yes he will be stubborn
   > but rightly so.
   > 
   > I don't see what the problem is with two manuals, from a users
   > perspective I actually prefer that and doing cross referencing
   > between manuals in texinfo is easy.

   OK, let's say Don Knuth decides he wants to spend his retirement
   contributing to GNU.  RMS is effectively saying that "literate
   programming" is banned from the GNU project and Knuth can just go
   away if he doesn't like it (and yes, requiring GFDL for
   documentation and GPL for code is equivalent to banning literate
   programming).  This is an anti-software-freedom argument, an
   attempt by one man to impose his personal taste.

The GFDL isn't required for all types of documentation, sometimes it
makes sense to use the GFDL for a manual (for example, the emacs
manual) sometimes it might not.  For literate programs, the comments
are as much part of the program as the code, it would make little
sense to require the GFDL for the documentation part of that program.
Infact, the literate programs that are part of the GNU project are
simply licensed under the GPL.  So Knuth is most free to join.  :-)

For some manuals, like the libstdc++ manual as someone mentioned,
maybe relicensing it under the GPL makes the most sense, since it is
mostly a API reference listing.  For other manuals, that contain
little auto-generated text, like the GCC manual, or the GCC Internals
manual, the GFDL makes more sense.

Painting all documentation under a single brush is a huge mistake,
sometimes the GFDL makes sense, sometimes it doesn't.  And one should
look at each specific case separately and make a decision based on
that.

Re: GFDL/GPL issues

[Diego Novillo]

On 10-08-04 16:03 , Alfred M. Szmidt wrote:

> There is no rule in the GNU project that all types of documentation
> must be licensed under the GFDL.  Sometimes it makes sense, good
> examples are the gccint

I don't think we want gccint to be under the GFDL.  This is the main 
part of the documentation that I would like to have mostly generated out 
of the code.


Diego.

Re: GFDL/GPL issues

[Richard Guenther]

On Wed, Aug 4, 2010 at 10:03 PM, Alfred M. Szmidt <ams@gnu.org> wrote:
>   > I have read the thread in full, and I do not see the problem with
>   > keeping that info in a seperate manual; GCC has so many options
>   > for various architectures and systems that I think it makes
>   > technical sense to have a "Invoking GCC" manual.
>
>   And what about libstdc++ API docs, which are currently quite
>   difficult to cross-reference with the libstdc++ manual, and cannot
>   be included in it?  The API docs come from C++ sources and the
>   manual from docbook sources, so texinfo has nothing to do with it.
>
> For a API reference listing document, it would make more sense to
> license the work under the GPL, is that possible?
>
> There is no rule in the GNU project that all types of documentation
> must be licensed under the GFDL.  Sometimes it makes sense, good
> examples are the gccint, gcc and the emacs manual, and sometimes it
> might not like for API reference listings.

I can't see how the GFDL "makes sense" for anything.

Richard.

Re: GFDL/GPL issues

[Paolo Bonzini]

On 08/04/2010 10:52 PM, Richard Guenther wrote:
> On Wed, Aug 4, 2010 at 10:03 PM, Alfred M. Szmidt<ams@gnu.org>  wrote:
>>    >  I have read the thread in full, and I do not see the problem with
>>    >  keeping that info in a seperate manual; GCC has so many options
>>    >  for various architectures and systems that I think it makes
>>    >  technical sense to have a "Invoking GCC" manual.
>>
>>    And what about libstdc++ API docs, which are currently quite
>>    difficult to cross-reference with the libstdc++ manual, and cannot
>>    be included in it?  The API docs come from C++ sources and the
>>    manual from docbook sources, so texinfo has nothing to do with it.
>>
>> For a API reference listing document, it would make more sense to
>> license the work under the GPL, is that possible?
>>
>> There is no rule in the GNU project that all types of documentation
>> must be licensed under the GFDL.  Sometimes it makes sense, good
>> examples are the gccint, gcc and the emacs manual, and sometimes it
>> might not like for API reference listings.
>
> I can't see how the GFDL "makes sense" for anything.

Actually, I do see the point in the Front/Back cover texts.  A manual is 
not a program, and those are not the same thing as the BSD advertising 
clause.  Invariant Sections are debatable but we all know why they exist.

However, until there is a possibility to relicense anything GPL->GFDL I 
cannot disagree.  In fact, since the GFDL is more restrictive, it is the 
same thing as the Affero GPL.

Paolo

Re: GFDL/GPL issues

[Joe Buck]

On Wed, Aug 04, 2010 at 02:12:18PM -0700, Paolo Bonzini wrote:
> However, until there is a possibility to relicense anything GPL->GFDL I 
> cannot disagree.  In fact, since the GFDL is more restrictive, it is the 
> same thing as the Affero GPL.

No, because there is explicit language in the Affero GPL and GPL3 to
prevent license incompatibility.

Re: GFDL/GPL issues

[Jonathan Wakely]

On 4 August 2010 21:03, Alfred M. Szmidt <ams@gnu.org> wrote:
>   > I have read the thread in full, and I do not see the problem with
>   > keeping that info in a seperate manual; GCC has so many options
>   > for various architectures and systems that I think it makes
>   > technical sense to have a "Invoking GCC" manual.
>
>   And what about libstdc++ API docs, which are currently quite
>   difficult to cross-reference with the libstdc++ manual, and cannot
>   be included in it?  The API docs come from C++ sources and the
>   manual from docbook sources, so texinfo has nothing to do with it.
>
> For a API reference listing document, it would make more sense to
> license the work under the GPL, is that possible?

Possible? It's required, because it's generated from C++ sources
covered by the GPL. What makes you think making the API reference GPL
would help?  The manual is GFDL. So they can't be combined.  That's a
problem.

The documentation I write for the libstdc++ manual and the
documentation I  write for libstdc++ API reference cannot be combined,
or merged, or derived from each other.

Take it from someone who actually does write the stuff: it's annoying.

Re: GFDL/GPL issues

[Paolo Bonzini]

On 08/04/2010 11:52 PM, Joe Buck wrote:
> On Wed, Aug 04, 2010 at 02:12:18PM -0700, Paolo Bonzini wrote:
>> However, until there is a possibility to relicense anything GPL->GFDL I
>> cannot disagree.  In fact, since the GFDL is more restrictive, it is the
>> same thing as the Affero GPL.
>
> No, because there is explicit language in the Affero GPL and GPL3 to
> prevent license incompatibility.

I know, I'm saying that it's not something unheard of to make the GPL 
compatible with a more restrictive license if there are good reasons to 
do so.

Paolo

Re: GFDL/GPL issues

[Florian Weimer]

* Robert Dewar:

>> Duplication is how other GNU projects handle this.  For instance, many
>> Emacs Lisp functions are documented twice: once as a docstring in the
>> source code (which is roughly equivalent to the comment-in-spec
>> approach), and once in the Elisp reference (which is GFDLed).
>
> Well probably we can all agree that such duplication is undesirable,
> unless it is automated, since documentation can get out of sync.

There's a school of thought that claims that things need to be
described at least twice, both formally and informally.  I don't think
these people mean "code and documentation", but rather "two forms of
documentation".

> In the case of the commented Ada specs, there is no point in duplicating
> them in the Ada documentation, since they are accessible easily in an
> appropriate form in the specs.

This approach is far less useful for languages which haven't got
separate spec files because it encourages programmers of client code
to look at the implementation, potentially picking up implementation
details.  It encourages the documentation writer to accidentally refer
to internals, too.

I don't think it works at all for modern C++ code where the surface
syntax of an API is an emerging property.  (The API of foo's type
ensures that "if (foo) { ...}" works as expected, but the exact
language mechanism which achieves that is an implementation detail, so
you can't really attach a docstring to it.)

On the other hand, it is better to generate *some* free documentation,
instead of assuming that programmers will turn to proprietary
documentation which is freely available on the web.

Re: GFDL/GPL issues

[Richard Kenner]

> I think there is a difference between a novel you can hold and
> read, and computer documentation. My question was not whether
> anyone reads books any more, it was whether people read computer
> manuals in this form any more.

To me, it depends on the type of manual and whether it's for something
new or something I've used already.  For things that I've been using for
a while, I much prefer an on-line manual since it's easily searchable.

But if I have a new piece of software (or hardware) I often print out
the manual to more easily read it (e.g., on the train).

I think the sort of stuff that's under the GFDL is much more likely to be
printed than things (like API documentation) that are automatically generated
and hence GPL'ed.

Re: GFDL/GPL issues

[Robert Dewar]

Florian Weimer wrote:

> I was still referring to computer documentation, but admittedly not
> reference manuals, rather works like introductory texts which have got
> some sort of narrative strucuture which guides the reader.
> 
> For reference manuals, it takes a huge amount of effort to make the
> printed version as useful as a hypertext version, and most reference
> manuals don't go to that length, so I don't see a reason to print them
> either (as long as a there aren't licensing constraints that make
> printing seem favorable).

OK, I fully agree with both points. In practice the issue we are
discussing here (automatic generation of documentation) is more
likely to occur in the latter context.

Re: GFDL/GPL issues

[Robert Dewar]

Florian Weimer wrote:
> * Robert Dewar:
> 
>> In the case of interfaces to library routines, what we do
>> is to have fully commented Ada package specs that act as
>> both the documentation of the implementation interface and
>> as the user documentation (for an example, look at g-spipat.ads).
>> I can't see any value in duplicating this information elsewhere.
> 
> Duplication is how other GNU projects handle this.  For instance, many
> Emacs Lisp functions are documented twice: once as a docstring in the
> source code (which is roughly equivalent to the comment-in-spec
> approach), and once in the Elisp reference (which is GFDLed).

Well probably we can all agree that such duplication is undesirable,
unless it is automated, since documentation can get out of sync.

In the case of the commented Ada specs, there is no point in duplicating
them in the Ada documentation, since they are accessible easily in an
appropriate form in the specs.

The more interesting issue is when the automated documentation does
more than just duplicate, and actually derives information not easily
accessible in the sources.

For example, in the case of the GtkAda documentation,
we actually do generate automatically the GtkAda RM from gtkada spec
files, and there's definitely an added value, since this is not just
a mere duplication: there's extra info (such as type hierarchy info
automatically generated, screenshots, links, ...).

That's the case where the licensing issue is significant. I don't
like the idea of padding out documentation with mere duplication
of code comments (I would rather work on making those comments more
accessible). But when there is additional information generated
automatically, that's a different matter entirely.

Re: GFDL/GPL issues

[Florian Weimer]

* Robert Dewar:

>> People still buy books which are available freely in electronic form.
>> This means that some printing still goes on.
>
> I think there is a difference between a novel you can hold and
> read, and computer documentation. My question was not whether
> anyone reads books any more, it was whether people read computer
> manuals in this form any more.

I was still referring to computer documentation, but admittedly not
reference manuals, rather works like introductory texts which have got
some sort of narrative strucuture which guides the reader.

For reference manuals, it takes a huge amount of effort to make the
printed version as useful as a hypertext version, and most reference
manuals don't go to that length, so I don't see a reason to print them
either (as long as a there aren't licensing constraints that make
printing seem favorable).

Re: GFDL/GPL issues

[Florian Weimer]

* Robert Dewar:

> Does *anyone* print documentation "out as a book", this seems to me
> to be a completely obsolete concept.

People still buy books which are available freely in electronic form.
This means that some printing still goes on.

It might also be necessary to consider what it means when a GFDLed
work is loaded into an electronic reader device.  (My immediate
reaction is that this usually done on explicit request from the reade,
and we're not in the business of restricting reading, but YMMV.)

Re: GFDL/GPL issues

[Richard Kenner]

> This approach is far less useful for languages which haven't got
> separate spec files

But there aren't many of those!  In C, a ".h" file can easily be viewed as
a "separate spec file" and interface documentation can and should be placed
there, though I understand that few coding conventions call for that.

Re: GFDL/GPL issues

[Robert Dewar]

Florian Weimer wrote:
> * Robert Dewar:
> 
>> Does *anyone* print documentation "out as a book", this seems to me
>> to be a completely obsolete concept.
> 
> People still buy books which are available freely in electronic form.
> This means that some printing still goes on.

I think there is a difference between a novel you can hold and
read, and computer documentation. My question was not whether
anyone reads books any more, it was whether people read computer
manuals in this form any more.
> 
> It might also be necessary to consider what it means when a GFDLed
> work is loaded into an electronic reader device.  (My immediate
> reaction is that this usually done on explicit request from the reade,
> and we're not in the business of restricting reading, but YMMV.)

Indeed, an interesting question, and of course in the case of electronic
reading, one can imagine generating absolutely up to date documentation
on demand.

Re: GFDL/GPL issues

[Florian Weimer]

* Robert Dewar:

> In the case of interfaces to library routines, what we do
> is to have fully commented Ada package specs that act as
> both the documentation of the implementation interface and
> as the user documentation (for an example, look at g-spipat.ads).
> I can't see any value in duplicating this information elsewhere.

Duplication is how other GNU projects handle this.  For instance, many
Emacs Lisp functions are documented twice: once as a docstring in the
source code (which is roughly equivalent to the comment-in-spec
approach), and once in the Elisp reference (which is GFDLed).

Re: GFDL/GPL issues

[Joel Sherrill]

On 08/15/2010 04:09 AM, Florian Weimer wrote:
> * Robert Dewar:
>
>    
>>> Duplication is how other GNU projects handle this.  For instance, many
>>> Emacs Lisp functions are documented twice: once as a docstring in the
>>> source code (which is roughly equivalent to the comment-in-spec
>>> approach), and once in the Elisp reference (which is GFDLed).
>>>        
>> Well probably we can all agree that such duplication is undesirable,
>> unless it is automated, since documentation can get out of sync.
>>      
> There's a school of thought that claims that things need to be
> described at least twice, both formally and informally.  I don't think
> these people mean "code and documentation", but rather "two forms of
> documentation".
>    
For RTEMS, that's what we try to do.  There is a User's
manual and the Doxygen generated documentation.
>> In the case of the commented Ada specs, there is no point in duplicating
>> them in the Ada documentation, since they are accessible easily in an
>> appropriate form in the specs.
>>      
> This approach is far less useful for languages which haven't got
> separate spec files because it encourages programmers of client code
> to look at the implementation, potentially picking up implementation
> details.  It encourages the documentation writer to accidentally refer
> to internals, too.
>
>    
That's a matter of style and project code style enforcement.
> I don't think it works at all for modern C++ code where the surface
> syntax of an API is an emerging property.  (The API of foo's type
> ensures that "if (foo) { ...}" works as expected, but the exact
> language mechanism which achieves that is an implementation detail, so
> you can't really attach a docstring to it.)
>
>    
So....?  As a user, I don't care how you implemented it.

Really, most of this is largely a matter of the markup and what
is included in the generated documentation.
RTEMS uses Doxygen for C which is probably not the ideal
language for this.  We have guidelines that the .h file always
defines the interface with no details on the implementation.
If there are things that are implementation specific you need
to document, they go in the bodies and are marked as internal
or whatever.

This way you can easily generate "public view" documents
from only the .h files and "augmented" versions with internal
details if you do .h and bodies.

RTEMS is a very old C project which predates Doxygen
by years.  But we believe in specs versus bodies, interfaces
versus implementations, etc.  It was easy to convert our
comments into Doxygen format.

http://www.rtems.org/onlinedocs/doxygen/cpukit/html/index.html

So just because it is possible to do the markup and
generation badly, doesn't mean it isn't possible to
do a good job in any language which supports separate
specs and bodies.

> On the other hand, it is better to generate *some* free documentation,
> instead of assuming that programmers will turn to proprietary
> documentation which is freely available on the web.
>    
And that's unfortunate. :(

--joel
RTEMS

Re: GFDL/GPL issues

[Florian Weimer]

* Joel Sherrill:

>> This approach is far less useful for languages which haven't got
>> separate spec files because it encourages programmers of client code
>> to look at the implementation, potentially picking up implementation
>> details.  It encourages the documentation writer to accidentally refer
>> to internals, too.

> That's a matter of style and project code style enforcement.

To my knowledge, the GNU project has no guidelines for the contents of
C header files, and heavy use of the preprocessor is rather common. 8-(

>> I don't think it works at all for modern C++ code where the surface
>> syntax of an API is an emerging property.  (The API of foo's type
>> ensures that "if (foo) { ...}" works as expected, but the exact
>> language mechanism which achieves that is an implementation detail, so
>> you can't really attach a docstring to it.)
>>
>>    
> So....?  As a user, I don't care how you implemented it.

That's precisely my point.  Doxygen-style documentation would have to
be attached to an implementation detail, something that the user does
not actually care about.

Re: GFDL/GPL issues

[Miles Bader]

Florian Weimer <fw@deneb.enyo.de> writes:
>>> Duplication is how other GNU projects handle this.  For instance, many
>>> Emacs Lisp functions are documented twice: once as a docstring in the
>>> source code (which is roughly equivalent to the comment-in-spec
>>> approach), and once in the Elisp reference (which is GFDLed).
>>
>> Well probably we can all agree that such duplication is undesirable,
>> unless it is automated, since documentation can get out of sync.
>
> There's a school of thought that claims that things need to be
> described at least twice, both formally and informally.  I don't think
> these people mean "code and documentation", but rather "two forms of
> documentation".

With elisp, I've found that in practice I usually start by copying the
docstring (the "in code doc") to the manual (the "doc doc"), but almost
always end up largely rewriting to fit the context in the manual better,
and to explain things in more detail (modern docstrings tend to be
rather verbose compared to docstrings-of-old, but they're still
generally more terse than the manual).

What this says, I dunno; it'd be nice to have the freedom to just do
whatever's best, of course...

-Miles

-- 
Neighbor, n. One whom we are commanded to love as ourselves, and who does all
he knows how to make us disobedient.

Re: GFDL/GPL issues

[Jonathan Corbet]

On Sun, 15 Aug 2010 04:45:53 -0400
Robert Dewar <dewar@adacore.com> wrote:

> I think there is a difference between a novel you can hold and
> read, and computer documentation. My question was not whether
> anyone reads books any more, it was whether people read computer
> manuals in this form any more.

Just as a random data point, I've been surprised at how well sales of
Linux Device Drivers have held up, despite (1) the book being freely
available online, and (2) the fact that it's hopelessly obsolete.  I
don't know how long it's going to last, but, for now, there is still
interest in this kind of information on dead trees.

jon

Re: GFDL/GPL issues

[Joern Rennecke]

Quoting Miles Bader <miles@gnu.org>:

> With elisp, I've found that in practice I usually start by copying the
> docstring (the "in code doc") to the manual (the "doc doc"), but almost
> always end up largely rewriting to fit the context in the manual better,
> and to explain things in more detail (modern docstrings tend to be
> rather verbose compared to docstrings-of-old, but they're still
> generally more terse than the manual).

Still, if anything copyrightable is left of the copied text, you need
license compatibility (or full copyright to the original text) in order
to be able to publish the result.

I find that a similar process is also often natural with going from code
comments to gcc internals documentation, but if I don't have copyright to
the comment, I don't want to deal with the license problems, so I rather
leave the documentation for someone else (or nobody...) to write.

Re: GFDL/GPL issues

[Richard Kenner]

> > With elisp, I've found that in practice I usually start by copying the
> > docstring (the "in code doc") to the manual (the "doc doc"), but almost
> > always end up largely rewriting to fit the context in the manual better,
> > and to explain things in more detail (modern docstrings tend to be
> > rather verbose compared to docstrings-of-old, but they're still
> > generally more terse than the manual).
> 
> Still, if anything copyrightable is left of the copied text, you need
> license compatibility (or full copyright to the original text) in order
> to be able to publish the result.

Unless one can claim "fair use".  But the above procedure is also likely
to result in taking nothing copyrightable from the original text anyway.

Re: GFDL/GPL issues

[Joern Rennecke]

Quoting Richard Kenner <kenner@vlsi1.ultra.nyu.edu>:

> Unless one can claim "fair use".  But the above procedure is also likely
> to result in taking nothing copyrightable from the original text anyway.

But fair use does not apply here (geographically), and I don't want to
have to consult a copyright lawyer to verify if I can safely submit my patch.

Plus, even if there was a cheap and quick test to find out if the result
is publishable, there is the hazard that you end up with something you
can't publish, and it's one more piece of unpublished non-mainline code
that makes it more complicated recall what really is in mainline and in
the set of submitted-but-not-yet-reviewed patches.

Re: GFDL/GPL issues

[Brian Makin]

I'd hate to see generated documented discounted so quickly.  
Especially if the alternative is no documentation.

I'd note the QT docs as a great example of embedded 
comments and auto generated documentation done very well.



      

Re: GFDL/GPL issues

[Joe Buck]

On Thu, Jul 29, 2010 at 01:20:45PM -0700, Brian Makin wrote:
> Or to move to a better foundation?  It seems to me that gcc has had various 
> issues for various reasons for quite a while now.  RMS is all for tightly 
> controller yet freely distributable software.
> Maybe it's time to throw more effort behind something like LLVM?

This is the gcc development list.  If you want to contribute to LLVM,
that's fine, but if so you're on the wrong list.

Re: GFDL/GPL issues

[Brian Makin]

>On Thu, Jul 29, 2010 at 12:08 AM, Steven Bosscher <stevenb.gcc@gmail.com> 
wrote:
>> On Wed, Jul 28, 2010 at 11:17 PM, Mark Mitchell <mark@codesourcery.com> 
wrote:
>>> Steven Bosscher wrote:
>>>
>>>>> Why not just ignore RMS and the license issues and simply do what we
>>>>> think suits us and the project.  Let the FSF deal with the legal 
>>>consequences,
>>>>> they put us in this messy situation, they deal with it.
>>>>
>>>> It seems to me that escalating the issue is more helpful. GCC is not
>>>> the only project with this problem.
>>>
>>> Sadly, at this point, RMS is simply taking the position that this is not
>>> a problem worth solving.
>>
>> Ah, how the "free" in Free Software Foundation takes a whole different
>> meaning when it comes to actual freedom...
>
>Ha!  Sounds like time to overturn the (benevolent?) dictator!
>
>Richard.

Or to move to a better foundation?  It seems to me that gcc has had various 
issues for various reasons for quite a while now.  RMS is all for tightly 
controller yet freely distributable software.
Maybe it's time to throw more effort behind something like LLVM?