PROBLEMS revision 55839
1This file describes various problems that have been encountered in 2compiling, installing and running groff. Suggestions for additions or 3other improvements to this file are welcome. 4 5* I get lots of `numeric overflow' error messages whenever I run 6groff; I compiled groff with AT&T C++ 2.0 with an ANSI C compiler. 7 8Make sure -DCFRONT_ANSI_BUG is included in DEFINES in the top-level 9Makefile. If that doesn't solve the problem, define INT_MIN as 10-INT_MAX in libgroff/lib.h. 11 12* I get errors when I try to compile groff with Sun C++ version 5.0 or 5.1. 13 14This is a known problem; see Sun bug #4301919. As of this writing, no 15patch is available. Use GCC 2.95.2 or later instead. 16 17* I get errors when I try to compile groff with Sun C++ version 3 or 18earlier. 19 20Groff requires header files that are moderately compatible with AT&T 21C++ and ANSI C. With some versions of Sun C++, the supplied header 22files need some of the following changes to meet this requirement: 23<string.h> must declare the mem* functions, (just add `#include 24<memory.h>' to <string.h>); the first argument to fopen and freopen 25should be declared as `const char *'; the first argument to fread 26should be declared as `void *'; the first argument to fwrite should be 27declared as `const void *'; malloc should be declared to return `void 28*'; in <alloca.h>, the declaration `extern "C" { void 29*__builtin_alloca(int); }' should be added; declarations of getopt(), 30optarg, optind and opterr should be added to <stdlib.h>; in 31<sys/signal.h> the return type and the second argument type of 32signal() should be changed to be `void (*)(int)'. 33 34You can either change them in place, or copy them to some other 35directory and include that directory with a -I option. 36 37* I get errors when I try to compile groff with DEC C++. 38 39Fix the declaration of write() in <unistd.h> so that the second 40argument is a const char *. Fix the declaration of open() in 41<sys/file.h> so that the first argument is a const char *. 42 43* On Ultrix, the make stops with the message 44 45 *** Error code 1 46 47 Stop. 48 49for no apparent reason. 50 51Use GNU make. 52 53* I'm having problems compiling groff on 386BSD 0.1. 54 55If you're using ash as /bin/sh, you'll need the following patch. 56 57*** gendef.sh.org Sun Jun 30 13:30:36 1991 58--- gendef.sh Sun Feb 28 10:23:49 1993 59*************** 60*** 3,9 **** 61 file=$1 62 shift 63 64! defs="#define $1" 65 shift 66 for def 67 do 68--- 3,10 ---- 69 file=$1 70 shift 71 72! x=$1 73! defs="#define $x" 74 shift 75 for def 76 do 77 78You'll also need to change dirnamemax.c so that it doesn't use 79pathconf(). 80 81* While compiling on Xenix, ranlib libgroff.a fails. 82 83The system ranlib can't handle externals longer than 40 characters. 84Use the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1 85instead. 86 87* Groff can't handle my troff document. It works fine with AT&T troff. 88 89Read the section on incompatibilities in gtroff(1). Try using the -C 90option. Alternatively there's the sed script in tmac/fixmacros.sed 91which will attempt to edit a file of macros so that it can be used 92with groff without the -C flag. 93 94* groff -Tdvi produces dvi files that use fonts at weird magnifications. 95 96Yes, it does. You may need to compile fonts with Metafont at these 97magnifications. The CompileFonts script in the devdvi/generate 98directory may help you to do this. (It will take a *long* time.) 99 100* pic output is not centered horizontally; pictures sometimes run off 101the bottom of the page. 102 103The macro package you are using is not supplying appropriate definitions 104of PS and PE. Give groff a -mpic option. 105 106* I'm having problems including PostScript illustrations using the PSPIC 107macro. 108 109A PostScript document must meet three requirements in order to be 110included with the PSPIC macro: it must comply with the Adobe Document 111Structuring Conventions; it must contain a BoundingBox line; it must 112be ``well-behaved''. The BoundingBox line should be of the form: 113 114 %%BoundingBox: llx lly urx ury 115 116where llx, lly, urx, ury are the coordinates of the lower left x, 117lower left y, upper right x, upper right y of the bounding box of 118marks on the page expressed as integers in the default PostScript 119coordinate system (72 units per inch, origin at bottom left corner). 120A useful tactic is to print out the illustration by itself (you may 121need to add a `showpage' at the end), and physically measure the 122bounding box. For more detail on these requirements, read the 123specification of Encapsulated PostScript format. (This is available 124from the Adobe file server; send a message with a body of `help' to 125ps-file-server@adobe.com.) 126 127* I've configured groff for A4 paper, but gtroff still seems to think 128that the length of a page (as returned by \n(.p) is 11 inches. 129 130This is intentional. The PAGE option is used only by grops. For 131compatibility with ditroff, the default page length in gtroff is 132always 11 inches. The page length can be changed with the `pl' 133request. 134 135* Groff doesn't use the font names I'm used to. 136 137Use the `ftr' request. See gtroff(1). 138 139* I get errors using the Unix -ms macros with groff -e -C. 140 141Apply this change: 142 143*** /usr/lib/ms/ms.eqn Tue Apr 25 02:14:28 1989 144--- ms.eqn Sun Nov 11 10:33:59 1990 145*************** 146*** 22,29 **** 147 .. 148 . \" EN - end of a displayed equation 149 .de EN 150! .if !\\*(10 .br 151 .di 152 .rm EZ 153 .nr ZN \\n(dn 154 .if \\n(ZN>0 .if \\n(YE=0 .LP 155--- 22,30 ---- 156 .. 157 . \" EN - end of a displayed equation 158 .de EN 159! .if \\n(.k>0 .br 160 .di 161+ .ds 10 \\*(EZ\\ 162 .rm EZ 163 .nr ZN \\n(dn 164 .if \\n(ZN>0 .if \\n(YE=0 .LP 165 166 167* gpic doesn't accept the syntax `chop N M' for chopping both ends of a 168line. 169 170The correct syntax is `chop N chop M'. 171 172* With gpic -t, when I print `line ->; box' using a dvi to ps 173program, the arrow head sticks through into the inside of the box. 174 175The dvi to ps program should be modified to set the line cap and 176line join parameters to 1 while printing tpic specials. 177 178* When I print the output groff -Tps, the output is always shifted up 179by about 0.7 inches; I'm using 8.5x11 inch paper. 180 181Make sure that PAGE is defined to be `letter' in the top-level 182Makefile. 183 184* When I try to print the output of groff -Tps, I get no output at all 185from the printer, and the log file shows the error 186%%[ error: undefined; offendingcommand: BP ]%% 187I'm using TranScript spooling software. 188 189This is a bug in the page reversal filter in early versions of 190TranScript. Change the `broken' parameter in 191/usr/local/lib/groff/font/devps/DESC to 7. 192 193* When I preview groff -Tps output using the Sun OpenWindows 2.0 pageview 194program, all the pages are displayed on top of each other. 195 196This is a defect in pageview. Change the `broken' parameter in 197/usr/local/lib/groff/font/devps/DESC to 2. 198 199* With groff -TX75, -TX100 or -X, I can only view the first page. 200 201The left mouse button brings up a menu that allows you to view other 202pages. 203 204* When I print the output of groff -Tdvi, I just get a black dot in 205upper left corner. 206 207Some dvi drivers (notably early versions of xtex) do not correctly 208handle dvi files that use a resolution different from that used by dvi 209files produced by TeX. Try getting a more up to date driver. 210 211* I get lots of errors when I use groff with the AT&T -mm macros. 212 213The AT&T -mm macros need a few changes to work with groff; `make 214install.dwbmm' will copy your -mm macros to groff's macro directory 215and make the necessary changes. You may need to edit the commands for 216the install.mm target in the Makefile. Alternatively use the groff 217-mm macros. 218 219* gtroff doesn't understand lines like `.ce99' with no space between 220the name of the request or macro and the arguments. 221 222Gtroff requires a space between macro or request and its arguments 223because it allows the use of long names for macros and requests. You 224can use the -C option or the `cp' request to put gtroff into a 225compatibility mode in which it is not possible to use long names for 226macros but in which no space is required between macros and their 227arguments. The use of compatibility mode is strongly discouraged. 228 229* gtroff gives warnings about lines like 230 .ev \" a comment 231(with a tab after the .ev). 232 233A tab character cannot be used as a substitute for a space character 234(except in one case: between a control character at the beginning of a 235line and the name of a macro or request). For example, in Unix troff 236 .ps \" restore the previous point size 237(with a tab after the .ps) will NOT restore the previous point-size; 238instead it will be silently ignored. Since this is very likely to be 239an error, gtroff can give a warning about it. If you want to align 240comments, you can do it like this: 241 .ev\" \" a comment 242 243* I don't like the page headers and footers produced by groff -man. 244 245There seem to be many different styles of page header and footer 246produced by different versions of the -man macros. You will need to 247modify macros/tmac.an to suit your personal taste. For example, if 248you want the center of the page header to say 249 System Programmer's Manual 250you will need to change the line 251 .el .ds an-extra3 \"System Programmer's Manual 252to 253 .el .ds an-extra3 System Programmer's Manual 254 255* While formatting a manual page, groff complains about not being able to 256break lines. The problem seems to be caused by a line like: 257 .TP \w'label'+2 258 259The -man documentation says that the default scale indicator for TP 260macro is `n'. The groff -man macros implement this correctly, so that 261the argument will be evaluated as if it were 262 \w'label'n+2n 263The Unix -man macros don't implement this correctly (probably because 264it's hard to do in Unix troff); they just append `n' to the entire 265argument, so that it will be evaluated as if it were 266 \w'label'u+2n 267The solution is to fix the manual page: 268 .TP \w'label'u+2 269 270* I'm having problems formatting Ultrix man pages with groff -man. 271 272The Ultrix man pages use a number of non-standard extensions to the 273Unix man macros. One solution is to use the Ultrix -man macros with 274groff. Rename /usr/local/lib/groff/tmac/tmac.an to 275/usr/local/lib/groff/tmac/tmac.an.gnu, copy /usr/lib/tmac/tmac.an to 276/usr/local/lib/groff/tmac/tmac.an and apply the following patch (from 277Frank Wortner): 278 279*** /usr/local/lib/groff/tmac/tmac.an Wed Sep 9 12:29:28 1992 280--- /usr/lib/tmac/tmac.an Fri Jul 24 19:58:19 1992 281*************** 282*** 489,495 **** 283 . \" make special case of shift out of italic 284 .de }S 285 .ds ]F 286! .if \\$12 .if !\\$5 .ds ]F \^ 287 .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9" 288 .el \\$3 289 .}f 290--- 489,495 ---- 291 . \" make special case of shift out of italic 292 .de }S 293 .ds ]F 294! .if \\$12 .if !\\$5 .ds ]F\^ 295 .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9" 296 .el \\$3 297 .}f 298 299Another possible solution is to install tmac/man.ultrix as 300/usr/local/lib/groff/tmac/man.local. 301 302* I'm having problems formatting HP-UX 9.0 man pages with groff -man. 303 304Rename /usr/local/lib/groff/tmac/tmac.an to (for example) 305/usr/local/lib/groff/tmac/tmac.gan, copy HP's tmac.an into 306/usr/local/lib/groff/tmac/tmac.an, and either put `.cp 1' at the 307beginning or filter it (and any files it .so's) through 308tmac/fixmacros.sed. 309 310* I'm having problems formatting man pages produced by the perl 311wrapman script. 312 313Some versions of wrapman have a superfluous blank line before the .TH 314line. This must be deleted. Then either use groff -C, or apply the 315following patch: 316 317*** wrapman.~2~ Sun Jan 19 12:10:24 1992 318--- wrapman Tue Aug 10 02:06:41 1993 319*************** 320*** 35,41 **** 321 $line1 .= <IN> if $line1 =~ /eval/; 322 $line1 .= <IN> if $line1 =~ /argv/; 323 $line2 = <IN>; 324! next if $line2 eq "'di';\n"; 325 326 # Pull the old switcheroo. 327 328--- 35,41 ---- 329 $line1 .= <IN> if $line1 =~ /eval/; 330 $line1 .= <IN> if $line1 =~ /argv/; 331 $line2 = <IN>; 332! next if $line2 eq "'di ';\n" || $line2 eq "'di';\n"; 333 334 # Pull the old switcheroo. 335 336*************** 337*** 49,56 **** 338 339 print OUT $line1; 340 print OUT <<EOF; 341! 'di'; 342! 'ig00'; 343 # 344 # $header 345 # 346--- 49,58 ---- 347 348 print OUT $line1; 349 print OUT <<EOF; 350! 'di '; 351! 'ds 00 \\"'; 352! 'eo '; 353! 'ig 00 '; 354 # 355 # $header 356 # 357*************** 358*** 72,85 **** 359 360 # These next few lines are legal in both Perl and nroff. 361 362! $null.00; # finish .ig 363 364 'di \\" finish diversion--previous line must be blank 365 .nr nl 0-1 \\" fake up transition to first page again 366 .nr % 0 \\" start at page 1 367! '; __END__ ##### From here on it's a standard manual page ##### 368 .TH $PROG 1 "$month $mday, 19$year" 369- .AT 3 370 .SH NAME 371 $prog \\- whatever 372 .SH SYNOPSIS 373--- 74,87 ---- 374 375 # These next few lines are legal in both Perl and nroff. 376 377! $null.00 ; # finish .ig 378! 'ec \\'; 379 380 'di \\" finish diversion--previous line must be blank 381 .nr nl 0-1 \\" fake up transition to first page again 382 .nr % 0 \\" start at page 1 383! .\\"'; __END__ ##### From here on it's a standard manual page ##### 384 .TH $PROG 1 "$month $mday, 19$year" 385 .SH NAME 386 $prog \\- whatever 387 .SH SYNOPSIS 388 389 390* When I preview documents using -TX75 or -TX100, the layout is not the same 391as when I print the document with -Tps: the line and page breaks come 392in different places. 393 394Use groff -X -Tps. 395 396* When I try to run gxditview, I get the error: 397Error: Widget viewport has zero width and/or height 398 399This error means you haven't correctly installed the application 400defaults file, GXditview.ad; ``make install'' does this for you 401automatically, so either you didn't do ``make install'', or you don't 402have imake configured correctly. 403 404* groff uses up an enormous amount of memory processing large files. 405I'm using 386BSD 0.1. 406 407386BSD includes an old version of g++, 1.39, which has a bug that 408causes a major memory leak in gtroff. Apply the following fix to g++ 409and recompile groff: 410 411*** cplus-decl.c.~1~ Mon Aug 6 05:28:59 1990 412--- cplus-decl.c Wed Jun 5 08:55:04 1991 413*************** 414*** 7951,7961 **** 415 416 /* At the end, call delete if that's what's requested. */ 417 if (TREE_GETS_DELETE (current_class_type)) 418 exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node), 419 get_identifier (OPERATOR_DELETE_FORMAT), 420! build_tree_list (NULL_TREE, integer_zero_node), 421 NULL_TREE, LOOKUP_NORMAL); 422 else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type)) 423 exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0); 424 else 425 exprstmt = 0; 426--- 7951,7961 ---- 427 428 /* At the end, call delete if that's what's requested. */ 429 if (TREE_GETS_DELETE (current_class_type)) 430 exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node), 431 get_identifier (OPERATOR_DELETE_FORMAT), 432! build_tree_list (NULL_TREE, current_class_decl), 433 NULL_TREE, LOOKUP_NORMAL); 434 else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type)) 435 exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0); 436 else 437 exprstmt = 0; 438 439* Where can I get grap? 440 441Grap is not freely available, but there is a nawk script implementing 442an extended subset of grap available for ftp as 443ftp.informatik.uni-rostock.de:/pub/local/software/prag-1.0.shar.gz. 444 445* How can I use groff with an old LaserJet printer that doesn't work 446with groff -Tlj4? 447 448You have at least 3 options: 449 450- use groff -Tps with GNU Ghostscript; 451 452- use groff -Tdvi with a TeX .dvi to Laserjet driver; 453 454- use groff with the LaserJet driver in Chris Lewis' psroff package 455(available for ftp from: 456ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17). 457 458* Groff seems to generate level 3 Postscript, but my printer is only a 459level 1 or 2 PostScript printer. 460 461In fact groff generates only level 1 PostScript. The `%!PS-Adobe-3.0' 462comment at the beginning of PostScript output generated by groff 463indicates that the file conforms to version 3.0 of the Adobe Document 464Structuring Conventions. The output generated by groff should be 465printable on any PostScript printer. Problems with groff output's not 466printing are most often caused by the spooling system. 467 468* The \n(st and \n(sb registers don't seem to work. I thought \w set 469them to the height and depth of its argument, but the registers always 470seem to be 0. 471 472\n(st and \n(sb aren't supposed to give the height and depth of the 473string rather they give the minimum and maximum vertical displacement 474of the baseline. For example for \v'2u'\v'-3u', \n(st will be 1 and 475\n(sb will be -2. The height and depth of the string is available in 476the \n[rst] and \n[rsb] registers: these are groff extensions. 477 478* On an SGI system, how can I make the man command use groff? 479 480From David Hinds <dhinds@allegro.stanford.edu> (some of these steps 481are unnecessary if you install with the `g' Makefile variable defined 482as empty): 483 484Create a script called 'eqn': 485 486 > #!/bin/sh 487 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi 488 > geqn $* 489 490and a script called 'neqn': 491 492 > #!/bin/sh 493 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi 494 > geqn -Tascii $* 495 496and do: 497 498 > ln -s gnroff nroff 499 500and edit the end of the gnroff script to be: 501 502 > rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'` 503 > exec groff -Wall -mtty-char $T $opts $rest 504 505To get PostScript output from 'man -t', you also need to create a 506'psroff' script similar to 'nroff'. Here are the context diffs: 507 508*** /usr/local/bin/nroff Sat Feb 13 15:51:09 1993 509--- /usr/local/bin/psroff Sat Feb 13 17:45:46 1993 510*************** 511*** 1,8 **** 512 #!/bin/sh 513! # Emulate nroff with groff. 514 515 prog="$0" 516! T=-Tascii 517 opts= 518 519 for i 520--- 1,8 ---- 521 #!/bin/sh 522! # Emulate psroff with groff. 523 524 prog="$0" 525! T=-Tps 526 opts= 527 528 for i 529*************** 530*** 25,30 **** 531--- 25,33 ---- 532 -Tascii|-Tlatin1) 533 T=$1 534 ;; 535+ -t) 536+ # ignore -- default is send to stdout 537+ ;; 538 -T*) 539 # ignore other devices 540 ;; 541*************** 542*** 49,53 **** 543 rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'` 544 545 # This shell script is intended for use with man, so warnings are 546 # probably not wanted. Also load nroff-style character definitions. 547! exec groff -Wall -mtty-char $T $opts $rest 548--- 52,56 ---- 549 rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'` 550 551 # This shell script is intended for use with man, so warnings are 552! # probably not wanted. 553! exec groff -Wall $T $opts $rest 554