This is a port of GNU Groff version 1.15 to DJGPP v2.03 or later.
Groff is the GNU version of document formatting tools related to
`troff'.

This README file describes how to build and install Groff on MS-DOS or
MS-Windows systems using the DJGPP port of GNU C/C++ compiler and
development tools.


I.  Installing the pre-compiled binary package
    ------------------------------------------

    1. Unzip the file gro115b.zip preserving the directory structure
       (-d switch to PKUNZIP) from the main DJGPP installation
       directory.  If you will use Groff on Windows 9X or Windows2000,
       use an unzip program which supports long filenames.

    2. Groff binaries were configured so that they will look for their
       standard directories under the directory pointed to by the
       DJDIR environment variable, so it should work automatically if
       you have DJGPP installed.  If you don't have a standard DJGPP
       installation, set the variable DJDIR to point to the directory
       where you unzip Groff.  In this latter case, you will need to
       set additional environment variables:

	GROFF_TMAC_PATH=.;%DJDIR%/share/groff/tmac
	GROFF_TYPESETTER=ascii
	GROFF_FONT_PATH=.;%DJDIR%/share/groff/font

       In addition, you can set the variable GROFF_TMPDIR to point to
       a directory where you want Groff to create temporary files it
       needs for running its jobs (these files are automatically
       deleted when Groff exits).

       All of those variables are automatically set in the file
       DJGPP.ENV that is part of the standard DJGPP distribution
       djdevNNN.zip (where NNN is the DJGPP version number), so you
       only need to set them manually if you don't have DJGPP
       installed.

       Note that the GROFF_TYPESETTER variable sets the default Groff
       device to be `ascii', which is suitable for formatting man
       pages to be viewed on the terminal.  Use the -T switch to
       generate output for other devices (e.g., -Tps for PostScript).

    3. If your TMPDIR environment variable points to a RAM drive, you
       might consider changing GROFF_TMPDIR to point to a directory on
       a real disk drive, especially if you intend to generate
       PostScript output, because RAM disks are typically small (2-3
       MBytes) which might be not enough for large jobs.

    4. Read the docs.  It comes as formatted manual pages called *.1n,
       *.5n and *.7n which unzip into your info/ subdirectory.  You
       can read them with a pager such as GNU Less (recommended, as
       Less will use colors for bold and underlined text) or with
       Info (which will remove the bold/underline attributes).
       Another alternative is to use Emacs built-in man page reader;
       the DJGPP FAQ lists other possibilities.

       Beginning with version 1.15, Groff comes with an Info manual;
       type "info -f groff" to read it.

       If you want to add a Groff entry to the main Info menu in the
       file DIR, chdir to the `info' subdirectory of the main Groff
       installation directory and run this command:

         install-info --dir-file=dir groff.info

       After you do that, "info groff" will also work.

    5. For those who only need Groff to format man pages and don't
       like reading the docs, here's how you do that:

		  groff -man -s foo.1 > foo.man

       where `foo.1' is the troff source of the man page and `foo.man'
       is the formatted page.  If you need to view the man page, say
       this:

		  groff -man -s foo.1 | less

       You can also use the DJGPP clone of the Unix `man' command, in
       which case `man' runs this command for you automatically.

       Here's how you print man pages on a PostScript printer:

		  groff -man -s -Tps foo.1 > prn

       And this is for a LaserJet4 printer:

		  groff -man -s -Tlj4 foo.1 > prn

       The default configuration assumes that, for

       Generally, you should redirect output of Groff to the printer,
       rather than use the `-l' switch to Groff.

       Printing the documents produced by Groff is possible either by
       redirecting Groff's stdandard output to the local printer
       device, like shown above, or by using the `-l' switch to Groff.
       The latter possibility causes Groff to pipe its output to a
       program whose name and arguments appear in the files named
       `DESC' in each of the `devFOO' subdirectories of the
       %DJDIR%/share/groff/font directory; for example, the file
       devps/DESC is used by "groff -Tps".  The relevant line in these
       files begins with the word "print".

       As configured, when invoked with the `-l' switch, Groff will
       call `cat' (from GNU Textutils) to pipe its output to the
       default printer device for -Tps and -Tlj4 options, and it will
       call `dvilj4' (from the dvljNNNb.zip package) for -Tdvi option.
       If you don't have these programs installed, you can edit the
       respective `DESC' files to replace these commands with
       something else.  The replacement program must be able to read
       its standard input and send its output to whatever printer you
       want.

       Beginning with version 1.15, Groff can create HTML output, like
       this:

		  groff -man -s -Thtml foo.1 > foo.html

       Producing HTML files sometimes requires Ghostscript to be
       installed, and, for gif images, ppmquant and ppmtogif as well.
       If you do not have these programs installed, Groff will print
       an error message, and the produced file will have links which
       will fail to resolve when you view it with a Web browser.

    6. Some programs in the package are supplied as Unix shell
       scripts.  While it is relatively easy to write a DOS batch file
       which will do the same, DOS doesn't allow to redirect input and
       output of a batch file.  Since Groff tools are meant to be
       invoked in a pipe, the batch files would be useless.  Some of
       the scripts are useful interactively, so for them, batch files
       were provided (see the next paragraph).

       If you need to run these scripts, you would need to install the
       port of bash (or other Unix-like shell) and any utilities
       called by the script.  Alternatively, just look inside the
       shell script and invoke the programs it calls manually.

    7. The `grog' script and `grog.bat' batch file need these
       utilities to run (in addition to the Groff programs they call):

		 - bash
		 - gawk
		 - egrep
		 - sed

       All of these should be available from the DJGPP sites.

       The `afmtodit' utility is a Perl script, so you will need a
       Perl port to run it.

       Fortunately, both `grog' and `afmtodit' are used infrequently
       and aren't required for core Groff functionality.

       Batch file is also provided for `nroff', which emulates the
       Unix `nroff' command by calling Groff.

    8. Note that Groff programs use floating point, so you will need
       an FP emulator if your machine doesn't have an FPU.  The binary
       distribution includes the emulator, in case you don't have the
       DJGPP development environment installed.  Please refer to the
       DJGPP FAQ list in case you have any problems with the emulator.

    9. The package does not include the directories under
       share/groff/font whose names begin with "devX": these are
       needed on X-Windows which are not supported by this port.

   10. The man page for the `mmse' macro package, the Swdish version
       of the `mm' macros, was renamed from `groff_mmse' to
       `groff_semm', to prevent file-name clashes with `groff_mm'.
       Type "man groff_semm" to read that page.  Likewise, the
       `groff_msafer' page was renamed to `groff_safer'.



