Re: Patch to update gdbint.texinfo [00/05]

[Jeremy Bennett <jeremy dot bennett at embecosm dot com>]

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 <jeremy.bennett@embecosm.com> 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