[groff] 24/27: INSTALL.REPO, INSTALL.extra: Update.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 825b39a71aa3ec343f7068501548d1b83196c05d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue May 3 12:20:02 2022 -0500

    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.
---
 INSTALL.REPO  | 124 ++++++++++++++++++++++------------------------------------
 INSTALL.extra | 121 +++++++++++++++++++++++++++++++-------------------------
 2 files changed, 113 insertions(+), 132 deletions(-)

diff --git a/INSTALL.REPO b/INSTALL.REPO
index cff37c30..3fda0076 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:
diff --git a/INSTALL.extra b/INSTALL.extra
index 97428718..8b559a14 100644
--- a/INSTALL.extra
+++ b/INSTALL.extra
@@ -1,69 +1,86 @@
-    Copyright 1997-2021 Free Software Foundation, Inc.
+    Copyright 1997-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'.
+installation instructions in file 'INSTALL'.
 
 
 Normal Installation
 ===================
 
-The simplest way to compile groff is:
+A simple method of building and installing groff is as follows.
 
-  1. `cd' to the directory containing groff's source code and type
-     `./configure' to configure groff for your system.  If you are
-     using `csh' on an old version of System V, you might need to type
-     `sh ./configure' instead to prevent `csh' from trying to execute
-     `configure' itself.
+  1. 'cd' to the directory containing groff's source code and type
+     './configure' to configure groff for your system.  If you are
+     using 'csh' on an old version of System V, you might need to type
+     'sh ./configure' instead to prevent 'csh' from trying to execute
+     'configure' itself.
 
-     Running `configure' takes awhile.  While running, it prints some
-     messages telling which features it is checking for.
+     While 'configure' runs, it reports properties of the host system
+     that determine how the build is to be performed.
 
-  2. Type `make' to compile groff.
+  2. Type 'make' to compile groff.  You may wish to add the '-j' option
+     to accelerate the build on multicore systems.
 
-  3. Type `sudo make install' to install the groff programs and any
-     data files and documentation.  `make install' is the only step for
-     which you need `root' access; this is done by `sudo'.
+  3. Type 'sudo make install' to install groff's programs, data files,
+     and documentation.  'make install' is the only step for which you
+     need 'root' access; 'sudo' obtains this access.
 
-  4. You can remove the groff binaries and object files from the
-     source code directory by typing `make clean'.  To also remove the
-     files that `configure' created (so you can compile groff for
-     a different kind of computer), type `make distclean'.
+  4. You can remove the groff executables and other generated files from
+     the source code directory by typing 'make clean'.  To also remove
+     the files that 'configure' created (so you can compile groff for a
+     different kind of computer or with different options to
+     'configure'), type 'make distclean'.
 
 
 External Installation
 =====================
 
-It is also possible to perform the whole installation process outside
-of the source code directory.  In this case a whole external build
+It is also possible to perform the build and installation procedure
+outside the source code directory.  In this case an external build
 directory structure is created without changing any parts of the source
-code tree.  This is useful if the source code is read-only or if
+tree.  This practice is useful if the source code is read-only or if
 several different installations, such as for multiple architectures,
 should be constructed.
 
-As an example we assume that the source code of the `groff' code is in
-`/usr/local/src/groff', and that the build process should be done
-within the directory `/home/my/groff.compile'.
+As an example, we will imagine that groff's source code is in
+'/usr/local/src/groff' and that the build should happen within the
+directory '/home/my/groff-build'.  You can choose your own name for the
+build directory.
 
-  0. Create `/home/my/groff.compile' and change to that directory.
+  0. Create '/home/my/groff-build' and change to that directory.
 
-  1. Call `/usr/local/src/groff/configure' in that directory to
-     configure groff for your system.  If you are using `csh' on an old
-     version of System V, you might need to type `sh
+  1. Call '/usr/local/src/groff/configure' in that directory to
+     configure groff for your system.  If you are using 'csh' on an old
+     version of AT&T System V Unix, you might need to type 'sh
      /usr/local/src/groff/configure' instead.
 
-  2. Type `make' to compile groff in that directory.
+  2. Type 'make' to compile groff in that directory.
 
-  3. Type `sudo make install' to install the groff programs and any
+  3. Type 'sudo make install' to install the groff programs and any
      data files and documentation.
 
   4. You can remove the groff binaries and object files from the
