Re: Merging manuals (was Re: How do you use GDB to debug GDB)

Re: Merging manuals (was Re: How do you use GDB to debug GDB)

[Michael Elizabeth Chastain]

Another argument for separation of gdb.texinfo and gdbint.texinfo:

gdb.texinfo is in some sense a public interface which is meant to be
stable.  But information in gdbint.texinfo is not a public interface
and can change at any moment.

For example, someone could re-implement the symbol table with tries
instead of hash tables (I would really like this!).  That would affect
gdbint.texinfo, but it would not affect gdb.texinfo.

Maybe "public"/"private" are not the right words but there is a
definite difference here.

Michael

Re: Merging manuals (was Re: How do you use GDB to debug GDB)

[Andrew Cagney]

Michael Elizabeth Chastain wrote:
> 
> Another argument for separation of gdb.texinfo and gdbint.texinfo:
> 
> gdb.texinfo is in some sense a public interface which is meant to be
> stable.  But information in gdbint.texinfo is not a public interface
> and can change at any moment.
> 
> For example, someone could re-implement the symbol table with tries
> instead of hash tables (I would really like this!).  That would affect
> gdbint.texinfo, but it would not affect gdb.texinfo.

Kind of.

GDB's user guide changes (well should also) as GDB evolves. That is
because the ``public'' interface isn't frozen, changing between
releases.

The reason for making it all part of the one mega document is that it
would stop us sticking our head in the sand and ignore the fact that
half of it is now crap^D^D^D^D out of date :-/

For what it is worth, I don't really care.  I just know what one of the
5.1 tick items is.

	enjoy,
		Andrew

Re: Merging manuals (was Re: How do you use GDB to debug GDB)

[Kevin Buettner]

On Mar 20, 12:16pm, Michael Elizabeth Chastain wrote:

> Another argument for separation of gdb.texinfo and gdbint.texinfo:
> 
> gdb.texinfo is in some sense a public interface which is meant to be
> stable.  But information in gdbint.texinfo is not a public interface
> and can change at any moment.

I find Michael's argument compelling.  I think the manuals should be
kept separate.

Kevin

Re: Merging manuals (was Re: How do you use GDB to debug GDB)

[Fernando Nasser]

Kevin Buettner wrote:
> 
> On Mar 20, 12:16pm, Michael Elizabeth Chastain wrote:
> 
> > Another argument for separation of gdb.texinfo and gdbint.texinfo:
> >
> > gdb.texinfo is in some sense a public interface which is meant to be
> > stable.  But information in gdbint.texinfo is not a public interface
> > and can change at any moment.
> 
> I find Michael's argument compelling.  I think the manuals should be
> kept separate.
> 

So do I.

-- 
Fernando Nasser
Red Hat Canada Ltd.                     E-Mail:  fnasser@redhat.com
2323 Yonge Street, Suite #300
Toronto, Ontario   M4P 2C9

GCC is depreciating multi-line strings

[Stephen Smith]

I don't know if the maintainers on this list have been following the discussion on the gcc mailing list regarding
multiline strings being depreciated.

All I know is that while I have been perusing the code looking for where to add my hook, for managing shared libraries
using the remote protocol,
I have seen quite a few.

Just wanted you all to know.

sps

Re: GCC is depreciating multi-line strings

[Andrew Cagney]

Um, I'm slightly confused.  What exactly is ment by multi-line strings? 
I've found this link and am still looking :-)

http://gcc.gnu.org/ml/gcc/2001-03/msg00855.html

	Andrew

Re: GCC is depreciating multi-line strings

[Christopher Faylor]

On Tue, Mar 20, 2001 at 06:04:47PM -0500, Andrew Cagney wrote:
>Um, I'm slightly confused.  What exactly is ment by multi-line strings? 
>I've found this link and am still looking :-)
>
> http://gcc.gnu.org/ml/gcc/2001-03/msg00855.html

Cygwin has been bit by this recent change.

a = "This is
the multiline string
that has been deprecated.";

gcc stores that as three separate lines.

The "correct" way to do this is:

a = "This is\n\
the multiline string\n\
which has not been deprecated.";

This is also ok, of course:

a = "abc\
def";

