Adding upstream version 1.23.0.upstream/1.23.0upstream

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

1 files changed, 326 insertions, 0 deletions

diff --git a/README.MinGW b/README.MinGW
new file mode 100644
index 0000000..412597a
--- /dev/null
+++ b/README.MinGW
@@ -0,0 +1,326 @@
+    Copyright (C) 2003-2020 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.
+
+  README.MinGW
+  ============
+
+  Contributed by Keith Marshall (keith.d.marshall@ntlworld.com)
+
+
+  INTRODUCTION
+  ------------
+
+  This file provides recommendations for building a Win32 implementation
+  of GNU Groff, using the MinGW port of GCC for Microsoft (TM)
+  Windows-32 platforms.  It is intended to supplement the standard
+  installation instructions (see file INSTALL); it does not replace
+  them.
+
+  You require both the MinGW implementation of GCC and its supporting
+  MSYS toolkit, which provides a Win-32 implementation of the GNU bash
+  shell, and a few other essential utilities; these may be obtained from
+
+    http://sourceforge.net/projects/mingw
+
+  by following the appropriate download links, where they are available
+  as self-extracting executable installation packages.  If installing
+  both from scratch, it is recommended that MinGW is installed first, as
+  the MSYS installer can then automatically set up the proper
+  environment for running MinGW.
+
+  Additionally, if you wish to compile groff with support for its HTML
+  (and XHTML) output capability, some additional tools are required as
+  described in the section PREREQUISITES FOR HTML OUTPUT later in this
+  file.
+
+
+  BUILDING GROFF WITH MINGW
+  -------------------------
+
+  *** WARNING ***
+
+  Before commencing this procedure, you should ensure that you are
+  running the MSYS shell in a *native* Win32 console window, and not in
+  any window managed by the rxvt emulator provided with MSYS; (this
+  emulator suffers from various known defects, which will prevent
+  successful completion of a groff build).
+
+  ******
+
+  Assuming that you have obtained the appropriate groff distribution,
+  and that you are already running an MSYS shell, then the
+  configuration, compilation, and installation of groff, using MinGW, is
+  performed in much the same way as it is described in the INSTALL file,
+  which is provided with the groff distribution.  The installation steps
+  are summarised below:
+
+  1. Change working directory to any suitable location where you may
+     unpack the groff distribution; you must be authorized for write
+     access.  Approximately 30MB of free disk space are needed.
+
+  2. Unpack the groff distribution:
+
+       tar xzf <download-path>/groff-<version>.tar.gz
+
+     This creates a new sub-directory, groff-<version>, containing an
+     image of the groff source tree.  You should now change directory,
+     to make this ./groff-<version> your working directory.
+
+  3. If you are intending to build groff with support for HTML (and
+     XHTML) output, then you must now ensure that the prerequisites
+     described in the later section PREREQUISITES FOR HTML OUTPUT are
+     satisfied, before proceeding to build groff; in particular, please
+     ensure that all required support programs are installed in the
+     current PATH.
+
+  4. You are now ready to configure, build, and install groff.  This is
+     accomplished using the conventional procedure, as described in the
+     file INSTALL, i.e.
+
+       ./configure --prefix=<win32-install-path> ...
+       make
+       make install
+
+     Please observe the syntax for the configure command, indicated
+     above; the default value for --prefix is not suitable for use with
+     MinGW, so the --prefix=<win32-install-path> option must be
+     specified, where <win32-install-path> is the chosen MS-Windows
+     directory in which the groff application files are to be installed
+     (see the later section entitled CHOOSING AN INSTALLATION PATH).
+     Any other desired configuration options may also be specified, as
+     described in the standard groff installation instructions.
+
+  5. After completing the above, groff should be successfully installed;
+     the build directory is no longer required; it may be simply deleted
+     in its entirety.  Alternatively, you may choose to keep it, but to
+     remove all files which can be reproduced later, by repeating the
+     configure, make and make install steps; this is readily
+     accomplished by the command
+
+       make distclean
+
+
+  This completes the installation of groff; please read the final
+  sections of this file, GROFF RUNTIME ENVIRONMENT and CAVEATS AND BUGS,
+  for advice on setting up the runtime environment, and avoiding known
+  runtime problems, before running groff.
+
+
+  CHOOSING AN INSTALLATION PATH
+  -----------------------------
+
+  It may be noted that the above instructions indicate that the
+  ./configure command must be invoked with an argument specifying a
+  preference for --prefix=<win32-install-path>, whereas the standard
+  groff installation instructions indicate that this may be omitted, in
+  which case it defaults to --prefix=/usr/local.
+
+  In the case of building with MinGW, the default behaviour of configure
+  is not appropriate for the following reasons.
+
+  o The MSYS environment creates a virtual Unix-like file system, with
+    its root mapped to the actual MS-Windows directory where MSYS itself
+    is installed; /usr is also mapped to this MSYS installation
+    directory.
+
+  o All of the MSYS tools, and the MinGW implementation of GCC, refer to
+    files via this virtual file system representation; thus, if the
+    --prefix=<win32-install-path> is not specified when groff is
+    configured, `make install' causes groff to be installed in
+    <MSYS-install-path>/local.
+
+  o groff needs to know its own installation path, so that it can locate
+    its own installed components.  This information is compiled in,
+    using the exact form specified with the
+    --prefix=<win32-install-path> option to configure.
+
+  o Knowledge of the MSYS virtual file system is not imparted to groff;
+    it expects the compiled-in path to its components to be a fully
+    qualified MS-Windows path name (although Unix-style slashes are
+    permitted, and preferred to the MS-Windows style backslashes, to
+    demarcate the directory hierarchy).  Thus, when configuring groff,
+    if --prefix=<win32-install-path> is not correctly specified, then
+    the installed groff application looks for its components in
+    /usr/local, and most likely doesn't find them, because they are
+    actually installed in <MSYS-install-path>/local.
+
+  It is actually convenient, but by no means a requirement, to have
+  groff installed in the /usr/local directory of the MSYS virtual file
+  system; this makes it easy to invoke groff from the MSYS shell, since
+  the virtual /usr/local/bin is normally added automatically to the PATH
+  (the default PATH, as set in MSYS's /etc/profile), when MSYS is
+  started.
+
+  In order to install groff into MSYS's /usr/local directory, it is
+  necessary to specify the fully qualified absolute MS-Windows path to
+  this directory, when configuring groff, i.e.
+
+    ./configure --prefix=<MSYS-install-path>/local ...
+
+  For example, on a system where MSYS is installed in the MS-Windows
+  directory D:\MSYS\1.0, the MSYS virtual path /usr/local resolves to
+  the absolute MS-Windows native path D:\MSYS\1.0\local (the /usr
+  component of the MSYS virtual path does not appear in the resolved
+  absolute native path name since MSYS maps this directly to the root of
+  the MSYS virtual file system).  Thus, the --prefix option should be
+  specified to configure as
+
+    ./configure --prefix=D:/MSYS/1.0/local ...
+
+  Note that the backslash characters, which appear in the native
+  MS-Windows form of the path name, are replaced by Unix-style slashes
+  in the argument to configure; this is the preferred syntax.
+
+  Also note that the MS-Windows device designator (D: in this instance)
+  is prepended to the specified path, in the normal MS-Windows format,
+  and that, since upper and lower case distinctions are ignored in
+  MS-Windows path names, any combination of upper and lower case is
+  acceptable.
+
+
+  PREREQUISITES FOR HTML OUTPUT
+  -----------------------------
+
+  If you intend to use groff for production of HTML or XHTML output,
+  then there are a few dependencies which must be satisfied.  Ideally,
+  these should be resolved before attempting to configure and build
+  groff, since the configuration script does check them.
+
+  In order to produce HTML or XHTML output, you first require a working
+  implementation of Ghostscript; either the AFPL Ghostscript or the GNU
+  Ghostscript implementation for MS-Windows should be suitable,
+  depending on your licensing preference.  It is highly recommended to
+  use version 8.11 or higher due to bugs in older versions.  These may
+  be obtained, in the form of self-installing binary packages, by
+  following the download links for the chosen licensing option, from
+  http://sourceforge.net/projects/ghostscript.
+
+  Please note that these packages install the Ghostscript interpreter
+  required by groff in the ./bin subdirectory of the Ghostscript
+  installation directory, with the name gswin32c.exe.  However, groff
+  expects this interpreter to be located in the system PATH, with the
+  name gs.exe.  Thus, to ensure that groff can correctly locate the
+  Ghostscript interpreter, it is recommended that the file gswin32c.exe
+  should be copied from the Ghostscript installation directory to the
+  MSYS /usr/local/bin directory, where it should be renamed to gs.exe.
+
+  In addition to a working Ghostscript interpreter, you also require
+  several image manipulation utilities, all of which may be scavenged
+  from various packages available from
+  http://sourceforge.net/projects/gnuwin32, and which should be
+  installed in the MSYS /usr/local/bin directory, or any other suitable
+  directory which is specified in the PATH.  These additional
+  prerequisites are
+
+    1. from the netpbm-<version>-bin.zip package:
+
+         netpbm.dll
+         pnmcrop.exe
+         pnmcut.exe
+         pnmtopng.exe
+         pnmtops.exe
+
+    2. from the libpng-<version>-bin.zip package:
+
+         libpng.dll
+
+    3. from the zlib-<version>-bin.zip package:
+
+         zlib-1.dll, which must be renamed to zlib.dll
+
+    4. from the psutils-<version>-bin.zip package:
+
+         psselect.exe
+
+  Note that it is not necessary to install the above four packages in
+  their entirety; of course, you may do so if you wish.
+
+  Further note that you are advised to avoid the netpbm-10.27 release
+  from the GnuWin32 download repository, as its pnmtopng.exe has been
+  reported to fail on even simple conversions, resulting in failure of
+  the groff build process; the earlier netpbm-10.18.4 has been found to
+  work successfully.  Also, you may find it necessary to use
+  libpng-1.2.7, rather than libpng-1.2.8, in conjunction with this
+  earlier release of netpbm.
+
+
+  GROFF RUNTIME ENVIRONMENT
+  -------------------------
+
+  The runtime environment, provided to groff by MSYS, is essentially the
+  same as would be provided under a Unix or GNU/Linux operating system;
+  thus, any environment variables which may be used to customize the
+  groff runtime environment have similar effects under MSYS, as they
+  would in Unix or GNU/Linux, with the exception that any variable
+  specifying a path should adopt the same syntax as a native MS-Windows
+  PATH specification.
+
+  There is, however, one known problem which is associated with the
+  implementation of the MS-Windows file system, and the manner in which
+  the Microsoft runtime library (which is used by the MinGW
+  implementation of GCC) generates names for temporary files.  This
+  known problem arises when groff is invoked with a current working
+  directory which refers to a network share, for which the user does not
+  have write access in the root directory, and there is no environment
+  variable set to define a writeable location for creating temporary
+  files.  When these conditions arise, groff fails with a `permission
+  denied' error, as soon as it tries to create any temporary file.
+
+  To specify the location for creating temporary files, the standard
+  Unix or GNU/Linux implementation of groff provides the GROFF_TMPDIR or
+  TMPDIR environment variables, whereas MS-Windows applications
+  generally use TMP or TEMP; furthermore, the MS-Windows implementations
+  of Ghostscript apparently support the use of only TEMP or TMPDIR.
+
+  To avoid problems with creation of temporary files, it is recommended
+  that you ensure that both TMP and TEMP are defined, with identical
+  values, to point to a suitable location for creating temporary files;
+  many MS-Windows boxes have them set already, and groff has been
+  adapted to honour them, when built in accordance with the preceding
+  instructions, using MinGW.
+
+
+  CAVEATS AND BUGS
+  ----------------
+
+  There are two known issues, observed when running groff in the
+  MinGW/MSYS environment, which would not affect groff in its native
+  Unix environment:
+
+  o Running groff with the working directory set to a subdirectory of a
+    network share, where the user does not have write permission in the
+    root directory of the share, causes groff to fail with a `permission
+    denied' exception, if the TMP environment variable is not
+    appropriately defined; it may also be necessary to define the TEMP
+    environment variable, to avoid a similar failure mode, when using
+    the -Thtml or -Txhtml output mode of groff.  This problem is more
+    fully discussed in the preceding section, GROFF RUNTIME ENVIRONMENT.
+
+  o When running groff (or nroff) to process standard input, where the
+    standard input stream is obtained directly from the RXVT console
+    provided with MSYS, groff cannot detect the end-of-file condition
+    for the standard input stream, and hangs.  This appears to be caused
+    by a fault in the MSYS implementation of RXVT; it may be worked
+    around by either starting MSYS without RXVT (see the comments in the
+    MSYS.BAT startup script); in this case standard input is terminated
+    by typing <Ctrl-Z> followed by <RETURN>, on a new input line.
+    Alternatively, if you prefer to use MSYS with RXVT, you can enter
+    the interactive groff command in the form
+
+      cat | groff ...
+
+    in which case <Ctrl-D> terminates the standard input stream, in just
+    the same way it does on a Unix system; the cat executable provided
+    with MSYS does seem to trap the end-of-file condition, and properly
+    signals groff that the input stream has terminated.
+
+
+##### Editor settings
+Local Variables:
+fill-column: 72
+mode: text
+End:
+vim: set textwidth=72: