[RFC/Doc]: Some words about Fortran debugging

[RFC/Doc]: Some words about Fortran debugging

[Wu Zhou]

Hi Eli,

I added some words in chapter 12 to describe some Fortran specific support.  
Appended is the patch.  I use "made info" to verify that it does works.  
Do I need to do anything other to verify that?  What things I need to keep 
in mind if I want to add something into the document?

As you might know, it is the first time for me to work on texinfo.  So if 
there is anything wrong or inproper, please feel free to correct me.  
Thanks a lot!

Here goes the patch:

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.282
diff -c -3 -p -r1.282 gdb.texinfo
*** gdb.texinfo	1 Nov 2005 11:09:18 -0000	1.282
--- gdb.texinfo	7 Nov 2005 03:10:21 -0000
*************** function, @code{_NSPrintForDebugger}, de
*** 9089,9094 ****
--- 9089,9153 ----
  @subsection Fortran
  @cindex Fortran-specific support in @value{GDBN}
  
+ @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.
+ 
+ @cindex Add a trailing underscore or not
+ 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.
+ 
+ @menu
+ * Fortran Operators::           Fortran operators and expressions
+ * Fortran Defaults::            Default settings for Fortran
+ * Special commands::            Special @value{GDBN} commands for Fortran
+ * Known Problems::              Known problems and workaround (if exists)
+ @end menu
+ 
+ @node Fortran Operators
+ @subsubsection Fortran operators and expressions
+ 
+ @cindex Fortran operators and expressions
+ 
+ Operators must be defined on values of specific types.  For instance,
+ @code{+} is defined on numbers, but not on structures.  Operators are
+ often defined on groups of types.
+ 
+ @table @code
+ @item **
+ The exponentiation operator. It raises the first operand to the power
+ of the second one.
+ 
+ @item :
+ The range operator.  Normally used in the form of array(low:high) to
+ represent a section of array.
+ @end table
+ 
+ @node Fortran Defaults
+ @subsubsection Fortran Defaults
+ 
+ @cindex Fortran Defaults
+ 
+ Fortran symbols are usually case-insensitive, so @value{GDBN} by
+ default uses case-insensitive matches for Fortran symbols.  You can
+ change that with the @samp{set case-insensitive} command, see
+ @ref{Symbols}, for the details.
+ 
+ @node Special commands
+ @subsubsection Special commands
+ 
+ @cindex Special commands
+ 
+ @value{GDBN} had some commands to support Fortran specific feature,
+ such as common block display.
+ 
  @table @code
  @cindex @code{COMMON} blocks, Fortran
  @kindex info common
*************** all @code{COMMON} blocks visible at curr
*** 9099,9108 ****
  printed.
  @end table
  
! Fortran symbols are usually case-insensitive, so @value{GDBN} by
! default uses case-insensitive matches for Fortran symbols.  You can
! change that with the @samp{set case-insensitive} command, see
! @ref{Symbols}, for the details.
  
  @node Pascal
  @subsection Pascal
--- 9158,9172 ----
  printed.
  @end table
  
! @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.
  
  @node Pascal
  @subsection Pascal

Regards
- Wu Zhou

P.S: This patch is quite an initial one.  I am mainly use this to solicit 
comment to see if I am on the correct track. 

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

[Eli Zaretskii]

> 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.

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

[Wu Zhou]

Hi Eli,

Thanks for your comment. I got some more understanding about the 
documenting mechnism now.

On Tue, 8 Nov 2005, Eli Zaretskii wrote:

> > Do I need to do anything other to verify that?
> 
> It's preferable to also "make dvi".
> 

It seems that it need tetex and te_latex.  Would you please tell me where 
I can get these packages?  I found that none of FC4, RHEL and SLES 
include these package.

> 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.)

Okay, I will adopt most of what you said.  But what about replace the word 
"only" with "mainly", because there is a little support for F95 already in 
current GDB.

Here goes the revised patch.  I checked it with "make info".  No obvious 
problem is found.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.284
diff -c -3 -p -r1.284 gdb.texinfo
*** gdb.texinfo	7 Nov 2005 13:56:48 -0000	1.284
--- gdb.texinfo	9 Nov 2005 08:24:00 -0000
*************** function, @code{_NSPrintForDebugger}, de
*** 9124,9129 ****
--- 9124,9182 ----
  @subsection Fortran
  @cindex Fortran-specific support in @value{GDBN}
  
