Adding upstream version 1.23.0.upstream/1.23.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 273 insertions, 0 deletions

diff --git a/INSTALL.extra b/INSTALL.extra
new file mode 100644
index 0000000..78d4139
--- /dev/null
+++ b/INSTALL.extra
@@ -0,0 +1,273 @@
+    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'.
+
+
+Building and Installing from within the Source Tree
+===================================================
+
+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 AT&T Unix System V, you might need
+     to type 'sh ./configure' instead to prevent 'csh' from trying to
+     execute 'configure' itself.
+
+     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.  You may wish to add the '-j' option
+     to accelerate the build on multicore systems.
+
+  3. Optionally, check the build for sound operation as described under
+     "Evaluation" below.
+
+  4. Type 'sudo make install install-doc' to install groff's programs,
+     data files, and documentation.  This is the only step for which you
+     need 'root' access; 'sudo' obtains this access.
+
+  5. 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'.
+
+
+Building and Installing from outside the Source Tree
+====================================================
+
+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
+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 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'.  These directory names can be anything
+valid on the operating system.
+
+  0. Create '/home/my/groff-build' and 'cd' to that directory.
+
+  1. Type '/usr/local/src/groff/configure' 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.  You may wish to add the '-j' option
+     to accelerate the build on multicore systems.
+
+  3. Optionally, check the build for sound operation as described under
+     "Evaluation" below.
+
+  4. Type 'sudo make install install-doc' to install groff's programs,
+     data files, and documentation.  This is the only step for which you
+     need 'root' access; 'sudo' obtains this access.
+
+  5. 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'.
+
+
+Unprivileged Installation
+=========================
+
+The use of 'sudo' is necessary only 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_BIN_PATH', 'GROFF_FONT_PATH', and 'GROFF_TMAC_PATH' environment
+variables.  See the groff(1) man page.  See "Evaluation" below for
+instructions on viewing this man page without having groff installed.
+
+
+Non-POSIX Platforms
+===================
+
+For instructions how to build groff with DJGPP tools for MS-DOS and
+MS-Windows, see the file arch/djgpp/README.
+
+For instructions how to build groff with the MinGW tools for
+MS-Windows, see the file README.MinGW.
+
+
+Dependencies
+============
+
+groff is predominantly 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.
+
+A few components of groff are written in ISO C99.  Features later made
+optional by ISO C11 (the 'complex' primitive data type and
+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.
+
+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'.  Discovery of the 'uchardet' library
+requires the 'pkg-config' program to be installed on your system, as
+well as the library's C header files--on a package-based host system,
+this can mean installing uchardet's '-dev' or '-devel' package.
+
+URW fonts
+---------
+
+The 'configure' script searches for PostScript Type 1 fonts originating
+with the URW foundry; these are metrically compatible replacements for
+the Adobe PostScript Level 2 base 35 fonts required by that standard.
+These URW fonts are packaged with Ghostscript and in various derivative
+versions.  The Adobe fonts are not free software, but the replacements,
+often named "Nimbus Roman", "Nimbus Sans", and "Nimbus Mono", and so
+forth, are.  The PostScript and early PDF standards assumed that these
+base fonts would be supplied by the rendering device (a printer or PDF
+viewer).  Nowadays the PDF standard expects all fonts to be embedded in
+the document; if groff's gropdf(1) output driver knows where to find
+these fonts, you can use its "-e" option for this purpose.
+
+The build process populates "Foundry" and "download" files that tell
+gropdf where to find their groff font descriptions and the font files
+themselves, respectively.  If you have multiple versions of the URW
+fonts available on your system, or the 'configure' script cannot locate
+them on its own, use its "--with-urw-fonts-dir" option to tell the
+script where to find them.  If you never use groff to generate
+PostScript or PDF documents, you can ignore any output from the
+'configure' script about URW fonts.
+
+
+Miscellaneous
+=============
+
+If you want A4 or U.S. letter paper format and the 'configure' script
+produces an incorrect guess, say
+
+  PAGE=xxx ./configure
+
+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 or with the "papersize"
+macro package; see section "Paper format" in groff(1).
+
+
+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'
+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
+environment variables to allow groff to run without being installed.
+For example, from the directory where you built groff, the command
+
+  ./test-groff -t -man -Tascii src/roff/groff/groff.1 | less -R
+
+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.)
+
+
+Documentation
+=============
+
+The groff Texinfo manual can be viewed in several formats.  Versions
+corresponding to the source document 'doc/groff.texi' are supplied with
+the source distribution archive.  You can browse it in GNU info format.
+
+  info doc/groff.info
+
+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
+
+Renderings in HTML, TeX DVI, and PDF are also available.
+
+  lynx doc/groff.html
+  xdvi doc/groff.dvi
+  evince doc/groff.pdf
+
+A compilation of groff's man pages is available in text (with ISO 6429
+escape sequences) and PDF.
+
+  less -R doc/groff-man-pages.utf8.txt
+  evince doc/groff-man-pages.pdf
+
+
+In Case of Trouble
+==================
+
+If a test fails, gather its log file from the build directory.  For
+instance, the test "tmac/tests/localization-works.sh" (in the source
+directory) will have a log file called
+"tmac/tests/localization-works.sh.log" in the build directory.
+
+To re-run a test, change to the top of the build directory (if
+necessary) and run the test by name from the shell prompt.
+
+For example, to rerun the test mentioned above from a "build" directory
+I created as a subdirectory in the source tree, I would do this.
+
+  (cd build && ../tmac/tests/localization-works.sh)
+
+I can view the test log as follows.
+
+  cat build/tmac/tests/localization-works.sh.log
+
+Many known issues are documented in the 'PROBLEMS' file; some apply to
+historical systems.  You can also browse groff bug reports via the GNU
+Savannah issue tracker to see if your issue has already been reported.
+
+  https://savannah.gnu.org/bugs/?group=groff
+
+If that doesn't help 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 ticket using the 'BUG-REPORT' file as a template.
+
+  https://savannah.gnu.org/bugs/?group=groff&func=additem
+
+
+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 'sudo make uninstall'.  (If you
+successfully used 'make install', simply run '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' command.  (As of this writing, 'install-info' offers no
+provision for removing an effectively empty 'dir' file, and groff does
+not attempt to parse this file to determine whether it can be safely
+removed.)  All other groff artifacts will be deleted from the
+installation hierarchy.
+
+
+##### Editor settings
+Local Variables:
+fill-column: 72
+mode: text
+End:
+vim: set autoindent textwidth=72: