[groff] 10/28: README: Revise.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 2a2016025d309a136c7a9984d1dc6cf0dc98dbd6
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue May 24 09:43:24 2022 -0500

    README: Revise.
    
    * Say simply "groff" instead of "GNU groff"--there is no other groff.
    * Contextualize groff with respect to Unix troff.
    * Add "nroff" to list of reimplemented programs.
    * Drop leading dashes from macro package names; they are unnecessary at
      best and misleading at worst.
    * Remove quotation marks from things that aren't program names, macro
      package names, or command-line options.
    * Convert `this' quotation style to 'this'.
    * Set item for Peter Schaffter's "mom" package apart since it is (1) in
      the 'contrib' directory, and (2) not a reimplementation of anything
      from AT&T or BSD Unix troff.
    * Drop discussion of build dependencies in favor of pointing user to the
      existing "INSTALL.REPO" and "INSTALL.extra" files which already cover
      this material.  Drop discussion of Bison 1.875 entirely since that
      release is over 19 years old (and was superseded in June 2003).
    * Retain and expand discussion of runtime dependencies, by contrast.
    * Recharacterize purpose of "NEWS" file since it documents more than
      just "recent" changes.
    * Mention "LICENSES" file alongside "COPYING".
    * Update URLs to use HTTPS schema.
    * Discuss and distinguish groff home page, Savannah project site, and
      groff's Git repository site.
    * Characterize "bug-groff" list as read-only; I don't think it's
      admnistratively configured that way at present, but it would be good
      to have that flexibility in the future, and in practice it is simply a
      reflector for groff project traffic on the Savannah issue tracker.
    * Bump copyright date.
---
 README | 153 +++++++++++++++++++++++++++++++----------------------------------
 1 file changed, 74 insertions(+), 79 deletions(-)

diff --git a/README b/README
index 42bc8a65..0dadd927 100644
--- a/README
+++ b/README
@@ -1,123 +1,118 @@
-    Copyright (C) 1989-2020 Free Software Foundation, Inc.
+    Copyright (C) 1989-2022 Free Software Foundation, Inc.
 
     Copying and distribution of this file, with or without
     modification, are permitted in any medium without royalty provided
     the copyright notice and this notice are preserved.
 
-This is the GNU `groff' document formatting system.  The version
-number is given in the file `.tarball-version' if you are building
-from a tarball, or the file `.version' if you are building directly
-from the git repository.
+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.
 
-Included in this release are implementations of `troff', `pic', `eqn',
-`tbl', `grn', `refer', `-man', `-mdoc', `-mom', and `-ms' macros, and
-drivers for `PostScript', `PDF', `TeX DVI' format, `HP LaserJet 4'
-printers, `Canon CaPSL' printers, `HTML' and `XHTML' formats (beta
-status), and typewriter-like devices.  Also included is a modified
-version of the Berkeley `-me' macros, the enhanced version `gxditview'
-of the X11 `xditview' previewer, and an implementation of the `-mm'
-macros contributed by Joergen Haegg.
+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.
 
-See the file `INSTALL' for instructions on how to install from a
-release.  You will require a C++ compiler.
+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.
 
-The file `INSTALL.REPO' contains supplementary instructions for
-building directly from a clone of the repository or a snapshot
-tarball.
+Peter Schaffter's 'mom' macro package is also featured.
 
-The file `NEWS' describes recent user-visible changes to `groff'.
+See the file 'INSTALL.extra' for instructions on how to install from a
+distribution archive, such as a release, beta, or release candidate.
 
-`groff' is free software.  See the file `COPYING' for copying
-permission.
+The file 'INSTALL.REPO' contains supplementary instructions for building
+directly from a clone of the Git repository or a snapshot archive.
 
-The file `PROBLEMS' describes various problems that have been
-encountered in compiling, installing, and running `groff'.
+The file 'NEWS' contains a history of user-visible changes to 'groff'.
 
-The file `MORE.STUFF' contains information about add-on packages
-useful for `groff'.
+'groff' is free software.  See the file 'COPYING' for copying
+permissions, and 'LICENSES' for further detail.
 
-The most recent released version of `groff' is always available by
-anonymous ftp from `ftp.gnu.org' in the directory `gnu/groff'.
+The file 'PROBLEMS' describes various problems that have been
+encountered in compiling, installing, and running 'groff'.
 
