INSTALL.REPO, INSTALL.extra: Update.

Bring discussion up to date.

INSTALL.REPO: Bump documented autoconf dependency.  Encourage use of
'-j' option to make(1), but stop explaining it--multicore machines are
standard these days and we can expect users building from Git to know
this.  Drop reassurance about transparent output-related diagnostics
since we have kludgily disabled them for the time being.  Drop
discussion of 'doc' and 'install-doc' targets since they have been
removed.  Drop discussion of autoreconf(1) since groff's migration to
Automake is a few years older now.  Fix error: automake.pdf _is_ built
by default; it's simply not installed.

INSTALL.extra: Encourage use of '-j' option to make(1).  Add discussion
of "unprivileged installation".  Simplify discussion of our Texinfo
manual's output formats since they're all shipped with the distribution
archive now.

1 files changed, 46 insertions, 78 deletions

diff --git a/INSTALL.REPO b/INSTALL.REPO
index cff37c30e..3fda00764 100644
--- a/INSTALL.REPO
+++ b/INSTALL.REPO
@@ -1,85 +1,81 @@
-    Copyright 2013-2020 Free Software Foundation, Inc.
+    Copyright 2013-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 file contains information that supplements the generic
-installation instructions in file `INSTALL'.  It is meant for
-people building directly from the development repository, rather than
-a release or snapshot tarball.
+This file contains information that supplements the generic installation
+instructions in file 'INSTALL'.  It is meant for people building
+directly from the development repository, rather than a release or
+snapshot tarball.
 
-If you want to start compiling the `groff' system with an existing
-script `configure' you won't need the information in this file. You
-need them only if you want to build groff from the git repository.
+If you want to start compiling the 'groff' system with an existing
+'configure' script, you won't need the information in this file.  You
+need it only if you want to build groff from its Git repository.
 
 1. Initial build
 ----------------
 
-You will need autoconf version and 2.65 or higher and automake version
-1.12.2 or higher. These minimal versions are set in the bootstrap.conf
+You will need autoconf version 2.68 or higher and automake version
+1.12.2 or higher.  These minimal versions are set in the bootstrap.conf
 file.
 
 On operating systems supporting concurrent installation of multiple
-versions of the autotools, set the following environment variables:
+versions of the autotools, set environment variables as in the following
+example, adjusting the version numbers as required.
 
   export AUTOMAKE_VERSION=1.14
   export AUTOCONF_VERSION=2.69
 
-You will also need to have `pkg-config' installed on your system.
+You will also need to have 'pkg-config' installed on your system.
 
-First invoke the bootstrap script:
+First invoke the bootstrap script.
 
     $ ./bootstrap
 
 This will:
 
-  - clone the gnulib repository as a git submodule in 'gnulib', add
-    the needed gnulib sources files in 'lib', add the needed gnulib m4
-    macros in 'gnulib_m4'
+  - clone the gnulib repository as a Git submodule in 'gnulib', add the
+    needed gnulib sources files in 'lib', add the needed gnulib m4
+    macros in 'gnulib_m4'; and
 
-  - Invoke autoreconf that will call all the `GNU autotools'
-    (`aclocal', `autoconf', `automake') in the right order for
-    creating the following files:
+  - invoke autoreconf that will call the GNU Autotools ('aclocal',
+    'autoconf', 'automake') in the right order for creating the
+    following files.
 
     -- INSTALL (a symlink to gnulib's INSTALL file)
     -- Makefile.in
     -- aclocal.m4
     -- autom4te.cache/
-    -- build-aux/ (that contains all the helper scripts)
+    -- build-aux/ (which contains all the helper scripts)
     -- configure
     -- src/include/config.hin
 
-Note that aclocal.m4 is generated and the groff m4 macros are included
-via the acinclude.m4 file.
+'aclocal.m4' is a generated file; groff's m4 macros are included via the
+'acinclude.m4' file.
 
-At this point you can invoke the `configure' script (that generates
-the `config.status' script; it is the `config.status' script generates
-the Makefile) and call 'make' to build the groff project. You can do
-it in the source tree:
+At this point you can invoke the 'configure' script.  It produces the
+'config.status' script, which generates the Makefile.  Then call 'make'
+to build the groff project.  You can do these in the source tree.
 
     $ ./configure
-    $ make
+    $ make # run with -j option if desired
 
-You can also build groff in an out of source build tree, which is cleaner:
+You can also build groff outside of its source tree, which is cleaner.
 
     $ mkdir build
     $ cd build
     $ ../configure
-    $ make
+    $ make # run with -j option if desired
 
-Note that parallel build is also supported and make can be invoked
-with the -j option, which will greatly speed up the build.
+When the build is finished you can install the groff build artifacts.
 
-When the build is finished you can install the whole groff
-installation with:
-
-    $ make install
+    $ make install # run with 'sudo' if necessary
 
 Notes:
 
-If you use an old `autoreconf' version < 2.69, there might be an error
-warning like:
+If you use an old 'autoreconf' version < 2.69, you might observe some
+diagnostic output like the following.
 
   /usr/share/aclocal/gtkglextmm-1.2.m4:225:
     warning: underquoted definition of AC_GTKGLEXTMM_SUPPORTS_MULTIHEAD
@@ -88,58 +84,30 @@ warning like:
   /usr/share/aclocal/gtkglextmm-1.2.m4:225:
     or see http://www.gnu.org/software/automake/manual/automake.html#Extending-aclocal
 
-Just ignore this.  It doesn't occur in the actual versions of
-`autoreconf'.
-
-Troff errors of the types
-
-  can't transparently output node at top level
-    and
-  can't translate character code n to special character 'c' in transparent throughput
-
-may safely be ignored.
-
-Several dozen sanity checks can be done with the command:
-
-    $ make check
-
-The groff Texinfo manual can be generated in PDF and HTML formats
-with:
-
-    $ make doc
-
-and installed with:
-
-    $ make install-doc
-
+Just ignore this.  It doesn't occur in more recent versions of
+'autoreconf'.
 
-2. Modification of autotools files
-----------------------------------
+Several dozen sanity checks can be performed within the build tree.
 
-Previously, when groff used `autoconf' only and not `automake', you
-had to invoke manually the autotools, depending on what you
-modified. For example, to change the file `aclocal.m4', you had to run
-the shell command 'aclocal -I m4', to recreate the files `configure'
-and `Makefile', you had to use the command 'autoreconf -I m4'.
+    $ make check # run with -j option if desired
 
-Now, as groff uses `automake', you don't need to run `autoreconf'. If
-you make some changes in Makefile.am or configure.ac, all the files
-that need to be updated will be regenerated when you execute `make'.
+Running these tests after building any substantive change to groff logic
+is encouraged.
 
 
+2. Guide to usage of 'automake' in groff
+----------------------------------------
 
-3. Quick start on the usage of `automake' in groff
---------------------------------------------------
+A document explaining the basics of automake and its usage in groff is
+available in 'doc/automake.mom'; a PDF rendering is built but not
+installed, since it is a developer-facing discussion.
 
-A little document explaining the basics of automake and its usage in
-groff is available in doc/automake.mom. It is currently not
-automatically generated, to build it:
+Peruse it in 'doc/automake.pdf' in your build tree.
 
-pdfmom automake.mom > automake.pdf
 
 ##### Editor settings
 Local Variables:
 fill-column: 72
 mode: text
 End:
-# vim: set textwidth=72:
+# vim: set autoindent textwidth=72: