This is the GNU `groff' document formatting system.  The version
number is given in the file VERSION.

Included in this release are implementations of `troff', `pic', `eqn',
`tbl', `grn', `refer', `-man', `-mdoc', `-mom', and `-ms' macros, and
drivers for `PostScript', `TeX dvi' format, `HP LaserJet 4' printers,
`Canon CAPSL' printers, `HTML' format (beta status), and
typewriter-like devices.  Also included is a modified version of the
Berkeley `-me' macros, the enhanced version `gxditview' of the X11
`xditview' previewer, and an implementation of the `-mm' macros
contributed by Joergen Haegg (jh@axis.se).

See the file `INSTALL' for installation instructions.  You will
require a C++ compiler.

The file `NEWS' describes recent user-visible changes to `groff'.

`groff' is free software.  See the file `COPYING' for copying
permission.

The file `PROBLEMS' describes various problems that have been
encountered in compiling, installing, and running `groff'.

The most recent released version of `groff' is always available by
anonymous ftp from `ftp.gnu.org' in the directory `gnu/groff'.

The current development version of `groff' is available from a `CVS'
repository.  You can access it by first selecting a parent directory
in which to create a working copy (call it, say, `~/cvswork'), and
then executing the commands

  cd ~/cvswork
  CVS_RSH=ssh; export CVS_RSH
  cvs -d:ext:anoncvs@savannah.gnu.org/cvsroot/groff -z5 co groff

(Note that you need an `ssh' client for security reasons.)

This will create a subdirectory, `~/cvswork/groff', with a "checked
out" copy of the `CVS' repository.  An update of this working copy may
be achieved, at any later time by invoking the commands

  cd ~/cvswork/groff
  CVS_RSH=ssh cvs -z5 update -dP

Please read the `CVS' info pages for further details.

Finally, it is possible to access the `CVS' with a web browser by
pointing it to

  http://savannah.gnu.org/cvs/?group=groff

Alternatively, you can download snapshots (which are updated twice a day).
The complete `groff' source as a single file is available at

  http://groff.ffii.org/groff/devel/groff-current.tar.gz

A diff file relative to `groff-<version>', the latest official `groff'
release is available at

  http://groff.ffii.org/groff/devel/groff-<version>-current.diff.gz

Assuming that `groff-<version>.tar.gz' and
`groff-<version>-current.diff.gz' are in the same directory, do the
following to apply the diff file:

  tar xzvf groff-<version>.tar.gz
  cd groff-<version>
  gunzip -c ../groff-<version>-current.diff.gz | patch -p1

Depending on your requirements, you may need at least some of the
following tools to build `groff' directly from its source:

  ghostscript
  the psutils package
  the netpbm package
  texinfo 4.8
  bison >= 1.875b or byacc

Note that `texinfo' and `bison' or `byacc' are required only for
building from `CVS' sources (either a checked out working copy, or a
daily snapshot).  They are not required for building from a stable
release tarball.  Also note that the version numbers stated are the
minimum supported.  No version of `texinfo' < 4.8 will work, and the
original release of `bison' 1.875 is known not to work; you *may* find
that `bison' releases < 1.875 will work, but in case of difficulty,
please update to a later version *before* posting a bug report.

For *all* sources, you need ghostscript for creation of either `PDF' or
`HTML' output; the `netpbm' and `psutils' packages are required only for
`HTML' output.  If you don't intend to produce output in either of these
formats, then these packages are unnecessary.

In Linux Debian, the installation of `texinfo' is dangerous.  For it
creates a file `install-info' that will block the system installation.
So the created `/usr/local/bin/install-info' must be renamed.

The `groff' configure script searches for the X11 headers and
libraries `Xaw' and `Xmu'.  So the corresponding developer packages of
your system must be installed, otherwise `groff' does not install
`gxditview' and the `-TX*' devices.  In Debian, the developer packages
are `libxaw7-dev' and `libxmu-dev'.

Please report bugs using the form in the file `BUG-REPORT'; the idea of
this is to make sure that FSF has all the information it needs to fix
the bug.  At the very least, read the `BUG-REPORT' form and make sure
that you supply all the information that it asks for.  Even if you are
not sure that something is a bug, report it using `BUG-REPORT': this will
enable us to determine whether it really is a bug or not.

Three mailing lists are available:

  bug-groff@gnu.org          for reporting bugs
  groff@gnu.org              for general discussion of groff
  groff-commit@gnu.org       a read-only list showing commitments
                             to the CVS repository

You can post mails directly to the `bug-groff' list, without subscribing;
to post mails to the `groff' list you must subscribe to it.

To subscribe, send a mail to <list>-request@<domain> (example:
groff-request@gnu.org for the `groff' list) with the word `subscribe'
in either the subject or body of the email (don't include the quotes).
Alternatively, you may subscribe by visiting the web pages at

  http://lists.gnu.org/mailman/listinfo/bug-groff
  http://lists.gnu.org/mailman/listinfo/groff
  http://lists.gnu.org/mailman/listinfo/groff-commit

Each of these web pages also provides a link to a browseable archive of
postings to the corresponding mailing list.

GNU `groff' was written by James Clark <jjc@jclark.com>.  It is now
maintained by Ted Harding <ted.harding@nessie.mcc.ac.uk> and Werner
Lemberg <wl@gnu.org>.

  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.

Indexes created Tue Apr 23 23:32:07 MDT 2024