PROBLEMS revision 18099
11573SrgrimesThis file describes various problems that have been encountered in
21573Srgrimescompiling, installing and running groff.  Suggestions for additions or
31573Srgrimesother improvements to this file are welcome.
41573Srgrimes
51573Srgrimes* I get lots of `numeric overflow' error messages whenever I run
61573Srgrimesgroff; I compiled groff with AT&T C++ 2.0 with an ANSI C compiler.
71573Srgrimes
81573SrgrimesMake sure -DCFRONT_ANSI_BUG is included in DEFINES in the top-level
91573SrgrimesMakefile.  If that doesn't solve the problem, define INT_MIN as
101573Srgrimes-INT_MAX in libgroff/lib.h.
111573Srgrimes
121573Srgrimes* I get errors when I try to compile groff with Sun C++ version 3 or
131573Srgrimesearlier.
141573Srgrimes
151573SrgrimesGroff requires header files that are moderately compatible with AT&T
161573SrgrimesC++ and ANSI C.  With some versions of Sun C++, the supplied header
171573Srgrimesfiles need some of the following changes to meet this requirement:
181573Srgrimes<string.h> must declare the mem* functions, (just add `#include
191573Srgrimes<memory.h>' to <string.h>); the first argument to fopen and freopen
201573Srgrimesshould be declared as `const char *'; the first argument to fread
211573Srgrimesshould be declared as `void *'; the first argument to fwrite should be
221573Srgrimesdeclared as `const void *'; malloc should be declared to return `void
231573Srgrimes*'; in <alloca.h>, the declaration `extern "C" { void
241573Srgrimes*__builtin_alloca(int); }' should be added; declarations of getopt(),
251573Srgrimesoptarg, optind and opterr should be added to <stdlib.h>; in
261573Srgrimes<sys/signal.h> the return type and the second argument type of
271573Srgrimessignal() should be changed to be `void (*)(int)'.
281573Srgrimes
291573SrgrimesYou can either change them in place, or copy them to some other
301573Srgrimesdirectory and include that directory with a -I option.
311573Srgrimes
321573Srgrimes* I get errors when I try to compile groff with DEC C++.
331573Srgrimes
341573SrgrimesFix the declaration of write() in <unistd.h> so that the second
351573Srgrimesargument is a const char *.  Fix the declaration of open() in
361573Srgrimes<sys/file.h> so that the first argument is a const char *.
371573Srgrimes
3862232Sdcs* On Ultrix, the make stops with the message
3962232Sdcs
401573Srgrimes  *** Error code 1
411573Srgrimes
421573Srgrimes  Stop.
431573Srgrimes
441573Srgrimesfor no apparent reason.
451573Srgrimes
461573SrgrimesUse GNU make.
471573Srgrimes
481573Srgrimes* I'm having problems compiling groff on 386BSD 0.1.
491573Srgrimes
501573SrgrimesIf you're using ash as /bin/sh, you'll need the following patch.
511573Srgrimes
521573Srgrimes*** gendef.sh.org	Sun Jun 30 13:30:36 1991
531573Srgrimes--- gendef.sh	Sun Feb 28 10:23:49 1993
541573Srgrimes***************
551573Srgrimes*** 3,9 ****
561573Srgrimes  file=$1
571573Srgrimes  shift
581573Srgrimes  
591573Srgrimes! defs="#define $1"
601573Srgrimes  shift
611573Srgrimes  for def
621573Srgrimes  do
631573Srgrimes--- 3,10 ----
641573Srgrimes  file=$1
651573Srgrimes  shift
661573Srgrimes  
671573Srgrimes! x=$1
681573Srgrimes! defs="#define $x"
691573Srgrimes  shift
701573Srgrimes  for def
711573Srgrimes  do
721573Srgrimes
731573SrgrimesYou'll also need to change dirnamemax.c so that it doesn't use
741573Srgrimespathconf().
751573Srgrimes
761573Srgrimes* While compiling on Xenix, ranlib libgroff.a fails.
771573Srgrimes
781573SrgrimesThe system ranlib can't handle externals longer than 40 characters.
791573SrgrimesUse the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1
801573Srgrimesinstead.
811573Srgrimes
8236043Sjb* Groff can't handle my troff document. It works fine with AT&T troff.
8336043Sjb
841573SrgrimesRead the section on incompatibilities in gtroff(1).  Try using the -C
851573Srgrimesoption.  Alternatively there's the sed script in tmac/fixmacros.sed
861573Srgrimeswhich will attempt to edit a file of macros so that it can be used
871573Srgrimeswith groff without the -C flag.
881573Srgrimes
891573Srgrimes* groff -Tdvi produces dvi files that use fonts at weird magnifications.
9036043Sjb
9136043SjbYes, it does.  You may need to compile fonts with Metafont at these
9236043Sjbmagnifications. The CompileFonts script in the devdvi/generate
9336043Sjbdirectory may help you to do this. (It will take a *long* time.)
9436043Sjb
9536043Sjb* pic output is not centered horizontally; pictures sometimes run off
9636043Sjbthe bottom of the page.
9736043Sjb
9836043SjbThe macro package you are using is not supplying appropriate definitions
9936043Sjbof PS and PE.  Give groff a -mpic option.
10036043Sjb
10136043Sjb* I'm having problems including PostScript illustrations using the PSPIC
10236043Sjbmacro.
10336043Sjb
10436043SjbA PostScript document must meet three requirements in order to be
10536043Sjbincluded with the PSPIC macro: it must comply with the Adobe Document
10636043SjbStructuring Conventions; it must contain a BoundingBox line; it must
10736043Sjbbe ``well-behaved''.  The BoundingBox line should be of the form:
10836043Sjb
10936043Sjb  %%BoundingBox: llx lly urx ury
1101573Srgrimes
1111573Srgrimeswhere llx, lly, urx, ury are the coordinates of the lower left x,
1121573Srgrimeslower left y, upper right x, upper right y of the bounding box of
1131573Srgrimesmarks on the page expressed as integers in the default PostScript
1141573Srgrimescoordinate system (72 units per inch, origin at bottom left corner).
1151573SrgrimesA useful tactic is to print out the illustration by itself (you may
1161573Srgrimesneed to add a `showpage' at the end), and physically measure the
1171573Srgrimesbounding box.  For more detail on these requirements, read the
1181573Srgrimesspecification of Encapsulated PostScript format.  (This is available
1191573Srgrimesfrom the Adobe file server; send a message with a body of `help' to
1201573Srgrimesps-file-server@adobe.com.)
1211573Srgrimes
1221573Srgrimes* I've configured groff for A4 paper, but gtroff still seems to think
1231573Srgrimesthat the length of a page (as returned by \n(.p) is 11 inches.
1241573Srgrimes
1251573SrgrimesThis is intentional.  The PAGE option is used only by grops.  For
12617508Sachecompatibility with ditroff, the default page length in gtroff is
1271573Srgrimesalways 11 inches.  The page length can be changed with the `pl'
1281573Srgrimesrequest.
1291573Srgrimes
1301573Srgrimes* Groff doesn't use the font names I'm used to.
13117508Sache
13217508SacheUse the `ftr' request.  See gtroff(1).
1331573Srgrimes
1341573Srgrimes* I get errors using the Unix -ms macros with groff -e -C.
1351573Srgrimes
1361573SrgrimesApply this change:
1371573Srgrimes
1381573Srgrimes*** /usr/lib/ms/ms.eqn	Tue Apr 25 02:14:28 1989
1391573Srgrimes--- ms.eqn	Sun Nov 11 10:33:59 1990
1401573Srgrimes***************
1411573Srgrimes*** 22,29 ****
1421573Srgrimes  ..
1431573Srgrimes  .	\" EN - end of a displayed equation
1441573Srgrimes  .de EN
1451573Srgrimes! .if !\\*(10 .br
1461573Srgrimes  .di
1471573Srgrimes  .rm EZ
1481573Srgrimes  .nr ZN \\n(dn
1491573Srgrimes  .if \\n(ZN>0 .if \\n(YE=0 .LP
1501573Srgrimes--- 22,30 ----
1511573Srgrimes  ..
1521573Srgrimes  .	\" EN - end of a displayed equation
1531573Srgrimes  .de EN
1541573Srgrimes! .if \\n(.k>0 .br
1551573Srgrimes  .di
1561573Srgrimes+ .ds 10 \\*(EZ\\
1571573Srgrimes  .rm EZ
1581573Srgrimes  .nr ZN \\n(dn
1591573Srgrimes  .if \\n(ZN>0 .if \\n(YE=0 .LP
1601573Srgrimes
1611573Srgrimes
1621573Srgrimes* gpic doesn't accept the syntax `chop N M' for chopping both ends of a
1631573Srgrimesline.
1641573Srgrimes
16562391SdcsThe correct syntax is `chop N chop M'.
16662232Sdcs
16762232Sdcs* With gpic -t, when I print `line ->; box' using a dvi to ps
1681573Srgrimesprogram, the arrow head sticks through into the inside of the box.
1691573Srgrimes
1701573SrgrimesThe dvi to ps program should be modified to set the line cap and
1711573Srgrimesline join parameters to 1 while printing tpic specials.
1721573Srgrimes
1731573Srgrimes* When I print the output groff -Tps, the output is always shifted up
1741573Srgrimesby about 0.7 inches; I'm using 8.5x11 inch paper.
1751573Srgrimes
1761573SrgrimesMake sure that PAGE is defined to be `letter' in the top-level
1771573SrgrimesMakefile.
17817508Sache
179* When I try to print the output of groff -Tps, I get no output at all
180from the printer, and the log file shows the error
181%%[ error: undefined; offendingcommand: BP ]%%
182I using TranScript spooling software.
183
184This is a bug in the page reversal filter in early versions of
185TranScript.  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
189program, all the pages are displayed on top of each other.
190
191This 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
196The left mouse button brings up a menu that allows you to view other
197pages.
198
199* When I print the output of groff -Tdvi, I just get a black dot in
200upper left corner.
201
202Some dvi drivers (notably early versions of xtex) do not correctly
203handle dvi files that use a resolution different from that used by dvi
204files 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
208The AT&T -mm macros need a few changes to work with groff; `make
209install.dwbmm' will copy your -mm macros to groff's macro directory
210and make the necessary changes.  You may need to edit the commands for
211the 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
215the name of the request or macro and the arguments.
216
217Gtroff requires a space between macro or request and its arguments
218because it allows the use of long names for macros and requests.  You
219can use the -C option or the `cp' request to put gtroff into a
220compatibility mode in which it is not possible to use long names for
221macros but in which no space is required between macros and their
222arguments.  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
228A 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
230line 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;
233instead it will be silently ignored.  Since this is very likely to be
234an error, gtroff can give a warning about it.  If you want to align
235comments, 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
240There seem to be many different styles of page header and footer
241produced by different versions of the -man macros.  You will need to
242modify macros/tmac.an to suit your personal taste.  For example, if
243you want the center of the page header to say
244  UNIX Programmer's Manual
245you will need to change the line
246  .el .ds an-extra3 \"UNIX Programmer's Manual
247to
248  .el .ds an-extra3 UNIX Programmer's Manual
249
250* While formatting a manual page, groff complains about not being able to
251break lines.  The problem seems to be caused by a line like:
252  .TP \w'label'+2
253
254The -man documentation says that the default scale indicator for TP
255macro is `n'.  The groff -man macros implement this correctly, so that
256the argument will be evaluated as if it were
257  \w'label'n+2n
258The Unix -man macros don't implement this correctly (probably because
259it's hard to do in Unix troff); they just append `n' to the entire
260argument, so that it will be evaluated as if it were
261  \w'label'u+2n
262The 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
267The Ultrix man pages use a number of non-standard extensions to the
268Unix man macros.  One solution is to use the Ultrix -man macros with
269groff.  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
272Frank 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
294Another 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
299Rename /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
302beginning or filter it (and any files it .so's) through
303tmac/fixmacros.sed.
304
305* I'm having problems formatting man pages produced by the perl
306wrapman script.
307
308Some versions of wrapman have a superfluous blank line before the .TH
309line.  This must be deleted.  Then either use groff -C, or apply the
310following 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
386as when I print the document with -Tps: the line and page breaks come
387in different places.
388
389Use groff -X -Tps.
390
391* When I try to run gxditview, I get the error:
392Error: Widget viewport has zero width and/or height
393
394This error means you haven't correctly installed the application
395defaults file, GXditview.ad; ``make install'' does this for you
396automatically, so either you didn't do ``make install'', or you don't
397have imake configured correctly.
398
399* groff uses up an enormous amount of memory processing large files.
400I'm using 386BSD 0.1.
401
402386BSD includes an old version of g++, 1.39, which has a bug that
403causes a major memory leak in gtroff.  Apply the following fix to g++
404and 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
436Grap is not freely available, but there is a nawk script implementing
437an extended subset of grap available for ftp as
438ftp.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
441with groff -Tlj4?
442
443You 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:
451ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17).
452
453* Groff seems to generate level 3 Postscript, but my printer is only a
454level 1 or 2 PostScript printer.
455
456In fact groff generates only level 1 PostScript.  The `%!PS-Adobe-3.0'
457comment at the beginning of PostScript output generated by groff
458indicates that the file conforms to version 3.0 of the Adobe Document
459Structuring Conventions.  The output generated by groff should be
460printable on any PostScript printer.  Problems with groff output's not
461printing 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
464them to the height and depth of its argument, but the registers always
465seem to be 0.
466
467\n(st and \n(sb aren't supposed to give the height and depth of the
468string rather they give the minimum and maximum vertical displacement
469of 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
471the \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
475From David Hinds <dhinds@allegro.stanford.edu> (some of these steps
476are unnecessary if you install with the `g' Makefile variable defined
477as empty):
478
479Create a script called 'eqn':
480
481 > #!/bin/sh
482 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
483 > geqn $*
484
485and a script called 'neqn':
486
487 > #!/bin/sh
488 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
489 > geqn -Tascii $*
490
491and do:
492
493 > ln -s gnroff nroff
494
495and 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
500To 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
549