[groff] 07/34: [docs]: Update installation instructions.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d877dee952a84de8bdf120f1549ea7536c223de8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Oct 16 14:50:13 2021 +1100

    [docs]: Update installation instructions.
    
    * INSTALL.REPO: Update characterization of our test repertoire.
    * INSTALL.extra: Update documented compiler requirements; I don't think
      GCC 2.7.1 has been supported by anyone for many years.  Document
      ISO C++98 requirement.  Drop advice about use of alternative mallocs;
      I haven't seen any evidence of anyone doing this or suffering because
      they haven't.  Add guidance re: uchardet '-dev{,el}' packages per
      suggestion from Deri James.  Fix error: "latin1" is a groff device;
      "latin" is not.
    
    Also fix minor style nits (capitalization, quotation style).
---
 INSTALL.REPO  |  7 ++-----
 INSTALL.extra | 63 +++++++++++++++++++++++++++--------------------------------
 2 files changed, 31 insertions(+), 39 deletions(-)

diff --git a/INSTALL.REPO b/INSTALL.REPO
index 384fff9..cff37c3 100644
--- a/INSTALL.REPO
+++ b/INSTALL.REPO
@@ -99,14 +99,11 @@ Troff errors of the types
 
 may safely be ignored.
 
-A few sanity checks can be done with the command:
+Several dozen sanity checks can be done with the command:
 
     $ make check
 
-This will perform some tests on the generated examples.  However,
-these checks are for the moment quite limited.
-
-The groff texinfo manual can be generated in pdf and html formats
+The groff Texinfo manual can be generated in PDF and HTML formats
 with:
 
     $ make doc
diff --git a/INSTALL.extra b/INSTALL.extra
index de47cfb..ac662c0 100644
--- a/INSTALL.extra
+++ b/INSTALL.extra
@@ -79,33 +79,28 @@ MS-Windows, see the file README.MinGW.
 Dependencies
 ============
 
-groff is written in C++, so you need a C++ compiler.  The C++ source
-files use a suffix of `.cpp', so your C++ compiler must be able to
-handle this.  If you don't already have a C++ compiler, we suggest gcc
-2.7.1 or later (gcc version 2 includes GNU C++ as well as GNU C).  From
-gcc 2.5, it is no longer necessary to install libg++: the C++ header
-files needed by groff are created by the gcc installation process.  To
-override configure's choice of C++ compiler, you can set the CXX
-environment variable.
-
-If you have a library that provides a faster malloc than your system's
-usual malloc, it is good idea to include it in LIBS.  For example,
-using the malloc that comes with GNU Emacs version 20 can give a
-worthwhile (and sometimes spectacular) performance improvement.
-
-Many programs within the `groff' system are written in the Perl
-language.  So you need a `perl' program with the least version of
-`v5.6.1'.
-
-In order to build the documentation you would need `makeinfo' from the
-'texinfo' package, in fact `configure' will fail if this program is
-not found unless you pass the option `with-doc=no'.
-
-The `uchardet' library is an optional dependency of the `preconv'
-program: if this library is found by `configure' it will be
-automatically used by `preconv'.  In order to discover the presence of
-the `uchardet' library you would also need to have the `pkg-config'
-program installed on your system.
+groff is written in ISO C++98, so you need a C++ compiler capable of
+handling this standardized version of the language.  The C++ source
+files use a suffix of '.cpp'; your C++ compiler must be able to
+handle this.  A C/C++ preprocessor that conforms to ISO C90 is also
+required.  If you don't already have a C++ compiler, we suggest GCC 9.4
+or later.  To override the configure script's choice of C++ compiler,
+you can set the CXX environment variable to the name of its executable.
+
+Several programs distributed with GNU roff are written in the Perl
+language.  Version 5.6.1 or later is required.
+
+In order to build the documentation, you need 'makeinfo' from the
+'texinfo' package; in fact 'configure' will fail if this program is
+not found unless you pass the option '--with-doc=no'.
+
+The 'uchardet' library is an optional dependency of the 'preconv'
+program: if this library is found by 'configure' it will be
+automatically used by 'preconv'.  In order to discover the presence of
+the 'uchardet' library, you will also need to have the 'pkg-config'
+program installed on your system, and the library's C header files will
+need to be present on the system--on a package-based host system, this
+can mean installing uchardet's '-dev' or '-devel' package.
 
 
 Miscellaneous
@@ -127,21 +122,21 @@ Evaluation
 ==========
 
 Once groff is built, you can check it for correct operation without
-having to install it.  groff comes with a test suite; use `make check'
+having to install it.  groff comes with a test suite; use 'make check'
 to run it.
 
 You can also try it out from the directory you used to build it.  A
-script called `test-groff' is supplied for this purpose.  It sets up
+script called 'test-groff' is supplied for this purpose.  It sets up
 environment variables to allow groff to run without being installed.
 For example, the command
 
   ./test-groff -man -Tascii src/roff/groff/groff.1 | less -R
 
-displays the groff(1) man page with the `less' pager.  (You might prefer
-either the `-Tlatin' or `-Tutf8' option to `-Tascii' depending on the
+displays the groff(1) man page with the 'less' pager.  (You might prefer
+either the '-Tlatin1' or '-Tutf8' option to '-Tascii' depending on the
 character set you're using.)
 
-The groff texinfo manual can be previewed as an info document.
+The groff Texinfo manual can be previewed as an info document.
 
   info ./doc/groff.info
 
@@ -151,8 +146,8 @@ It can be viewed as text as well (albeit text encoded in 
ISO Latin-1).
   less doc/groff.txt # for Latin-1 users
 
 To get a DVI, PDF, or HTML version of the groff texinfo manual, say
-`make groff.dvi', `make groff.pdf', or `make groff.html', respectively,
-in the `doc' subdirectory (after configuring the groff package).
+'make groff.dvi', 'make groff.pdf', or 'make groff.html', respectively,
+in the 'doc' subdirectory (after configuring the groff package).
 Texinfo version 5.0 or later is a prerequisite for generation of these
 formats.  Here are some ways you might view the documents produced.