Re: Conditionals in GDB manual

Re: Conditionals in GDB manual

[Jeffrey A Law]

  In message <199902050402.UAA16377@cygint.cygnus.com>you write:
  > I've been working over the GDB manual, and am looking at all the
  > conditionals in it; AMD29K, SPARCLET, VXWORKS, DOSHOST, POSIX, etc.
  > There are about 40 of them, and as far as I can tell, many of them
  > have never been used to make a subset manual.  The exceptions are a
  > Hitachi H8-specific manual done in 1993, and more recently an HP-UX
  > specific manual, although many of the HPPA conditionals should appear
  > in the generic manual also.
  > 
  > So I'm considering whacking most or all of the conditionals.  This
  > won't matter to most people, because the default build/configure
  > enables almost all of these conditionals.  However, if anybody has a
  > good use for a particular conditional, you'll know what it is and can
  > tell me, so that I preserve it.  (I'm already discussing the HPPA bits
  > with Roz de la Torre at HP.)
Might it make more sense to have processor specific appendices?  We need
somewhere to put processor/os specific stuff.

Just a thought.  

jeff

Re: Conditionals in GDB manual

[J.T. Conklin]

>> I've been working over the GDB manual, and am looking at all the
>> conditionals in it; AMD29K, SPARCLET, VXWORKS, DOSHOST, POSIX, etc.
>> There are about 40 of them, and as far as I can tell, many of them
>> have never been used to make a subset manual.  The exceptions are a
>> Hitachi H8-specific manual done in 1993, and more recently an HP-UX
>> specific manual, although many of the HPPA conditionals should
>> appear in the generic manual also.
>> 
>> So I'm considering whacking most or all of the conditionals.  This
>> won't matter to most people, because the default build/configure
>> enables almost all of these conditionals.  However, if anybody has
>> a good use for a particular conditional, you'll know what it is and
>> can tell me, so that I preserve it.  (I'm already discussing the
>> HPPA bits with Roz de la Torre at HP.)

> Might it make more sense to have processor specific appendices?
> We need somewhere to put processor/os specific stuff.

Ideally, there would be One True GDB Manual that contained all
information for all hosts and targets, organized in such a way so
environment specific information could be identified and located
easily by readers.  Appendicies for both host and target specific
information might be a good way to accomplish this.

The many conditionals that select parts of the "Remote Debugging"
chapter seem to go along with this idea, although the individual
sections don't share the same outline of sub-sections and moving
them to an appendix might be a bit more of an overhaul than is 
envisioned.

As removing the conditionals doesn't preclude a more comprehensive
edit later, I'd be in favor of it.

	--jtc

-- 
J.T. Conklin
RedBack Networks

Re: Conditionals in GDB manual

[Stan Shebs]

   From: jtc@redbacknetworks.com (J.T. Conklin)
   Date: 05 Feb 1999 12:15:50 -0800

   Ideally, there would be One True GDB Manual that contained all
   information for all hosts and targets, organized in such a way so
   environment specific information could be identified and located
   easily by readers.  Appendicies for both host and target specific
   information might be a good way to accomplish this.

Yes.  The effect of the conditionals is to allow people to make 2^40
different One of Many GDB Manuals, each with no indication to the
reader that they are different from the complete manual.

   The many conditionals that select parts of the "Remote Debugging"
   chapter seem to go along with this idea, although the individual
   sections don't share the same outline of sub-sections and moving
   them to an appendix might be a bit more of an overhaul than is 
   envisioned.

There's no reason not to reorganize the manual in whatever way makes
it the most accessible to readers.  I note that most of GCC's target
specific info sits in the chapter on command-line options, and
everybody seems to be OK with that.  For GDB, I'm leaning towards a
regular chapter or two, mostly because the info for some targets is
fairly extensive and critical to using them, and appendices are better
for small amounts of optional info.  But I haven't made a decision yet.

							Stan


							

Re: Conditionals in GDB manual

[Stan Shebs]

   Date: Fri, 05 Feb 1999 09:36:31 -0700
   From: Jeffrey A Law <law@hurl.cygnus.com>

   Might it make more sense to have processor specific appendices?  We need
   somewhere to put processor/os specific stuff.

Yes, I'd like to do that anyway.  There have been two different attempts
to organize platform-specific stuff, each incomplete.  I think readers
just flip over those sections now, so I don't think their presence is
objectionable, but it is hard to find, say, all remote debugging details
or all native debugging details.

Right now the conditionals are making it hard even to figure out what
the organization should be, since there are so many (about 280
ifset/ifclears in the 11K lines of gdb.texinfo).  Makes the manual
look like an over-ifdefed piece of source code...

							Stan

Conditionals in GDB manual

[Stan Shebs]

I've been working over the GDB manual, and am looking at all the
conditionals in it; AMD29K, SPARCLET, VXWORKS, DOSHOST, POSIX, etc.
There are about 40 of them, and as far as I can tell, many of them
have never been used to make a subset manual.  The exceptions are a
Hitachi H8-specific manual done in 1993, and more recently an HP-UX
specific manual, although many of the HPPA conditionals should appear
in the generic manual also.

So I'm considering whacking most or all of the conditionals.  This
won't matter to most people, because the default build/configure
enables almost all of these conditionals.  However, if anybody has a
good use for a particular conditional, you'll know what it is and can
tell me, so that I preserve it.  (I'm already discussing the HPPA bits
with Roz de la Torre at HP.)

							Stan