[groff] 05/39: BUG-REPORT: Modernize.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit fbdf4d972a115bac7bbf948e870554c0052553b2
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Oct 8 23:23:40 2022 -0500

    BUG-REPORT: Modernize.
    
    * Give more detailed instructions for Savannah bug tracker usage.
    * Replace "machine" and "OS" fields with "platform"; solicit "uname -a"
      output, a much more economical means of collecting this information.
      Suggest a possibly feeble alternative for MS-DOS/Windows systems.
    * Replace "OS" and "compiler" fields with "configuration report"; ask
      for the configuration report banner if we can get it.  Otherwise
      solicit GNU/Linux package information.
    * Update "input files" field to reflect the fact that groff ships
      several full-service macro packages these days.  Also, the
      configuration report and failing command line will tell us what we
      need to know about system/proprietary macro packages being used in
      preference to groff's alternatives.
    * Tweak wording.
---
 BUG-REPORT | 56 +++++++++++++++++++++++++++++---------------------------
 1 file changed, 29 insertions(+), 27 deletions(-)

diff --git a/BUG-REPORT b/BUG-REPORT
index 8ef3cf35a..b1cefa16b 100644
--- a/BUG-REPORT
+++ b/BUG-REPORT
@@ -1,4 +1,4 @@
-# Copyright (C) 1999-2020 Free Software Foundation, Inc.
+# Copyright (C) 1999-2020, 2022 Free Software Foundation, Inc.
 #
 # This file is part of 'groff'.
 #
@@ -17,7 +17,7 @@
 # <http://www.gnu.org/licenses/gpl-2.0.html>.
 
 
-                          Groff Bug Report
+                          groff Bug Report
 
 Please read the PROBLEMS file before submitting a bug report.
 
@@ -25,53 +25,55 @@ Please fill in all fields, even if you think they are not 
relevant.
 
 Please delete the text in brackets before submitting it.
 
-Please report separate bugs separately.
+Please report distinguishable problems separately.
 
 Place the completed form in a new bug report at
-http://savannah.gnu.org/bugs/?group=groff.
+<http://savannah.gnu.org/bugs/?group=groff>.  Click on the "Bugs" link,
+then select "Submit new" from the menu.
 
 GROFF VERSION:
-[The version of groff you are using.  For example, '1.23.0']
+[Put the output of the failing command when run with the '--version'
+option here.  For example, "groff --version".]
 
-MACHINE:
-[The machine you are using.  For example, 'Sun SPARCstation 2']
+PLATFORM:
+[Put the output of the 'uname -a' command here.  On non-POSIX systems,
+some alternative should be available; on Windows systems, use 'ver'.]
 
-OS:
-[The operating system you are using.  For example, 'SunOS 4.1.1']
-
-COMPILER:
-[The compiler you used to compile groff.  For example, 'g++ 1.40.3']
+CONFIGURATION REPORT:
+[If you compiled groff yourself, include the portion of the 'configure'
+script's output between rows of dashes.  If you didn't compile groff
+yourself, supply the packaging information from your distributor: in
+DEB- and RPM-based GNU/Linux distributions, gather it with the commands
+"dpkg -s groff" or "rpm -qi groff", respectively.]
 
 INPUT FILES:
 [Include all the files necessary to reproduce the problem that are not
-part of the standard groff distribution.  This includes font
-description files, DESC files and macro files (with the exception of
-the -ms and -mm macros: we have them).  Attach them to the bug report.
+part of the standard groff distribution.  This includes device and font
+description files and any macro files your document uses that groff does
+not supply.  Attach them to the bug report.
 
 It's easier for us if you can provide an example that doesn't depend on
 any macro package, but obviously if you're reporting a problem with a
-macro package that won't be possible.  Also a short example is more
+macro package that won't be possible.  Further, a short example is more
 convenient than a long one, but don't worry if you can't find a short
-example.  Don't say something like "any file that X": Always include a
-definite example.]
+example.  A claim like "any file that X" is not helpful: always include
+a concrete example.]
 
 COMMAND LINE:
 [The command line that we should run in order to observe the bug.  For
-example, 'gtroff -Tps bug.tr'.  If the command line uses -ms or -mm,
-say whether these refer to the groff versions or the Unix versions of
-the macros.]
+example, 'groff -Tps bug.tr'.]
 
 DESCRIPTION OF INCORRECT BEHAVIOUR:
-[What goes wrong when that command line is run?  For example, 'gtroff
-gets a segmentation fault', or 'The output looks bad because the bar
+[What goes wrong when that command line is run?  For example, 'groff
+gets a segmentation fault.', or 'The output looks bad because the bar
 over the x is too long and is too far over to the left.'  If you get an
-error message, include it here without modification: Don't edit it to
+error message, include it here without modification: don't edit it to
 make it more readable.]
 
 SUGGESTED FIX [optional]:
-[If you can suggest a fix for the problem, include a context diff here.
-But don't delay submitting a bug report in the hope of finding a fix.
-Guesses about the cause of the bug are not usually helpful.]
+[If you can suggest a fix for the problem, you might include a unified
+diff here.  But don't delay submitting a bug report in the hope of
+finding a fix.  A guess about a bug's cause is not usually helpful.]
 
 ##### Editor settings
 Local Variables: