Re: [Patch] Remove gccbug from bugreport.texi, take 3

[Wolfgang Bangerth <bangerth at ices dot utexas dot edu>]

> > So is the following something that people would like?
> 
> This patch looks good to me (the copyright notice in bugreport.texi may
> need updating, and there's a typo "thath" on the last line of the patch);  

Thanks. Taken care of.

> let Gerald look at it as well (and if it's approved, a follow-up patch to
> do much the same with the Fortran manual would be nice).

Done, too. Attached is the patch for both files. 

W.


Index: doc/bugreport.texi
===================================================================
RCS file: /cvsroot/gcc/gcc/gcc/doc/bugreport.texi,v
retrieving revision 1.4
diff -c -r1.4 bugreport.texi
*** doc/bugreport.texi	11 Apr 2003 21:34:57 -0000	1.4
--- doc/bugreport.texi	13 May 2003 22:16:42 -0000
***************
*** 1,5 ****
  @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
! @c 1999, 2000, 2001 Free Software Foundation, Inc.
  @c This is part of the GCC manual.
  @c For copying conditions, see the file gcc.texi.
  
--- 1,5 ----
  @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
! @c 1999, 2000, 2001, 2003 Free Software Foundation, Inc.
  @c This is part of the GCC manual.
  @c For copying conditions, see the file gcc.texi.
  
***************
*** 29,42 ****
  
  @menu
  * Criteria:  Bug Criteria.   Have you really found a bug?
- * Where: Bug Lists.	     Where to send your bug report.
  * Reporting: Bug Reporting.  How to report a bug effectively.
- * GNATS: gccbug.             You can use a bug reporting tool.
  * Known: Trouble.            Known problems.
  * Help: Service.             Where to ask for help.
  @end menu
  
! @node Bug Criteria,Bug Lists,,Bugs
  @section Have You Found a Bug?
  @cindex bug criteria
  
--- 29,40 ----
  
  @menu
  * Criteria:  Bug Criteria.   Have you really found a bug?
  * Reporting: Bug Reporting.  How to report a bug effectively.
  * Known: Trouble.            Known problems.
  * Help: Service.             Where to ask for help.
  @end menu
  
! @node Bug Criteria,Bug Reporting,,Bugs
  @section Have You Found a Bug?
  @cindex bug criteria
  
***************
*** 99,391 ****
  suggestions for improvement of GCC are welcome in any case.
  @end itemize
  
! @node Bug Lists,Bug Reporting,Bug Criteria,Bugs
! @section Where to Report Bugs
! @cindex bug report mailing lists
! @kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
! 
! Send bug reports for the GNU Compiler Collection to
! @email{gcc-bugs@@gcc.gnu.org}.  In accordance with the GNU-wide
! convention, in which bug reports for tool ``foo'' are sent
! to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org}
! may also be used; it will forward to the address given above.
! 
! Please read @uref{http://gcc.gnu.org/bugs.html} for additional and/or
! more up-to-date bug reporting instructions before you post a bug report.
! 
! @node Bug Reporting,gccbug,Bug Lists,Bugs
! @section How to Report Bugs
  @cindex compiler bugs, reporting
  
! The fundamental principle of reporting bugs usefully is this:
! @strong{report all the facts}.  If you are not sure whether to state a
! fact or leave it out, state it!
! 
! Often people omit facts because they think they know what causes the
! problem and they conclude that some details don't matter.  Thus, you might
! assume that the name of the variable you use in an example does not matter.
! Well, probably it doesn't, but one cannot be sure.  Perhaps the bug is a
! stray memory reference which happens to fetch from the location where that
! name is stored in memory; perhaps, if the name were different, the contents
! of that location would fool the compiler into doing the right thing despite
! the bug.  Play it safe and give a specific, complete example.  That is the
! easiest thing for you to do, and the most helpful.
! 
! Keep in mind that the purpose of a bug report is to enable someone to
! fix the bug if it is not known.  It isn't very important what happens if
! the bug is already known.  Therefore, always write your bug reports on
! the assumption that the bug is not known.
! 
! Sometimes people give a few sketchy facts and ask, ``Does this ring a
! bell?''  This cannot help us fix a bug, so it is basically useless.  We
! respond by asking for enough details to enable us to investigate.
! You might as well expedite matters by sending them to begin with.
! 
! Try to make your bug report self-contained.  If we have to ask you for
! more information, it is best if you include all the previous information
! in your response, as well as the information that was missing.
! 
! Please report each bug in a separate message.  This makes it easier for
! us to track which bugs have been fixed and to forward your bugs reports
! to the appropriate maintainer.
! 
! To enable someone to investigate the bug, you should include all these
! things:
! 
! @itemize @bullet
! @item
! The version of GCC@.  You can get this by running it with the
! @option{-v} option.
! 
! Without this, we won't know whether there is any point in looking for
! the bug in the current version of GCC@.
! 
! @item
! A complete input file that will reproduce the bug.  If the bug is in the
! C preprocessor, send a source file and any header files that it
! requires.  If the bug is in the compiler proper (@file{cc1}), send the
! preprocessor output generated by adding @option{-save-temps} to the
! compilation command (@pxref{Debugging Options}).  When you do this, use
! the same @option{-I}, @option{-D} or @option{-U} options that you used in
! actual compilation.  Then send the @var{input}.i or @var{input}.ii files
! generated.
! 
! A single statement is not enough of an example.  In order to compile it,
! it must be embedded in a complete file of compiler input; and the bug
! might depend on the details of how this is done.
! 
! Without a real example one can compile, all anyone can do about your bug
! report is wish you luck.  It would be futile to try to guess how to
! provoke the bug.  For example, bugs in register allocation and reloading
! frequently depend on every little detail of the function they happen in.
! 
! Even if the input file that fails comes from a GNU program, you should
! still send the complete test case.  Don't ask the GCC maintainers to
! do the extra work of obtaining the program in question---they are all
! overworked as it is.  Also, the problem may depend on what is in the
! header files on your system; it is unreliable for the GCC maintainers
! to try the problem with the header files available to them.  By sending
! CPP output, you can eliminate this source of uncertainty and save us
! a certain percentage of wild goose chases.
! 
! @item
! The command arguments you gave GCC to compile that example
! and observe the bug.  For example, did you use @option{-O}?  To guarantee
! you won't omit something important, list all the options.
! 
! If we were to try to guess the arguments, we would probably guess wrong
! and then we would not encounter the bug.
! 
! @item
! The type of machine you are using, and the operating system name and
! version number.
! 
! @item
! The operands you gave to the @code{configure} command when you installed
! the compiler.
! 
! @item
! A complete list of any modifications you have made to the compiler
! source.  (We don't promise to investigate the bug unless it happens in
! an unmodified compiler.  But if you've made modifications and don't tell
! us, then you are sending us on a wild goose chase.)
! 
! Be precise about these changes.  A description in English is not
! enough---send a context diff for them.
! 
! Adding files of your own (such as a machine description for a machine we
! don't support) is a modification of the compiler source.
! 
! @item
! Details of any other deviations from the standard procedure for installing
! GCC@.
! 
! @item
! A description of what behavior you observe that you believe is
! incorrect.  For example, ``The compiler gets a fatal signal,'' or,
! ``The assembler instruction at line 208 in the output is incorrect.''
! 
! Of course, if the bug is that the compiler gets a fatal signal, then one
! can't miss it.  But if the bug is incorrect output, the maintainer might
! not notice unless it is glaringly wrong.  None of us has time to study
! all the assembler code from a 50-line C program just on the chance that
! one instruction might be wrong.  We need @emph{you} to do this part!
! 
! Even if the problem you experience is a fatal signal, you should still
! say so explicitly.  Suppose something strange is going on, such as, your
! copy of the compiler is out of synch, or you have encountered a bug in
! the C library on your system.  (This has happened!)  Your copy might
! crash and the copy here would not.  If you @i{said} to expect a crash,
! then when the compiler here fails to crash, we would know that the bug
! was not happening.  If you don't say to expect a crash, then we would
! not know whether the bug was happening.  We would not be able to draw
! any conclusion from our observations.
! 
! If the problem is a diagnostic when compiling GCC with some other
! compiler, say whether it is a warning or an error.
! 
! Often the observed symptom is incorrect output when your program is run.
! Sad to say, this is not enough information unless the program is short
! and simple.  None of us has time to study a large program to figure out
! how it would work if compiled correctly, much less which line of it was
! compiled wrong.  So you will have to do that.  Tell us which source line
! it is, and what incorrect result happens when that line is executed.  A
! person who understands the program can find this as easily as finding a
! bug in the program itself.
! 
! @item
! If you send examples of assembler code output from GCC,
! please use @option{-g} when you make them.  The debugging information
! includes source line numbers which are essential for correlating the
! output with the input.
! 
! @item
! If you wish to mention something in the GCC source, refer to it by
! context, not by line number.
! 
! The line numbers in the development sources don't match those in your
! sources.  Your line numbers would convey no useful information to the
! maintainers.
! 
! @item
! Additional information from a debugger might enable someone to find a
! problem on a machine which he does not have available.  However, you
! need to think when you collect this information if you want it to have
! any chance of being useful.
! 
! @cindex backtrace for bug reports
! For example, many people send just a backtrace, but that is never
! useful by itself.  A simple backtrace with arguments conveys little
! about GCC because the compiler is largely data-driven; the same
! functions are called over and over for different RTL insns, doing
! different things depending on the details of the insn.
! 
! Most of the arguments listed in the backtrace are useless because they
! are pointers to RTL list structure.  The numeric values of the
! pointers, which the debugger prints in the backtrace, have no
! significance whatever; all that matters is the contents of the objects
! they point to (and most of the contents are other such pointers).
! 
! In addition, most compiler passes consist of one or more loops that
! scan the RTL insn sequence.  The most vital piece of information about
! such a loop---which insn it has reached---is usually in a local variable,
! not in an argument.
! 
! @findex debug_rtx
! What you need to provide in addition to a backtrace are the values of
! the local variables for several stack frames up.  When a local
! variable or an argument is an RTX, first print its value and then use
! the GDB command @code{pr} to print the RTL expression that it points
! to.  (If GDB doesn't run on your machine, use your debugger to call
! the function @code{debug_rtx} with the RTX as an argument.)  In
! general, whenever a variable is a pointer, its value is no use
! without the data it points to.
! @end itemize
! 
! Here are some things that are not necessary:
! 
! @itemize @bullet
! @item
! A description of the envelope of the bug.
! 
! Often people who encounter a bug spend a lot of time investigating
! which changes to the input file will make the bug go away and which
! changes will not affect it.
! 
! This is often time consuming and not very useful, because the way we
! will find the bug is by running a single example under the debugger with
! breakpoints, not by pure deduction from a series of examples.  You might
! as well save your time for something else.
! 
! Of course, if you can find a simpler example to report @emph{instead} of
! the original one, that is a convenience.  Errors in the output will be
! easier to spot, running under the debugger will take less time, etc.
! Most GCC bugs involve just one function, so the most straightforward
! way to simplify an example is to delete all the function definitions
! except the one where the bug occurs.  Those earlier in the file may be
! replaced by external declarations if the crucial function depends on
! them.  (Exception: inline functions may affect compilation of functions
! defined later in the file.)
! 
! However, simplification is not vital; if you don't want to do this,
! report the bug anyway and send the entire test case you used.
! 
! @item
! In particular, some people insert conditionals @samp{#ifdef BUG} around
! a statement which, if removed, makes the bug not happen.  These are just
! clutter; we won't pay any attention to them anyway.  Besides, you should
! send us cpp output, and that can't have conditionals.
! 
! @item
! A patch for the bug.
! 
! A patch for the bug is useful if it is a good one.  But don't omit the
! necessary information, such as the test case, on the assumption that a
! patch is all we need.  We might see problems with your patch and decide
! to fix the problem another way, or we might not understand it at all.
! 
! Sometimes with a program as complicated as GCC it is very hard to
! construct an example that will make the program follow a certain path
! through the code.  If you don't send the example, we won't be able to
! construct one, so we won't be able to verify that the bug is fixed.
! 
! And if we can't understand what bug you are trying to fix, or why your
! patch should be an improvement, we won't install it.  A test case will
! help us to understand.
! 
! See @uref{http://gcc.gnu.org/contribute.html}
! for guidelines on how to make it easy for us to
! understand and install your patches.
! 
! @item
! A guess about what the bug is or what it depends on.
! 
! Such guesses are usually wrong.  Even I can't guess right about such
! things without first using the debugger to find the facts.
! 
! @item
! A core dump file.
! 
! We have no way of examining a core dump for your type of machine
! unless we have an identical system---and if we do have one,
! we should be able to reproduce the crash ourselves.
! @end itemize
! 
! @node gccbug,, Bug Reporting, Bugs
! @section The gccbug script
! @cindex gccbug script
! 
! To simplify creation of bug reports, and to allow better tracking of
! reports, we use the GNATS bug tracking system.  Part of that system is
! the @command{gccbug} script.  This is a Unix shell script, so you need a
! shell to run it.  It is normally installed in the same directory where
! @command{gcc} is installed.
! 
! The gccbug script is derived from send-pr, @pxref{using
! send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}.  When
! invoked, it starts a text editor so you can fill out the various fields
! of the report.  When the you quit the editor, the report is automatically
! send to the bug reporting address.
! 
! A number of fields in this bug report form are specific to GCC, and are
! explained at @uref{http://gcc.gnu.org/gnats.html}.
--- 97,107 ----
  suggestions for improvement of GCC are welcome in any case.
  @end itemize
  
! @node Bug Reporting,Trouble,Bug Criteria,Bugs
! @section How and where to Report Bugs
  @cindex compiler bugs, reporting
  
! Bugs should be reported to our bug database.  Please refer to
! @uref{http://gcc.gnu.org/bugs.html} for up-to-date instructions how to
! submit bug reports.  A copy of this file should also be part of the
! documentation that comes with GCC releases.
Index: f/g77.texi
===================================================================
RCS file: /cvsroot/gcc/gcc/gcc/f/g77.texi,v
retrieving revision 1.102
diff -c -r1.102 g77.texi
*** f/g77.texi	11 May 2003 12:57:34 -0000	1.102
--- f/g77.texi	13 May 2003 22:16:43 -0000
***************
*** 2,9 ****
  @c %**start of header
  @setfilename g77.info
  
! @set last-update 2002-04-29
! @set copyrights-g77 1995,1996,1997,1998,1999,2000,2001,2002
  
  @include root.texi
  
--- 2,9 ----
  @c %**start of header
  @setfilename g77.info
  
! @set last-update 2003-05-13
! @set copyrights-g77 1995,1996,1997,1998,1999,2000,2001,2002,2003
  
  @include root.texi
  
***************
*** 10445,10451 ****
  
  @menu
  * Criteria: Bug Criteria.    Have you really found a bug?
- * Where: Bug Lists.          Where to send your bug report.
  * Reporting: Bug Reporting.  How to report a bug effectively.
  @end menu
  
--- 10445,10450 ----
***************
*** 10636,10983 ****
  exposes it more readily than other compilers.
  @end itemize
  
- @node Bug Lists
- @section Where to Report Bugs
- @cindex bug report mailing lists
- @kindex @value{email-bugs}
- Send bug reports for GNU Fortran to @email{@value{email-bugs}}.
- 
- Often people think of posting bug reports to a newsgroup instead of
- mailing them.
- This sometimes appears to work, but it has one problem which can be
- crucial: a newsgroup posting does not contain a mail path back to the
- sender.
- Thus, if maintainers need more information, they might be unable
- to reach you.  For this reason, you should always send bug reports by
- mail to the proper mailing list.
- 
- As a last resort, send bug reports on paper to:
- 
- @example
- GNU Compiler Bugs
- Free Software Foundation
- 59 Temple Place - Suite 330
- Boston, MA 02111-1307, USA
- @end example
- 
  @node Bug Reporting
  @section How to Report Bugs
  @cindex compiler bugs, reporting
  
! The fundamental principle of reporting bugs usefully is this:
! @strong{report all the facts}.
! If you are not sure whether to state a
! fact or leave it out, state it!
! 
! Often people omit facts because they think they know what causes the
! problem and they conclude that some details don't matter.
! Thus, you might
! assume that the name of the variable you use in an example does not matter.
! Well, probably it doesn't, but one cannot be sure.
! Perhaps the bug is a
! stray memory reference which happens to fetch from the location where that
! name is stored in memory; perhaps, if the name were different, the contents
! of that location would fool the compiler into doing the right thing despite
! the bug.
! Play it safe and give a specific, complete example.
! That is the
! easiest thing for you to do, and the most helpful.
! 
! Keep in mind that the purpose of a bug report is to enable someone to
! fix the bug if it is not known.
! It isn't very important what happens if
! the bug is already known.
! Therefore, always write your bug reports on
! the assumption that the bug is not known.
! 
! Sometimes people give a few sketchy facts and ask, ``Does this ring a
! bell?''
! This cannot help us fix a bug, so it is rarely helpful.
! We respond by asking for enough details to enable us to investigate.
! You might as well expedite matters by sending them to begin with.
! (Besides, there are enough bells ringing around here as it is.)
! 
! Try to make your bug report self-contained.
! If we have to ask you for
! more information, it is best if you include all the previous information
! in your response, as well as the information that was missing.
! 
! Please report each bug in a separate message.
! This makes it easier for
! us to track which bugs have been fixed and to forward your bugs reports
! to the appropriate maintainer.
! 
! Do not compress and encode any part of your bug report using programs
! such as @file{uuencode}.
! If you do so it will slow down the processing
! of your bug.
! If you must submit multiple large files, use @file{shar},
! which allows us to read your message without having to run any
! decompression programs.
! 
! (As a special exception for GNU Fortran bug-reporting, at least
! for now, if you are sending more than a few lines of code, if
! your program's source file format contains ``interesting'' things
! like trailing spaces or strange characters, or if you need to
! include binary data files, it is acceptable to put all the
! files together in a @command{tar} archive, and, whether you need to
! do that, it is acceptable to then compress the single file (@command{tar}
! archive or source file)
! using @command{gzip} and encode it via @command{uuencode}.
! Do not use any MIME stuff---the current maintainer can't decode this.
! Using @command{compress} instead of @command{gzip} is acceptable, assuming
! you have licensed the use of the patented algorithm in
! @command{compress} from Unisys.)
! 
! To enable someone to investigate the bug, you should include all these
! things:
! 
! @itemize @bullet
! @item
! The version of GNU Fortran.
! You can get this by running @command{g77} with the @option{-v} option.
! (Ignore any error messages that might be displayed
! when the linker is run.)
! 
! Without this, we won't know whether there is any point in looking for
! the bug in the current version of GNU Fortran.
! 
! @item
! @cindex preprocessor
! @cindex cpp program
! @cindex programs, cpp
! @pindex cpp
! A complete input file that will reproduce the bug.
! 
! If your source file(s) require preprocessing
! (for example, their names have suffixes like
! @samp{.F}, @samp{.fpp}, @samp{.FPP}, and @samp{.r}),
! and the bug is in the compiler proper (@file{f771})
! or in a subsequent phase of processing,
! run your source file through the C preprocessor
! by doing @samp{g77 -E @var{sourcefile} > @var{newfile}}.
! Then, include the contents of @var{newfile} in the bug report.
! (When you do this, use the same preprocessor options---such as
! @option{-I}, @option{-D}, and @option{-U}---that you used in actual
! compilation.)
! 
! A single statement is not enough of an example.
! In order to compile it,
! it must be embedded in a complete file of compiler input.
! The bug might depend on the details of how this is done.
! 
! Without a real example one can compile,
! all anyone can do about your bug report is wish you luck.
! It would be futile to try to guess how to provoke the bug.
! For example, bugs in register allocation and reloading
! can depend on every little detail of the source and include files
! that trigger them.
! 
! @item
! @cindex included files
! @cindex INCLUDE directive
! @cindex directive, INCLUDE
! @cindex #include directive
! @cindex directive, #include
! Note that you should include with your bug report any files
! included by the source file
! (via the @code{#include} or @code{INCLUDE} directive)
! that you send, and any files they include, and so on.
! 
! It is not necessary to replace
! the @code{#include} and @code{INCLUDE} directives
! with the actual files in the version of the source file that
! you send, but it might make submitting the bug report easier
! in the end.
! However, be sure to @emph{reproduce} the bug using the @emph{exact}
! version of the source material you submit, to avoid wild-goose
! chases.
! 
! @item
! The command arguments you gave GNU Fortran to compile that example
! and observe the bug.  For example, did you use @option{-O}?  To guarantee
! you won't omit something important, list all the options.
! 
! If we were to try to guess the arguments, we would probably guess wrong
! and then we would not encounter the bug.
! 
! @item
! The type of machine you are using, and the operating system name and
! version number.
! (Much of this information is printed by @samp{g77 -v}---if you
! include that, send along any additional info you have that you
! don't see clearly represented in that output.)
! 
! @item
! The operands you gave to the @command{configure} command when you installed
! the compiler.
! 
! @item
! A complete list of any modifications you have made to the compiler
! source.  (We don't promise to investigate the bug unless it happens in
! an unmodified compiler.  But if you've made modifications and don't tell
! us, then you are sending us on a wild-goose chase.)
! 
! Be precise about these changes.  A description in English is not
! enough---send a context diff for them.
! 
! Adding files of your own (such as a machine description for a machine we
! don't support) is a modification of the compiler source.
! 
! @item
! Details of any other deviations from the standard procedure for installing
! GNU Fortran.
! 
! @item
! A description of what behavior you observe that you believe is
! incorrect.  For example, ``The compiler gets a fatal signal,'' or,
! ``The assembler instruction at line 208 in the output is incorrect.''
! 
! Of course, if the bug is that the compiler gets a fatal signal, then one
! can't miss it.  But if the bug is incorrect output, the maintainer might
! not notice unless it is glaringly wrong.  None of us has time to study
! all the assembler code from a 50-line Fortran program just on the chance that
! one instruction might be wrong.  We need @emph{you} to do this part!
! 
! Even if the problem you experience is a fatal signal, you should still
! say so explicitly.  Suppose something strange is going on, such as, your
! copy of the compiler is out of synch, or you have encountered a bug in
! the C library on your system.  (This has happened!)  Your copy might
! crash and the copy here would not.  If you @i{said} to expect a crash,
! then when the compiler here fails to crash, we would know that the bug
! was not happening.  If you don't say to expect a crash, then we would
! not know whether the bug was happening.  We would not be able to draw
! any conclusion from our observations.
! 
! If the problem is a diagnostic when building GNU Fortran with some other
! compiler, say whether it is a warning or an error.
  
- Often the observed symptom is incorrect output when your program is run.
- Sad to say, this is not enough information unless the program is short
- and simple.  None of us has time to study a large program to figure out
- how it would work if compiled correctly, much less which line of it was
- compiled wrong.  So you will have to do that.  Tell us which source line
- it is, and what incorrect result happens when that line is executed.  A
- person who understands the program can find this as easily as finding a
- bug in the program itself.
- 
- @item
- If you send examples of assembler code output from GNU Fortran,
- please use @option{-g} when you make them.  The debugging information
- includes source line numbers which are essential for correlating the
- output with the input.
- 
- @item
- If you wish to mention something in the GNU Fortran source, refer to it by
- context, not by line number.
- 
- The line numbers in the development sources don't match those in your
- sources.  Your line numbers would convey no convenient information to the
- maintainers.
- 
- @item
- Additional information from a debugger might enable someone to find a
- problem on a machine which he does not have available.  However, you
- need to think when you collect this information if you want it to have
- any chance of being useful.
- 
- @cindex backtrace for bug reports
- For example, many people send just a backtrace, but that is never
- useful by itself.  A simple backtrace with arguments conveys little
- about GNU Fortran because the compiler is largely data-driven; the same
- functions are called over and over for different RTL insns, doing
- different things depending on the details of the insn.
- 
- Most of the arguments listed in the backtrace are useless because they
- are pointers to RTL list structure.  The numeric values of the
- pointers, which the debugger prints in the backtrace, have no
- significance whatever; all that matters is the contents of the objects
- they point to (and most of the contents are other such pointers).
- 
- In addition, most compiler passes consist of one or more loops that
- scan the RTL insn sequence.  The most vital piece of information about
- such a loop---which insn it has reached---is usually in a local variable,
- not in an argument.
- 
- @findex debug_rtx
- What you need to provide in addition to a backtrace are the values of
- the local variables for several stack frames up.  When a local
- variable or an argument is an RTX, first print its value and then use
- the GDB command @command{pr} to print the RTL expression that it points
- to.  (If GDB doesn't run on your machine, use your debugger to call
- the function @code{debug_rtx} with the RTX as an argument.)  In
- general, whenever a variable is a pointer, its value is no use
- without the data it points to.
- @end itemize
- 
- Here are some things that are not necessary:
- 
- @itemize @bullet
- @item
- A description of the envelope of the bug.
- 
- Often people who encounter a bug spend a lot of time investigating
- which changes to the input file will make the bug go away and which
- changes will not affect it.
- 
- This is often time consuming and not very useful, because the way we
- will find the bug is by running a single example under the debugger with
- breakpoints, not by pure deduction from a series of examples.  You might
- as well save your time for something else.
- 
- Of course, if you can find a simpler example to report @emph{instead} of
- the original one, that is a convenience.  Errors in the output will be
- easier to spot, running under the debugger will take less time, etc.
- Most GNU Fortran bugs involve just one function, so the most straightforward
- way to simplify an example is to delete all the function definitions
- except the one where the bug occurs.  Those earlier in the file may be
- replaced by external declarations if the crucial function depends on
- them.  (Exception: inline functions might affect compilation of functions
- defined later in the file.)
- 
- However, simplification is not vital; if you don't want to do this,
- report the bug anyway and send the entire test case you used.
- 
- @item
- In particular, some people insert conditionals @samp{#ifdef BUG} around
- a statement which, if removed, makes the bug not happen.  These are just
- clutter; we won't pay any attention to them anyway.  Besides, you should
- send us preprocessor output, and that can't have conditionals.
- 
- @item
- A patch for the bug.
- 
- A patch for the bug is useful if it is a good one.  But don't omit the
- necessary information, such as the test case, on the assumption that a
- patch is all we need.  We might see problems with your patch and decide
- to fix the problem another way, or we might not understand it at all.
- 
- Sometimes with a program as complicated as GNU Fortran it is very hard to
- construct an example that will make the program follow a certain path
- through the code.  If you don't send the example, we won't be able to
- construct one, so we won't be able to verify that the bug is fixed.
- 
- And if we can't understand what bug you are trying to fix, or why your
- patch should be an improvement, we won't install it.  A test case will
- help us to understand.
- 
- See @uref{http://gcc.gnu.org/contribute.html}
- for guidelines on how to make it easy for us to
- understand and install your patches.
- 
- @item
- A guess about what the bug is or what it depends on.
- 
- Such guesses are usually wrong.  Even the maintainer can't guess right
- about such things without first using the debugger to find the facts.
- 
- @item
- A core dump file.
- 
- We have no way of examining a core dump for your type of machine
- unless we have an identical system---and if we do have one,
- we should be able to reproduce the crash ourselves.
- @end itemize
  
  @node Service
  @chapter How To Get Help with GNU Fortran
--- 10635,10649 ----
  exposes it more readily than other compilers.
  @end itemize
  
  @node Bug Reporting
  @section How to Report Bugs
  @cindex compiler bugs, reporting
  
! Bugs should be reported to our bug database.  Please refer to
! @uref{http://gcc.gnu.org/bugs.html} for up-to-date instructions how to
! submit bug reports.  A copy of this file should also be part of the
! documentation that comes with GCC releases.
  
  
  @node Service
  @chapter How To Get Help with GNU Fortran