Re: @dircategory for gdb manuals

Re: @dircategory for gdb manuals

[Andrew Cagney]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 3101 bytes --]

Eli, are the attatched tweaks ok, for 6.1.1?

Andrew
---  Begin Message  ---

From : karl at gnu dot org (Karl Berry)
To : gdb at sources dot redhat dot com
Date : Sat, 10 Apr 2004 21:02:30 +0200
Subject : @dircategory for gdb manuals
Delivery-date : Sat, 10 Apr 2004 15:02:55 -0400
Envelope-to : cagney@gnu.org

(Sorry if this is the wrong place, mail to bug-gdb only elicited a
suggestion to try here.)

I'd like to suggest the following minor changes to the GDB manuals to
change their categories in the Texinfo dir file -- I've been trying to
rationalize these categories per rms's suggestions.  (I know that
"Software libraries" is not exactly right for internals documents, but
it is the closest we've got.)

Also, the frontmatter should be changed to use @copying, the GNU free
documentation license, @ifnottex around the Top node, etc. -- this patch
doesn't do those things.  See
  http://texinfo.org/manual/Document-Permissions.html
  http://texinfo.org/manual/GNU-Sample-Texts.html
for information and for an example of recommended frontmatter for GNU
manuals.  Right now, the copying information doesn't end up in the HTML
output, for instance, which is not a good thing.

Finally, at one point there seems to have been a libgdb.texinfo.  Is
that no longer being distributed?  I don't see it in the 6.0
distribution.  (I'd just like to remove it from my example dir file, if
it's truly gone.)

Please let me know if questions or problems.

Thanks,
karl (Texinfo maintainer)


*** ./ORIG/gdb.texinfo	Sat Aug  9 08:10:35 2003
--- ./gdb.texinfo	Sat Nov 15 09:03:32 2003
***************
*** 39,45 ****
  @c This is a dir.info fragment to support semi-automated addition of
  @c manuals to an info tree.
! @dircategory Programming & development tools.
  @direntry
! * Gdb: (gdb).                     The @sc{gnu} debugger.
  @end direntry
  
--- 39,45 ----
  @c This is a dir.info fragment to support semi-automated addition of
  @c manuals to an info tree.
! @dircategory Software development
  @direntry
! * Gdb: (gdb).                   The GNU debugger.
  @end direntry
  
*** ./ORIG/gdbint.texinfo	Mon Aug 18 13:12:32 2003
--- ./gdbint.texinfo	Sat Nov 15 09:05:42 2003
***************
*** 2,6 ****
  @setfilename gdbint.info
  @include gdb-cfg.texi
! @dircategory Programming & development tools.
  @direntry
  * Gdb-Internals: (gdbint).	The GNU debugger's internals.
--- 2,6 ----
  @setfilename gdbint.info
  @include gdb-cfg.texi
! @dircategory Software libraries
  @direntry
  * Gdb-Internals: (gdbint).      The GNU debugger's internals.
*** ./ORIG/stabs.texinfo	Mon Aug  4 13:43:36 2003
--- ./stabs.texinfo	Sat Nov 15 09:05:57 2003
***************
*** 4,14 ****
  @c @finalout
  
! @ifinfo
! @format
! START-INFO-DIR-ENTRY
  * Stabs: (stabs).                 The "stabs" debugging information format.
! END-INFO-DIR-ENTRY
! @end format
! @end ifinfo
  
  @ifinfo
--- 4,11 ----
  @c @finalout
  
! @dircategory Software libraries
! @direntry
  * Stabs: (stabs).               The "stabs" debugging information format.
! @end direntry
  
  @ifinfo

---  End Message  ---

Re: @dircategory for gdb manuals

[Eli Zaretskii]

> Date: Tue, 25 May 2004 17:26:59 -0400
> From: Andrew Cagney <cagney@gnu.org>
> 
> Eli, are the attatched tweaks ok, for 6.1.1?

I'm a bit unhappy with classifying the internals manuals under
"Software Libraries".  Karl, could you please you explain the
rationale behind such a bizarre classification?

Re: @dircategory for gdb manuals

[Eli Zaretskii]

> Date: Mon, 31 May 2004 15:21:50 -0400
> From: Andrew Cagney <cagney@gnu.org>
> > 
> > Andrew, I guess it's your call.
> 
> Hmm,  Eli, you're the maintainer for GDB's doco :-)

Hmm.., gee, I am, am I?

> So, which section should they go in?

"Software Development", IMO.

Re: @dircategory for gdb manuals

[Andrew Cagney]

Date: Fri, 28 May 2004 09:24:40 -0400
From: karl@freefriends.org (Karl Berry)

Anyway, of course you're the maintainers, it's your decision.  I was
just trying to make the dir file a little cleaner, and rms asked me to
use the FSD categories, so I sent off patches doing that.  Do with it
what you will.


Andrew, I guess it's your call.
Hmm,  Eli, you're the maintainer for GDB's doco :-)

To clarify, I would put both stabs and gdbint in the same section as
the GDB user manual.
So, which section should they go in?

Andrew

Re: @dircategory for gdb manuals

[Eli Zaretskii]

> Date: Fri, 28 May 2004 09:24:40 -0400
> From: karl@freefriends.org (Karl Berry)
> 
> Anyway, of course you're the maintainers, it's your decision.  I was
> just trying to make the dir file a little cleaner, and rms asked me to
> use the FSD categories, so I sent off patches doing that.  Do with it
> what you will.

Andrew, I guess it's your call.

To clarify, I would put both stabs and gdbint in the same section as
the GDB user manual.

Re: @dircategory for gdb manuals

[Eli Zaretskii]

> Date: Thu, 27 May 2004 09:41:36 -0400
> From: karl@freefriends.org (Karl Berry)
> 
>     > Perhaps "Software development" would be better.
> 
>     Why not leave it in the same category as the GDB user manual?  
> 
> "Software development" is in fact the category I was proposing for the
> GDB user manual.

That's okay with me.

>     I doubt that some J. Random Hacker will be too interested in reading
>     that, unless he or she is working on GDB development.
> 
> I don't understand what you're saying.  I agree, J. Random Hacker is not
> likely to be interested in reading the GDB internals manual unless
> they're working on GDB.  And this is why I proposed different categories
> for them!

I was saying that gdbint.texinfo without gdb.texinfo is not a useful
reading.  They should be (and probably are) read together, and thus
it doesn't make much sense, IMHO, to separate them.

> Since stabs, bfd, and mmalloc are pretty clearly "Software libraries",
> it seemed to me that the most natural place for the internals manual
> (which is related to those) was also Software libraries

The difference between bfd and mmalloc on the one side, and stabs on
the other is that the latter is not really a general-purpose library
like the former.

Re: @dircategory for gdb manuals

[Eli Zaretskii]

> Date: Wed, 26 May 2004 09:26:29 -0400
> From: karl@freefriends.org (Karl Berry)
> 
> Perhaps "Software development" would be better.

Why not leave it in the same category as the GDB user manual?  I doubt
that some J. Random Hacker will be too interested in reading that,
unless he or she is working on GDB development.