gbranden pushed a commit to branch master
in repository groff.
commit 16ed8d0d6f5cab26e305bae74fdcc026f080cebf
Author: G. Branden Robinson <[email protected]>
AuthorDate: Mon Nov 3 00:48:11 2025 -0600
INSTALL.REPO: Recast and adjust style.
* Use double quotes. This is not Texinfo output.
* Favor active voice over passive.
* Favor present tense over future.
* Favor "run" over "invoke". Executing programs is not magic, and not
issuance of groff requests.
* Coalesce two closely related sections together.
---
INSTALL.REPO | 84 ++++++++++++++++++++++++++++--------------------------------
1 file changed, 39 insertions(+), 45 deletions(-)
diff --git a/INSTALL.REPO b/INSTALL.REPO
index 655c7fddc..855ac8a13 100644
--- a/INSTALL.REPO
+++ b/INSTALL.REPO
@@ -5,22 +5,20 @@
the copyright notice and this notice are preserved.
This information supplements the generic installation instructions in
-the file 'INSTALL'. It is meant for people building from the
-development repository, rather than a distribution archive.
-Distribution archives include a 'configure' script, among other files;
-the repository does not. If you want to start building the 'groff'
-system using an existing 'configure' script, you don't need the
-information in this file.
+the file "INSTALL". It addresses people building from the development
+repository, rather than a distribution archive. Distribution archives
+include a "configure" script, among other files; the repository does
+not. If you want to start building the groff system using an existing
+"configure" script, you don't need the information in this file.
Dependencies
------------
-The dependencies documented in the 'INSTALL.extra' file are required, as
-are several others.
+The "INSTALL.extra" file documents required dependencies and discusses
+some optional ones.
-* You will need Autoconf version 2.68 or higher and Automake version
- 1.12.2 or higher. These requirements are asserted in the
- 'bootstrap.conf' file.
+* You need Autoconf version 2.68 or higher and Automake version 1.12.2
+ or higher. The "bootstrap.conf" file asserts these requirements.
On operating systems supporting concurrent installation of multiple
versions of the GNU Autotools, set environment variables as in the
@@ -29,45 +27,41 @@ are several others.
$ export AUTOMAKE_VERSION=1.14
$ export AUTOCONF_VERSION=2.69
-* You will need a 'yacc' program. We recommend Berkeley yacc ('byacc')
- or GNU Bison ('bison'). The version of byacc in OpenBSD 7.4 is known
- to not work; Bison does.
+* You need a "yacc" program. We recommend Berkeley yacc ("byacc") or
+ GNU Bison ("bison"). The version of byacc in OpenBSD 7.4 is known to
+ not work; Bison does.
-* groff's Texinfo manual is generated in several formats: GNU Info,
- HTML, plain text, TeX DVI, and PDF. The former three require
- 'makeinfo' from GNU Texinfo 5.0 or later. The latter two additionally
- require a TeX installation, such as TeX Live. If TeX is not
- installed, the DVI and PDF formats of the manual cannot be generated.
- This will cause a build failure only if the Texinfo source file
- "groff.texi" is updated and the make(1) "dist" or relevant file
- targets are manually specified.
+* Building from a repository checkout generates groff's Texinfo manual
+ in several formats: GNU Info, HTML, plain text, TeX DVI, and PDF. The
+ former three require "makeinfo" from GNU Texinfo 5.0 or later. The
+ latter two additionally require a TeX installation, such as TeX Live.
+ If TeX is not installed, the DVI and PDF formats of the manual cannot
+ be generated. TeX's absence causes a build failure only if you update
+ the file "groff.texi" and you specify "dist", "distcheck", or relevant
+ file targets to the "make" command explicitly.
-* You will need the 'xpmtoppm', 'pnmdepth', and 'pnmtops' programs from
- the Netpbm distribution.
+* You need the "xpmtoppm", "pnmdepth", and "pnmtops" programs from the
+ Netpbm distribution.
Bootstrapping from a Git checkout
---------------------------------
-Invoke the bootstrap script.
+Run the bootstrap script.
$ ./bootstrap
+This procedure does two things.
-What bootstrapping does
------------------------
+ - It clones the gnulib repository as a Git submodule in "gnulib", and
+ adds any needed gnulib source files to the "lib" directory as well
+ as required gnulib m4 macros to the "gnulib_m4" directory; and
-The foregoing procedure will do two things:
-
- - clone the gnulib repository as a Git submodule in 'gnulib', add the
- needed gnulib source files in 'lib' as well as required gnulib m4
- macros in 'gnulib_m4'; and
-
- - invoke 'autoreconf', which will call the GNU Autotools ('aclocal',
- 'autoconf', 'automake') in the right order to create the following
+ - it runs "autoreconf", which runs the GNU Autotools ("aclocal",
+ "autoconf", "automake") in the correct order to create the following
files.
- -- INSTALL (a symlink to gnulib's INSTALL file)
+ -- INSTALL (a symlink to gnulib's "INSTALL" file)
-- Makefile.in
-- aclocal.m4
-- autom4te.cache/
@@ -75,22 +69,22 @@ The foregoing procedure will do two things:
-- configure
-- src/include/config.hin
-'aclocal.m4' is a generated file; groff's m4 macros are included via the
-'acinclude.m4' file.
+"aclocal.m4" is a generated file; the repository's "acinclude.m4" file
+collects into it m4 macros specific to groff from the "m4" directory.
Building
--------
-You can now 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 from the source tree.
+You can now run the "configure" script. It produces the "config.status"
+script, which generates the Makefile. Then run "make" to build the
+groff project. You can perform these actions from the source tree.
$ ./configure
$ make # run with -j option if desired
You can alternatively build groff outside of its source tree, which is
-cleaner, leaving fewer files to confuse 'git status' if you aim to
+cleaner, leaving fewer files to confuse "git status" if you aim to
undertake development.
$ mkdir build
@@ -114,15 +108,15 @@ Installation
When the build is finished you can install the groff build artifacts.
- $ make install install-doc # run with 'sudo' if necessary
+ $ make install install-doc # run with "sudo" if necessary
-The "install-doc" target will not work if TeX is not installed.
+The "install-doc" target does not work if TeX is not installed.
Uninstalling
------------
-See "Uninstalling" in the 'INSTALL.extra' file.
+See "Uninstalling" in the "INSTALL.extra" file.
Rebuilding
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