It is equivalent to:

a = "abcdef";

The reason for deprecating the non \ usage is that it is not portable.

If gdb uses this construct, I have a hard time believing that this could
be true.

A quick grep seems to show that gdb is doing the right thing so I really
don't think that this is an issue.

cgf

Re: GCC is depreciating multi-line strings

[Andrew Cagney]

Andrew Cagney wrote:
> 
> Um, I'm slightly confused.  What exactly is ment by multi-line strings?
> I've found this link and am still looking :-)
> 
> http://gcc.gnu.org/ml/gcc/2001-03/msg00855.html

Ok, there are the following:

   illegal:

	"blah
	blah"

    k&r

	"blah\n\
	blah"

    iso-c

	"blah\n"
	"blah"

GDB should only be using the latter two with new code prefering the last
one.  I think, for the most part, it is.  Code using the first can
obviously be fixed :-)

	Andrew

Re: Merging manuals (was Re: How do you use GDB to debug GDB)

[Eli Zaretskii]

On Tue, 20 Mar 2001, Michael Elizabeth Chastain wrote:

> gdb.texinfo is in some sense a public interface which is meant to be
> stable.  But information in gdbint.texinfo is not a public interface
> and can change at any moment.

As Andrew says, ``humor me''.

IMHO, we have a looong way to go before we could claim that any of our
documents are complete enough to make the interface stability
consideration enter our radar screens.  Try to diff gdb.texinfo from
v5.0 against the current version and see for yourself: it's still very
much in a fluid phase.  And rightly so: we still have a lot to do to
to make it exhaustive and well-indexed (I'm still finding myself
looking for index entries that aren't there too often).

> For example, someone could re-implement the symbol table with tries
> instead of hash tables (I would really like this!).  That would affect
> gdbint.texinfo, but it would not affect gdb.texinfo.

I'd be happy if I could assume such reimplementation will be
documented as part of the redesign; right now, most changes are not
accompanied with documentation.  Heck, I'd be happy if the _current_
design of symbol tables were documented.  While Michael happened to
pick up one of the more documented aspects of GDB internals, even
symtabs docs leaves a lot to be desired.  For example, minsyms are not
documented at all.

In other words, there are more omissions in gdbint.texinfo than there
is information.  I don't think the rate of change matters, given this.

Re: Merging manuals (was Re: How do you use GDB to debug GDB)

[J.T. Conklin]

>>>>> "Eli" == Eli Zaretskii <eliz@is.elta.co.il> writes:
Eli> On Tue, 20 Mar 2001, Michael Elizabeth Chastain wrote:

>> gdb.texinfo is in some sense a public interface which is meant to be
>> stable.  But information in gdbint.texinfo is not a public interface
>> and can change at any moment.

Eli> As Andrew says, ``humor me''.

Wouldn't Andrew say ``humour me'' :-)

        --jtc

-- 
J.T. Conklin
RedBack Networks

Re: How do you use GDB to debug GDB

[Eli Zaretskii]

On Mon, 19 Mar 2001, Michael Elizabeth Chastain wrote:

>   % gdb powerpc-motorola-elf-gdb
>   (gdb) set prompt [top] 
>   [top] set args --command=C:/rti/bin/rtidbug.ini C:/examples/dll/main.exe
>   [top] break help_command
>   [top] run
> 
> The first command helps me keep track of which gdb I'm in.  There is
> a space at the end of the command: "set prompt [top] ".
> 
> The second command tells the superior gdb what the arguments are for
> the inferior gdb.  This is the heart of what you want.  Note that you
> can re-run the inferior gdb and the arguments will repeat.
> 
> The third line sets a convenient breakpoint in the superior gdb so that
> you can bounce back up to it.  I usually do "help foo" instead of "help"
> for getting to the superior gdb, to reduce the screen output.
> 
> The fourth line starts the inferior gdb with the arguments given on the
> second line.

I think this is important enough to go into the manual.

If anyone has additional tricks pertginent to debugging GDB, please
post them, and I will merge them all together.

One thing puzzles me, though: why is the section "Debugging GDB with
itself" in gdbint.texinfo instead of gdb.texinfo?  Is there any reason
not to move (or copy) it to gdb.texinfo?  Can some of the elders
please shed some light on this?

Re: How do you use GDB to debug GDB

[Andrew Cagney]

> One thing puzzles me, though: why is the section "Debugging GDB with
> itself" in gdbint.texinfo instead of gdb.texinfo?  Is there any reason
> not to move (or copy) it to gdb.texinfo?  Can some of the elders
> please shed some light on this?

To expand a little on Michael's comment.

gdbint.texinfo is for internals - the things you see when you lift the
bonnet (1) and start poking around with the engine.

gdb.texinfo is for the user - the external interfaces to GDB.  If anyone
has ever wondered why the remote protocol is documented in gdb.texinfo
and not gdbint.texinfo then this is it - it is an external interface to
gdb.  To get carried away with the car metaphore, its a bit like the
section of the manual which tries to explain how it is possible to
change a flat using just the spare and tools all hidden somewhere in the
boot (2).

As a complete asside, it has also been suggested that the two documents
be merged.  From memory GCC did this.

	Andrew


(1) Hood for the geographically impaired.
(2) Trunk for the geographically impaired.

Merging manuals (was Re: How do you use GDB to debug GDB)

[Stan Shebs]

Andrew Cagney wrote:
> 
> gdbint.texinfo is for internals - the things you see when you lift the
> bonnet (1) and start poking around with the engine.
> 
> gdb.texinfo is for the user - the external interfaces to GDB.  If anyone
> has ever wondered why the remote protocol is documented in gdb.texinfo
> and not gdbint.texinfo then this is it - it is an external interface to
> gdb.  To get carried away with the car metaphore, its a bit like the
> section of the manual which tries to explain how it is possible to
> change a flat using just the spare and tools all hidden somewhere in the
> boot (2).

A good analogy!

> As a complete asside, it has also been suggested that the two documents
> be merged.  From memory GCC did this.

GCC still works this way.  GDB has it as a separate document because
that's how John Gilmore set it up, and although I wasn't there, I bet
Roland Pesch, as the only professional tech writer at Cygnus at the time,
strongly objected to gluing the internals documentation into the user
manual.  (Probably the same way would have happened to GCC if he'd had
any input into GCC docs.)

I've thought about merging them from time to time.  The main argument
against merging should be obvious; the user manual is just that, and
should not include anything that might mislead or intimidate users.
The arguments for merging are that it slightly simplifies document
maintenance, and more importantly that it facilitates the transition
from being a user of the tool to being a developer of it.  (How often
have you looked at a GCC manual to find an option, then idly flipped
through the porting section and thought about trying your hand at it?
All the info you need is right there, right?....)

To me the arguments on each side seemed to have about equal weight, and
so I opted for the status quo.  But if people felt strongly that the GCC
approach was better, I'd be agreeable to merging the GDB manuals.

Stan

Re: Merging manuals (was Re: How do you use GDB to debug GDB)

[J.T. Conklin]

>>>>> "Stan" == Stan Shebs <shebs@apple.com> writes:
>> As a complete asside, it has also been suggested that the two documents
>> be merged.  From memory GCC did this.

Stan> GCC still works this way.  GDB has it as a separate document
Stan> because that's how John Gilmore set it up, and although I wasn't
Stan> there, I bet Roland Pesch, as the only professional tech writer
Stan> at Cygnus at the time, strongly objected to gluing the internals
Stan> documentation into the user manual.  (Probably the same way
Stan> would have happened to GCC if he'd had any input into GCC docs.)

Stan> I've thought about merging them from time to time.  The main
Stan> argument against merging should be obvious; the user manual is
Stan> just that, and should not include anything that might mislead or
Stan> intimidate users.

I think the split users/internals manuals is a good thing.  I've seen
the puzzled expressions of folks when encountering the gcc manual for
the first time.  They were quite relieved when they learned that they
didn't have to learn about all that stuff just to use the compiler.

A further split into a users and a reference manual is also desirable.
I can't recall a single manual where both introductory and reference
information was presented well.  Separating them into two allows each
to focus more clearly on it's target audiance, but the pair would
probably be more difficult to maintain than one.  Because of that, I
can't recommend we go that route.  

But it is something to consider as we continue editing the manual, I
think our current scheme leaves a lot to be desired.

        --jtc

-- 
J.T. Conklin
RedBack Networks

Re: Merging manuals (was Re: How do you use GDB to debug GDB)

[Michael Meissner]

On Tue, Mar 20, 2001 at 04:23:37PM -0800, J.T. Conklin wrote:
> >>>>> "Stan" == Stan Shebs <shebs@apple.com> writes:
> >> As a complete asside, it has also been suggested that the two documents
> >> be merged.  From memory GCC did this.
> 
> Stan> GCC still works this way.  GDB has it as a separate document
> Stan> because that's how John Gilmore set it up, and although I wasn't
> Stan> there, I bet Roland Pesch, as the only professional tech writer
> Stan> at Cygnus at the time, strongly objected to gluing the internals
> Stan> documentation into the user manual.  (Probably the same way
> Stan> would have happened to GCC if he'd had any input into GCC docs.)
> 
> Stan> I've thought about merging them from time to time.  The main
> Stan> argument against merging should be obvious; the user manual is
> Stan> just that, and should not include anything that might mislead or
> Stan> intimidate users.
> 
> I think the split users/internals manuals is a good thing.  I've seen
> the puzzled expressions of folks when encountering the gcc manual for
> the first time.  They were quite relieved when they learned that they
> didn't have to learn about all that stuff just to use the compiler.

Note, in the case of the GCC manual, you really can't use the extended asm
extension, without knowing what the valid constraint letters are, and those of
course are in the implementation section.

-- 
Michael Meissner, Red Hat, Inc.  (GCC group)
PMB 198, 174 Littleton Road #3, Westford, Massachusetts 01886, USA
Work:	  meissner@redhat.com		phone: +1 978-486-9304
Non-work: meissner@spectacle-pond.org	fax:   +1 978-692-4482

Re: Merging manuals (was Re: How do you use GDB to debug GDB)

[Eli Zaretskii]

On 20 Mar 2001, J.T. Conklin wrote:

> I've seen the puzzled expressions of folks when encountering the gcc
> manual for the first time.

I don't think the GCC manual is something we should consider as an
example: it is IMHO in such a bad shape that it cannot possibly serve
as a useful example of anything.  For starters, its indices, the
single most important means for finding information quickly, omit too
much; even the command-line options are not indexed!

> A further split into a users and a reference manual is also desirable.
> I can't recall a single manual where both introductory and reference
> information was presented well.

Please tell what would you like to see in a typical reference
manual, and why do you think a single manual cannot usefully serve
that purpose along with being an introduction.

The usual philosophy of a good manual written in Texinfo is that you
describe the various package facilities in a logical order, as
appropriate for someone who learns to use the package for the first
time, and leave it up to the indexing to provide the ability of using
the manual as a reference.

> But it is something to consider as we continue editing the manual, I
> think our current scheme leaves a lot to be desired.

If you have specific issues with the current scheme and/or suggestions
for improvement, please tell what they are.

Re: Merging manuals (was Re: How do you use GDB to debug GDB)

[Eli Zaretskii]

On Tue, 20 Mar 2001, Stan Shebs wrote:

> The arguments for merging are that it slightly simplifies document
> maintenance, and more importantly that it facilitates the transition
> from being a user of the tool to being a developer of it.

There's another important consideration: the ease of finding
information when you use the manual as a reference (as opposed to a
textbook which is read in its entirety).

The most efficient means of using a manual as a reference is the `i'
command of the Info browser.  (For those who don't know: that command
looks up a string you type in the manual's indices, and in a
well-indexed manual, will usually land you on the right spot in a
matter of seconds.)

If that fails, the next best alternative is `s' which searches the
manual's text for a string or a regexp.

By contrast, the facilities presented by today's Info browsers for
searching multiple documents are abysmally inadequate.  In the
stand-alone Info reader, we have the --apropos option (which I'm quite
sure some of the people here have never heard about); and we have
nothing similar in Emacs.

Also, please note that the chapters which describe annotations and
GDB/MI are already very technical in nature and come very close to
documenting the internals.

So I think, on balance, merging the two documents would be a good
thing.