-     build directory by typing `make clean'.  To also remove the
-     files that `configure' created (so you can compile the package for
-     a different kind of computer), type `make distclean'.
+     build directory by typing 'make clean'.  To also remove the
+     files that 'configure' created (so you can compile the package for
+     a different kind of computer), type 'make distclean'.
+
+
+Unprivileged Installation
+=========================
+
+The use of 'sudo' is only necessary if one or more destination
+directories used by the 'make install' command are in locations that
+require administrative access for writing.  You can 'configure' groff
+with options like '--prefix' that select an alternative directory that
+is writable by the user conducting the build.  type './configure --help'
+from the groff source tree for documentation of relevant options.
+Running groff commands from such a directory may require you to set the
+'GROFF_FONT_PATH' and 'GROFF_TMAC_PATH' environment variables.  See the
+groff(1) man page.
 
 
 Special Platforms
@@ -94,10 +111,9 @@ variable-length arrays) are not used.
 Several programs distributed with GNU roff are written in the Perl
 language.  Version 5.6.1 (1 April 2001) or later is required.
 
-groff's Texinfo manual is distributed in source, GNU info, HTML, and
-plain text formats.  To regenerate the latter formats (if you alter the
-source, for example), or to produce DVI or PDF versions, see section
-"Evaluation" below.
+groff's Texinfo manual is distributed in source, GNU info, HTML, TeX
+DVI, PDF, and plain text formats.  To regenerate the latter formats (if
+you alter the source, for example), see section "Evaluation" below.
 
 The 'uchardet' library is an optional dependency of the 'preconv'
 program: if this library is found by 'configure', it will be
@@ -116,11 +132,11 @@ produces an incorrect guess, say
 
   PAGE=xxx ./configure
 
-where `xxx' should be either `A4' or `letter'.  This affects only the
-paper selection of some groff output drivers, like grops (which can
+where 'xxx' should be either 'A4' or 'letter'.  This affects only the
+media size used by some groff output drivers, like grops (which can
 still be overridden on the command line).  For compatibility with AT&T
 troff, GNU troff's default page length is always 11 inches.  The page
-length can be changed with the `pl' request.
+length can be changed with the 'pl' request.
 
 
 Evaluation
@@ -152,28 +168,24 @@ It can be viewed as text encoded in ISO Latin-1 as well.
   iconv -f latin1 -t utf8 doc/groff.txt | less # for UTF-8 users
   less doc/groff.txt # for Latin-1 users
 
-An HTML rendering is also available.
+Renderings in HTML, TeX DVI, and PDF are also available.
 
   lynx doc/groff.html
-
-Texinfo version 5.0 or later is a prerequisite for regeneration of
-groff's Texinfo manual if you make changes.  If you also have a working
-TeX installation, you can furthermore render it in DVI or PDF.  Say
-'make doc/groff.dvi' or 'make doc/groff.pdf', respectively, in your
-build directory after configuring the groff package.  Here are some ways
-you might view the formats produced.  Do so from your build directory.
-
   xdvi doc/groff.dvi
   evince doc/groff.pdf
 
+Texinfo version 5.0 or later is a prerequisite for regeneration of
+groff's Texinfo manual if you make changes.  A working TeX installation
+(such as TeX Live) is furthermore required to render it in DVI or PDF.
+
 
 In Case of Trouble
 ==================
 
 If you have problems, read the PROBLEMS file.  If this doesn't help
-and you need support, please contact the `groff' mailing list.  If you
-think that you have found a bug, please submit a report to our bug
-tracker.
+and you need support, please contact the groff mailing list at
+groff@gnu.org.  If you think that you have found a bug, please submit a
+report to our bug tracker.
 
   https://savannah.gnu.org/bugs/?group=groff&func=additem
 
@@ -183,7 +195,8 @@ Uninstalling
 
 If you are dissatisfied with groff, or to prepare for a new installation
 from source, you can uninstall it to ensure that no stale files persist
-on the system.  Run the command 'make uninstall'.  At a minimum, some
+on the system.  Run the command 'make uninstall'.  (If you used 'sudo
+make install', run 'sudo make uninstall'.)  At a minimum, some
 directories not particular to groff, like 'bin' and (depending on
 configuration) an X11 'app-defaults' directory will remain, as will one
 plain file called 'dir', created by GNU Texinfo's 'install-info'
@@ -198,4 +211,4 @@ Local Variables:
 fill-column: 72
 mode: text
 End:
-vim: set textwidth=72:
+vim: set autoindent textwidth=72: