new diff: gdb.texinfo

new diff: gdb.texinfo

[Brian Youmans]

This is a consolidated diff for the changes I have made to the
5.1.0.1 gdb.texinfo.  It includes most of the diffs I sent yesterday.

1. I have removed the change I made adding the GFDL to the list of
Invariant Sections in the copying permissions - RMS does not think it
is proper to list it as an "Invariant Section", although it is
effectively one anyways, since you can't alter or remove it.  The
changes I made to include the text of the GFDL are still in place.

2. Most of the new changes are meant to solve "Overfull /hbox" 
problems when the manual is printed using @smallbook.  Some of them
are very ugly and people may want to come up with better solutions.

3. This makes more fixes to the multitables.  Have I mentioned lately
how much I *hate* multitables?  The fixes don't solve the "Overfull
/hbox" problems, but they make it so that at least the text doesn't
print over itself.

4. I put in a FIXME at one spot I noticed where I think a word is 
missing.

There are more Overfull /hboxes to fix, but I haven't figured out
good solutions for those yet.

- Brian Youmans, FSF office staff
----------------------------------------------------------------------------

*** /home/opus/manuscripts/GDB/gdb-5.1.0.1/gdb/doc/gdb.texinfo	Thu Jan  3 00:40:49 2002
--- gdb.texinfo	Wed Jan 16 16:56:10 2002
***************
*** 50,57 ****
  of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}
  for @value{GDBN} Version @value{GDBVN}.
  
! Copyright (C) 1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
!    Free Software Foundation, Inc.
  
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1 or
--- 50,56 ----
  of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}
  for @value{GDBN} Version @value{GDBVN}.
  
! Copyright (C) 1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001, 2002 Free Software Foundation, Inc.
  
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1 or
***************
*** 60,68 ****
  Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
  and with the Back-Cover Texts as in (a) below.
  
! (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
! this GNU Manual, like GNU software.  Copies published by the Free
! Software Foundation raise funds for GNU development.''
  @end ifinfo
  
  @titlepage
--- 59,68 ----
  Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
  and with the Back-Cover Texts as in (a) below.
  
! (a) The Free Software Foundation's Back-Cover Text is: ``You have
! freedom to copy and modify this GNU Manual, like GNU software.  Copies
! published by the Free Software Foundation raise funds for GNU
! development.''
  @end ifinfo
  
  @titlepage
***************
*** 82,89 ****
  @end tex
  
  @vskip 0pt plus 1filll
! Copyright @copyright{} 1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
!    Free Software Foundation, Inc.
  @sp 2
  Published by the Free Software Foundation @*
  59 Temple Place - Suite 330, @*
--- 82,89 ----
  @end tex
  
  @vskip 0pt plus 1filll
! Copyright @copyright{} 1988,1989,1990,1991,1992,1993,1994,1995,1996,@*
! 1998,1999,2000,2001,2002 Free Software Foundation, Inc.
  @sp 2
  Published by the Free Software Foundation @*
  59 Temple Place - Suite 330, @*
***************
*** 97,105 ****
  Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
  and with the Back-Cover Texts as in (a) below.
  
! (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
! this GNU Manual, like GNU software.  Copies published by the Free
! Software Foundation raise funds for GNU development.''
  @end titlepage
  @page
  
--- 97,106 ----
  Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
  and with the Back-Cover Texts as in (a) below.
  
! (a) The Free Software Foundation's Back-Cover Text is: ``You have
! freedom to copy and modify this GNU Manual, like GNU software.  Copies
! published by the Free Software Foundation raise funds for GNU
! development.''
  @end titlepage
  @page
  
***************
*** 148,153 ****
--- 149,155 ----
  * Command Line Editing::        Command Line Editing
  * Using History Interactively:: Using History Interactively
  * Installing GDB::              Installing GDB
+ * GNU Free Documentation License::  The license for this documentation
  * Index::                       Index
  @end menu
  
***************
*** 197,202 ****
--- 199,205 ----
  * Command Line Editing::        Command Line Editing
  * Using History Interactively:: Using History Interactively
  * Installing GDB::              Installing GDB
+ * GNU Free Documentation License::  The license for this documentation
  * Index::                       Index
  @end menu
  
***************
*** 5910,5928 ****
  Examples:
  
  @smallexample
! (@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of tracepoint 2
  
  (@value{GDBP}) @b{passcount 12}  // Stop on the 12th execution of the
!                                 // most recently defined tracepoint.
  (@value{GDBP}) @b{trace foo}
  (@value{GDBP}) @b{pass 3}
  (@value{GDBP}) @b{trace bar}
  (@value{GDBP}) @b{pass 2}
  (@value{GDBP}) @b{trace baz}
  (@value{GDBP}) @b{pass 1}        // Stop tracing when foo has been
!                                  // executed 3 times OR when bar has
!                                  // been executed 2 times
!                                  // OR when baz has been executed 1 time.
  @end smallexample
  @end table
  
--- 5913,5932 ----
  Examples:
  
  @smallexample
! (@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of 
! @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2}
  
  (@value{GDBP}) @b{passcount 12}  // Stop on the 12th execution of the
! @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.}
  (@value{GDBP}) @b{trace foo}
  (@value{GDBP}) @b{pass 3}
  (@value{GDBP}) @b{trace bar}
  (@value{GDBP}) @b{pass 2}
  (@value{GDBP}) @b{trace baz}
  (@value{GDBP}) @b{pass 1}        // Stop tracing when foo has been
! @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has}
! @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times}
! @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.}
  @end smallexample
  @end table
  
