From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 27225 invoked by alias); 1 Aug 2008 18:34:49 -0000 Received: (qmail 27211 invoked by uid 22791); 1 Aug 2008 18:34:49 -0000 X-Spam-Check-By: sourceware.org Received: from mail.idnet.net.uk (HELO mail.idnet.net.uk) (212.69.36.63) by sourceware.org (qpsmtpd/0.31) with ESMTP; Fri, 01 Aug 2008 18:34:20 +0000 Received: from [91.135.5.64] by mail.idnet.net.uk (GMS 15.00.3626/NU3963.00.7ca42f0c) with ESMTP id ojtptkba for gdb@sourceware.org; Fri, 1 Aug 2008 19:34:16 +0100 Subject: Re: Autogenerate gdbarch doc for internals manual From: Jeremy Bennett Reply-To: jeremy.bennett@embecosm.com To: gdb@sourceware.org In-Reply-To: <4893427D.1000909@codesourcery.com> References: <4893427D.1000909@codesourcery.com> Content-Type: text/plain Date: Fri, 01 Aug 2008 18:34:00 -0000 Message-Id: <1217615665.2879.40.camel@thomas> Mime-Version: 1.0 X-Mailer: Evolution 2.22.3.1 (2.22.3.1-1.fc9) Content-Transfer-Encoding: 7bit X-AuthenticatedSender: jeremy.bennett.embecosm.com@idnet.net.uk X-IsSubscribed: yes Mailing-List: contact gdb-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sourceware.org X-SW-Source: 2008-08/txt/msg00028.txt.bz2 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