Virgin import of FSF groff v1.19.2

1 files changed, 277 insertions, 0 deletions

diff --git a/contrib/groff/README.MinGW b/contrib/groff/README.MinGW
new file mode 100644
index 0000000..342aac2
--- /dev/null
+++ b/contrib/groff/README.MinGW
@@ -0,0 +1,277 @@
+  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 output
+  capability, some additional tools are required as decribed in the section
+  PREREQUISITES FOR HTML OUTPUT later in this file.
+
+
+  BUILDING GROFF WITH MINGW
+  -------------------------
+
+  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 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 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 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.
+
+
+  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 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.