***************
*** 5950,5958 ****
  @smallexample
  (@value{GDBP}) @b{collect @var{data}} // collect some data
  
! (@value{GDBP}) @b{while-stepping 5}   // single-step 5 times and collect data
  
! (@value{GDBP}) @b{end}                // signals the end of actions.
  @end smallexample
  
  In the following example, the action list begins with @code{collect}
--- 5954,5962 ----
  @smallexample
  (@value{GDBP}) @b{collect @var{data}} // collect some data
  
! (@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data
  
! (@value{GDBP}) @b{end}              // signals the end of actions.
  @end smallexample
  
  In the following example, the action list begins with @code{collect}
***************
*** 6027,6032 ****
--- 6031,6038 ----
  @kindex info tracepoints
  @cindex information about tracepoints
  @item info tracepoints @r{[}@var{num}@r{]}
+ @c FIXME: Shouldn't there be an "at", "on", or "for" in the next
+ @c sentence?  - Brian Y., FSF office staff
  Display information the tracepoint @var{num}.  If you don't specify a
  tracepoint number displays information about all the tracepoints
  defined so far.  For each tracepoint, the following information is
***************
*** 6053,6060 ****
  (@value{GDBP}) @b{info trace}
  Num Enb Address    PassC StepC What
  1   y   0x002117c4 0     0     <gdb_asm>
! 2   y   0x0020dc64 0     0     in gdb_test at gdb_test.c:375
! 3   y   0x0020b1f4 0     0     in collect_data at ../foo.c:1741
  (@value{GDBP})
  @end smallexample
  
--- 6059,6066 ----
  (@value{GDBP}) @b{info trace}
  Num Enb Address    PassC StepC What
  1   y   0x002117c4 0     0     <gdb_asm>
! 2   y   0x0020dc64 0     0     in g_test at g_test.c:1375
! 3   y   0x0020b1f4 0     0     in get_data at ../foo.c:41
  (@value{GDBP})
  @end smallexample
  
***************
*** 10521,10526 ****
--- 10527,10534 ----
  @item
  @tab reply @code{qSymbol:}@var{sym_name}
  @tab
+ @sp 2
+ @noindent
  The target requests the value of symbol @var{sym_name} (hex encoded).  
  @value{GDBN} may provide the value by using the 
  @code{qSymbol:}@var{sym_value}:@var{sym_name}
***************
*** 10529,10534 ****
--- 10537,10544 ----
  @item symbol value
  @tab @code{qSymbol:}@var{sym_value}:@var{sym_name}
  @tab
+ @sp 1
+ @noindent
  Set the value of SYM_NAME to SYM_VALUE.
  @item
  @tab
***************
*** 10548,10553 ****
--- 10558,10565 ----
  @item
  @tab reply @code{qSymbol:}@var{sym_name}
  @tab
+ @sp 2
+ @noindent
  The target requests the value of a new symbol @var{sym_name} (hex encoded).
  @value{GDBN} will continue to supply the values of symbols (if available),
  until the target ceases to request them.
***************
*** 14291,14296 ****
--- 14303,14312 ----
  There are many other options available as well, but they are generally
  needed for special purposes only.
  
+ @node GNU Free Documentation License
+ @appendix GNU Free Documentation License
+ @include fdl.texi
+ 
  @node Index
  @unnumbered Index
  

Re: new diff: gdb.texinfo

[Eli Zaretskii]

On Wed, 16 Jan 2002, Brian Youmans wrote:

> 1. I have removed the change I made adding the GFDL to the list of
> Invariant Sections in the copying permissions - RMS does not think it
> is proper to list it as an "Invariant Section", although it is
> effectively one anyways, since you can't alter or remove it.

Yes, the GFDL usage guidelines on www.gnu.org clearly say GFDL itself
shouldn't be marked invariant since its text already prohibits its
modifcation.

> 3. This makes more fixes to the multitables.  Have I mentioned lately
> how much I *hate* multitables?

There's no reason to hate @multitable, IMHO, it's just that the GDB
manual abuses it: it tries to squeeze too much information into a
table, and the table items have too many @code markup in them, so TeX
cannot break the lines in a useful way.  Unfortunately, I don't know
enough about the related subject matter (the remote protocol) to
rewrite that table.

> 4. I put in a FIXME at one spot I noticed where I think a word is 
> missing.

Thanks, I will fix it.

Andrew, I don't know whether I should bother checking in these changes
on the branch anymore, what with your intent to release v5.2 from the
trunk.  Please advise.

Re: new diff: gdb.texinfo

[Richard Earnshaw]

3diff@gnu.org said:
> ! Copyright @copyright{} 1988,1989,1990,1991,1992,1993,1994,1995,1996,@*
> ! 1998,1999,2000,2001,2002 Free Software Foundation, Inc. 

Is there a good reason why there isn't a space after each of those commas? 
 It looks truly horrible when printed out.

This one isn't even consistent:

! Copyright (C) 1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000
,2001, 2002 Free Software Foundation, Inc.
  

Re: new diff: gdb.texinfo

[Eli Zaretskii]

On Thu, 17 Jan 2002, Richard Earnshaw wrote:

> 3diff@gnu.org said:
> > ! Copyright @copyright{} 1988,1989,1990,1991,1992,1993,1994,1995,1996,@*
> > ! 1998,1999,2000,2001,2002 Free Software Foundation, Inc. 
> 
> Is there a good reason why there isn't a space after each of those commas? 

To conserve space, I guess.

> This one isn't even consistent:
> 
> ! Copyright (C) 1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000
> ,2001, 2002 Free Software Foundation, Inc.

I did make that consistent in the version I eventually committed.

Re: new diff: gdb.texinfo

[Brian Youmans]

I think I found the list of years in that state.  It is important that each
year be listed individually, but we don't otherwise care about the form factor.
Adding spaces after the commas would be fine with me.

I stuck in the @* because the line wasn't breaking and it was causing an 
Overfull /hbox.

- Brian Youmans, FSF office staff

Re: new diff: gdb.texinfo

[Richard Earnshaw]

> I think I found the list of years in that state.  It is important that each
> year be listed individually, but we don't otherwise care about the form factor.
> Adding spaces after the commas would be fine with me.
> 
> I stuck in the @* because the line wasn't breaking and it was causing an 
> Overfull /hbox.

Indeed, but it will probably be in the wrong place for a different 
form-factor printing.

Putting spaces in between each date would allow TeX to select its own 
line-breaking points.  Since you've no objection, I suggest we do that.

R.

Re: new diff: gdb.texinfo

[Andrew Cagney]

> 
> There's no reason to hate @multitable, IMHO, it's just that the GDB
> manual abuses it: it tries to squeeze too much information into a
> table, and the table items have too many @code markup in them, so TeX
> cannot break the lines in a useful way.  Unfortunately, I don't know
> enough about the related subject matter (the remote protocol) to
> rewrite that table.


Things to do one day.  The entire chapter needs to be re-structured (again).


>> 4. I put in a FIXME at one spot I noticed where I think a word is 
>> missing.
> 
> 
> Thanks, I will fix it.
> 
> Andrew, I don't know whether I should bother checking in these changes
> on the branch anymore, what with your intent to release v5.2 from the
> trunk.  Please advise.


The still need to go onto the 5.1 branch because these are fixing (C) 
problems and I'm going to have to spin another 5.1.something with those 
fixes included (sigh).

Andrew

Re: new diff: gdb.texinfo

[Eli Zaretskii]

> Date: Thu, 17 Jan 2002 11:31:14 -0500
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> The still need to go onto the 5.1 branch because these are fixing (C) 
> problems and I'm going to have to spin another 5.1.something with those 
> fixes included (sigh).

Okay, will do (the changes are already there on the trunk).

Re: new diff: gdb.texinfo

[Eli Zaretskii]

On Thu, 17 Jan 2002, Richard Earnshaw wrote:

> > I stuck in the @* because the line wasn't breaking and it was causing an 
> > Overfull /hbox.
> 
> Indeed, but it will probably be in the wrong place for a different 
> form-factor printing.
> 
> Putting spaces in between each date would allow TeX to select its own 
> line-breaking points.  Since you've no objection, I suggest we do that.

Done.

Re: new diff: gdb.texinfo

[Eli Zaretskii]

On Thu, 17 Jan 2002, Andrew Cagney wrote:

> > Andrew, I don't know whether I should bother checking in these changes
> > on the branch anymore, what with your intent to release v5.2 from the
> > trunk.  Please advise.
> 
> The still need to go onto the 5.1 branch because these are fixing (C) 
> problems and I'm going to have to spin another 5.1.something with those 
> fixes included (sigh).

Okay, I committed to the branch as well.  But please check whether making 
a distribution from the branch works, including "make info", because 
something strange happened with fdl.texi on the branch, probably because 
CVS and myself don't get along very well ;-)

Re: new diff: gdb.texinfo

[Andrew Cagney]

> On Thu, 17 Jan 2002, Andrew Cagney wrote:
> 
> 
>> > Andrew, I don't know whether I should bother checking in these changes
>> > on the branch anymore, what with your intent to release v5.2 from the
>> > trunk.  Please advise.
> 
>> 
>> The still need to go onto the 5.1 branch because these are fixing (C) 
>> problems and I'm going to have to spin another 5.1.something with those 
>> fixes included (sigh).
> 
> 
> Okay, I committed to the branch as well.  But please check whether making 
> a distribution from the branch works, including "make info", because 
> something strange happened with fdl.texi on the branch, probably because 
> CVS and myself don't get along very well ;-)


FYI, I try to remember to do this but ...  I'm adding a checklist it to 
the release process.

The best way to check the doco on the 5.1 branch:
http://sources.redhat.com/gdb/5.1/onlinedocs/
it is updated once every 24hrs.

Andrew

Re: new diff: gdb.texinfo

[Eli Zaretskii]

> Date: Sun, 20 Jan 2002 12:33:46 -0500
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> The best way to check the doco on the 5.1 branch:
> http://sources.redhat.com/gdb/5.1/onlinedocs/
> it is updated once every 24hrs.

Thanks for the pointer.