1 Copyright (C) 2000-2014 Free Software Foundation, Inc.
3 Copying and distribution of this file, with or without modification,
4 are permitted in any medium without royalty provided the copyright
5 notice and this notice are preserved.
7 This is a port of GNU Groff to DJGPP v2.03 or later.
8 Groff is the GNU version of document formatting tools related to
11 This README file describes how to build and install Groff on MS-DOS or
12 MS-Windows systems using the DJGPP port of GNU C/C++ compiler and
16 I. Installing the pre-compiled binary package
17 ------------------------------------------
19 1. Unzip the file groNNNb.zip (where NNN is the version number)
20 preserving the directory structure (-d switch to PKUNZIP) from
21 the main DJGPP installation directory. If you will use Groff
22 on Windows 9X or Windows2000, use an unzip program which
23 supports long filenames.
25 2. Groff binaries were configured so that they will look for their
26 standard directories under the directory pointed to by the
27 DJDIR environment variable, so it should work automatically if
28 you have DJGPP installed. If you don't have a standard DJGPP
29 installation, set the variable DJDIR to point to the directory
30 where you unzip Groff. In this latter case, you will need to
31 set additional environment variables:
33 GROFF_TMAC_PATH=%DJDIR%/share/groff/<version>/tmac:%DJDIR%/share/groff/site-tmac
34 GROFF_TYPESETTER=ascii
35 GROFF_FONT_PATH=%DJDIR%/share/groff/<version>/font
37 <version> is something like `1.16.1' or `1.17'.
39 In addition, you can set the variable GROFF_TMPDIR to point to
40 a directory where you want Groff to create temporary files it
41 needs for running its jobs (these files are automatically
42 deleted when Groff exits).
44 All of those variables are automatically set in the file
45 DJGPP.ENV that is part of the standard DJGPP distribution
46 djdevNNN.zip (where NNN is the DJGPP version number), so you
47 only need to set them manually if you don't have DJGPP
50 Note that the GROFF_TYPESETTER variable sets the default Groff
51 device to be `ascii', which is suitable for formatting man
52 pages to be viewed on the terminal. Use the -T switch to
53 generate output for other devices (e.g., -Tps for PostScript).
55 3. If your TMPDIR environment variable points to a RAM drive, you
56 might consider changing GROFF_TMPDIR to point to a directory on
57 a real disk drive, especially if you intend to generate
58 PostScript output, because RAM disks are typically small (2-3
59 MBytes) which might be not enough for formatting large
62 4. Read the docs. It comes as formatted manual pages called *.1,
63 *.5 and *.7 which unzip into your man/ subdirectory. You
64 can read them with a pager such as GNU Less (recommended, as
65 Less will use colors for bold and underlined text) or with
66 Info (which will remove the bold/underline attributes).
67 Another alternative is to use Emacs built-in man page reader;
68 the DJGPP FAQ lists other possibilities.
70 Beginning with version 1.15, Groff comes with an Info manual;
71 type "info -f groff" to read it. The Info manual is still
72 under construction, so some sections are empty.
74 If you want to add a Groff entry to the main Info menu in the
75 file DIR, chdir to the `info' subdirectory of the main Groff
76 installation directory and run this command:
78 install-info --dir-file=dir groff.info
80 After you do that, "info groff" will also work.
82 5. For those who only need Groff to format man pages and don't
83 like reading the docs, here's a minimal cookbook:
85 groff -man -s foo.1 > foo.man
87 where `foo.1' is the troff source of the man page and `foo.man'
88 is the formatted page. If you need to view the man page, say
91 groff -man -s foo.1 | less
93 You can also use the DJGPP clone of the Unix `man' command, in
94 which case `man' runs the above command for you automatically.
96 Here's how you print man pages on a PostScript printer:
98 groff -man -s -Tps foo.1 > prn
100 And this is for a LaserJet4 printer:
102 groff -man -s -Tlj4 foo.1 > prn
104 Printing the documents produced by Groff is possible either by
105 redirecting Groff's standard output to the local printer
106 device, like shown above, or by using the `-l' switch to Groff.
107 The latter possibility causes Groff to pipe its output to a
108 program whose name and arguments appear in the files named
109 `DESC' in each of the `devFOO' subdirectories of the
110 %DJDIR%/share/groff/<version>/font directory; for example, the
111 file devps/DESC is used by "groff -Tps". The relevant line in
112 these files begins with the word "print".
114 As configured, when invoked with the `-l' switch, Groff will
115 call `cat' (from GNU Textutils) to pipe its output to the
116 default printer device for -Tps, -Tlbp and -Tlj4 options, and
117 it will call `dvilj4' (from the dvljNNNb.zip package) for -Tdvi
118 option. If you don't have these programs installed, you can
119 edit the respective `DESC' files to replace these commands with
120 something else. The replacement program must be able to read
121 its standard input and send its output to whatever printer you
122 want. The "print" entry is assumed to be a shell command, so
123 it can use redirection, pipes, and other shell features.
125 Beginning with version 1.15, Groff can create HTML output, like
128 groff -man -s -Thtml foo.1 > foo.html
130 Producing HTML files sometimes requires Ghostscript to be
131 installed, and, for gif images, ppmquant and ppmtogif as well.
132 If you do not have these programs installed, Groff will print
133 an error message, and the produced file will have links which
134 will fail to resolve when you view it with a Web browser.
136 6. Some programs in the package are supplied as Unix shell
137 scripts. While it is relatively easy to write a DOS batch file
138 which will do the same, DOS doesn't allow to redirect input and
139 output of a batch file. Since Groff tools are meant to be
140 invoked in a pipe, the batch files are not very useful. The
141 batch files are included in the binary distribution
144 These scripts need the following utilities to run (in addition
145 to the Groff programs they invoke):
152 The `afmtodit' and `mmroff' utilities are Perl scripts, so you
153 will need a Perl port to run them.
155 All of these ports should be available from the DJGPP sites.
157 If you need to run these scripts and batch files, you have to
158 install the port of bash (or another Unix-like shell) and the
159 above-mentioned utilities called by the script. Alternatively,
160 just look inside the shell script and invoke the programs it
163 To run the scripts with redirection, invoke them via the shell,
164 like this: "sh mmroff > foo".
166 7. Note that Groff programs use floating point, so you will need
167 an FP emulator if your machine doesn't have an FPU. The binary
168 distribution includes the emulator, in case you don't have the
169 DJGPP development environment installed. Please refer to the
170 DJGPP FAQ list in case you have any problems with the emulator.
172 8. The package does not include the directories under
173 share/groff/<version>/font whose names begin with "devX": these
174 are needed on X-Windows for running the gxditview program, which
175 is not supported by this port.
177 9. Due to 8+3 limitations of DOS filesystems, several files were
180 - groff_mdoc.samples.7 was renamed to groff-mdoc_samples.7
181 and groff_mmse.7 to groff-mmse.7. The latter was also
182 converted from Latin-1 encoding to codepage 437.
186 II. Building Groff from sources
187 ---------------------------
189 1. To build Groff, you will need the following tools (the file
190 name in parentheses is what you need to download from one of
193 - Standard DJGPP development environment (djdev203.zip)
194 - GNU C compiler (gcc2721b.zip)
195 - GNU C++ compiler (gpp2721b.zip)
196 - GNU Make 3.79 (mak379b.zip)
197 - Bash v2.03 (bsh203b.zip)
198 - Fileutils 3.16 (fil316b.zip)
199 - Textutils 2.0 (txt20b.zip)
200 - Sh-utils 1.12 (shl112b.zip)
201 - Sed 3.02 (sed302b.zip)
202 - Gawk 3.04 (gwk304b.zip)
203 - Grep 2.4 (grep24b.zip)
204 - Bison (only if you change one of the *.y files)
206 Note that you don't need to install libg++ (lgpNNNb.zip) since
207 Groff doesn't use any C++ classes except its own.
209 Any versions of the utilities later than what's mentioned above
210 should also do; in particular, GCC 2.95.2 was tested and Groff
211 built okay with it. Versions older than in the above list
212 might also work, but I don't guarantee that; you are on your
215 Special considerations apply if you have GCC 2.8.1 installed,
216 and cannot upgrade to a later version. See paragraph 4 below.
218 After you install these tools, make sure you have a ``symlink''
219 to bash.exe called sh.exe and a ``symlink'' to gawk.exe called
220 awk.exe. If not, go to the DJGPP bin/ subdirectory and type
221 the following words of wisdom from the DOS prompt:
223 ln -s bash.exe sh.exe
224 ln -s gawk.exe awk.exe
226 (`ln' is part of GNU Fileutils, see above.)
228 2. Unzip the source distribution groXYZs.zip (where XYZ is the
229 version number) preserving the directory structure (-d switch
230 to PKUNZIP) from the main DJGPP installation directory. (If
231 you are building Groff on Windows 9X or Windows 2000, use an
232 unzip program which supports long filenames.) This creates
233 directory gnu/groff-X.YZ and unzips the sources there.
235 If you are building from the official GNU distribution, unpack
236 the .tar.gz archive like this:
238 djtar -x groff-X.YZ.tar.gz
240 (DJTAR is part of the standard DJGPP development distribution.)
242 3. Groff sources on DJGPP sites are already configured for the
243 current version of DJGPP. If that is the version you have,
244 then you can just chdir to gnu/groff-X.YZ and say "make" to
245 build the entire package (if you have GCC 2.8.1, see the next
248 If you have version of DJGPP other than the current one, or if
249 you build the official GNU distribution, or if you prefer to
250 configure the package so that it defaults to the directory
251 structure on your machine, or need to change some options
252 (e.g., compile with different optimization options), you will
253 have to reconfigure Groff. To this end, use the CONFIG.BAT
254 batch file in the DJGPP subdirectory:
258 You can configure and build Groff from outside its source
259 directory. In that case, you need to pass the full path to the
260 source directory as an argument to CONFIG.BAT, like this:
262 d:\gnu\groff-1.16\arch\djgpp\config d:/gnu/groff-1.16
264 Note that you MUST use forward slashes in the path you pass to
265 CONFIG.BAT, or else it may fail. (For versions of Groff other
266 than 1.16, change the above command accordingly.)
268 4. If your version of GCC is 2.8.1, you cannot build the
269 preconfigured package without some tinkering. The DJGPP port
270 of GCC 2.8.1 had a bug in its C++ configuration, whereby the
271 file _G_config.h erroneously indicated that the header
272 <sys/socket.h> is available, and also undefined the symbol
273 NULL. This causes several files in the Groff distribution to
276 The easiest way to solve this is to upgrade to a later version
277 of GCC; then you can simply say "make" to build the
278 preconfigured package. If this is not an option, you will have
279 to edit the file lang/cxx/_G_config.h and change this line:
281 #define _G_HAVE_SYS_SOCKET 1
285 #define _G_HAVE_SYS_SOCKET 0
287 The problem with redefining NULL should not happen with DJGPP
288 v2.03 or later. But if you still see compilation errors which
289 say "`NULL' undeclared", comment out the line in _G_config.h
294 Alternatively, you can reconfigure the package as described in
295 the previous paragraph, before building it.
297 5. After the configure script exits, say "make" to build Groff.
298 Groff is a large package, and it might take a few minutes to
299 build, depending on your CPU, so you might as well go for a
300 coffee while it grinds away.
302 6. Test the package that you have built. A batch file T-GROFF.BAT
303 in the DJGPP subdirectory is supplied for that purpose. Most
304 of the commands there are commented out, since I cannot
305 possibly know what kind of printer do you have and which
306 additional programs, such as Less, do you have installed. The
307 only command that runs by default will format a large document
308 and print it to the screen. Read the comments in the batch
309 file, uncomment additional lines as you see fit and run the
310 batch file to see that you get the document printed as you'd
311 expect. (Btw, the document that the batch file prints is an
312 introduction to the entire Groff package, so you might as well
313 read it to make yourself familiar with the programs.)
315 Note that the batch file sets a lot of environment variables;
316 if you get ``Out of environment space'' messages, launch a
317 subsidiary COMMAND.COM with plenty of environment space, like
322 then invoke T-GROFF.BAT from that COMMAND.COM.
324 7. Install the package by typing "make install". This will copy
325 all the binaries, the auxiliary files (fonts, macros, etc.) and
326 the docs into their places. If you configured the package for
327 your system, these are precisely the directories where the
328 files should remain (with the exception of the man pages, see
329 below). If you use the default configuration, the files will
330 be installed under the top DJGPP installation directory.
332 Alternatively, you could instruct Make explicitly where to
333 install the package by setting the `prefix' variable. For
336 make install prefix=c:/groff
338 "make install" doesn't format the man pages, it just copies
339 them into subdirectories of the %DJDIR%\MAN directory. If you
340 need to keep formatted pages in your man/ subdirectory, you
341 will need to format them. Use the commands shown in chapter I,
342 section 5 above to do that, and redirect its output to the
343 appropriate catN subdirectory. Alternatively, you could format
344 the pages when you need to view them (the DJGPP clone of `man'
345 will automatically format them).
347 Consult the installation instructions for pre-compiled binaries
348 above, for more info about installing and using Groff.
350 8. You can safely delete the directories under
351 share/groff/<version>/font whose names begin with "devX": these
352 are needed on X-Windows which is not supported by this port.