347 lines
15 KiB
Plaintext
347 lines
15 KiB
Plaintext
This is a port of GNU Groff 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 groNNNb.zip (where NNN is the version number)
|
|
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/<version>/tmac:%DJDIR%/share/groff/site-tmac
|
|
GROFF_TYPESETTER=ascii
|
|
GROFF_FONT_PATH=%DJDIR%/share/groff/<version>/font
|
|
|
|
<version> is something like `1.16.1' or `1.17'.
|
|
|
|
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 formatting large
|
|
documents.
|
|
|
|
4. Read the docs. It comes as formatted manual pages called *.1,
|
|
*.5 and *.7 which unzip into your man/ 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. The Info manual is still
|
|
under construction, so some sections are empty.
|
|
|
|
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 a minimal cookbook:
|
|
|
|
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 the above 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
|
|
|
|
Printing the documents produced by Groff is possible either by
|
|
redirecting Groff's standard 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/<version>/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, -Tlbp 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. The "print" entry is assumed to be a shell command, so
|
|
it can use redirection, pipes, and other shell features.
|
|
|
|
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 are not very useful. The
|
|
batch files are included in the binary distribution
|
|
nonetheless.
|
|
|
|
These scripts need the following utilities to run (in addition
|
|
to the Groff programs they invoke):
|
|
|
|
- bash
|
|
- gawk
|
|
- egrep
|
|
- sed
|
|
|
|
The `afmtodit' and `mmroff' utilities are Perl scripts, so you
|
|
will need a Perl port to run them.
|
|
|
|
All of these ports should be available from the DJGPP sites.
|
|
|
|
If you need to run these scripts and batch files, you have to
|
|
install the port of bash (or another Unix-like shell) and the
|
|
above-mentioned utilities called by the script. Alternatively,
|
|
just look inside the shell script and invoke the programs it
|
|
calls manually.
|
|
|
|
To run the scripts with redirection, invoke them via the shell,
|
|
like this: "sh mmroff > foo".
|
|
|
|
7. 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.
|
|
|
|
8. The package does not include the directories under
|
|
share/groff/<version>/font whose names begin with "devX": these
|
|
are needed on X-Windows for running the gxditview program, which
|
|
is not supported by this port.
|
|
|
|
9. Due to 8+3 limitations of DOS filesystems, several files were
|
|
renamed:
|
|
|
|
- groff_mdoc.samples.7 was renamed to groff-mdoc_samples.7
|
|
and groff_mmse.7 to groff-mmse.7. The latter was also
|
|
converted from Latin-1 encoding to codepage 437.
|
|
|
|
|
|
|
|
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. Versions older than in the above list
|
|
might also 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 groXYZs.zip (where XYZ is the
|
|
version number) 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-X.YZ and unzips the sources there.
|
|
|
|
If you are building from the official GNU distribution, unpack
|
|
the .tar.gz archive like this:
|
|
|
|
djtar -x groff-X.YZ.tar.gz
|
|
|
|
(DJTAR is part of the standard DJGPP development distribution.)
|
|
|
|
3. Groff sources on DJGPP sites are already configured for the
|
|
current version of DJGPP. If that is the version you have,
|
|
then you can just chdir to gnu/groff-X.YZ 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 the current one, or if
|
|
you build the official GNU distribution, or if you prefer to
|
|
configure the package so that it defaults to the directory
|
|
structure on your machine, or 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:
|
|
|
|
arch\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.16\arch\djgpp\config d:/gnu/groff-1.16
|
|
|
|
Note that you MUST use forward slashes in the path you pass to
|
|
CONFIG.BAT, or else it may fail. (For versions of Groff other
|
|
than 1.16, change the above command accordingly.)
|
|
|
|
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 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.com /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 man/ subdirectory, you
|
|
will need to format them. Use the commands shown in chapter I,
|
|
section 5 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).
|
|
|
|
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/<version>/font whose names begin with "devX": these
|
|
are needed on X-Windows which is not supported by this port.
|