[groff] 04/04: FOR-RELEASE, HACKING, INSTALL.REPO, README: Tweak.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c893202d20273c037cb4007e70f38bdc17946cb4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu May 26 09:29:16 2022 -0500

    FOR-RELEASE, HACKING, INSTALL.REPO, README: Tweak.
    
    * FOR-RELEASE: Split-off ChangeLog files need to be added to the
      distribution archive.
    
    * HACKING: Clarify non-ChangeLoggable items.  Generally, an item that
      resolves a Savannah ticket should be ChangeLogged even if it would not
      normally meet that threshold.  Also clarify a point in an example; we
      certainly expect table entries containing the word "FOOBAR" to show up
      that way when formatted.
    
    * INSTALL.REPO: Correct prose description of what to do with unpacked
      "gnulib" snapshot.
    
    * README: Clarify that the '.version' file is produced by the build
      process.  Clarify origins and provenance of various groff components.
      Use a more appropriate URL for the Savannah issue tracker.  Lightly
      recast.
---
 FOR-RELEASE  |  2 +-
 HACKING      | 10 +++++-----
 INSTALL.REPO |  4 ++--
 README       | 46 ++++++++++++++++++++++++----------------------
 4 files changed, 32 insertions(+), 30 deletions(-)

diff --git a/FOR-RELEASE b/FOR-RELEASE
index fc3ff0e7..e89e3ecc 100644
--- a/FOR-RELEASE
+++ b/FOR-RELEASE
@@ -44,7 +44,7 @@ This file describes how to prepare 'groff' for a new release.
   + doc/webpage.ms
 
 * If the major or minor version number is being incremented, split off
-  a historical ChangeLog file.
+  a historical ChangeLog file and add it to `EXTRA_DIST` in Makefile.am.
 
 * Update in 'src/roff/groff/groff.cpp' the 'printf' that displays the
   copyright.
diff --git a/HACKING b/HACKING
index ff7014d7..94c3ad7a 100644
--- a/HACKING
+++ b/HACKING
@@ -37,9 +37,9 @@ Changes may need to be documented in up to three places 
depending on
 their impact.
 
 1.  Changes should of course be documented in the Git commit message.
-    If a change does not resolve a Savannah ticket, alters only
-    comments to source code, or makes editorial changes to
-    documentation, you can stop at that.
+    If a change alters only comments or formatting of source code, or
+    makes editorial changes to documentation, and does not resolve a
+    Savannah ticket, you can stop at that.
 
 2.  The 'ChangeLog' file follows the format and practices documented in
     the GNU Coding Standards.
@@ -62,8 +62,8 @@ their impact.
 
     As a hypothetical example, correcting a rendering error in tbl(1)
     such that any table with more than 20 rows no longer had the text
-    "FOOBAR" added to some of entries would not be a 'NEWS' item,
-    because the appearance of such text in the first place is a
+    "FOOBAR" spuriously added to some of entries would not be a 'NEWS'
+    item, because the appearance of such text in the first place is a
     surprising deviation from tbl's ideal and historical behavior.  In
     contrast, adding a command-line option to tbl, or changing the
     meaning of its "expand" region option such that it no longer
diff --git a/INSTALL.REPO b/INSTALL.REPO
index 47374141..1adfbdbf 100644
--- a/INSTALL.REPO
+++ b/INSTALL.REPO
@@ -49,8 +49,8 @@ Invoke the bootstrap script.
 Bootstrapping from a snapshot archive
 -------------------------------------
 
-Obtain groff's supported revision of gnulib and place it in the empty
-"gnulib" directory.
+Obtain groff's supported revision of gnulib and instruct the bootstrap
+script where to find it.
 
 Here is the output of "git submodule" for this groff release.
 
diff --git a/README b/README
index 0dadd927..2292551c 100644
--- a/README
+++ b/README
@@ -7,19 +7,21 @@
 This is the 'groff' document formatting system, a reimplementation and
 extension of the AT&T Unix 'troff' system.  The version number is given
 in the file '.tarball-version' if you are building from a distribution
-archive, or the file '.version' if you are building directly from its
-Git repository.
-
-This release includes implementations of the 'troff', 'nroff', 'pic',
-'eqn', 'tbl', 'grn', 'refer' programs; the 'man', 'mdoc', and 'ms' macro
-packages; and output drivers for for PostScript, PDF, and TeX DVI file
-formats, HP LaserJet 4- and Canon CaPSL-compatible printers, HTML and
-XHTML (in beta status), and typewriter/terminal devices.
-
-It also provides a modified version of the Berkeley 'me' macro packages;
-'gxditview', an enhanced version of the X11 'xditview' previewer for
-'troff' device-independent output, and an implementation of the 'mm'
-macro package contributed by Joergen Haegg.
+archive; otherwise, building from its Git repository or a snapshot
+archive will store it in the file '.version'.
+
+This release includes original implementations (not derived from AT&T
+Unix code) of the 'troff', 'nroff', 'pic', 'eqn', 'tbl', 'refer'
+programs; the 'man' and 'ms' macro packages; and output drivers for for
+PostScript, PDF, and TeX DVI file formats, HP LaserJet 4- and Canon
+CaPSL-compatible printers, HTML and XHTML (in beta status), and
+typewriter/terminal devices.
+
+It also provides modified versions of BSD Unix additions to Unix troff:
+the 'grn' preprocessor and 'me' macro package; 'gxditview', an enhanced
+version of the X11 'xditview' previewer for 'troff' device-independent
+output, and an original reimplementation and extension of the 'mm' macro
+package (not derived from DWB 'troff') contributed by Joergen Haegg.
 
 Peter Schaffter's 'mom' macro package is also featured.
 
@@ -81,17 +83,17 @@ headers for the 'uchardet', 'Xaw', and 'Xmu' libraries (and 
their
 dependencies) assumes that their runtime counterparts will remain
 installed to support the 'groff' that is built.
 
-The GNU project's web page for 'groff' includes a link to its issue
-tracker.
+You can view or add to to groff's bug database via its issue tracker on
+the Savannah site (also linked from the groff home page).
 
-  https://savannah.gnu.org/projects/groff
+  http://savannah.gnu.org/bugs/?group=groff
 
-You may use the form in the file 'BUG-REPORT'; its purpose is to
-make sure that FSF has all the information it needs to fix the bug.
-At the very least, read the 'BUG-REPORT' form and make sure that you
-supply all the information that it asks for.  Even if you are not sure
-that something is a bug, report it: this enables us to determine whether
-it is a software defect, or an omission from our documentation.
+To report a problem, you may use the form in the file 'BUG-REPORT'; its
+purpose is to make sure that FSF has all the information it needs to fix
+the bug.  At the very least, read the 'BUG-REPORT' form and make sure
+that you supply all the information that it asks for.  Even if you are
+not sure that something is a bug, please report it so we can determine
+whether it is a software defect, or an omission from our documentation.
 
 Three mailing lists are available.