Documentation generated from sources proposal

Documentation generated from sources proposal

[Jan Kratochvil]

Hi,

currently there is gdb/doc/gdbint.texinfo referencing gdb/ sources functions
and duplicating various comments in the gdb/*.c sources.  At the same time the
gdb/doc/gdbint.texinfo content is obsolete and one usually misses it when
dealing with the sources.

May the GDB project start using some tool to format documentation from the
sources?  One could move the appropriate parts of gdb/doc/gdbint.texinfo into
gdb/*.c along the patches being submitted, keeping in gdb/doc/gdbint.texinfo
only the abstract parts in the future.

This proposal was already discussed in the past.

Vote from me for gtk-doc, its plus is that it is a part of GNU project GTK.



Thanks,
Jan

Re: Documentation generated from sources proposal

[Tom Tromey]

>>>>> "Jan" == Jan Kratochvil <jan.kratochvil@redhat.com> writes:

Jan> May the GDB project start using some tool to format documentation
Jan> from the sources?  One could move the appropriate parts of
Jan> gdb/doc/gdbint.texinfo into gdb/*.c along the patches being
Jan> submitted, keeping in gdb/doc/gdbint.texinfo only the abstract
Jan> parts in the future.

I would like to do this, but my understanding is that there is a
licensing problem, in that the source is GPL and the documentation is
GFDL.  (Joseph Myers has mentioned this several times on the GCC lists.)

Until that is resolved I don't think any progress can be made here.

Apparently we got some kind of special permission for observer.texi, so
I suppose it is possible in principle.

Tom

Re: Documentation generated from sources proposal

[Jan Kratochvil]

On Mon, 12 Oct 2009 19:12:25 +0200, Tom Tromey wrote:
> I would like to do this, but my understanding is that there is a
> licensing problem, in that the source is GPL and the documentation is
> GFDL.  (Joseph Myers has mentioned this several times on the GCC lists.)
> 
> Until that is resolved I don't think any progress can be made here.

Still GDB can already start using new gdbint-type documentation parts in the
sources instead of writing it in gdbint.texinfo and obsoleting the parts in
gdbint.texinfo, just one cannot move updated parts.


Regards,
Jan

Re: Documentation generated from sources proposal

[Daniel Jacobowitz]

On Mon, Oct 12, 2009 at 07:15:56PM +0200, Jan Kratochvil wrote:
> On Mon, 12 Oct 2009 19:12:25 +0200, Tom Tromey wrote:
> > I would like to do this, but my understanding is that there is a
> > licensing problem, in that the source is GPL and the documentation is
> > GFDL.  (Joseph Myers has mentioned this several times on the GCC lists.)
> > 
> > Until that is resolved I don't think any progress can be made here.
> 
> Still GDB can already start using new gdbint-type documentation parts in the
> sources instead of writing it in gdbint.texinfo and obsoleting the parts in
> gdbint.texinfo, just one cannot move updated parts.

Not without changing the license of the GDB Internals manual.

-- 
Daniel Jacobowitz
CodeSourcery

Re: Documentation generated from sources proposal

[Jan Kratochvil]

On Mon, 12 Oct 2009 20:00:27 +0200, Daniel Jacobowitz wrote:
> On Mon, Oct 12, 2009 at 07:15:56PM +0200, Jan Kratochvil wrote:
> > Still GDB can already start using new gdbint-type documentation parts in the
> > sources instead of writing it in gdbint.texinfo and obsoleting the parts in
> > gdbint.texinfo, just one cannot move updated parts.
> 
> Not without changing the license of the GDB Internals manual.

This is still misunderstood.

I can write a completely new comment in gdb/breakpoint.c in the gtk-doc
format.  This new comment is unrelated to the license of gdbint.texinfo.

Still such possibility would not be enough for my current patch so it will
probably still remain unresolved for some time.


Regards,
Jan

Re: Documentation generated from sources proposal

[Daniel Jacobowitz]

On Mon, Oct 12, 2009 at 08:07:04PM +0200, Jan Kratochvil wrote:
> I can write a completely new comment in gdb/breakpoint.c in the gtk-doc
> format.  This new comment is unrelated to the license of gdbint.texinfo.

Sure you can.  But the comment would be under the GPL.  The resulting
manual (the GDB Internals manual, not the gdbint.texinfo source file)
could not be distributed under the GFDL.

-- 
Daniel Jacobowitz
CodeSourcery

Re: Documentation generated from sources proposal

[Jan Kratochvil]

On Mon, 12 Oct 2009 20:13:38 +0200, Daniel Jacobowitz wrote:
> Sure you can.  But the comment would be under the GPL.  The resulting
> manual (the GDB Internals manual, not the gdbint.texinfo source file)
> could not be distributed under the GFDL.

I expected to start some new separate GDB Reference Manual with whatever
compliant license (therefore probably the GPLv3 one).

The new file format (such as gtk-doc output choices) would be difficult to
merge with existing gdbint texinfo source or its output formats.


Thanks,
Jan

Re: Documentation generated from sources proposal

[Tom Tromey]

>>>>> "Jan" == Jan Kratochvil <jan.kratochvil@redhat.com> writes:

Jan> On Mon, 12 Oct 2009 20:13:38 +0200, Daniel Jacobowitz wrote:
>> Sure you can.  But the comment would be under the GPL.  The resulting
>> manual (the GDB Internals manual, not the gdbint.texinfo source file)
>> could not be distributed under the GFDL.

Jan> I expected to start some new separate GDB Reference Manual with whatever
Jan> compliant license (therefore probably the GPLv3 one).

I imagine that the FSF would require us to GFDL any new manual.

I support this effort in general but it can't really be resolved here.

Jan> The new file format (such as gtk-doc output choices) would be difficult to
Jan> merge with existing gdbint texinfo source or its output formats.

I am purposely avoiding this discussion until the legal stuff is dealt
with :-)

Tom

Re: Documentation generated from sources proposal

[Jan Kratochvil]

On Mon, 12 Oct 2009 20:26:46 +0200, Tom Tromey wrote:
> >>>>> "Jan" == Jan Kratochvil <jan.kratochvil@redhat.com> writes:
> Jan> I expected to start some new separate GDB Reference Manual with whatever
> Jan> compliant license (therefore probably the GPLv3 one).
> 
> I imagine that the FSF would require us to GFDL any new manual.

OK, got the point now.  And having a single .c file licensed both GPLv3 and
GFDL is either even not possible or at least a subject for legal discussion.


Thanks for info,
Jan

Re: Documentation generated from sources proposal

[Eli Zaretskii]

> From: Tom Tromey <tromey@redhat.com>
> Cc: gdb@sourceware.org
> Date: Mon, 12 Oct 2009 11:12:25 -0600
> 
> >>>>> "Jan" == Jan Kratochvil <jan.kratochvil@redhat.com> writes:
> 
> Jan> May the GDB project start using some tool to format documentation
> Jan> from the sources?  One could move the appropriate parts of
> Jan> gdb/doc/gdbint.texinfo into gdb/*.c along the patches being
> Jan> submitted, keeping in gdb/doc/gdbint.texinfo only the abstract
> Jan> parts in the future.
> 
> I would like to do this, but my understanding is that there is a
> licensing problem, in that the source is GPL and the documentation is
> GFDL.  (Joseph Myers has mentioned this several times on the GCC lists.)

Then how come libiberty and other packages do that?

I'd suggest to clear this up with RMS.

> Apparently we got some kind of special permission for observer.texi, so
> I suppose it is possible in principle.

observer.texi is not documentation, it's code written in Texinfo.

Re: Documentation generated from sources proposal

[Eli Zaretskii]

> Date: Mon, 12 Oct 2009 18:14:24 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> 
> May the GDB project start using some tool to format documentation from the
> sources?  One could move the appropriate parts of gdb/doc/gdbint.texinfo into
> gdb/*.c along the patches being submitted, keeping in gdb/doc/gdbint.texinfo
> only the abstract parts in the future.

Assuming the license problem is resolved, I'll support this, provided
that someone steps forward to do the initial job of moving the
up-to-date parts of gdbint to the sources and developing the
infrastructure for processing comments into Texinfo.

Re: Documentation generated from sources proposal

[Daniel Jacobowitz]

On Mon, Oct 12, 2009 at 08:55:42PM +0200, Eli Zaretskii wrote:
> Then how come libiberty and other packages do that?

I suspect, because no one has reported the problem in libiberty to
the FSF.

-- 
Daniel Jacobowitz
CodeSourcery

Re: Documentation generated from sources proposal

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

>> Apparently we got some kind of special permission for observer.texi, so
>> I suppose it is possible in principle.

Eli> observer.texi is not documentation, it's code written in Texinfo.

We were talking about the license, not its inherent nature.
It is GFDL plus an exception.

Tom

Re: Documentation generated from sources proposal

[Eli Zaretskii]

> From: Tom Tromey <tromey@redhat.com>
> Cc: jan.kratochvil@redhat.com, gdb@sourceware.org
> Date: Mon, 12 Oct 2009 13:25:01 -0600
> 
> >>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Apparently we got some kind of special permission for observer.texi, so
> >> I suppose it is possible in principle.
> 
> Eli> observer.texi is not documentation, it's code written in Texinfo.
> 
> We were talking about the license, not its inherent nature.
> It is GFDL plus an exception.

The exception was possible _because_ observer.texi is not
documentation at all.  If it were a real manual, the FSF would never
give any waivers.

Re: Documentation generated from sources proposal

[Jeremy Bennett]

On Mon, 2009-10-12 at 20:58 +0200, Eli Zaretskii wrote:
> > Date: Mon, 12 Oct 2009 18:14:24 +0200
> > From: Jan Kratochvil <jan.kratochvil@redhat.com>
> > 
> > May the GDB project start using some tool to format documentation from the
> > sources?  One could move the appropriate parts of gdb/doc/gdbint.texinfo into
> > gdb/*.c along the patches being submitted, keeping in gdb/doc/gdbint.texinfo
> > only the abstract parts in the future.
> 
> Assuming the license problem is resolved, I'll support this, provided
> that someone steps forward to do the initial job of moving the
> up-to-date parts of gdbint to the sources and developing the
> infrastructure for processing comments into Texinfo.

I support this approach - we use it in house all the time. Once the
legal side is sorted out, I'm quite happy to contribute by migrating the
relevant parts of gdbint to the sources.

One suggestion: gtk-doc is not that general purpose. Doxygen (as
recommended by the gtk-doc website) might prove a more flexible
alternative.

The one caveat is that neither of these programs can generate Texinfo,
so generating .info files will be hard (all the other output formats,
including man pages can be generated directly, at least by Doxygen). In
principle it could be done (gtk-doc->docbook->texinfo->info or
doxygen->XML->texinfo->info), but who knows what the output might end up
like!

ATB,


Jeremy

-- 
Tel:      +44 (1590) 610184
Cell:     +44 (7970) 676050
SkypeID: jeremybennett
Email:   jeremy.bennett@embecosm.com
Web:     www.embecosm.com

Re: Documentation generated from sources proposal

[Eli Zaretskii]

> From: Jeremy Bennett <jeremy.bennett@embecosm.com>
> Cc: Jan Kratochvil <jan.kratochvil@redhat.com>, gdb@sourceware.org
> Date: Tue, 13 Oct 2009 09:23:37 +0100
> 
> One suggestion: gtk-doc is not that general purpose. Doxygen (as
> recommended by the gtk-doc website) might prove a more flexible
> alternative.
> 
> The one caveat is that neither of these programs can generate Texinfo,
> so generating .info files will be hard (all the other output formats,
> including man pages can be generated directly, at least by Doxygen). In
> principle it could be done (gtk-doc->docbook->texinfo->info or
> doxygen->XML->texinfo->info), but who knows what the output might end up
> like!

No, the format generated from the comments must be Texinfo.

Can't we use whatever libiberty is using (gather-doc), and format the
comments as it does?  Why do we need to switch to such drastically
different tools?

Re: Documentation generated from sources proposal

[Jan Kratochvil]

On Tue, 13 Oct 2009 20:18:28 +0200, Eli Zaretskii wrote:
> No, the format generated from the comments must be Texinfo.

Are there some specific technical or FSF reasons?

The reference manuals are normally delivered as HTML.
http://library.gnome.org/devel/gtk/stable/
http://java.sun.com/javase/6/docs/api/


> Can't we use whatever libiberty is using (gather-doc), and format the
> comments as it does?  Why do we need to switch to such drastically
> different tools?

I freely admit a side track of my proposal was to be able to start writing the
doc in a different format than texinfo.

Still a .c-placed doc even in the texinfo format I find a useful improvement.


Regards,
Jan

Re: Documentation generated from sources proposal

[Eli Zaretskii]

> Date: Tue, 13 Oct 2009 21:13:01 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: jeremy.bennett@embecosm.com, gdb@sourceware.org
> 
> On Tue, 13 Oct 2009 20:18:28 +0200, Eli Zaretskii wrote:
> > No, the format generated from the comments must be Texinfo.
> 
> Are there some specific technical or FSF reasons?

Both.  The GNU Project writes documentation in Texinfo, and if I need
to be responsible for the GDB manuals, I need to be an expert in the
language we use to write them.

> I freely admit a side track of my proposal was to be able to start writing the
> doc in a different format than texinfo.

I don't see a need to start that battle.  Texinfo is more than
adequate for GDB, IMO.

> Still a .c-placed doc even in the texinfo format I find a useful improvement.

Yes, of course.

Re: Documentation generated from sources proposal

[Mark Kettenis]

> X-SWARE-Spam-Status: No, hits=-2.5 required=5.0 	tests=AWL,BAYES_00,SPF_HELO_PASS,SPF_PASS
> Date: Mon, 12 Oct 2009 18:14:24 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> 
> Hi,
> 
> currently there is gdb/doc/gdbint.texinfo referencing gdb/ sources functions
> and duplicating various comments in the gdb/*.c sources.  At the same time the
> gdb/doc/gdbint.texinfo content is obsolete and one usually misses it when
> dealing with the sources.
> 
> May the GDB project start using some tool to format documentation from the
> sources?  One could move the appropriate parts of gdb/doc/gdbint.texinfo into
> gdb/*.c along the patches being submitted, keeping in gdb/doc/gdbint.texinfo
> only the abstract parts in the future.
> 
> This proposal was already discussed in the past.

I'm not a big fan of this sort od documentation for three reasons:

1. It makes it harder to write documentation in the code since you
   need to use the proper markup commands.  And depending on the tool
   used for this there may be restrictions on how comments have to be
   structured.

2. It makes it harder to read comments in the source code, since they
   will contain all sorts of distracting markup.

3. In my experience the approach usually leads to fairly useless
   documentation.