[rfa] Add ``Maintenance Commands'' appendix

[rfa] Add ``Maintenance Commands'' appendix

[Andrew Cagney]

[-- Attachment #1: Type: text/plain, Size: 205 bytes --]

Hello,

This was suggested long ago as a way of incorporating the maintenance 
commands (one of those strange GDB interfaces that should be in the user 
guide but can't be made to fit).

Thoughts?

Andrew

[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 1299 bytes --]

2002-01-15  Andrew Cagney  <ac131313@redhat.com>

	* gdb.texinfo (Maintenance Commands): Add appendix.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.70
diff -p -r1.70 gdb.texinfo
*** gdb.texinfo	2002/01/11 20:24:14	1.70
--- gdb.texinfo	2002/01/15 05:33:14
*************** Copyright (C) 1988-2001 Free Software Fo
*** 149,154 ****
--- 149,155 ----
  * Command Line Editing::        Command Line Editing
  * Using History Interactively:: Using History Interactively
  * Installing GDB::              Installing GDB
+ * Maintenance Commands::        Maintenance Commands
  * Index::                       Index
  @end menu
  
*************** There is no convenient way to generate a
*** 14850,14855 ****
--- 14851,14865 ----
  
  There are many other options available as well, but they are generally
  needed for special purposes only.
+ 
+ @node Maintenance Commands
+ @appendix Maintenance Commands
+ @cindex maintenance commands
+ @cindex internal commands
+ 
+ In addition to commands intended for @value{GDBN} users, @value{GDBN}
+ includes a number of commands intended, mainly, for @value{GDBN}
+ developers.  They are provided here for reference.
  
  @node Index
  @unnumbered Index

Re: [rfa] Add ``Maintenance Commands'' appendix

[Eli Zaretskii]

On Tue, 15 Jan 2002, Andrew Cagney wrote:

> This was suggested long ago as a way of incorporating the maintenance 
> commands (one of those strange GDB interfaces that should be in the user 
> guide but can't be made to fit).
> 
> Thoughts?

I'm for it, but such a change should include moving the few maint
commands already documented in gdb.texinfo into this appendix.

Re: [rfa] Add ``Maintenance Commands'' appendix

[Andrew Cagney]

> On Tue, 15 Jan 2002, Andrew Cagney wrote:
> 
> 
>> This was suggested long ago as a way of incorporating the maintenance 
>> commands (one of those strange GDB interfaces that should be in the user 
>> guide but can't be made to fit).
>> 
>> Thoughts?
> 
> 
> I'm for it, but such a change should include moving the few maint
> commands already documented in gdb.texinfo into this appendix.


Found one (there are not too many):

> @cindex negative breakpoint numbers
> @cindex internal @value{GDBN} breakpoints
> @value{GDBN} itself sometimes sets breakpoints in your program for special
> purposes, such as proper handling of @code{longjmp} (in C programs).
> These internal breakpoints are assigned negative numbers, starting with
> @code{-1}; @samp{info breakpoints} does not display them.
> 
> You can see these breakpoints with the @value{GDBN} maintenance command
> @samp{maint info breakpoints}.


I guess I snip things here and change the @samp{} to some sort of cross 
reference to the maintenance command.

The below being moved to the maintenance section and being the target of 
the reference.


> @table @code
> @kindex maint info breakpoints
> @item maint info breakpoints
> Using the same format as @samp{info breakpoints}, display both the
> breakpoints you've set explicitly, and those @value{GDBN} is using for
> internal purposes.  Internal breakpoints are shown with negative
> breakpoint numbers.  The type column identifies what kind of breakpoint
> is shown:
> 
> @table @code
> @item breakpoint
> Normal, explicitly set breakpoint.
> 
> @item watchpoint
> Normal, explicitly set watchpoint.
> 
> @item longjmp
> Internal breakpoint, used to handle correctly stepping through
> @code{longjmp} calls.
> 
> @item longjmp resume
> Internal breakpoint at the target of a @code{longjmp}.
> 
> @item until
> Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
> 
> @item finish
> Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
> 
> @item shlib events
> Shared library events.
> 
> @end table
> 
> @end table


Er, how do I do the cross reference bit?

Andrew

Re: [rfa] Add ``Maintenance Commands'' appendix

[Michael Snyder]

Andrew Cagney wrote:
> 
> > On Tue, 15 Jan 2002, Andrew Cagney wrote:
> >
> >
> >> This was suggested long ago as a way of incorporating the maintenance
> >> commands (one of those strange GDB interfaces that should be in the user
> >> guide but can't be made to fit).
> >>
> >> Thoughts?
> >
> >
> > I'm for it, but such a change should include moving the few maint
> > commands already documented in gdb.texinfo into this appendix.
> 
> Found one (there are not too many):

Don't forget maint info sections

Re: [rfa] Add ``Maintenance Commands'' appendix

[Andrew Cagney]

> Andrew Cagney wrote:
> 
>> 
> 
>> > On Tue, 15 Jan 2002, Andrew Cagney wrote:
>> >
>> >
> 
>> >> This was suggested long ago as a way of incorporating the maintenance
>> >> commands (one of those strange GDB interfaces that should be in the user
>> >> guide but can't be made to fit).
>> >>
>> >> Thoughts?
> 
>> >
>> >
>> > I'm for it, but such a change should include moving the few maint
>> > commands already documented in gdb.texinfo into this appendix.
> 
>> 
>> Found one (there are not too many):
> 
> 
> Don't forget maint info sections


I'll get to it (there are only 4-5 in total).

BTW, the reason for posting this is to try and un-stuck a really old 
profile patch.  One of the things it tripped up on was doco - it needed 
this new section.

Andrew

Re: [rfa] Add ``Maintenance Commands'' appendix

[Eli Zaretskii]

On Tue, 15 Jan 2002, Andrew Cagney wrote:

> > You can see these breakpoints with the @value{GDBN} maintenance command
> > @samp{maint info breakpoints}.
> 
> I guess I snip things here and change the @samp{} to some sort of cross 
> reference to the maintenance command.

Yes, that would be useful.

> Er, how do I do the cross reference bit?

Like this:

 You can see these breakpoints with the @value{GDBN} maintenance command
 @samp{maint info breakpoints} (@pxref{Maintenance Commands}).

(The node name inside @pxref might need to be changed to the actual name 
of the new node you are writing; I don't remember how did you call it.)

Re: [rfa] Add ``Maintenance Commands'' appendix

[Andrew Cagney]

> Er, how do I do the cross reference bit?
> 
> 
> Like this:
> 
>  You can see these breakpoints with the @value{GDBN} maintenance command
>  @samp{maint info breakpoints} (@pxref{Maintenance Commands}).
> 
> (The node name inside @pxref might need to be changed to the actual name 
> of the new node you are writing; I don't remember how did you call it.)


Thanks.

It is called ``Maintenance Commands''.  Would a link direct to the 
relevant ``maint info breakpoints'' section be better or isn't that 
possible?  (Hmm, probably not, I think I made that chapter a single big 
table).

Andrew

Re: [rfa] Add ``Maintenance Commands'' appendix

[Eli Zaretskii]

On Wed, 16 Jan 2002, Andrew Cagney wrote:

> Would a link direct to the 
> relevant ``maint info breakpoints'' section be better or isn't that 
> possible?

It's possible if you use @anchor.  Then you could reference the text 
inside @anchor{} instead of the node name.

But before you do, we should see if texi2html supports @anchor.

Re: [rfa] Add ``Maintenance Commands'' appendix

[Andrew Cagney]

> On Wed, 16 Jan 2002, Andrew Cagney wrote:
> 
> 
>> Would a link direct to the 
>> relevant ``maint info breakpoints'' section be better or isn't that 
>> possible?
> 
> 
> It's possible if you use @anchor.  Then you could reference the text 
> inside @anchor{} instead of the node name.
> 
> But before you do, we should see if texi2html supports @anchor.


Ah.  Don't forget we're (I'm?) ment to be replacing that with makeinfo 
4.something.somethingextra.

Andrew

Re: [rfa] Add ``Maintenance Commands'' appendix

[Eli Zaretskii]

> Date: Wed, 16 Jan 2002 10:40:56 -0500
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> Ah.  Don't forget we're (I'm?) ment to be replacing that with makeinfo 
> 4.something.somethingextra.

Yes, the latest version of Texinfo 4.0d (available from
alpha.gnu.org) supports split-HTML mode, so we could switch.  In that
case, @anchor is certainly an option.

Re: [rfa] Add ``Maintenance Commands'' appendix

[Andrew Cagney]

[-- Attachment #1: Type: text/plain, Size: 932 bytes --]

> Date: Wed, 16 Jan 2002 10:40:56 -0500
>> From: Andrew Cagney <ac131313@cygnus.com>
>> 
>> Ah.  Don't forget we're (I'm?) ment to be replacing that with makeinfo 
>> 4.something.somethingextra.
> 
> 
> Yes, the latest version of Texinfo 4.0d (available from
> alpha.gnu.org) supports split-HTML mode, so we could switch.  In that
> case, @anchor is certainly an option.


Hmm, @anchor ...

Attached is a revised patch.  It moves the ``maint info breakpoints'' 
and adds a reference.  it appears to work with texinfo 4.0*, texi2html 
(1.64) and pdftex.  How does it look?

Regarding a switch to ``makeinfo --html'' I think I'll put it on hold. 
I gave it a quick trial but tripped up on two points: I couldn't figure 
out where exactly it was putting the generated files (it wanted a 
gdb.html/ directory but put only index.html in it);  I found the 
generated pages too fine grained (down to a section not chapter).

enjoy,
Andrew

[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 4529 bytes --]

2002-01-16  Andrew Cagney  <ac131313@redhat.com>

	* gdb.texinfo 	(Maintenance Commands): Add appendix.
	(Set Breaks): Copy ``maint info breakpoint'' doco to
	``Maintenance Commands'' appendix.  Add reference.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.70
diff -p -r1.70 gdb.texinfo
*** gdb.texinfo	2002/01/11 20:24:14	1.70
--- gdb.texinfo	2002/01/16 20:20:38
*************** Copyright (C) 1988-2001 Free Software Fo
*** 149,154 ****
--- 149,155 ----
  * Command Line Editing::        Command Line Editing
  * Using History Interactively:: Using History Interactively
  * Installing GDB::              Installing GDB
+ * Maintenance Commands::        Maintenance Commands
  * Index::                       Index
  @end menu
  
*************** the breakpoints are conditional, this is
*** 2627,2675 ****
  
  @cindex negative breakpoint numbers
  @cindex internal @value{GDBN} breakpoints
! @value{GDBN} itself sometimes sets breakpoints in your program for special
! purposes, such as proper handling of @code{longjmp} (in C programs).
! These internal breakpoints are assigned negative numbers, starting with
! @code{-1}; @samp{info breakpoints} does not display them.
! 
  You can see these breakpoints with the @value{GDBN} maintenance command
! @samp{maint info breakpoints}.
! 
! @table @code
! @kindex maint info breakpoints
! @item maint info breakpoints
! Using the same format as @samp{info breakpoints}, display both the
! breakpoints you've set explicitly, and those @value{GDBN} is using for
! internal purposes.  Internal breakpoints are shown with negative
! breakpoint numbers.  The type column identifies what kind of breakpoint
! is shown:
! 
! @table @code
! @item breakpoint
! Normal, explicitly set breakpoint.
! 
! @item watchpoint
! Normal, explicitly set watchpoint.
! 
! @item longjmp
! Internal breakpoint, used to handle correctly stepping through
! @code{longjmp} calls.
! 
! @item longjmp resume
! Internal breakpoint at the target of a @code{longjmp}.
! 
! @item until
! Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
! 
! @item finish
! Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
! 
! @item shlib events
! Shared library events.
! 
! @end table
! 
! @end table
  
  
  @node Set Watchpoints
--- 2628,2639 ----
  
  @cindex negative breakpoint numbers
  @cindex internal @value{GDBN} breakpoints
! @value{GDBN} itself sometimes sets breakpoints in your program for
! special purposes, such as proper handling of @code{longjmp} (in C
! programs).  These internal breakpoints are assigned negative numbers,
! starting with @code{-1}; @samp{info breakpoints} does not display them.
  You can see these breakpoints with the @value{GDBN} maintenance command
! @samp{maint info breakpoints} (@pxref{maint info breakpoints}).
  
  
  @node Set Watchpoints
*************** There is no convenient way to generate a
*** 14850,14855 ****
--- 14814,14864 ----
  
  There are many other options available as well, but they are generally
  needed for special purposes only.
+ 
+ @node Maintenance Commands
+ @appendix Maintenance Commands
+ @cindex maintenance commands
+ @cindex internal commands
+ 
+ In addition to commands intended for @value{GDBN} users, @value{GDBN}
+ includes a number of commands intended for @value{GDBN} developers.
+ These commands are provided here for reference.
+ 
+ @table @code
+ @kindex maint info breakpoints
+ @item @anchor{maint info breakpoints}maint info breakpoints
+ Using the same format as @samp{info breakpoints}, display both the
+ breakpoints you've set explicitly, and those @value{GDBN} is using for
+ internal purposes.  Internal breakpoints are shown with negative
+ breakpoint numbers.  The type column identifies what kind of breakpoint
+ is shown:
+ 
+ @table @code
+ @item breakpoint
+ Normal, explicitly set breakpoint.
+ 
+ @item watchpoint
+ Normal, explicitly set watchpoint.
+ 
+ @item longjmp
+ Internal breakpoint, used to handle correctly stepping through
+ @code{longjmp} calls.
+ 
+ @item longjmp resume
+ Internal breakpoint at the target of a @code{longjmp}.
+ 
+ @item until
+ Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
+ 
+ @item finish
+ Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
+ 
+ @item shlib events
+ Shared library events.
+ 
+ @end table
+ 
+ @end table
  
  @node Index
  @unnumbered Index

Re: [rfa] Add ``Maintenance Commands'' appendix

[Eli Zaretskii]

On Wed, 16 Jan 2002, Andrew Cagney wrote:

> Attached is a revised patch.  It moves the ``maint info breakpoints'' 
> and adds a reference.  it appears to work with texinfo 4.0*, texi2html 
> (1.64) and pdftex.  How does it look?

Looks fine.

> Regarding a switch to ``makeinfo --html'' I think I'll put it on hold. 
> I gave it a quick trial but tripped up on two points: I couldn't figure 
> out where exactly it was putting the generated files (it wanted a 
> gdb.html/ directory but put only index.html in it)

That's a bug in 4.0d; fixed in the next pretest that should be
available shortly (I'm told by the Texinfo maintainer).

> I found the 
> generated pages too fine grained (down to a section not chapter).

It splits by nodes, so what's important is where are the @node
directives, not @chapter or @section.  I think for a Web-based manual,
a node is the right split point, as chapters can be very large.

Re: [rfa] Add ``Maintenance Commands'' appendix

[Andrew Cagney]

> On Wed, 16 Jan 2002, Andrew Cagney wrote:
> 
> 
>> Attached is a revised patch.  It moves the ``maint info breakpoints'' 
>> and adds a reference.  it appears to work with texinfo 4.0*, texi2html 
>> (1.64) and pdftex.  How does it look?
> 
> 
> Looks fine.


Ok, I've checked it in.


>> Regarding a switch to ``makeinfo --html'' I think I'll put it on hold. 
>> I gave it a quick trial but tripped up on two points: I couldn't figure 
>> out where exactly it was putting the generated files (it wanted a 
>> gdb.html/ directory but put only index.html in it)
> 
> 
> That's a bug in 4.0d; fixed in the next pretest that should be
> available shortly (I'm told by the Texinfo maintainer).



Thanks,

Andrew