Re: Autogenerate gdbarch doc for internals manual

[Jeremy Bennett <jeremy.bennett@embecosm.com>]

On Fri, 2008-08-01 at 10:06 -0700, Stan Shebs wrote:
> Undeterred by the stunning lack of response to my last internals manuals 
> query (http://sourceware.org/ml/gdb/2008-07/msg00309.html, not too late 
> to speak up :-) ), I bring up an idea suggested on irc, which is to 
> generate the internals manual's detailed description of gdbarch methods 
> from gdbarch.sh . Although I'm not generally a fan of autogenerated docs 
> - I find they tend to be heavy on syntax, and light on semantics - the 
> internals manual has fallen way behind what is actually in gdbarch, and 
> there are other manual sections that can talk more about how all the 
> different methods work together.
> 
> Mechanically, the way I see it working is that running gdbarch.sh 
> produces a third file, doc/gdbarch.texi, which is then included in 
> doc/gdbint.texinfo. Some gdbint.texinfo bits will migrate into 
> gdbarch.sh; I don't think there will be a problem including texinfo 
> markup in gdbarch.sh, just need basic @foo{} constructs to get passed 
> through. This is going to be more of a background task for me, but I 
> wanted to get some agreement on the direction before starting to tinker.
> 
> Stan

Hi Stan,

As an outsider, who's recently dived into the workings of GDB, I'd
encourage anything that keeps the internals manual up to date and
complete. I'm a strong believer in auto-generating as much of this sort
of documentation as possible. Write it down once in one place is the
only way that ever works. Even in the current internals manual, a lot of
the content duplicates comments in the header files - except it's out of
date.

Auto-generating does tend to emphasize the syntax, but even that's
better than nothing. A good discipline in commenting global functions
and variables goes a long way to fixing this. GDB code is well
disciplined already, so this should fit with the coding culture.

For what it's worth I've had good experience with Doxygen as a tool for
this, so long as the commenting discipling is observed. That's for the C
code - you would have to pre-process for gdbarch.sh.

I'd be dismayed if the GFDL/GPL conflict was to get in the way of this.
Every internals manual I know quotes heavily from the code it is
describing - doing the same automatically doesn't particularly change
the legal position. I'd suggest that what is needed is not a particular
exception for GDB, but a general clarification of the position for all
GPL/LGPL/AGPL/GFDL projects.

The most significant problem I found was lack of a "big picture" section
to the internals document. What are the chunks I put together to port a
new architecture to GDB? I'm writing up my recent experiences in doing a
first port of an architecture to GDB. When it's complete I'll share it
with this group.

Keep up the good work.


Jeremy

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