Re: ANNOUNCE: The GTK+ Reference Documentation Project

[Owen Taylor <otaylor redhat com>]

David Helder <dhelder@umich.edu> writes:

> Why not use a javadoc-like system where documentation can been written
> along with the declarations in the headers?
> 
> The advantages are that:
> * The documention can be kept up-to-date as development progresses.
> * It encourages the developers to write the reference documentation, which
> 	they should be doing in the first place.
> * It aids in debugging because the testers know what the functions do and
> 	can easily determine if they are performing correctly.
> 
> There may even be a program that will generate DocBook SGML DTD.  You
> could even modify the gtk-doc scanner to grab comments in front of the
> functions.

gtk-doc already can do that, and the GNOME project is using
this capability in gtk-doc. We have chosen not to go that 
route for a couple of reasons:

 1) We are interested documenting 1.2. 1.2 is already stable,
    and close to release, and we don't want to have to 
    go in and modify all the source files to include 
    the documentation.

 2) It is our belief that concentrating on the documentation
    independent of the code will produce more readable
    and useable documentation. 
 
> I would also encourage the developers not to accept any new code in 1.3
> that isn't completely documented, with a tutorial.
> 
> Also, will the book be free?  Maybe the copyright should be assigned to
> GNU or FSF, rather than the people publishing the book.

The material from the Reference Documentation Project
will be freely modifiable, reprintable and redistributable. 
Because of  this it really shouldn't matter who is holding 
copyright. The reason for assignment of copyright is
that there simply needs to be a clear copyright holder
for the purpose of assigning a license. This is the
same reason that projects like X or GNU require assignments
of copyright.

I'll agree with you that it having the copyright assigned
to a non-profit organization would be preferrable.
Unfortunately, we were unable to come up with a good
alternative. Because there isn't yet a good agreement on 
what the appropriate terms for licensing and distributing 
free software documentation are, there was some discomfort 
at assigning copyright to the FSF at the present time.

Hopefully, in the future, the appropriate organization
will become apparent, either the FSF or somebody else.
At that point, we will be able to transfer the copyright.

Regards,
                                        Owen


[
  P.S. - As mentioned in the announcement, if are
  eager to contribute, but just can't stand the thought
  of turning over the copyright to Red Hat, do let us know,
  so we can try to arrange an alternative.
]