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.
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
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
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
* 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
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
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
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
* 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
* 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
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
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
* 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
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
* 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
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
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
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
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
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
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
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
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
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
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
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
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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
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
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
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
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
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
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
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
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
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
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
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
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
Please move such unconstructive arguments elsewhere.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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;
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
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
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
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
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
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
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
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)
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
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
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.
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,
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
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
1 - 100 of 134 matches
Mail list logo
