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 * My document says that the current year is 19100, not 2000.
7 In groff, as in traditional troff, the yr number register yields the
8 year minus 1900. Unfortunately, there is a longstanding bug in the
9 Troff User's Manual <http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz>,
10 which incorrectly claims that yr is the last two digits of the year.
11 This claim was never true of either Unix troff or of groff.
13 If your text looks like this:
16 This document was formatted in 19\n(yr.
18 you can correct it as follows:
20 This document was formatted in \n[year].
22 or, if you want to be portable to older troff versions, as follows:
25 This document was formatted in \n(y4.
27 * I get lots of `numeric overflow' error messages whenever I run
28 groff; I compiled groff with AT&T C++ 2.0 with an ANSI C compiler.
30 Make sure -DCFRONT_ANSI_BUG is included in DEFINES in the top-level
31 Makefile. If that doesn't solve the problem, define INT_MIN as
32 -INT_MAX in libgroff/lib.h.
34 * I get errors when I try to compile groff with Sun C++ version 5.0 or 5.1.
36 This is a known problem; see Sun bug #4301919. As of this writing, no
37 patch is available. Use GCC 2.95.2 or later instead.
39 * I get errors when I try to compile groff with Sun C++ version 3 or
42 Groff requires header files that are moderately compatible with AT&T
43 C++ and ANSI C. With some versions of Sun C++, the supplied header
44 files need some of the following changes to meet this requirement:
45 <string.h> must declare the mem* functions, (just add `#include
46 <memory.h>' to <string.h>); the first argument to fopen and freopen
47 should be declared as `const char *'; the first argument to fread
48 should be declared as `void *'; the first argument to fwrite should be
49 declared as `const void *'; malloc should be declared to return `void
50 *'; in <alloca.h>, the declaration `extern "C" { void
51 *__builtin_alloca(int); }' should be added; in <sys/signal.h> the
52 return type and the second argument type of signal() should be
53 changed to be `void (*)(int)'.
55 You can either change them in place, or copy them to some other
56 directory and include that directory with a -I option.
58 * I get errors when I try to compile groff with DEC C++.
60 Fix the declaration of write() in <unistd.h> so that the second
61 argument is a const char *. Fix the declaration of open() in
62 <sys/file.h> so that the first argument is a const char *.
64 * On Ultrix, the make stops with the message
70 for no apparent reason.
74 * I'm having problems compiling groff on 386BSD 0.1.
76 If you're using ash as /bin/sh, you'll need the following patch.
78 *** gendef.sh.org Sun Jun 30 13:30:36 1991
79 --- gendef.sh Sun Feb 28 10:23:49 1993
99 You'll also need to change dirnamemax.c so that it doesn't use
102 * While compiling on Xenix, ranlib libgroff.a fails.
104 The system ranlib can't handle externals longer than 40 characters.
105 Use the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1
108 * Groff can't handle my troff document. It works fine with AT&T troff.
110 Read the section on incompatibilities in gtroff(1). Try using the -C
111 option. Alternatively there's the sed script in tmac/fixmacros.sed
112 which will attempt to edit a file of macros so that it can be used
113 with groff without the -C flag.
115 * groff -Tdvi produces dvi files that use fonts at weird magnifications.
117 Yes, it does. You may need to compile fonts with Metafont at these
118 magnifications. The CompileFonts script in the devdvi/generate
119 directory may help you to do this. (It will take a *long* time.)
121 * pic output is not centered horizontally; pictures sometimes run off
122 the bottom of the page.
124 The macro package you are using is not supplying appropriate definitions
125 of PS and PE. Give groff a -mpic option.
127 * I'm having problems including PostScript illustrations using the PSPIC
130 A PostScript document must meet three requirements in order to be
131 included with the PSPIC macro: it must comply with the Adobe Document
132 Structuring Conventions; it must contain a BoundingBox line; it must
133 be ``well-behaved''. The BoundingBox line should be of the form:
135 %%BoundingBox: llx lly urx ury
137 where llx, lly, urx, ury are the coordinates of the lower left x,
138 lower left y, upper right x, upper right y of the bounding box of
139 marks on the page expressed as integers in the default PostScript
140 coordinate system (72 units per inch, origin at bottom left corner).
141 A useful tactic is to print out the illustration by itself (you may
142 need to add a `showpage' at the end), and physically measure the
143 bounding box. For more detail on these requirements, read the
144 specification of Encapsulated PostScript format. (This is available
145 from the Adobe file server; send a message with a body of `help' to
146 ps-file-server@adobe.com.)
148 * I've configured groff for A4 paper, but gtroff still seems to think
149 that the length of a page (as returned by \n(.p) is 11 inches.
151 This is intentional. The PAGE option is used only by grops. For
152 compatibility with ditroff, the default page length in gtroff is
153 always 11 inches. The page length can be changed with the `pl'
156 * Groff doesn't use the font names I'm used to.
158 Use the `ftr' request. See gtroff(1).
160 * I get errors using the Unix -ms macros with groff -e -C.
164 *** /usr/lib/ms/ms.eqn Tue Apr 25 02:14:28 1989
165 --- ms.eqn Sun Nov 11 10:33:59 1990
169 . \" EN - end of a displayed equation
171 ! .if !
\a\\*(10
\a\a .br
175 .if \\n(ZN>0 .if \\n(YE=0 .LP
178 . \" EN - end of a displayed equation
185 .if \\n(ZN>0 .if \\n(YE=0 .LP
188 * gpic doesn't accept the syntax `chop N M' for chopping both ends of a
191 The correct syntax is `chop N chop M'.
193 * With gpic -t, when I print `line ->; box' using a dvi to ps
194 program, the arrow head sticks through into the inside of the box.
196 The dvi to ps program should be modified to set the line cap and
197 line join parameters to 1 while printing tpic specials.
199 * When I print the output groff -Tps, the output is always shifted up
200 by about 0.7 inches; I'm using 8.5x11 inch paper.
202 Make sure that PAGE is defined to be `letter' in the top-level
205 * When I try to print the output of groff -Tps, I get no output at all
206 from the printer, and the log file shows the error
207 %%[ error: undefined; offendingcommand: BP ]%%
208 I'm using TranScript spooling software.
210 This is a bug in the page reversal filter in early versions of
211 TranScript. Change the `broken' parameter in
212 /usr/local/lib/groff/font/devps/DESC to 7.
214 * When I preview groff -Tps output using the Sun OpenWindows 2.0 pageview
215 program, all the pages are displayed on top of each other.
217 This is a defect in pageview. Change the `broken' parameter in
218 /usr/local/lib/groff/font/devps/DESC to 2.
220 * With groff -TX75, -TX100 or -X, I can only view the first page.
222 The left mouse button brings up a menu that allows you to view other
225 * When I print the output of groff -Tdvi, I just get a black dot in
228 Some dvi drivers (notably early versions of xtex) do not correctly
229 handle dvi files that use a resolution different from that used by dvi
230 files produced by TeX. Try getting a more up to date driver.
232 * I get lots of errors when I use groff with the AT&T -mm macros.
234 The AT&T -mm macros need a few changes to work with groff; `make
235 install.dwbmm' will copy your -mm macros to groff's macro directory
236 and make the necessary changes. You may need to edit the commands for
237 the install.mm target in the Makefile. Alternatively use the groff
240 * gtroff doesn't understand lines like `.ce99' with no space between
241 the name of the request or macro and the arguments.
243 Gtroff requires a space between macro or request and its arguments
244 because it allows the use of long names for macros and requests. You
245 can use the -C option or the `cp' request to put gtroff into a
246 compatibility mode in which it is not possible to use long names for
247 macros but in which no space is required between macros and their
248 arguments. The use of compatibility mode is strongly discouraged.
250 * gtroff gives warnings about lines like
252 (with a tab after the .ev).
254 A tab character cannot be used as a substitute for a space character
255 (except in one case: between a control character at the beginning of a
256 line and the name of a macro or request). For example, in Unix troff
257 .ps \" restore the previous point size
258 (with a tab after the .ps) will NOT restore the previous point-size;
259 instead it will be silently ignored. Since this is very likely to be
260 an error, gtroff can give a warning about it. If you want to align
261 comments, you can do it like this:
264 * I don't like the page headers and footers produced by groff -man.
266 There seem to be many different styles of page header and footer
267 produced by different versions of the -man macros. You will need to
268 modify macros/tmac.an to suit your personal taste. For example, if
269 you want the center of the page header to say
270 System Programmer's Manual
271 you will need to change the line
272 .el .ds an-extra3 \"System Programmer's Manual
274 .el .ds an-extra3 System Programmer's Manual
276 * While formatting a manual page, groff complains about not being able to
277 break lines. The problem seems to be caused by a line like:
280 The -man documentation says that the default scale indicator for TP
281 macro is `n'. The groff -man macros implement this correctly, so that
282 the argument will be evaluated as if it were
284 The Unix -man macros don't implement this correctly (probably because
285 it's hard to do in Unix troff); they just append `n' to the entire
286 argument, so that it will be evaluated as if it were
288 The solution is to fix the manual page:
291 * I'm having problems formatting Ultrix man pages with groff -man.
293 The Ultrix man pages use a number of non-standard extensions to the
294 Unix man macros. One solution is to use the Ultrix -man macros with
295 groff. Rename /usr/local/lib/groff/tmac/tmac.an to
296 /usr/local/lib/groff/tmac/tmac.an.gnu, copy /usr/lib/tmac/tmac.an to
297 /usr/local/lib/groff/tmac/tmac.an and apply the following patch (from
300 *** /usr/local/lib/groff/tmac/tmac.an Wed Sep 9 12:29:28 1992
301 --- /usr/lib/tmac/tmac.an Fri Jul 24 19:58:19 1992
304 . \" make special case of shift out of italic
307 ! .if \\$12 .if !\\$5 .ds ]F \^
308 .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
312 . \" make special case of shift out of italic
315 ! .if \\$12 .if !\\$5 .ds ]F\^
316 .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
320 Another possible solution is to install tmac/man.ultrix as
321 /usr/local/lib/groff/tmac/man.local.
323 * I'm having problems formatting HP-UX 9.0 man pages with groff -man.
325 Rename /usr/local/lib/groff/tmac/tmac.an to (for example)
326 /usr/local/lib/groff/tmac/tmac.gan, copy HP's tmac.an into
327 /usr/local/lib/groff/tmac/tmac.an, and either put `.cp 1' at the
328 beginning or filter it (and any files it .so's) through
331 * I'm having problems formatting man pages produced by the perl
334 Some versions of wrapman have a superfluous blank line before the .TH
335 line. This must be deleted. Then either use groff -C, or apply the
338 *** wrapman.~2~ Sun Jan 19 12:10:24 1992
339 --- wrapman Tue Aug 10 02:06:41 1993
342 $line1 .= <IN> if $line1 =~ /eval/;
343 $line1 .= <IN> if $line1 =~ /argv/;
345 ! next if $line2 eq "'di';\n";
347 # Pull the old switcheroo.
350 $line1 .= <IN> if $line1 =~ /eval/;
351 $line1 .= <IN> if $line1 =~ /argv/;
353 ! next if $line2 eq "'di ';\n" || $line2 eq "'di';\n";
355 # Pull the old switcheroo.
381 # These next few lines are legal in both Perl and nroff.
383 ! $null.00; # finish .ig
385 'di \\" finish diversion--previous line must be blank
386 .nr nl 0-1 \\" fake up transition to first page again
387 .nr % 0 \\" start at page 1
388 ! '; __END__ ##### From here on it's a standard manual page #####
389 .TH $PROG 1 "$month $mday, 19$year"
396 # These next few lines are legal in both Perl and nroff.
398 ! $null.00 ; # finish .ig
401 'di \\" finish diversion--previous line must be blank
402 .nr nl 0-1 \\" fake up transition to first page again
403 .nr % 0 \\" start at page 1
404 ! .\\"'; __END__ ##### From here on it's a standard manual page #####
405 .TH $PROG 1 "$month $mday, 19$year"
411 * When I preview documents using -TX75 or -TX100, the layout is not the same
412 as when I print the document with -Tps: the line and page breaks come
417 * When I try to run gxditview, I get the error:
418 Error: Widget viewport has zero width and/or height
420 This error means you haven't correctly installed the application
421 defaults file, GXditview.ad; ``make install'' does this for you
422 automatically, so either you didn't do ``make install'', or you don't
423 have imake configured correctly.
425 * groff uses up an enormous amount of memory processing large files.
426 I'm using 386BSD 0.1.
428 386BSD includes an old version of g++, 1.39, which has a bug that
429 causes a major memory leak in gtroff. Apply the following fix to g++
432 *** cplus-decl.c.~1~ Mon Aug 6 05:28:59 1990
433 --- cplus-decl.c Wed Jun 5 08:55:04 1991
437 /* At the end, call delete if that's what's requested. */
438 if (TREE_GETS_DELETE (current_class_type))
439 exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
440 get_identifier (OPERATOR_DELETE_FORMAT),
441 ! build_tree_list (NULL_TREE, integer_zero_node),
442 NULL_TREE, LOOKUP_NORMAL);
443 else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
444 exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
449 /* At the end, call delete if that's what's requested. */
450 if (TREE_GETS_DELETE (current_class_type))
451 exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
452 get_identifier (OPERATOR_DELETE_FORMAT),
453 ! build_tree_list (NULL_TREE, current_class_decl),
454 NULL_TREE, LOOKUP_NORMAL);
455 else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
456 exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
460 * Where can I get grap?
462 Ted Faber <faber@lunabase.org> has written a freely available grap:
464 http://www.lunabase.org/~faber/Vault/software/grap/
466 * How can I use groff with an old LaserJet printer that doesn't work
469 You have at least 3 options:
471 - use groff -Tps with GNU Ghostscript;
473 - use groff -Tdvi with a TeX .dvi to Laserjet driver;
475 - use groff with the LaserJet driver in Chris Lewis' psroff package
476 (available for ftp from:
477 ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17).
479 * Groff seems to generate level 3 Postscript, but my printer is only a
480 level 1 or 2 PostScript printer.
482 In fact groff generates only level 1 PostScript. The `%!PS-Adobe-3.0'
483 comment at the beginning of PostScript output generated by groff
484 indicates that the file conforms to version 3.0 of the Adobe Document
485 Structuring Conventions. The output generated by groff should be
486 printable on any PostScript printer. Problems with groff output's not
487 printing are most often caused by the spooling system.
489 * The \n(st and \n(sb registers don't seem to work. I thought \w set
490 them to the height and depth of its argument, but the registers always
493 \n(st and \n(sb aren't supposed to give the height and depth of the
494 string rather they give the minimum and maximum vertical displacement
495 of the baseline. For example for \v'2u'\v'-3u', \n(st will be 1 and
496 \n(sb will be -2. The height and depth of the string is available in
497 the \n[rst] and \n[rsb] registers: these are groff extensions.
499 * On an SGI system, how can I make the man command use groff?
501 From David Hinds <dhinds@allegro.stanford.edu> (some of these steps
502 are unnecessary if you install with the `g' Makefile variable defined
505 Create a script called 'eqn':
508 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
511 and a script called 'neqn':
514 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
521 and edit the end of the gnroff script to be:
523 > rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
524 > exec groff -Wall -mtty-char $T $opts $rest
526 To get PostScript output from 'man -t', you also need to create a
527 'psroff' script similar to 'nroff'. Here are the context diffs:
529 *** /usr/local/bin/nroff Sat Feb 13 15:51:09 1993
530 --- /usr/local/bin/psroff Sat Feb 13 17:45:46 1993
534 ! # Emulate nroff with groff.
543 ! # Emulate psroff with groff.
557 + # ignore -- default is send to stdout
560 # ignore other devices
564 rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
566 # This shell script is intended for use with man, so warnings are
567 # probably not wanted. Also load nroff-style character definitions.
568 ! exec groff -Wall -mtty-char $T $opts $rest
570 rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
572 # This shell script is intended for use with man, so warnings are
573 ! # probably not wanted.
574 ! exec groff -Wall $T $opts $rest