-The current development version of `groff' is available from a git
-repository at
+The file 'MORE.STUFF' contains information about add-on packages
+useful for 'groff'.
 
-  https://savannah.gnu.org/git/?group=groff
+Current and historical releases of 'groff' are available via HTTPS and
+anonymous FTP from the host 'ftp.gnu.org' in the directory 'gnu/groff'.
+
+'groff' has a home page at the GNU Project.
 
-To view the git repository in your browser, go to
+https://www.gnu.org/software/groff/
 
-  http://git.savannah.gnu.org/cgit/groff.git
+Administration of the project is done through GNU Savannah.
+
+  https://savannah.gnu.org/git/?group=groff
 
-There you can also download snapshots; simply click on a commit entry
-line to get the URL.
+'groff' is developed at its Git repository, which has a web interface.
 
-Depending on your requirements, you may need at least some of the
-following tools to build `groff' directly from its source:
+  https://git.savannah.gnu.org/cgit/groff.git
 
-  perl >= v5.6.1 (see macro GROFF_PERL in file `m4/groff.m4')
-  ghostscript
-  the psutils package
-  the netpbm package
-  texinfo 5.0
-  bison >= 1.875b or byacc
+You can view any commit in isolation, and browse the entire source tree
+or produce a snapshot archive corresponding to its state as of that
+commit.  Click the summary line of the commit message to expose these
+options.
 
-Note that `texinfo' and `bison' or `byacc' are required only for
-building from repository sources (either a checked out working copy,
-or a commit snapshot).  They are not required for building from a
-stable release tarball.  Also note that the version numbers stated are
-the minimum supported.  No version of `texinfo' < 5.0 works, and the
-original release of `bison' 1.875 is known not to work; you *may* find
-that `bison' releases < 1.875 work, but in case of difficulty, please
-update to a later version *before* posting a bug report.
+Build requirements are discussed in the 'INSTALL.extra' and
+'INSTALL.REPO' files noted above.  'groff' also has runtime
+dependencies.
 
-For *all* sources, you need `ghostscript' for creation of either `PDF'
-or `HTML' output; the `netpbm' and `psutils' packages are required
-only for `HTML' output (and for compilation from the repository).  If
-you don't intend to produce output in either of these formats, then
-these packages are unnecessary.
+Ghostscript is required for creation of PDF and (X)HTML output.
+Production of (X)HTML furthermore demands tools from the 'netpbm' and
+'psutils' packages.
 
-Additionally, producing `PDF' output directly with the `gropdf' device
-needs a working installation of `perl'.  The same is true for some other
-preprocessors like `chem'.
+Perl is required for production of PDF output using the 'gropdf' output
+driver.  (You can alternatively produce PostScript with 'groff' and
+covert that to PDF using Ghostscipt.)  The 'chem', 'gperl', and
+'gpinyin' preprocessors and several utilities, such as 'grog', are also
+written in Perl.
 
-The `groff' configure script searches for the X11 headers and
-libraries `Xaw' and `Xmu'.  So the corresponding developer packages of
-your system must be installed, otherwise `groff' does not install
-`gxditview' and the `-TX*' devices.  In Debian, the developer packages
-are `libxaw7-dev' and `libxmu-dev'.
+If 'groff' is configured with 'lp' or 'lpr' support, the corresponding
+program must remain available on the system for the 'groff' command's
+'-l' option to work.  Similarly, build-time detection of development
+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.
 
-Please report bugs using the bug tracker available from the project
-page at
+The GNU project's web page for 'groff' includes a link to its issue
+tracker.
 
   https://savannah.gnu.org/projects/groff
 
-You may use the form in the file `BUG-REPORT'; the idea of this is to
+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
+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 really is a bug.
+it is a software defect, or an omission from our documentation.
 
-Three mailing lists are available:
+Three mailing lists are available.
 
-  bug-groff@gnu.org          for following bug reports
+  bug-groff@gnu.org          a read-only list for following bug reports
   groff@gnu.org              for general discussion of groff
-  groff-commit@gnu.org       a read-only list to follow commits
-                             to the git repository
+  groff-commit@gnu.org       a read-only list for following commits
+                             to the Git repository
 
 To subscribe, send a mail to <list>-request@<domain> (example:
-groff-request@gnu.org for the `groff' list) with the word `subscribe'
-in either the subject or body of the e-mail (don't include the quotes).
-Alternatively, you may subscribe by visiting the web pages at
+groff-request@gnu.org for the 'groff' list) with the word 'subscribe'
+in either the subject or body of the email (don't include the quotes).
+Alternatively, subscribe via our web pages by completing an HTML form.
 
-  http://lists.gnu.org/mailman/listinfo/bug-groff
-  http://lists.gnu.org/mailman/listinfo/groff
-  http://lists.gnu.org/mailman/listinfo/groff-commit
+  https://lists.gnu.org/mailman/listinfo/bug-groff
+  https://lists.gnu.org/mailman/listinfo/groff
+  https://lists.gnu.org/mailman/listinfo/groff-commit
 
 Each of these web pages also provides a link to a browseable archive of
 postings to the corresponding mailing list.
 
-GNU `groff' was written by James Clark <jjc@jclark.com>.
+'groff' was primarily written by James Clark <jjc@jclark.com>.
 
 
 ##### Editor settings