Re: GFDL/GPL issues
On Sun, 15 Aug 2010 04:45:53 -0400 Robert Dewar de...@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
Quoting Miles Bader mi...@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
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
Quoting Richard Kenner ken...@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
* 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
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
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
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
* 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
* 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
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
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
* 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
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
* 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
Florian Weimer f...@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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
On Wed, Aug 4, 2010 at 10:03 PM, Alfred M. Szmidt a...@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
On 08/04/2010 10:52 PM, Richard Guenther wrote: On Wed, Aug 4, 2010 at 10:03 PM, Alfred M. Szmidta...@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
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
On 4 August 2010 21:03, Alfred M. Szmidt a...@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
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
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
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
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
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
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
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 jos...@codesourcery.com
Re: GFDL/GPL issues
On Tue, Aug 3, 2010 at 8:48 PM, Robert Dewar de...@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
Robert Dewar de...@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
On Sat, Jul 31, 2010 at 00:16, Mark Mitchell m...@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
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
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
On Tue, Aug 3, 2010 at 1:17 AM, Richard Kenner ken...@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
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
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
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, 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
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
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
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
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
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
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
Quoting Mark Mitchell m...@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
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: t...@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
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 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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
Quoting Robert Dewar de...@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
Please move such unconstructive arguments elsewhere.
Re: GFDL/GPL issues
Alfred M. Szmidt a...@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
Ian Lance Taylor i...@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
Ian Lance Taylor wrote: Alfred M. Szmidt a...@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: t...@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
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
Quoting Richard Kenner ken...@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
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
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
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
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
On Thu, Jul 29, 2010 at 12:08 AM, Steven Bosscher stevenb@gmail.com wrote: On Wed, Jul 28, 2010 at 11:17 PM, Mark Mitchell m...@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?
Re: GFDL/GPL issues
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
On Tue, Jul 27, 2010 at 10:25 PM, Richard Guenther richard.guent...@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
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
On Wed, Jul 28, 2010 at 11:17 PM, Mark Mitchell m...@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
On Thu, Jul 29, 2010 at 12:08 AM, Steven Bosscher stevenb@gmail.com wrote: On Wed, Jul 28, 2010 at 11:17 PM, Mark Mitchell m...@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
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
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
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
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
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
On Tue, Jul 27, 2010 at 8:09 PM, Mark Mitchell m...@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
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
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
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
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
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
Mark Mitchell m...@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 m...@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
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
Mark Mitchell m...@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
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
On Fri, Jul 23, 2010 at 1:22 AM, Mark Mitchell m...@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
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 m...@codesourcery.com (650) 331-3385 x713
Re: GFDL/GPL issues
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
Quoting Joe Buck joe.b...@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
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 m...@codesourcery.com (650) 331-3385 x713