Re: Documentation generated from sources proposal

[Jeremy Bennett <jeremy dot bennett at embecosm dot com>]

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