+ @value{GDBN} can be used to debug programs written in Fortran, but it
+ currently supports mainly the features of Fortran 77 language.
+ 
+ @cindex trailing underscore, in Fortran symbols
+ 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.
+ 
+ @menu
+ * Fortran Operators::           Fortran operators and expressions
+ * Fortran Defaults::            Default settings for Fortran
+ * Special Fortran commands::    Special @value{GDBN} commands for Fortran
+ @end menu
+ 
+ @node Fortran Operators
+ @subsubsection Fortran operators and expressions
+ 
+ @cindex Fortran operators and expressions
+ 
+ Operators must be defined on values of specific types.  For instance,
+ @code{+} is defined on numbers, but not on structures.  Operators are
+ often defined on groups of types.
+ 
+ @table @code
+ @item **
+ The exponentiation operator. It raises the first operand to the power
+ of the second one.
+ 
+ @item :
+ The range operator.  Normally used in the form of array(low:high) to
+ represent a section of array.
+ @end table
+ 
+ @node Fortran Defaults
+ @subsubsection Fortran Defaults
+ 
+ @cindex Fortran Defaults
+ 
+ Fortran symbols are usually case-insensitive, so @value{GDBN} by
+ default uses case-insensitive matches for Fortran symbols.  You can
+ change that with the @samp{set case-insensitive} command, see
+ @ref{Symbols}, for the details.
+ 
+ @node Special Fortran commands
+ @subsubsection Special Fortran commands
+ 
+ @cindex Special Fortran commands
+ 
+ @value{GDBN} had some commands to support Fortran specific feature,
+ such as common block displaying.
+ 
  @table @code
  @cindex @code{COMMON} blocks, Fortran
  @kindex info common
*************** all @code{COMMON} blocks visible at curr
*** 9134,9144 ****
  printed.
  @end table
  
- Fortran symbols are usually case-insensitive, so @value{GDBN} by
- default uses case-insensitive matches for Fortran symbols.  You can
- change that with the @samp{set case-insensitive} command, see
- @ref{Symbols}, for the details.
- 
  @node Pascal
  @subsection Pascal
  
--- 9187,9192 ----


Regards
- Wu Zhou

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

[Eli Zaretskii]

> Date: Wed, 9 Nov 2005 16:40:41 +0800 (CST)
> From: Wu Zhou <woodzltc@cn.ibm.com>
> cc: gdb-patches@sources.redhat.com
> 
> > It's preferable to also "make dvi".
> > 
> 
> It seems that it need tetex and te_latex.  Would you please tell me where 
> I can get these packages?

Googling finds teTeX's home page as the first hit:

    http://www.tug.org/teTeX/

> Okay, I will adopt most of what you said.  But what about replace the word 
> "only" with "mainly", because there is a little support for F95 already in 
> current GDB.

What F95 features do we support now?

> Here goes the revised patch.

Fine with me, thanks.

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

[Wu Zhou]

On Wed, 9 Nov 2005, Eli Zaretskii wrote:

> Googling finds teTeX's home page as the first hit:
> 
>     http://www.tug.org/teTeX/

I just got a teTex installed and do a "make dvi".  No obvious error is 
detected.
 
> > Okay, I will adopt most of what you said.  But what about replace the word 
> > "only" with "mainly", because there is a little support for F95 already in 
> > current GDB.
> 
> What F95 features do we support now?

In fact, the array section operation is standardized in Fortran 90.  Not 
any other Fortran 95 features is supported in current GDB.  So I can 
change the word back to "only". (I am working on some Fortran 95 features,
such as derived type and so on.  Maybe I can change the wording when they 
are added into GDB.)
 
> > Here goes the revised patch.
> 
> Fine with me, thanks.

Do you means that I can commit the patch into cvs tree, with the above 
wording change?  Or that I still need to get other maintainers' approval?

Regards
- Wu Zhou

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

[Eli Zaretskii]

> Date: Thu, 10 Nov 2005 11:33:14 +0800 (CST)
> From: Wu Zhou <woodzltc@cn.ibm.com>
> cc: gdb-patches@sources.redhat.com
> 
> I just got a teTex installed and do a "make dvi".  No obvious error is 
> detected.

Thanks.

> > > Here goes the revised patch.
> > 
> > Fine with me, thanks.
> 
> Do you means that I can commit the patch into cvs tree, with the above 
> wording change?

Yes.

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

[Wu Zhou]

On Thu, 10 Nov 2005, Eli Zaretskii wrote:

> > Date: Thu, 10 Nov 2005 11:33:14 +0800 (CST)
> > From: Wu Zhou <woodzltc@cn.ibm.com>
> > cc: gdb-patches@sources.redhat.com
> > 
> > I just got a teTex installed and do a "make dvi".  No obvious error is 
> > detected.
> 
> Thanks.
> 
> > > > Here goes the revised patch.
> > > 
> > > Fine with me, thanks.
> > 
> > Do you means that I can commit the patch into cvs tree, with the above 
> > wording change?
> 
> Yes.

Thanks.  The patch is just checked in.

BTW, there was a merge error when I tried the first checkin.  That deleted 
Jim Blandy's latest patch about general query packets.  So I made another 
checkin correcting that.

