From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 5718 invoked by alias); 20 Sep 2008 18:39:23 -0000 Received: (qmail 5703 invoked by uid 22791); 20 Sep 2008 18:39:22 -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; Sat, 20 Sep 2008 18:38:21 +0000 Received: from [91.135.5.64] by mail.idnet.net.uk (GMS 15.01.3664/NU3963.00.7ca42f0c) with ESMTP id vydnemba for gdb-patches@sourceware.org; Sat, 20 Sep 2008 19:38:15 +0100 Subject: Re: Patch to update gdbint.texinfo [00/05] From: Jeremy Bennett Reply-To: jeremy.bennett@embecosm.com To: gdb-patches@sourceware.org In-Reply-To: References: <1221919290.2827.495.camel@thomas> Content-Type: text/plain Date: Sat, 20 Sep 2008 18:39:00 -0000 Message-Id: <1221935896.2827.545.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-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2008-09/txt/msg00443.txt.bz2 On Sat, 2008-09-20 at 20:04 +0300, Eli Zaretskii wrote: > Thanks. Thanks for such a thorough read-through. I've got a few questions for clarification on one or two below. > However, I don't see your name in the FSF records of copyright > assignments. If you didn't submit legal paperwork to the FSF, please > do, because your contribution is substantial to require that. We > cannot use such large patches without legal papers. I sent an email to assign@gnu.org yesterday requesting help in assigning the copyright. The text has been taken from an existing paper under Creative Commons Attribution 2.0 license with the copyright owned by Embecosm (my company). However we're very happy to assign the rights to all contributions to FSF. Anything you can do to expedite this would be appreciated > We don't really add each contributor to the list of authors. E.g., my > name is not there. Agreed. There ought to be a section mentioning contributors, like the main GDB User Guide (it's a good motivator for anything open source). I'll add one, and solicit names to put in it - yours included of course. > I don't think this is needed. > > > +@c Much of the following section has been taken from the Open Source > > +@c application note ``Howto: Porting the GNU Debugger: Practical > > +@c Experience with the OpenRISC 1000 Architecture'', written by Jeremy > > +@c Bennett of Embecosm. See > > +@c http://www.embecosm.com/download/ean3.html for more information. It can go once the legal papers have been signed. It means the text as it was sent out is compliant with the Creative Commons Attribution licence. > > +@deftypefn {Architecture Function} CORE_ADDR read_pc (struct regcache *@var{regcache}) > > +@findex read_pc > Do you really need this @findex? I think @deftypefn generates an > index entry automatically, doesn't it? Thanks for pointing this out. I found a small Texinfo "feature". It is the third entity after the @deftypefn that appears in the index, so if you have a typename that has a space in it things get confused. Thus @deftypefn {Architecture Function} struct frame_id unwind_dummy_id (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame}) puts "frame_id" into the index, not "unwind_dummy_id". I can fix it by using: @deftypefn {Architecture Function} {struct frame_id} unwind_dummy_id (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame}) This occurs in various places in the existing document. I'll go through and fix the lot. > > +@quotation Note > > +@code{gdbarch_register_to_value} and @code{gdbarch_value_to_register} > > take their @var{reg} and @var{type} arguments in different orders. > > +@end quotation > Please don't put anything after @quotation on the same line. Strictly > speaking, @quotation (as many any other similar @-command in Texinfo) > should appear on a line by themselves; a Texinfo translator may decide > to ignore anything after them. Texinfo manual suggests this way of doing Notes etc (@quotation can take one argument, which is bolded with ":" after it). But I'll use @footnote as you recommended earlier. > > + if( 0 == n ) @{ > > + return 1; > > + @} > > + else @{ > > + return n * fact( n - 1 ); > > + @} > > This is not the GNU style of formatting C code. Please use the GNU > style. This was deliberate - the diagram has the code squashed up like this, so it fits in the space available, and I've used the text from the diagram literally. I can use GNU style in the text, but the diagram will have to use squashed up code. > > +the @emph{NEXT} frame. For a falling stack this will be the lowest > > Isn't "push-down stack" the more widely used terminology? I think the phrase "push-down stack" is a generic term for this LIFO data structure. It doesn't imply a direction of implementation, although almost all descriptions are implicitly a rising stack, with a "top" of stack. I've always used the phrases "falling stack" and "rising stack" to describe stack direction, but you got me wondering. I took a quick dive into a few compiler books (and for completeness Wikipedia), and found they barely mention stack direction at all. A quick web trawl found that the terms "stack growing up" and "stack growing down" are more widely used, particularly in the context of GCC, so I'll use that as the main terminology. > > +@code{@w{frame_unwind_append_sniffer}} is used to add a new sniffer to > > No need for a @w here. Hmmm... I started adding these, because I thought TeX was splitting at underscores, at least in the PDF output. I'll double check. > Thanks again for working on this. You're welcome. I shall have a busy Sunday afternoon applying all your suggestions. Best wishes, Jeremy -- Tel: +44 (1202) 416955 Cell: +44 (7970) 676050 SkypeID: jeremybennett Email: jeremy.bennett@embecosm.com Web: www.embecosm.com