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.
5 ----------------------------------------------------------------------
7 * My document says that the current year is 19100, not 2000.
9 In groff, as in traditional troff, the yr number register yields the
10 year minus 1900. Unfortunately, there is a longstanding bug in the
11 Troff User's Manual <http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz>,
12 which incorrectly claims that yr is the last two digits of the year.
13 This claim was never true of either Unix troff or of groff.
15 If your text looks like this:
18 This document was formatted in 19\n(yr.
20 you can correct it as follows:
22 This document was formatted in \n[year].
24 or, if you want to be portable to older troff versions, as follows:
27 This document was formatted in \n(y4.
29 ----------------------------------------------------------------------
31 * I get lots of `numeric overflow' error messages whenever I run
32 groff; I compiled groff with AT&T C++ 2.0 with an ANSI C compiler.
34 Make sure -DCFRONT_ANSI_BUG is included in DEFINES in the top-level
35 Makefile. If that doesn't solve the problem, define INT_MIN as
36 -INT_MAX in libgroff/lib.h.
38 ----------------------------------------------------------------------
40 * I get errors when I try to compile groff with Sun C++ version 5.0
43 This is a known problem; see Sun bug #4301919. As of this writing, no
44 patch is available. Use GCC 2.95.2 or later instead.
46 ----------------------------------------------------------------------
48 * I get errors when I try to compile groff with Sun C++ version 3 or
51 Groff requires header files that are moderately compatible with AT&T
52 C++ and ANSI C. With some versions of Sun C++, the supplied header
53 files need some of the following changes to meet this requirement:
54 <string.h> must declare the mem* functions, (just add `#include
55 <memory.h>' to <string.h>); the first argument to fopen and freopen
56 should be declared as `const char *'; the first argument to fread
57 should be declared as `void *'; the first argument to fwrite should be
58 declared as `const void *'; malloc should be declared to return
59 `void *'; in <alloca.h>, the declaration `extern "C" { void
60 *__builtin_alloca(int); }' should be added; in <sys/signal.h> the
61 return type and the second argument type of signal() should be changed
62 to be `void (*)(int)'.
64 You can either change them in place, or copy them to some other
65 directory and include that directory with a -I option.
67 ----------------------------------------------------------------------
69 * The configure script fails on OS/390 Unix.
71 There is a bug in the Language Environment (LE) whereby the test
72 program for static destructors fails. You will see the message
73 'configure: error: a working C++ compiler is required'
75 Applying PTF UQ42006 is supposed to fix this, but the test program is
76 still returning the wrong value (1). To work around this problem, you
77 can comment out the following in the configure script (near line 956).
78 This will effectively bypass the test (static constructors and
79 destructors do actually work properly):
81 #if { (eval echo configure:957: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext} && (./conftest; exit) 2>/dev/null
83 echo "$ac_t""yes" 1>&6
85 # echo "configure: failed program was:" >&5
86 # cat conftest.$ac_ext >&5
88 # echo "$ac_t""no" 1>&6;{ echo "configure: error: a working C++ compiler is required" 1>&2; exit 1; }
91 ----------------------------------------------------------------------
93 * I get errors when I try to compile groff with DEC C++.
95 Fix the declaration of write() in <unistd.h> so that the second
96 argument is a const char *. Fix the declaration of open() in
97 <sys/file.h> so that the first argument is a const char *.
99 ----------------------------------------------------------------------
101 * On a host using Unix make (e.g. Solaris), if you are compiling for
102 multiple architectures by building in a subdirectory, the make stops
103 with a message like this:
105 make: Fatal error: Don't know how to make target `assert.o'
109 make: Fatal error: Can't find /u/src/groff/src/include/Makefile.sub': No such file or directory
111 This occurs because GNU make and Unix make handle VPATH differently,
112 and the groff build relies on GNU make's VPATH handling.
114 Use GNU make to work around the problem. In Solaris 8, GNU make is
115 on the Software Companion CD and is installed as /opt/sfw/bin/gmake.
117 ----------------------------------------------------------------------
119 * On Ultrix, the make stops with the message
125 for no apparent reason.
129 ----------------------------------------------------------------------
131 * I'm having problems compiling groff on 386BSD 0.1.
133 If you're using ash as /bin/sh, you'll need the following patch.
135 *** gendef.sh.org Sun Jun 30 13:30:36 1991
136 --- gendef.sh Sun Feb 28 10:23:49 1993
156 You'll also need to change dirnamemax.c so that it doesn't use
159 ----------------------------------------------------------------------
161 * While compiling on Xenix, ranlib libgroff.a fails.
163 The system ranlib can't handle externals longer than 40 characters.
164 Use the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1
167 ----------------------------------------------------------------------
169 * There are many empty `Makefile.dep' files. Is this a bug?
171 No. Real dependency files are created with a `make depend' call.
173 ----------------------------------------------------------------------
175 * Groff can't handle my troff document. It works fine with AT&T troff.
177 Read the section on incompatibilities in gtroff(1). Try using the -C
178 option. Alternatively there's the sed script `tmac/fixmacros.sed'
179 which will attempt to edit a file of macros so that it can be used
180 with groff without the -C flag.
182 ----------------------------------------------------------------------
184 * groff -Tdvi produces dvi files that use fonts at weird
187 Yes, it does. You may need to compile fonts with Metafont at these
188 magnifications. The CompileFonts script in the devdvi/generate
189 directory may help you to do this. (It will take a *long* time on
192 ----------------------------------------------------------------------
194 * pic output is not centered horizontally; pictures sometimes run off
195 the bottom of the page.
197 The macro package you are using is not supplying appropriate
198 definitions of PS and PE. Give groff a -mpic option.
200 ----------------------------------------------------------------------
202 * I'm having problems including PostScript illustrations using the
205 A PostScript document must meet three requirements in order to be
206 included with the PSPIC macro: it must comply with the Adobe Document
207 Structuring Conventions; it must contain a BoundingBox line; it must
208 be ``well-behaved''. The BoundingBox line should be of the form:
210 %%BoundingBox: llx lly urx ury
212 where llx, lly, urx, ury are the coordinates of the lower left x,
213 lower left y, upper right x, upper right y of the bounding box of
214 marks on the page expressed as integers in the default PostScript
215 coordinate system (72 units per inch, origin at bottom left corner).
216 A useful tactic is to print out the illustration by itself (you may
217 need to add a `showpage' at the end), and physically measure the
218 bounding box. For more detail on these requirements, read the
219 specification of Encapsulated PostScript format. (This is available
220 from the Adobe file server; send a message with a body of `help' to
221 ps-file-server@adobe.com.)
223 ----------------------------------------------------------------------
225 * I've configured groff for A4 paper, but gtroff still seems to think
226 that the length of a page (as returned by `\n(.p') is 11 inches.
228 This is intentional. The PAGE option is used only by grops. For
229 compatibility with ditroff, the default page length in gtroff is
230 always 11 inches. The page length can be changed with the `pl'
233 ----------------------------------------------------------------------
235 * groff produces wrapper macros for `ms' and friends which call the
236 system's original macros. Then, to get groff's ms macro package I
237 have to use `-mgs' instead `-ms'. Can I avoid this?
239 Yes. Configure and compile groff as usual, but install it with
241 make install tmac_wrap=""
243 Then no wrapper files are produced, and `-ms' will use groff's `ms'
246 ----------------------------------------------------------------------
248 * Groff doesn't use the font names I'm used to.
250 Use the `ftr' request. See (g)troff(1).
252 ----------------------------------------------------------------------
254 * I get errors using the Unix -ms macros with groff -e -C.
258 *** /usr/lib/ms/ms.eqn Tue Apr 25 02:14:28 1989
259 --- ms.eqn Sun Nov 11 10:33:59 1990
263 . \" EN - end of a displayed equation
265 ! .if !
\a\\*(10
\a\a .br
269 .if \\n(ZN>0 .if \\n(YE=0 .LP
272 . \" EN - end of a displayed equation
279 .if \\n(ZN>0 .if \\n(YE=0 .LP
281 ----------------------------------------------------------------------
283 * gpic doesn't accept the syntax `chop N M' for chopping both ends of
286 The correct syntax is `chop N chop M'.
288 ----------------------------------------------------------------------
290 * With gpic -t, when I print `line ->; box' using a dvi to ps program,
291 the arrow head sticks through into the inside of the box.
293 The dvi to ps program should be modified to set the line cap and line
294 join parameters to 1 while printing tpic specials.
296 ----------------------------------------------------------------------
298 * When I print the output groff -Tps, the output is always shifted up
299 by about 0.7 inches; I'm using 8.5x11 inch paper.
301 Make sure that PAGE is defined to be `letter' in the top-level
304 ----------------------------------------------------------------------
306 * When I try to print the output of groff -Tps, I get no output at all
307 from the printer, and the log file shows the error
308 %%[ error: undefined; offendingcommand: BP ]%%
309 I'm using TranScript spooling software.
311 This is a bug in the page reversal filter in early versions of
312 TranScript. Change the `broken' parameter in
313 /usr/local/lib/groff/font/devps/DESC to 7.
315 ----------------------------------------------------------------------
317 * When I preview groff -Tps output using the Sun OpenWindows 2.0
318 pageview program, all the pages are displayed on top of each other.
320 This is a defect in pageview. Change the `broken' parameter in
321 /usr/local/lib/groff/font/devps/DESC to 2.
323 ----------------------------------------------------------------------
325 * With groff -TX75, -TX100 or -X, I can only view the first page.
327 The left mouse button brings up a menu that allows you to view other
330 ----------------------------------------------------------------------
332 * When I print the output of groff -Tdvi, I just get a black dot in
335 Some dvi drivers (notably early versions of xtex) do not correctly
336 handle dvi files that use a resolution different from that used by dvi
337 files produced by TeX. Try getting a more up to date driver.
339 ----------------------------------------------------------------------
341 * I get lots of errors when I use groff with the AT&T -mm macros.
343 Use the groff -mm macros.
345 ----------------------------------------------------------------------
347 * gtroff doesn't understand lines like `.ce99' with no space between
348 the name of the request or macro and the arguments.
350 gtroff requires a space between macro or request and its arguments
351 because it allows the use of long names for macros and requests. You
352 can use the -C option or the `cp' request to put gtroff into a
353 compatibility mode in which it is not possible to use long names for
354 macros but in which no space is required between macros and their
355 arguments. The use of compatibility mode is strongly discouraged.
357 ----------------------------------------------------------------------
359 * gtroff gives warnings about lines like
361 (with a tab after the .ev).
363 A tab character cannot be used as a substitute for a space character
364 (except in one case: between a control character at the beginning of a
365 line and the name of a macro or request). For example, in Unix troff
367 .ps \" restore the previous point size
369 (with a tab after the .ps) will NOT restore the previous point-size;
370 instead it will be silently ignored. Since this is very likely to be
371 an error, gtroff can give a warning about it. If you want to align
372 comments, you can do it like this:
376 ----------------------------------------------------------------------
378 * I don't like the page headers and footers produced by groff -man.
380 There seem to be many different styles of page header and footer
381 produced by different versions of the -man macros. You will need to
382 modify tmac/an-old.tmac to suit your personal taste. For example, if
383 you want the center of the page header to say
385 System Programmer's Manual
387 you will need to change the line
389 .el .ds an-extra3 \"System Programmer's Manual
393 .el .ds an-extra3 System Programmer's Manual
395 ----------------------------------------------------------------------
397 * While formatting a manual page, groff complains about not being able
398 to break lines. The problem seems to be caused by a line like:
401 The -man documentation says that the default scale indicator for TP
402 macro is `n'. The groff -man macros implement this correctly, so that
403 the argument will be evaluated as if it were
407 The Unix -man macros don't implement this correctly (probably because
408 it's hard to do in Unix troff); they just append `n' to the entire
409 argument, so that it will be evaluated as if it were
413 The solution is to fix the manual page:
417 ----------------------------------------------------------------------
419 * I'm having problems formatting Ultrix man pages with groff -man.
421 The Ultrix man pages use a number of non-standard extensions to the
422 Unix man macros. One solution is to use the Ultrix -man macros with
423 groff. Copy /usr/lib/tmac/tmac.an to
424 /usr/local/share/groff/site-tmac/an.tmac and apply the following patch
425 (from Frank Wortner):
427 *** /usr/local/lib/groff/tmac/tmac.an Wed Sep 9 12:29:28 1992
428 --- /usr/lib/tmac/tmac.an Fri Jul 24 19:58:19 1992
431 . \" make special case of shift out of italic
434 ! .if \\$12 .if !\\$5 .ds ]F \^
435 .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
439 . \" make special case of shift out of italic
442 ! .if \\$12 .if !\\$5 .ds ]F\^
443 .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
447 Another possible solution is to install tmac/man.ultrix as
448 /usr/local/share/groff/site-tmac/man.local.
450 ----------------------------------------------------------------------
452 * I'm having problems formatting HP-UX 9.0 man pages with groff -man.
454 Copy HP's tmac.an into /usr/local/share/groff/site-tmac/an.tmac, and
455 either put `.cp 1' at the beginning or filter it (and any files it .so's)
456 through tmac/fixmacros.sed.
458 ----------------------------------------------------------------------
460 * On HP-UX, the compiler complains about missing symbol `alloca'.
466 before starting the configure script.
468 ----------------------------------------------------------------------
470 * I'm having problems formatting man pages produced by the perl
473 Some versions of wrapman have a superfluous blank line before the .TH
474 line. This must be deleted. Then either use groff -C, or apply the
477 *** wrapman.~2~ Sun Jan 19 12:10:24 1992
478 --- wrapman Tue Aug 10 02:06:41 1993
481 $line1 .= <IN> if $line1 =~ /eval/;
482 $line1 .= <IN> if $line1 =~ /argv/;
484 ! next if $line2 eq "'di';\n";
486 # Pull the old switcheroo.
489 $line1 .= <IN> if $line1 =~ /eval/;
490 $line1 .= <IN> if $line1 =~ /argv/;
492 ! next if $line2 eq "'di ';\n" || $line2 eq "'di';\n";
494 # Pull the old switcheroo.
520 # These next few lines are legal in both Perl and nroff.
522 ! $null.00; # finish .ig
524 'di \\" finish diversion--previous line must be blank
525 .nr nl 0-1 \\" fake up transition to first page again
526 .nr % 0 \\" start at page 1
527 ! '; __END__ ##### From here on it's a standard manual page #####
528 .TH $PROG 1 "$month $mday, 19$year"
535 # These next few lines are legal in both Perl and nroff.
537 ! $null.00 ; # finish .ig
540 'di \\" finish diversion--previous line must be blank
541 .nr nl 0-1 \\" fake up transition to first page again
542 .nr % 0 \\" start at page 1
543 ! .\\"'; __END__ ##### From here on it's a standard manual page #####
544 .TH $PROG 1 "$month $mday, 19$year"
550 ----------------------------------------------------------------------
552 * When I preview documents using -TX75 or -TX100, the layout is not
553 the same as when I print the document with -Tps: the line and page
554 breaks come in different places.
558 ----------------------------------------------------------------------
560 * When I try to run gxditview, I get the error:
561 Error: Widget viewport has zero width and/or height
563 This error means you haven't correctly installed the application
564 defaults file, GXditview.ad; ``make install'' does this for you
565 automatically, so either you didn't do ``make install'', or you don't
566 have imake configured correctly.
568 ----------------------------------------------------------------------
570 * groff uses up an enormous amount of memory processing large files.
571 I'm using 386BSD 0.1.
573 386BSD includes an old version of g++, 1.39, which has a bug that
574 causes a major memory leak in gtroff. Apply the following fix to g++
577 *** cplus-decl.c.~1~ Mon Aug 6 05:28:59 1990
578 --- cplus-decl.c Wed Jun 5 08:55:04 1991
582 /* At the end, call delete if that's what's requested. */
583 if (TREE_GETS_DELETE (current_class_type))
584 exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
585 get_identifier (OPERATOR_DELETE_FORMAT),
586 ! build_tree_list (NULL_TREE, integer_zero_node),
587 NULL_TREE, LOOKUP_NORMAL);
588 else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
589 exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
594 /* At the end, call delete if that's what's requested. */
595 if (TREE_GETS_DELETE (current_class_type))
596 exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
597 get_identifier (OPERATOR_DELETE_FORMAT),
598 ! build_tree_list (NULL_TREE, current_class_decl),
599 NULL_TREE, LOOKUP_NORMAL);
600 else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
601 exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
605 ----------------------------------------------------------------------
607 * Where can I get grap?
609 Ted Faber <faber@lunabase.org> has written a freely available grap:
611 http://www.lunabase.org/~faber/Vault/software/grap/
613 ----------------------------------------------------------------------
615 * How can I use groff with an old LaserJet printer that doesn't work
618 You have at least 3 options:
620 - use groff -Tps with GNU Ghostscript;
622 - use groff -Tdvi with a TeX .dvi to Laserjet driver;
624 - use groff with the LaserJet driver in Chris Lewis' psroff package
625 (available for ftp from:
626 ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17).
628 ----------------------------------------------------------------------
630 * Groff seems to generate level 3 Postscript, but my printer is only a
631 level 1 or 2 PostScript printer.
633 In fact groff generates only level 1 PostScript. The `%!PS-Adobe-3.0'
634 comment at the beginning of PostScript output generated by groff
635 indicates that the file conforms to version 3.0 of the Adobe Document
636 Structuring Conventions. The output generated by groff should be
637 printable on any PostScript printer. Problems with groff output's not
638 printing are most often caused by the spooling system.
640 ----------------------------------------------------------------------
642 * The \n(st and \n(sb registers don't seem to work. I thought \w set
643 them to the height and depth of its argument, but the registers
646 \n(st and \n(sb aren't supposed to give the height and depth of the
647 string rather they give the minimum and maximum vertical displacement
648 of the baseline. For example for \v'2u'\v'-3u', \n(st will be 1 and
649 \n(sb will be -2. The height and depth of the string is available in
650 the \n[rst] and \n[rsb] registers: these are groff extensions.
652 ----------------------------------------------------------------------
654 * On an SGI system, how can I make the man command use groff?
656 From David Hinds <dhinds@allegro.stanford.edu> (some of these steps
657 are unnecessary if you install with the `g' Makefile variable defined
660 Create a script called 'eqn':
663 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
666 and a script called 'neqn':
669 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
676 and edit the end of the gnroff script to be:
678 > rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
679 > exec groff -Wall -mtty-char $T $opts $rest
681 To get PostScript output from 'man -t', you also need to create a
682 'psroff' script similar to 'nroff'. Here are the context diffs:
684 *** /usr/local/bin/nroff Sat Feb 13 15:51:09 1993
685 --- /usr/local/bin/psroff Sat Feb 13 17:45:46 1993
689 ! # Emulate nroff with groff.
698 ! # Emulate psroff with groff.
712 + # ignore -- default is send to stdout
715 # ignore other devices
719 rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
721 # This shell script is intended for use with man, so warnings are
722 # probably not wanted. Also load nroff-style character definitions.
723 ! exec groff -Wall -mtty-char $T $opts $rest
725 rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
727 # This shell script is intended for use with man, so warnings are
728 ! # probably not wanted.
729 ! exec groff -Wall $T $opts $rest