Re: [RFC/Doc]: Some words about Fortran debugging

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Mon, 7 Nov 2005 11:26:02 +0800 (CST)
> From: Wu Zhou <woodzltc@cn.ibm.com>
> 
> I added some words in chapter 12 to describe some Fortran specific support.  
> Appended is the patch.

Thanks!

> Do I need to do anything other to verify that?

It's preferable to also "make dvi".

> What things I need to keep in mind if I want to add something into
> the document?

See my comments below.

> + @value{GDBN} can be used to debug programs written in Fortran, but it
> + mainly support the old Fortran 77 language features.  For most of these
> + new language feature introduced after Fortran 77 standard, such as
> + derived type, modular, pointer and so on, @value{GDBN} doesn't support
> + yet.  But there are some effort trying to add support for them.

I'd remove most of this text, leaving just this:

  @value{GDBN} can be used to debug programs written in Fortran, but it
  currently supports only the features of the Fortran 77 language.

(The manual is not the place to tell users we are improving GDB.
Reading that doesn't help them if they need those unimplemented
features now.)

> + @cindex Add a trailing underscore or not

This is too cumbersome for an index entry, and uses up valuable space
for uninformative words such as "a", "add", and "or".  I suggest this
instead:

  @cindex trailing underscore, in Fortran symbols

> + To debug some Fortran compilers generated code, you may need to refer to
> + some variables or functions with a trailing underscore.  GNU Fortran 77
> + and Fortran 95 compiler are among this kind of compilers.  As far as I
> + know, you don't need to do that for IBM's XL Fortran compiler and Intel's
> + Fortran compiler.  If you are not sure, you can use the command completion
> + feature of @value{GDBN} to see whether there is a trailing underscore or
> + not.

I'd simplify this as follows:

  Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers
  among them) append an underscore to the names of variables and
  functions.  When you debug programs compiled by those compilers, you
  will need to refer to variables and functions with a trailing
  underscore.

> + * Special commands::            Special @value{GDBN} commands for Fortran

Suggest to rename this node to "Special Fortran Commands", so it is
more specific.

> + @node Special commands

and here as well.

> ! @node Known Problems
> ! @subsubsection Known Problems
> ! 
> ! @cindex Known Problems
> ! 
> ! There are a few known problems while using @value{GDBN} to debug Fortran
> ! code.  Some of them might even crash GDB or the debugged program.  So
> ! you need to pay attention to them when using @value{GDBN} to debug Fortran
> ! program.

This is not useful at all: you are telling the user that GDB might
crash unless they pay attention to something, but don't say what that
something is!

Unless we can give specific advice what they shouldn't do, I'd prefer
to remove this subsubsection.

Thanks again for working on this.