contrib/groff/PROBLEMS

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