Re: Autogenerate gdbarch doc for internals manual

["Joseph S. Myers" <joseph at codesourcery dot com>]

On Fri, 1 Aug 2008, 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.

You have the issue that's been discussed before in the GCC context: the 
need for an appropriate license text on gdbarch.sh to allow parts of it to 
be used in the manual that's under a different license from the code.  
Good luck getting the FSF to produce a GPLv3 exception text for this in 
reasonable time given how long all the other exceptions have taken so far 
(getting the manual GPLed seems even less likely).

-- 
Joseph S. Myers
joseph@codesourcery.com