II. Building Groff from sources
    ---------------------------

    1. To build Groff, you will need the following tools (the file
       name in parentheses is what you need to download from one of
       the DJGPP sites):

	  - Standard DJGPP development environment (djdev203.zip)
	  - GNU C compiler (gcc2721b.zip)
	  - GNU C++ compiler (gpp2721b.zip)
	  - GNU Make 3.79 (mak379b.zip)
	  - Bash v2.03 (bsh203b.zip)
	  - Fileutils 3.16 (fil316b.zip)
	  - Textutils 2.0 (txt20b.zip)
	  - Sh-utils 1.12 (shl112b.zip)
	  - Sed 3.02 (sed302b.zip)
	  - Gawk 3.04 (gwk304b.zip)
	  - Grep 2.4 (grep24b.zip)
	  - Bison (only if you change one of the *.y files)

       Note that you don't need to install libg++ (lgpNNNb.zip) since
       Groff doesn't use any C++ classes except its own.

       Any versions of the utilities later than what's mentioned above
       should also do; in particular, GCC 2.95.2 was tested and Groff
       built okay with it.  Older versions might work, but I don't
       guarantee that; you are on your own.

       Special considerations apply if you have GCC 2.8.1 installed,
       and cannot upgrade to a later version.  See paragraph 4 below.

       After you install these tools, make sure you have a ``symlink''
       to bash.exe called sh.exe and a ``symlink'' to gawk.exe called
       awk.exe.  If not, go to the DJGPP bin/ subdirectory and type
       the following words of wisdom from the DOS prompt:

		     ln -s bash.exe sh.exe
		     ln -s gawk.exe awk.exe

       (`ln' is part of GNU Fileutils, see above.)

    2. Unzip the source distribution gro115s.zip preserving the
       directory structure (-d switch to PKUNZIP) from the main DJGPP
       installation directory.  (If you are building Groff on Windows
       9X or Windows 2000, use an unzip program which supports long
       filenames.)  This creates directory gnu/groff-1.15 and unzips
       the sources there.

    3. Groff sources are already configured for version 2.03 of DJGPP.
       If that is the version you have, then you can just chdir to
       gnu/groff-1.15 and say "make" to build the entire package (if
       you have GCC 2.8.1, see the next paragraph).

       If you have version of DJGPP other than v2.03, or if you prefer
       to configure the package so that it defaults to the directory
       structure on your machine, or if you need to change some
       options (e.g., compile with different optimization options),
       you will have to reconfigure Groff.  To this end, use the
       CONFIG.BAT batch file in the DJGPP subdirectory:

		     djgpp\config

       You can configure and build Groff from outside its source
       directory.  In that case, you need to pass the full path to the
       source directory as an argument to CONFIG.BAT, like this:

	  d:\gnu\groff-1.15\djgpp\config d:/gnu/groff-1.15

       Note that you MUST use forward slashes in the path you pass to
       CONFIG.BAT, or else it may fail.

    4. If your version of GCC is 2.8.1, you cannot build the
       preconfigured package without some tinkering.  The DJGPP port
       of GCC 2.8.1 had a bug in its C++ configuration, whereby the
       file _G_config.h erroneously indicated that the header
       <sys/socket.h> is available, and also undefined the symbol
       NULL.  This causes several files in the Groff distribution to
       fail to compile.

       The easiest way to solve this is to upgrade to a later version
       of GCC; then you can simply say "make" to build the
       preconfigured package.  If this is not an option, you will have
       to edit the file lang/cxx/_G_config.h and change this line:

	  #define _G_HAVE_SYS_SOCKET 1

       to say this instead:

	  #define _G_HAVE_SYS_SOCKET 0

       The problem with redefining NULL should not happen with DJGPP
       v2.03 or later.  But if you still see compilation errors which
       say "`NULL' undeclared", comment out the line in _G_config.h
       that says this:

	  #undef NULL

       Alternatively, you can reconfigure the package as described in
       the previous paragraph, before building it.

    5. After the configure script exits, say "make" to build Groff.
       Groff is a large package, and it might take a a few minutes to
       build, depending on your CPU, so you might as well go for a
       coffee while it grinds away.

    6. Test the package that you have built.  A batch file T-GROFF.BAT
       in the DJGPP subdirectory is supplied for that purpose.  Most
       of the commands there are commented out, since I cannot
       possibly know what kind of printer do you have and which
       additional programs, such as Less, do you have installed.  The
       only command that runs by default will format a large document
       and print it to the screen.  Read the comments in the batch
       file, uncomment additional lines as you see fit and run the
       batch file to see that you get the document printed as you'd
       expect.  (Btw, the document that the batch file prints is an
       introduction to the entire Groff package, so you might as well
       read it to make yourself familiar with the programs.)

       Note that the batch file sets a lot of environment variables;
       if you get ``Out of environment space'' messages, launch a
       subsidiary COMMAND.COM with plenty of environment space, like
       so:

		     command /e:3000

       then invoke T-GROFF.BAT from that COMMAND.COM.

    7. Install the package by typing "make install".  This will copy
       all the binaries, the auxiliary files (fonts, macros, etc.) and
       the docs into their places.  If you configured the package for
       your system, these are precisely the directories where the
       files should remain (with the exception of the man pages, see
       below).  If you use the default configuration, the files will
       be installed under the top DJGPP installation directory.

       Alternatively, you could instruct Make explicitly where to
       install the package by setting the `prefix' variable.  For
       example:

	       make install prefix=c:/groff

       "make install" doesn't format the man pages, it just copies
       them into subdirectories of the %DJDIR%\MAN directory.  If you
       need to keep formatted pages in your info/ subdirectory, you
       will need to format them.  Use the command shown above to do
       that, and redirect its output to the appropriate catN
       subdirectory.  Alternatively, you could format the pages when
       you need to view them (the DJGPP clone of `man' will
       automatically format them).

       "make install" assumes that the directory under which you
       install the package already exists.  For the default location
       under the main DJGPP directory, this is true, but if you
       install Groff elsewhere, you will have to make sure the target
       directory exists before saying "make install".

       Consult the installation instructions for pre-compiled binaries
       above, for more info about installing and using Groff.

    8. You can safely delete the directories under share/groff/font
       whose names begin with "devX": these are needed on X-Windows
       which is not supported by this port.

    9. The file djgpp/DIFFS shows what changes did I make in the
       sources, so you could see what I broke ;-).

