Autogenerate gdbarch doc for internals manual

Autogenerate gdbarch doc for internals manual

[Stan Shebs]

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

Re: Autogenerate gdbarch doc for internals manual

[Joseph S. Myers]

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

Re: Autogenerate gdbarch doc for internals manual

[Stan Shebs]

Joseph S. Myers wrote:
> 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).
>   
Ouch, I hadn't even thought of that! But then how does that work for 
libiberty, which collects snippets from LGPL files and pastes them into 
functions.texi, which is included in the GFDLed manual?

Stan

Re: Autogenerate gdbarch doc for internals manual

[Mark Kettenis]

> Date: Fri, 01 Aug 2008 10:39:14 -0700
> From: Stan Shebs <stan@codesourcery.com>
> 
> > 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).
> >   
> Ouch, I hadn't even thought of that! But then how does that work for 
> libiberty, which collects snippets from LGPL files and pastes them into 
> functions.texi, which is included in the GFDLed manual?

Shhht, don't tell the lawyers!

Re: Autogenerate gdbarch doc for internals manual

[Eli Zaretskii]

> Date: Fri, 01 Aug 2008 10:06:05 -0700
> From: Stan Shebs <stan@codesourcery.com>
> 
> 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 :-) ),

Hey, I didn't respond because you didn't ask for any specific decision
there.  All I see in that message (and I just re-read it to refresh my
memory) is that you tell us you are working on a script that would
announce discrepancies between the docs and the code; a very good
initiative, IMO.

> 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 my agreement.

Thanks!

Re: Autogenerate gdbarch doc for internals manual

[Jeremy Bennett]

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

Re: Autogenerate gdbarch doc for internals manual

[Eli Zaretskii]

> Date: Fri, 1 Aug 2008 17:22:12 +0000 (UTC)
> From: "Joseph S. Myers" <joseph@codesourcery.com>
> cc: gdb@sourceware.org
> 
> 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.  

That depends on how Stan writes those parts.  We could, for instance,
have some template outside gdbarch.sh which the script will edit to
produce the actual Texinfo.

In general, there's any number of ways to do this job without
violating the GNU licenses.

> 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 

RMS always asserted that such jobs will not present any
license-related problems in practice.  I can run the idea through him
in advance and see if he has any specific advice, if Stan would like
that before he embarks on doing this job.

Re: Autogenerate gdbarch doc for internals manual

[Eli Zaretskii]

> Date: Fri, 01 Aug 2008 10:39:14 -0700
> From: Stan Shebs <stan@codesourcery.com>
> CC: Stan Shebs <stan@codesourcery.com>, gdb@sourceware.org
> 
> how does that work for libiberty, which collects snippets from LGPL
> files and pastes them into functions.texi, which is included in the
> GFDLed manual?

Not only libiberty does that; bfd does that as well.  I very much
doubt that this is somehow an omission on the part of FSF lawyers.

Re: Autogenerate gdbarch doc for internals manual

[Daniel Jacobowitz]

On Fri, Aug 01, 2008 at 09:37:39PM +0300, Eli Zaretskii wrote:
> > Date: Fri, 01 Aug 2008 10:39:14 -0700
> > From: Stan Shebs <stan@codesourcery.com>
> > CC: Stan Shebs <stan@codesourcery.com>, gdb@sourceware.org
> > 
> > how does that work for libiberty, which collects snippets from LGPL
> > files and pastes them into functions.texi, which is included in the
> > GFDLed manual?
> 
> Not only libiberty does that; bfd does that as well.  I very much
> doubt that this is somehow an omission on the part of FSF lawyers.

On the other hand, it took me some weeks and a go-around with the FSF
to get a correct license on observers.texi.  I think it's simply an
omission, but it will be a hassle to fix up if someone points it out.

-- 
Daniel Jacobowitz
CodeSourcery

Re: Autogenerate gdbarch doc for internals manual

[Stan Shebs]

Eli Zaretskii wrote:
>> Date: Fri, 1 Aug 2008 17:22:12 +0000 (UTC)
>> From: "Joseph S. Myers" <joseph@codesourcery.com>
>> cc: gdb@sourceware.org
>>
>>     
>> 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 
>>     
>
> RMS always asserted that such jobs will not present any
> license-related problems in practice.  I can run the idea through him
> in advance and see if he has any specific advice, if Stan would like
> that before he embarks on doing this job.
>   
If you'd do that, I'd sure appreciate it! It's not a rush situation, and 
there are plenty of other doc bits to work on in the meantime.

Stan