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 ----------------------------------------------------------------------
14 * Displaying a man page on a terminal with/without my favourite pager
17 groff by default now uses SGR escape sequences (`ANSI color') to
18 control the display attributes (bold, underlined, colour) on TTYs.
19 Some terminals (e.g. `kterm') don't understand SGR, and some pagers
20 (e.g. older versions of `less' or `less' without the -R option) don't
21 understand SGR either. There are three solutions to fix this, in order
22 of preference; please read the grotty man page for more details.
24 The fourth and probably best option is to update your terminal program
25 and pager to versions which can handle SGR.
27 1. Set the GROFF_NO_SGR environment variable.
29 2. Pass option -c to grotty.
31 3. Append the following fragment to the `troffrc' file:
39 . \" The following code sets a top-of-page trap to disable grotty's TTY
40 . \" mode. Since neither \X nor .output can be used before the first
41 . \" page has started, we must use a trap. To make it work with troff's
42 . \" -o option, we wait until the first printed page.
49 . \" The stand-alone version. If no other trap is set, we can safely
50 . \" insert the truncated vertical space caused by the trap (if any).
51 . \" Otherwise we assume that the document's main macro package takes
52 . \" care of that. As soon as the trap has been executed, it is removed.
55 . if (\\n[.t] == \\n[.p]) \{\
67 . \" The piggyback version to be appended to macros planted with the
68 . \" modified
\x17h' request.
78 . \" We redefine the
\x17h' request so that
\x0eo@sgr1' is appended to
91 ----------------------------------------------------------------------
93 * My document says that the current year is 19100, not 2000.
95 In groff, as in traditional troff, the yr number register yields the
96 year minus 1900. Unfortunately, there is a longstanding bug in the
97 Troff User's Manual <http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz>,
98 which incorrectly claims that yr is the last two digits of the year.
99 This claim was never true of either Unix troff or of groff.
101 If your text looks like this:
104 This document was formatted in 19\n(yr.
106 you can correct it as follows:
108 This document was formatted in \n[year].
110 or, if you want to be portable to older troff versions, as follows:
113 This document was formatted in \n(y4.
115 ----------------------------------------------------------------------
117 * groff can't handle my troff document. It works fine with AT&T
120 Read the section on incompatibilities in groff_diff(7). Try using
121 the -C option. Alternatively there's the sed script
122 `tmac/fixmacros.sed' which will attempt to edit a file of macros so
123 that it can be used with groff without the -C flag.
125 ----------------------------------------------------------------------
127 * gtroff doesn't understand lines like `.ce99' with no space between
128 the name of the request or macro and the arguments.
130 gtroff requires a space between macro or request and its arguments
131 because it allows the use of long names for macros and requests. You
132 can use the -C option or the `cp' request to put gtroff into a
133 compatibility mode in which it is not possible to use long names for
134 macros but in which no space is required between macros and their
135 arguments. The use of compatibility mode is strongly discouraged.
137 ----------------------------------------------------------------------
139 * groff -Tdvi produces dvi files that use fonts at weird
142 Yes, it does. You may need to compile fonts with Metafont at these
143 magnifications. The CompileFonts script in the devdvi/generate
144 directory may help you to do this. (It will take a *long* time on
147 ----------------------------------------------------------------------
149 * Groff doesn't use the font names I'm used to.
151 Use the `ftr' request. See groff_diff(7).
153 ----------------------------------------------------------------------
155 * pic output is not centered horizontally; pictures sometimes run off
156 the bottom of the page.
158 The macro package you are using is not supplying appropriate
159 definitions of PS and PE. Give groff a -mpic option.
161 ----------------------------------------------------------------------
163 * gpic doesn't accept the syntax `chop N M' for chopping both ends of
166 The correct syntax is `chop N chop M'.
168 ----------------------------------------------------------------------
170 * With gpic -t, when I print `line ->; box' using a dvi to ps program,
171 the arrow head sticks through into the inside of the box.
173 The dvi to ps program should be modified to set the line cap and line
174 join parameters to 1 while printing tpic specials.
176 ----------------------------------------------------------------------
178 * gtroff gives warnings about lines like
180 (with a tab after the .ev).
182 A tab character cannot be used as a substitute for a space character
183 (except in one case: between a control character at the beginning of a
184 line and the name of a macro or request). For example, in Unix troff
186 .ps \" restore the previous point size
188 (with a tab after the .ps) will NOT restore the previous point-size;
189 instead it will be silently ignored. Since this is very likely to be
190 an error, gtroff can give a warning about it. If you want to align
191 comments, you can do it like this:
195 ----------------------------------------------------------------------
197 * I don't like the page headers and footers produced by groff -man.
199 There seem to be many different styles of page header and footer
200 produced by different versions of the -man macros. You will need to
201 put modified macros from tmac/an-old.tmac into man.local. More
202 information is available in groff_man(7).
204 ----------------------------------------------------------------------
206 * Where can I get grap?
208 Ted Faber <faber@lunabase.org> has written a freely available grap:
210 http://www.lunabase.org/~faber/Vault/software/grap/
212 ----------------------------------------------------------------------
214 * The \n(st and \n(sb registers don't seem to work. I thought \w set
215 them to the height and depth of its argument, but the registers
218 \n(st and \n(sb aren't supposed to give the height and depth of the
219 string rather they give the minimum and maximum vertical displacement
220 of the baseline. For example for \v'2u'\v'-3u', \n(st will be 1 and
221 \n(sb will be -2. The height and depth of the string is available in
222 the \n[rst] and \n[rsb] registers: these are groff extensions.
224 ----------------------------------------------------------------------
226 * While formatting a manual page, groff complains about not being able
227 to break lines. The problem seems to be caused by a line like:
230 The -man documentation says that the default scale indicator for TP
231 macro is `n'. The groff -man macros implement this correctly, so that
232 the argument will be evaluated as if it were
236 The Unix -man macros don't implement this correctly (probably because
237 it's hard to do in Unix troff); they just append `n' to the entire
238 argument, so that it will be evaluated as if it were
242 The solution is to fix the manual page:
246 ----------------------------------------------------------------------
248 * I'm having problems formatting man pages produced by the perl
251 Some versions of wrapman have a superfluous blank line before the .TH
252 line. This must be deleted. Then either use groff -C, or apply the
255 *** wrapman.~2~ Sun Jan 19 12:10:24 1992
256 --- wrapman Tue Aug 10 02:06:41 1993
259 $line1 .= <IN> if $line1 =~ /eval/;
260 $line1 .= <IN> if $line1 =~ /argv/;
262 ! next if $line2 eq "'di';\n";
264 # Pull the old switcheroo.
267 $line1 .= <IN> if $line1 =~ /eval/;
268 $line1 .= <IN> if $line1 =~ /argv/;
270 ! next if $line2 eq "'di ';\n" || $line2 eq "'di';\n";
272 # Pull the old switcheroo.
298 # These next few lines are legal in both Perl and nroff.
300 ! $null.00; # finish .ig
302 'di \\" finish diversion--previous line must be blank
303 .nr nl 0-1 \\" fake up transition to first page again
304 .nr % 0 \\" start at page 1
305 ! '; __END__ ##### From here on it's a standard manual page #####
306 .TH $PROG 1 "$month $mday, 19$year"
313 # These next few lines are legal in both Perl and nroff.
315 ! $null.00 ; # finish .ig
318 'di \\" finish diversion--previous line must be blank
319 .nr nl 0-1 \\" fake up transition to first page again
320 .nr % 0 \\" start at page 1
321 ! .\\"'; __END__ ##### From here on it's a standard manual page #####
322 .TH $PROG 1 "$month $mday, 19$year"
327 ----------------------------------------------------------------------
329 * groff uses up an enormous amount of memory processing large files.
330 I'm using 386BSD 0.1.
332 386BSD includes an old version of g++, 1.39, which has a bug that
333 causes a major memory leak in gtroff. Apply the following fix to g++
336 *** cplus-decl.c.~1~ Mon Aug 6 05:28:59 1990
337 --- cplus-decl.c Wed Jun 5 08:55:04 1991
341 /* At the end, call delete if that's what's requested. */
342 if (TREE_GETS_DELETE (current_class_type))
343 exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
344 get_identifier (OPERATOR_DELETE_FORMAT),
345 ! build_tree_list (NULL_TREE, integer_zero_node),
346 NULL_TREE, LOOKUP_NORMAL);
347 else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
348 exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
353 /* At the end, call delete if that's what's requested. */
354 if (TREE_GETS_DELETE (current_class_type))
355 exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
356 get_identifier (OPERATOR_DELETE_FORMAT),
357 ! build_tree_list (NULL_TREE, current_class_decl),
358 NULL_TREE, LOOKUP_NORMAL);
359 else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
360 exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
366 Printing and Display Problems
367 =============================
371 * I'm having problems including PostScript illustrations (EPS) using
372 the PSPIC macro and/or \X'ps: import ...'.
374 A PostScript document must meet three requirements in order to be
375 included with the PSPIC macro: it must comply with the Adobe Document
376 Structuring Conventions; it must contain a BoundingBox line; it must
377 be ``well-behaved''. The BoundingBox line should be of the form:
379 %%BoundingBox: llx lly urx ury
381 where llx, lly, urx, ury are the coordinates of the lower left x,
382 lower left y, upper right x, upper right y of the bounding box of
383 marks on the page expressed as integers in the default PostScript
384 coordinate system (72 units per inch, origin at bottom left corner).
386 The most convenient program to get the bounding box of a document is
387 the `ps2epsi' script coming with GhostScript.
389 If you can't use this program, another useful tactic is to print out
390 the illustration by itself (you may need to add a `showpage' at the
391 end), and physically measure the bounding box. For more detail on
392 these requirements, read the specification of Encapsulated PostScript
393 format. (This is available from the Adobe file server; send a message
394 with a body of `help' to ps-file-server@adobe.com.)
396 If an EPS file to be included via \X'ps: import' does not start with
397 %!PS-Adobe-...', gtroff will still include the file, but grops will
398 not add any fonts to the generated output file that are listed in the
399 EPS file, even though the files are listed in the `download' file and
400 are available in the devps directory.
402 ----------------------------------------------------------------------
404 * I've configured groff for A4 paper, but gtroff still seems to think
405 that the length of a page (as returned by `\n(.p') is 11 inches.
407 This is intentional. The PAGE option during configuration is used
408 only by grops. For compatibility with ditroff, the default page
409 length in gtroff is always 11 inches. The page length can be changed
410 with the `pl' request.
412 A convenient way to set paper dimensions is to use the -dpaper option
413 of groff, together with proper -P options for the postprocessor
414 (overriding the default). For example, use the following for PS
415 output on A4 paper in landscape orientation:
417 groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
419 See groff_tmac(5) for more information.
421 ----------------------------------------------------------------------
423 * When I print the output of groff -Tps, the output is always shifted
424 up by about 0.7 inches; I'm using 8.5x11 inch paper.
426 Make sure that the paper size is `letter'. See groff_tmac(5).
428 ----------------------------------------------------------------------
430 * When I try to run gxditview, I get the error:
431 Error: Widget viewport has zero width and/or height
433 This error means you haven't correctly installed the application
434 defaults file, GXditview.ad; ``make install'' does this for you
435 automatically, so either you didn't do ``make install'', or you don't
436 have imake configured correctly.
438 ----------------------------------------------------------------------
440 * When I preview documents using -TX75 or -TX100, the layout is not
441 the same as when I print the document with -Tps: the line and page
442 breaks come in different places.
446 ----------------------------------------------------------------------
448 * When I try to print the output of groff -Tps, I get no output at all
449 from the printer, and the log file shows the error
450 %%[ error: undefined; offendingcommand: BP ]%%
451 I'm using TranScript spooling software.
453 This is a bug in the page reversal filter in early versions of
454 TranScript. Change the `broken' parameter in
455 /usr/local/lib/groff/font/devps/DESC to 7.
457 ----------------------------------------------------------------------
459 * When I preview groff -Tps output using the Sun OpenWindows 2.0
460 pageview program, all the pages are displayed on top of each other.
462 This is a defect in pageview. Change the `broken' parameter in
463 /usr/local/lib/groff/font/devps/DESC to 2.
465 ----------------------------------------------------------------------
467 * With groff -TX75, -TX100 or -X, I can only view the first page.
469 The left mouse button brings up a menu that allows you to view other
472 ----------------------------------------------------------------------
474 * When I print the output of groff -Tdvi, I just get a black dot in
477 Some dvi drivers (notably early versions of xtex) do not correctly
478 handle dvi files that use a resolution different from that used by dvi
479 files produced by TeX. Try getting a more up to date driver.
481 ----------------------------------------------------------------------
483 * How can I use groff with an old LaserJet printer that doesn't work
486 You have at least 3 options:
488 - use groff -Tps with GNU Ghostscript;
490 - use groff -Tdvi with a TeX .dvi to Laserjet driver;
492 - use groff with the LaserJet driver in Chris Lewis' psroff package
493 (available for ftp from:
494 ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17).
496 ----------------------------------------------------------------------
498 * Groff seems to generate level 3 Postscript, but my printer is only a
499 level 1 or 2 PostScript printer.
501 In fact groff generates only level 2 PostScript (or rather level 1
502 with some extensions; see grops(1) for more information how to disable
503 them). The `%!PS-Adobe-3.0' comment at the beginning of PostScript
504 output generated by groff indicates that the file conforms to
505 version 3.0 of the Adobe Document Structuring Conventions. The output
506 generated by groff should be printable on any PostScript printer.
507 Problems with groff output's not printing are most often caused by the
512 Platform-Dependent Macro Problems
513 =================================
517 * I get lots of errors when I use groff with the AT&T -mm macros.
519 Use the groff -mm macros.
521 ----------------------------------------------------------------------
523 * groff produces wrapper macros for `ms' and friends which call the
524 system's original macros. Then, to get groff's ms macro package I
525 have to use `-mgs' instead `-ms'. Can I avoid this?
527 Yes. Configure and compile groff as usual, but install it with
529 make install tmac_wrap=""
531 Then no wrapper files are produced, and `-ms' will use groff's `ms'
534 ----------------------------------------------------------------------
536 * I'm having problems formatting HP-UX 9.0 man pages with groff -man.
538 Copy HP's tmac.an into /usr/local/share/groff/site-tmac/an.tmac, and
539 either put `.cp 1' at the beginning or filter it (and any files it
540 .so's) through tmac/fixmacros.sed.
542 ----------------------------------------------------------------------
544 * I get errors using the Unix -ms macros with groff -e -C.
548 *** /usr/lib/ms/ms.eqn Tue Apr 25 02:14:28 1989
549 --- ms.eqn Sun Nov 11 10:33:59 1990
553 . \" EN - end of a displayed equation
555 ! .if !
\a\\*(10
\a\a .br
559 .if \\n(ZN>0 .if \\n(YE=0 .LP
562 . \" EN - end of a displayed equation
569 .if \\n(ZN>0 .if \\n(YE=0 .LP
571 ----------------------------------------------------------------------
573 * I'm having problems formatting Ultrix man pages with groff -man.
575 The Ultrix man pages use a number of non-standard extensions to the
576 Unix man macros. One solution is to use the Ultrix -man macros with
577 groff. Copy /usr/lib/tmac/tmac.an to
578 /usr/local/share/groff/site-tmac/an.tmac and apply the following patch
579 (from Frank Wortner):
581 *** /usr/local/lib/groff/tmac/tmac.an Wed Sep 9 12:29:28 1992
582 --- /usr/lib/tmac/tmac.an Fri Jul 24 19:58:19 1992
585 . \" make special case of shift out of italic
588 ! .if \\$12 .if !\\$5 .ds ]F \^
589 .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
593 . \" make special case of shift out of italic
596 ! .if \\$12 .if !\\$5 .ds ]F\^
597 .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
601 Another possible solution is to install tmac/man.ultrix as
602 /usr/local/share/groff/site-tmac/man.local.
604 ----------------------------------------------------------------------
606 * On an SGI system, how can I make the man command use groff?
608 From David Hinds <dhinds@allegro.stanford.edu> (some of these steps
609 are unnecessary if you install with the `g' Makefile variable defined
612 Create a script called 'eqn':
615 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
618 and a script called 'neqn':
621 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
628 and edit the end of the gnroff script to be:
630 > rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
631 > exec groff -Wall -mtty-char $T $opts $rest
633 To get PostScript output from 'man -t', you also need to create a
634 'psroff' script similar to 'nroff'. Here are the context diffs:
636 *** /usr/local/bin/nroff Sat Feb 13 15:51:09 1993
637 --- /usr/local/bin/psroff Sat Feb 13 17:45:46 1993
641 ! # Emulate nroff with groff.
650 ! # Emulate psroff with groff.
664 + # ignore -- default is send to stdout
667 # ignore other devices
671 rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
673 # This shell script is intended for use with man, so warnings are
674 # probably not wanted. Also load nroff-style character definitions.
675 ! exec groff -Wall -mtty-char $T $opts $rest
677 rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
679 # This shell script is intended for use with man, so warnings are
680 ! # probably not wanted.
681 ! exec groff -Wall $T $opts $rest
690 * Compilation dies with
692 y.tab.c: In function `int yyparse()':
693 y.tab.c: `size_t' undeclared in namespace `std'
695 * bison reports conflicts (either on stderr or in the `pic.output'
696 file) while processing `pic.y', and the produced pic binary doesn't
699 You need bison version 1.875b or greater. Alternatively, use yacc or
702 ----------------------------------------------------------------------
704 * There are many empty `Makefile.dep' files. Is this a bug?
706 No. Real dependency files are created with a `make depend' call.
708 ----------------------------------------------------------------------
710 * On HP-UX, the compiler complains about missing symbol `alloca'.
716 before starting the configure script.
718 ----------------------------------------------------------------------
720 * The configure script fails on OS/390 (z/OS) Unix.
722 [This has been fixed in z/OS V1R3 (aka OS/390 R13).]
724 There is a bug in the Language Environment (LE) whereby the test
725 program for static destructors fails. You will see the message
726 `configure: error: a working C++ compiler is required'
728 Applying PTF UQ42006 is supposed to fix this, but the test program is
729 still returning the wrong value (1). To work around this problem, you
730 can comment out the following in the configure script (near line 2029).
731 This will effectively bypass the test (static constructors and
732 destructors do actually work properly):
734 #if { (eval echo "$as_me:2029: \"$ac_link\"") >&5
735 # (eval $ac_link) 2>&5
737 # echo "$as_me:2032: \$? = $ac_status" >&5
738 # (exit $ac_status); } && { ac_try='./conftest$ac_exeext'
739 # { (eval echo "$as_me:2034: \"$ac_try\"") >&5
740 # (eval $ac_try) 2>&5
742 # echo "$as_me:2037: \$? = $ac_status" >&5
743 # (exit $ac_status); }; }; then
744 # echo "$as_me:2039: result: yes" >&5
745 #echo "${ECHO_T}yes" >&6
747 # echo "$as_me: program exited with status $ac_status" >&5
748 #echo "$as_me: failed program was:" >&5
749 #cat conftest.$ac_ext >&5
750 #echo "$as_me:2045: result: no" >&5
751 #echo "${ECHO_T}no" >&6;{ { echo "$as_me:2046: error: a working C++ compiler is required" >&5
752 #echo "$as_me: error: a working C++ compiler is required" >&2;}
753 # { (exit 1); exit 1; }; }
756 ----------------------------------------------------------------------
758 * I get errors when I try to compile groff with DEC C++.
760 Fix the declaration of write() in <unistd.h> so that the second
761 argument is a const char *. Fix the declaration of open() in
762 <sys/file.h> so that the first argument is a const char *.
764 ----------------------------------------------------------------------
766 * On a host using Unix make (e.g. Solaris), if you are compiling for
767 multiple architectures by building in a subdirectory, the make stops
768 with a message like this:
770 make: Fatal error: Don't know how to make target `assert.o'
774 make: Fatal error: Can't find /u/src/groff/src/include/Makefile.sub': No such file or directory
776 This occurs because GNU make and Unix make handle VPATH differently,
777 and the groff build relies on GNU make's VPATH handling.
779 Use GNU make to work around the problem. In Solaris 8, GNU make is
780 on the Software Companion CD and is installed as /opt/sfw/bin/gmake.
782 ----------------------------------------------------------------------
784 * On Ultrix, the make stops with the message
790 for no apparent reason.
794 ----------------------------------------------------------------------
796 * I'm having problems compiling groff on 386BSD 0.1.
798 If you're using ash as /bin/sh, you'll need the following patch.
800 *** gendef.sh.org Sun Jun 30 13:30:36 1991
801 --- gendef.sh Sun Feb 28 10:23:49 1993
821 You'll also need to change dirnamemax.c so that it doesn't use
824 ----------------------------------------------------------------------
826 * While compiling on Xenix, ranlib libgroff.a fails.
828 The system ranlib can't handle externals longer than 40 characters.
829 Use the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1
832 ----------------------------------------------------------------------
834 * I get errors when I try to compile groff with Sun C++ version 3 or
837 Groff requires header files that are moderately compatible with AT&T
838 C++ and ANSI C. With some versions of Sun C++, the supplied header
839 files need some of the following changes to meet this requirement:
840 <string.h> must declare the mem* functions, (just add `#include
841 <memory.h>' to <string.h>); the first argument to fopen and freopen
842 should be declared as `const char *'; the first argument to fread
843 should be declared as `void *'; the first argument to fwrite should be
844 declared as `const void *'; malloc should be declared to return
845 `void *'; in <alloca.h>, the declaration `extern "C" { void
846 *__builtin_alloca(int); }' should be added; in <sys/signal.h> the
847 return type and the second argument type of signal() should be changed
848 to be `void (*)(int)'.
850 You can either change them in place, or copy them to some other
851 directory and include that directory with a -I option.
853 ----------------------------------------------------------------------
855 * I get errors when I try to compile groff with Sun C++ version 5.0
858 This is a known problem; see Sun bug #4301919. As of this writing, no
859 patch is available. Use GCC 2.95.2 or later instead.
861 ----------------------------------------------------------------------
863 * I get lots of `numeric overflow' error messages whenever I run
864 groff; I compiled groff with AT&T C++ 2.0 with an ANSI C compiler.
866 Make sure -DCFRONT_ANSI_BUG is included in DEFINES in the top-level
867 Makefile. If that doesn't solve the problem, define INT_MIN as
868 -INT_MAX in libgroff/lib.h.
870 ----------------------------------------------------------------------
872 * When compiling on MacOS X, groff compiles but does not run well,
873 especially `eqn', causing many `can't break line' messages.
875 Use ./configure CXX=g++2 then make as usual.