Really sorry for that, Jim and Eli.  If there are yet some errors around, 
please correct me.  Thanks.

Regards
- Wu Zhou

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

[Wu Zhou]

Hi Eli,

On Thu, 10 Nov 2005, Eli Zaretskii wrote:

> > Date: Thu, 10 Nov 2005 11:33:14 +0800 (CST)
> > From: Wu Zhou <woodzltc@cn.ibm.com>
> > cc: gdb-patches@sources.redhat.com
> > 
> > I just got a teTex installed and do a "make dvi".  No obvious error is 
> > detected.
> 
> Thanks.
> 
> > > > Here goes the revised patch.
> > > 
> > > Fine with me, thanks.
> > 
> > Do you means that I can commit the patch into cvs tree, with the above 
> > wording change?
> 
> Yes.
> 

Could I check in this patch into gdb_6_4 branch as well. I had already checked 
it into the mainline tree.

Regards
- Wu Zhou

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

[Eli Zaretskii]

> Date: Tue, 22 Nov 2005 14:14:43 +0800 (CST)
> From: Wu Zhou <woodzltc@cn.ibm.com>
> 
> On Thu, 10 Nov 2005, Eli Zaretskii wrote:
> 
> > > Date: Thu, 10 Nov 2005 11:33:14 +0800 (CST)
> > > From: Wu Zhou <woodzltc@cn.ibm.com>
> > > cc: gdb-patches@sources.redhat.com
> > > 
> > > I just got a teTex installed and do a "make dvi".  No obvious error is 
> > > detected.
> > 
> > Thanks.
> > 
> > > > > Here goes the revised patch.
> > > > 
> > > > Fine with me, thanks.
> > > 
> > > Do you means that I can commit the patch into cvs tree, with the above 
> > > wording change?
> > 
> > Yes.
> > 
> 
> Could I check in this patch into gdb_6_4 branch as well.

Yes, please do.

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

[Wu Zhou]

On Tue, 22 Nov 2005, Eli Zaretskii wrote:

> > Could I check in this patch into gdb_6_4 branch as well.
> 
> Yes, please do.

Checked in.  Thanks. 

Appended is the cvs diff.

2005-11-23  Wu Zhou  <woodzltc@cn.ibm.com>

	* gdb.texinfo (Fortran): Add some words about Fortran debugging.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.282.2.3
diff -u -p -r1.282.2.3 gdb.texinfo
--- gdb.texinfo	16 Nov 2005 12:44:11 -0000	1.282.2.3
+++ gdb.texinfo	23 Nov 2005 02:29:12 -0000
@@ -9124,6 +9124,59 @@ function, @code{_NSPrintForDebugger}, de
 @subsection Fortran
 @cindex Fortran-specific support in @value{GDBN}
 
+@value{GDBN} can be used to debug programs written in Fortran, but it
+currently supports only the features of Fortran 77 language.
+
+@cindex trailing underscore, in Fortran symbols
+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.
+
+@menu
+* Fortran Operators::           Fortran operators and expressions
+* Fortran Defaults::            Default settings for Fortran
+* Special Fortran commands::    Special @value{GDBN} commands for Fortran
+@end menu
+
+@node Fortran Operators
+@subsubsection Fortran operators and expressions
+
+@cindex Fortran operators and expressions
+
+Operators must be defined on values of specific types.  For instance,
+@code{+} is defined on numbers, but not on characters or other non-
+arithmetic types.  Operators are often defined on groups of types.
+
+@table @code
+@item **
+The exponentiation operator. It raises the first operand to the power
+of the second one.
+
+@item :
+The range operator.  Normally used in the form of array(low:high) to
+represent a section of array.
+@end table
+
+@node Fortran Defaults
+@subsubsection Fortran Defaults
+
+@cindex Fortran Defaults
+
+Fortran symbols are usually case-insensitive, so @value{GDBN} by
+default uses case-insensitive matches for Fortran symbols.  You can
+change that with the @samp{set case-insensitive} command, see
+@ref{Symbols}, for the details.
+
+@node Special Fortran commands
+@subsubsection Special Fortran commands
+
+@cindex Special Fortran commands
+
+@value{GDBN} had some commands to support Fortran specific feature,
+such as common block displaying.
+
 @table @code
 @cindex @code{COMMON} blocks, Fortran
 @kindex info common
@@ -9134,11 +9187,6 @@ all @code{COMMON} blocks visible at curr
 printed.
 @end table
 
-Fortran symbols are usually case-insensitive, so @value{GDBN} by
-default uses case-insensitive matches for Fortran symbols.  You can
-change that with the @samp{set case-insensitive} command, see
-@ref{Symbols}, for the details.
-
 @node Pascal
 @subsection Pascal

 
Regards
- Wu Zhou