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.
gcc-4.3-20100815 is now available
Snapshot gcc-4.3-20100815 is now available on ftp://gcc.gnu.org/pub/gcc/snapshots/4.3-20100815/ and on various mirrors, see http://gcc.gnu.org/mirrors.html for details. This snapshot has been generated from the GCC 4.3 SVN branch with the following options: svn://gcc.gnu.org/svn/gcc/branches/gcc-4_3-branch revision 163267 You'll find: gcc-4.3-20100815.tar.bz2 Complete GCC (includes all of below) SHA1=4fa7230c4535f91521bda26cc225508fe0b4e626 gcc-core-4.3-20100815.tar.bz2C front end and core compiler SHA1=a67a0288a170edc807b4cc9a655b26626f6d64a9 gcc-ada-4.3-20100815.tar.bz2 Ada front end and runtime SHA1=e6d1ece000be13dd6c46527fefb6116d4068deeb gcc-fortran-4.3-20100815.tar.bz2 Fortran front end and runtime SHA1=a9ac72d1cec14f2c6870f37c83b204a2d04d0032 gcc-g++-4.3-20100815.tar.bz2 C++ front end and runtime SHA1=40405597744e11b79dbb52f81f4cf501f2024c72 gcc-java-4.3-20100815.tar.bz2Java front end and runtime SHA1=6347afa317fef174bcddd9d587bef7654f1298bb gcc-objc-4.3-20100815.tar.bz2Objective-C front end and runtime SHA1=21ebc9770dbbc844c88e7e1d22329be2c2e567a3 gcc-testsuite-4.3-20100815.tar.bz2 The GCC testsuite SHA1=260d59206ea22f06b4535a867ea1d91f9a9482d9 Diffs from 4.3-20100808 are available in the diffs/ subdirectory. When a particular snapshot is ready for public consumption the LATEST-4.3 link is updated and a message is sent to the gcc list. Please do not use a snapshot before it has been announced that way.
Re: gcc-4.3-20100815 is now available
On Sun, 15 Aug 2010, gccad...@gcc.gnu.org wrote: > gcc-4.3-20100815.tar.bz2 Complete GCC (includes all of below) > > > SHA1=4fa7230c4535f91521bda26cc225508fe0b4e626 In case anyone wonders, given the weakness of md5 I added sha1 as an additional hash¹. md5 is just missing due to an single extra blank I had inserted before the script ran in production, my bad. I'll commit and post the patch after the next regular snapshot which runs on Tuesday. Gerald ¹ I know, sha1 also is under attack, openssl on our host doesn't support ssh2 yet, though.
Re: x86 assembler syntax
Hi Rick (and others), On Thu, 12 Aug 2010, Rick C. Hodgin wrote: >> This question would have been more appropriate on the gcc-help mailing >> list. -Ian Lance Taylor > My apologies to everyone. I did not know such a list existed. all of our web pages have a footer which refers to gcc-help, but apparently this pointer is not working sufficiently well. This is _not_ to blame anyone, rather I'd like to see whether/how I can improve the situation. Any suggestions? Gerald
Re: x86 assembler syntax
On Sun, Aug 15, 2010 at 2:44 PM, Gerald Pfeifer wrote: > Hi Rick (and others), > > On Thu, 12 Aug 2010, Rick C. Hodgin wrote: >>> This question would have been more appropriate on the gcc-help mailing >>> list. -Ian Lance Taylor >> My apologies to everyone. I did not know such a list existed. > > all of our web pages have a footer which refers to gcc-help, but > apparently this pointer is not working sufficiently well. > > This is _not_ to blame anyone, rather I'd like to see whether/how > I can improve the situation. Any suggestions? Apart from using the name gcc@gcc.gnu.org for the help list, and gcc-...@gcc.gnu.org for developers (who should be able to find the right list)? Maybe it's too late for that, but it's unfortunate that the primary mailing list name is taken for the implementors, not the users. -- James
Re: GFDL/GPL issues
Florian Weimer 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.
