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