1This file describes various problems that have been encountered in
2compiling, installing and running groff. Suggestions for additions or
3other improvements to this file are welcome.
4
5----------------------------------------------------------------------
6
7* My document says that the current year is 19100, not 2000.
8
9In groff, as in traditional troff, the yr number register yields the
10year minus 1900. Unfortunately, there is a longstanding bug in the
11Troff User's Manual <http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz>,
12which incorrectly claims that yr is the last two digits of the year.
13This claim was never true of either Unix troff or of groff.
14
15If your text looks like this:
16
17 .\" Wrong:
18 This document was formatted in 19\n(yr.
19
20you can correct it as follows:
21
22 This document was formatted in \n[year].
23
24or, if you want to be portable to older troff versions, as follows:
25
26 .nr y4 1900+\n(yr
27 This document was formatted in \n(y4.
28
29----------------------------------------------------------------------
30
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.
33
34Make sure -DCFRONT_ANSI_BUG is included in DEFINES in the top-level
35Makefile. If that doesn't solve the problem, define INT_MIN as
36-INT_MAX in libgroff/lib.h.
37
38----------------------------------------------------------------------
39
40* I get errors when I try to compile groff with Sun C++ version 5.0
41 or 5.1.
42
43This is a known problem; see Sun bug #4301919. As of this writing, no
44patch is available. Use GCC 2.95.2 or later instead.
45
46----------------------------------------------------------------------
47
48* I get errors when I try to compile groff with Sun C++ version 3 or
49 earlier.
50
51Groff requires header files that are moderately compatible with AT&T
52C++ and ANSI C. With some versions of Sun C++, the supplied header
53files 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
56should be declared as `const char *'; the first argument to fread
57should be declared as `void *'; the first argument to fwrite should be
58declared 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
61return type and the second argument type of signal() should be changed
62to be `void (*)(int)'.
63
64You can either change them in place, or copy them to some other
65directory and include that directory with a -I option.
66
67----------------------------------------------------------------------
68
69* The configure script fails on OS/390 Unix.
70
71There is a bug in the Language Environment (LE) whereby the test
72program for static destructors fails. You will see the message
73'configure: error: a working C++ compiler is required'
74
75Applying PTF UQ42006 is supposed to fix this, but the test program is
76still returning the wrong value (1). To work around this problem, you
77can comment out the following in the configure script (near line 956).
78This will effectively bypass the test (static constructors and
79destructors do actually work properly):
80
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
82#then
83 echo "$ac_t""yes" 1>&6
84#else
85# echo "configure: failed program was:" >&5
86# cat conftest.$ac_ext >&5
87# rm -fr conftest*
88# echo "$ac_t""no" 1>&6;{ echo "configure: error: a working C++ compiler is required" 1>&2; exit 1; }
89#fi
90
91----------------------------------------------------------------------
92
93* I get errors when I try to compile groff with DEC C++.
94
95Fix the declaration of write() in <unistd.h> so that the second
96argument is a const char *. Fix the declaration of open() in
97<sys/file.h> so that the first argument is a const char *.
98
99----------------------------------------------------------------------
100
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:
104
105 make: Fatal error: Don't know how to make target `assert.o'
106
107 or like this:
108
109 make: Fatal error: Can't find /u/src/groff/src/include/Makefile.sub': No such file or directory
110
111This occurs because GNU make and Unix make handle VPATH differently,
112and the groff build relies on GNU make's VPATH handling.
113
114Use GNU make to work around the problem. In Solaris 8, GNU make is
115on the Software Companion CD and is installed as /opt/sfw/bin/gmake.
116
117----------------------------------------------------------------------
118
119* On Ultrix, the make stops with the message
120
121 *** Error code 1
122
123 Stop.
124
125for no apparent reason.
126
127Use GNU make.
128
129----------------------------------------------------------------------
130
131* I'm having problems compiling groff on 386BSD 0.1.
132
133If you're using ash as /bin/sh, you'll need the following patch.
134
135*** gendef.sh.org Sun Jun 30 13:30:36 1991
136--- gendef.sh Sun Feb 28 10:23:49 1993
137***************
138*** 3,9 ****
--- 12 unchanged lines hidden (view full) ---
151! defs="#define $x"
152 shift
153 for def
154 do
155
156You'll also need to change dirnamemax.c so that it doesn't use
157pathconf().
158
159----------------------------------------------------------------------
160
161* While compiling on Xenix, ranlib libgroff.a fails.
162
163The system ranlib can't handle externals longer than 40 characters.
164Use the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1
165instead.
166
167----------------------------------------------------------------------
168
169* There are many empty `Makefile.dep' files. Is this a bug?
170
171No. Real dependency files are created with a `make depend' call.
172
173----------------------------------------------------------------------
174
175* Groff can't handle my troff document. It works fine with AT&T troff.
176
177Read the section on incompatibilities in gtroff(1). Try using the -C
178option. Alternatively there's the sed script in tmac/fixmacros.sed
179which will attempt to edit a file of macros so that it can be used
180with groff without the -C flag.
181
182----------------------------------------------------------------------
183
184* groff -Tdvi produces dvi files that use fonts at weird
185 magnifications.
186
187Yes, it does. You may need to compile fonts with Metafont at these
188magnifications. The CompileFonts script in the devdvi/generate
189directory may help you to do this. (It will take a *long* time.)
190
191----------------------------------------------------------------------
192
193* pic output is not centered horizontally; pictures sometimes run off
194 the bottom of the page.
195
196The macro package you are using is not supplying appropriate
197definitions of PS and PE. Give groff a -mpic option.
198
199----------------------------------------------------------------------
200
201* I'm having problems including PostScript illustrations using the
202 PSPIC macro.
203
204A PostScript document must meet three requirements in order to be
205included with the PSPIC macro: it must comply with the Adobe Document
206Structuring Conventions; it must contain a BoundingBox line; it must
207be ``well-behaved''. The BoundingBox line should be of the form:
208
209 %%BoundingBox: llx lly urx ury
210
211where llx, lly, urx, ury are the coordinates of the lower left x,
212lower left y, upper right x, upper right y of the bounding box of
213marks on the page expressed as integers in the default PostScript
214coordinate system (72 units per inch, origin at bottom left corner).
215A useful tactic is to print out the illustration by itself (you may
216need to add a `showpage' at the end), and physically measure the
217bounding box. For more detail on these requirements, read the
218specification of Encapsulated PostScript format. (This is available
219from the Adobe file server; send a message with a body of `help' to
220ps-file-server@adobe.com.)
221
222----------------------------------------------------------------------
223
224* I've configured groff for A4 paper, but gtroff still seems to think
225 that the length of a page (as returned by \n(.p) is 11 inches.
226
227This is intentional. The PAGE option is used only by grops. For
228compatibility with ditroff, the default page length in gtroff is
229always 11 inches. The page length can be changed with the `pl'
230request.
231
232----------------------------------------------------------------------
233
234* Groff doesn't use the font names I'm used to.
235
236Use the `ftr' request. See gtroff(1).
237
238----------------------------------------------------------------------
239
240* I get errors using the Unix -ms macros with groff -e -C.
241
242Apply this change:
243
244*** /usr/lib/ms/ms.eqn Tue Apr 25 02:14:28 1989
245--- ms.eqn Sun Nov 11 10:33:59 1990
246***************
247*** 22,29 ****
--- 11 unchanged lines hidden (view full) ---
259 .de EN
260! .if \\n(.k>0 .br
261 .di
262+ .ds 10 \\*(EZ\\
263 .rm EZ
264 .nr ZN \\n(dn
265 .if \\n(ZN>0 .if \\n(YE=0 .LP
266
267----------------------------------------------------------------------
268
269* gpic doesn't accept the syntax `chop N M' for chopping both ends of
270 a line.
271
272The correct syntax is `chop N chop M'.
273
274----------------------------------------------------------------------
275
276* With gpic -t, when I print `line ->; box' using a dvi to ps program,
277 the arrow head sticks through into the inside of the box.
278
279The dvi to ps program should be modified to set the line cap and line
280join parameters to 1 while printing tpic specials.
281
282----------------------------------------------------------------------
283
284* When I print the output groff -Tps, the output is always shifted up
285 by about 0.7 inches; I'm using 8.5x11 inch paper.
286
287Make sure that PAGE is defined to be `letter' in the top-level
288Makefile.
289
290----------------------------------------------------------------------
291
292* When I try to print the output of groff -Tps, I get no output at all
293 from the printer, and the log file shows the error
294 %%[ error: undefined; offendingcommand: BP ]%%
295 I'm using TranScript spooling software.
296
297This is a bug in the page reversal filter in early versions of
298TranScript. Change the `broken' parameter in
299/usr/local/lib/groff/font/devps/DESC to 7.
300
301----------------------------------------------------------------------
302
303* When I preview groff -Tps output using the Sun OpenWindows 2.0
304 pageview program, all the pages are displayed on top of each other.
305
306This is a defect in pageview. Change the `broken' parameter in
307/usr/local/lib/groff/font/devps/DESC to 2.
308
309----------------------------------------------------------------------
310
311* With groff -TX75, -TX100 or -X, I can only view the first page.
312
313The left mouse button brings up a menu that allows you to view other
314pages.
315
316----------------------------------------------------------------------
317
318* When I print the output of groff -Tdvi, I just get a black dot in
319 upper left corner.
320
321Some dvi drivers (notably early versions of xtex) do not correctly
322handle dvi files that use a resolution different from that used by dvi
323files produced by TeX. Try getting a more up to date driver.
324
325----------------------------------------------------------------------
326
327* I get lots of errors when I use groff with the AT&T -mm macros.
328
329The AT&T -mm macros need a few changes to work with groff; `make
330install.dwbmm' will copy your -mm macros to groff's macro directory
331and make the necessary changes. You may need to edit the commands for
332the install.mm target in the Makefile. Alternatively use the groff
333-mm macros.
334
335----------------------------------------------------------------------
336
337* gtroff doesn't understand lines like `.ce99' with no space between
338 the name of the request or macro and the arguments.
339
340gtroff requires a space between macro or request and its arguments
341because it allows the use of long names for macros and requests. You
342can use the -C option or the `cp' request to put gtroff into a
343compatibility mode in which it is not possible to use long names for
344macros but in which no space is required between macros and their
345arguments. The use of compatibility mode is strongly discouraged.
346
347----------------------------------------------------------------------
348
349* gtroff gives warnings about lines like
350 .ev \" a comment
351 (with a tab after the .ev).
352
353A tab character cannot be used as a substitute for a space character
354(except in one case: between a control character at the beginning of a
355line and the name of a macro or request). For example, in Unix troff
356
357 .ps \" restore the previous point size
358
359(with a tab after the .ps) will NOT restore the previous point-size;
360instead it will be silently ignored. Since this is very likely to be
361an error, gtroff can give a warning about it. If you want to align
362comments, you can do it like this:
363
364 .ev\" \" a comment
365
366----------------------------------------------------------------------
367
368* I don't like the page headers and footers produced by groff -man.
369
370There seem to be many different styles of page header and footer
371produced by different versions of the -man macros. You will need to
372modify macros/tmac.an to suit your personal taste. For example, if
373you want the center of the page header to say
374
375 System Programmer's Manual
376
377you will need to change the line
378
379 .el .ds an-extra3 \"System Programmer's Manual
380
381to
382
383 .el .ds an-extra3 System Programmer's Manual
384
385----------------------------------------------------------------------
386
387* While formatting a manual page, groff complains about not being able
388 to break lines. The problem seems to be caused by a line like:
389 .TP \w'label'+2
390
391The -man documentation says that the default scale indicator for TP
392macro is `n'. The groff -man macros implement this correctly, so that
393the argument will be evaluated as if it were
394
395 \w'label'n+2n
396
397The Unix -man macros don't implement this correctly (probably because
398it's hard to do in Unix troff); they just append `n' to the entire
399argument, so that it will be evaluated as if it were
400
401 \w'label'u+2n
402
403The solution is to fix the manual page:
404
405 .TP \w'label'u+2
406
407----------------------------------------------------------------------
408
409* I'm having problems formatting Ultrix man pages with groff -man.
410
411The Ultrix man pages use a number of non-standard extensions to the
412Unix man macros. One solution is to use the Ultrix -man macros with
413groff. Rename /usr/local/lib/groff/tmac/tmac.an to
414/usr/local/lib/groff/tmac/tmac.an.gnu, copy /usr/lib/tmac/tmac.an to
415/usr/local/lib/groff/tmac/tmac.an and apply the following patch (from
416Frank Wortner):
--- 16 unchanged lines hidden (view full) ---
433! .if \\$12 .if !\\$5 .ds ]F\^
434 .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
435 .el \\$3
436 .}f
437
438Another possible solution is to install tmac/man.ultrix as
439/usr/local/lib/groff/tmac/man.local.
440
441----------------------------------------------------------------------
442
443* I'm having problems formatting HP-UX 9.0 man pages with groff -man.
444
445Rename /usr/local/lib/groff/tmac/tmac.an to (for example)
446/usr/local/lib/groff/tmac/tmac.gan, copy HP's tmac.an into
447/usr/local/lib/groff/tmac/tmac.an, and either put `.cp 1' at the
448beginning or filter it (and any files it .so's) through
449tmac/fixmacros.sed.
450
451----------------------------------------------------------------------
452
453* I'm having problems formatting man pages produced by the perl
454 wrapman script.
455
456Some versions of wrapman have a superfluous blank line before the .TH
457line. This must be deleted. Then either use groff -C, or apply the
458following patch:
459
460*** wrapman.~2~ Sun Jan 19 12:10:24 1992
461--- wrapman Tue Aug 10 02:06:41 1993
462***************
--- 62 unchanged lines hidden (view full) ---
525 .nr % 0 \\" start at page 1
526! .\\"'; __END__ ##### From here on it's a standard manual page #####
527 .TH $PROG 1 "$month $mday, 19$year"
528 .SH NAME
529 $prog \\- whatever
530 .SH SYNOPSIS
531
532
533----------------------------------------------------------------------
534
535* When I preview documents using -TX75 or -TX100, the layout is not
536 the same as when I print the document with -Tps: the line and page
537 breaks come in different places.
538
539Use groff -X -Tps.
540
541----------------------------------------------------------------------
542
543* When I try to run gxditview, I get the error:
544 Error: Widget viewport has zero width and/or height
545
546This error means you haven't correctly installed the application
547defaults file, GXditview.ad; ``make install'' does this for you
548automatically, so either you didn't do ``make install'', or you don't
549have imake configured correctly.
550
551----------------------------------------------------------------------
552
553* groff uses up an enormous amount of memory processing large files.
554 I'm using 386BSD 0.1.
555
556386BSD includes an old version of g++, 1.39, which has a bug that
557causes a major memory leak in gtroff. Apply the following fix to g++
558and recompile groff:
559
560*** cplus-decl.c.~1~ Mon Aug 6 05:28:59 1990
561--- cplus-decl.c Wed Jun 5 08:55:04 1991
562***************
--- 17 unchanged lines hidden (view full) ---
580 get_identifier (OPERATOR_DELETE_FORMAT),
581! build_tree_list (NULL_TREE, current_class_decl),
582 NULL_TREE, LOOKUP_NORMAL);
583 else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
584 exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
585 else
586 exprstmt = 0;
587
588----------------------------------------------------------------------
589
590* Where can I get grap?
591
592Ted Faber <faber@lunabase.org> has written a freely available grap:
593
594 http://www.lunabase.org/~faber/Vault/software/grap/
595
596----------------------------------------------------------------------
597
598* How can I use groff with an old LaserJet printer that doesn't work
599 with groff -Tlj4?
600
601You have at least 3 options:
602
603- use groff -Tps with GNU Ghostscript;
604
605- use groff -Tdvi with a TeX .dvi to Laserjet driver;
606
607- use groff with the LaserJet driver in Chris Lewis' psroff package
608 (available for ftp from:
609 ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17).
610
611----------------------------------------------------------------------
612
613* Groff seems to generate level 3 Postscript, but my printer is only a
614 level 1 or 2 PostScript printer.
615
616In fact groff generates only level 1 PostScript. The `%!PS-Adobe-3.0'
617comment at the beginning of PostScript output generated by groff
618indicates that the file conforms to version 3.0 of the Adobe Document
619Structuring Conventions. The output generated by groff should be
620printable on any PostScript printer. Problems with groff output's not
621printing are most often caused by the spooling system.
622
623----------------------------------------------------------------------
624
625* The \n(st and \n(sb registers don't seem to work. I thought \w set
626 them to the height and depth of its argument, but the registers
627 always seem to be 0.
628
629\n(st and \n(sb aren't supposed to give the height and depth of the
630string rather they give the minimum and maximum vertical displacement
631of the baseline. For example for \v'2u'\v'-3u', \n(st will be 1 and
632\n(sb will be -2. The height and depth of the string is available in
633the \n[rst] and \n[rsb] registers: these are groff extensions.
634
635----------------------------------------------------------------------
636
637* On an SGI system, how can I make the man command use groff?
638
639From David Hinds <dhinds@allegro.stanford.edu> (some of these steps
640are unnecessary if you install with the `g' Makefile variable defined
641as empty):
642
643Create a script called 'eqn':
644
--- 68 unchanged lines hidden ---
2compiling, installing and running groff. Suggestions for additions or
3other improvements to this file are welcome.
4
5----------------------------------------------------------------------
6
7* My document says that the current year is 19100, not 2000.
8
9In groff, as in traditional troff, the yr number register yields the
10year minus 1900. Unfortunately, there is a longstanding bug in the
11Troff User's Manual <http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz>,
12which incorrectly claims that yr is the last two digits of the year.
13This claim was never true of either Unix troff or of groff.
14
15If your text looks like this:
16
17 .\" Wrong:
18 This document was formatted in 19\n(yr.
19
20you can correct it as follows:
21
22 This document was formatted in \n[year].
23
24or, if you want to be portable to older troff versions, as follows:
25
26 .nr y4 1900+\n(yr
27 This document was formatted in \n(y4.
28
29----------------------------------------------------------------------
30
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.
33
34Make sure -DCFRONT_ANSI_BUG is included in DEFINES in the top-level
35Makefile. If that doesn't solve the problem, define INT_MIN as
36-INT_MAX in libgroff/lib.h.
37
38----------------------------------------------------------------------
39
40* I get errors when I try to compile groff with Sun C++ version 5.0
41 or 5.1.
42
43This is a known problem; see Sun bug #4301919. As of this writing, no
44patch is available. Use GCC 2.95.2 or later instead.
45
46----------------------------------------------------------------------
47
48* I get errors when I try to compile groff with Sun C++ version 3 or
49 earlier.
50
51Groff requires header files that are moderately compatible with AT&T
52C++ and ANSI C. With some versions of Sun C++, the supplied header
53files 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
56should be declared as `const char *'; the first argument to fread
57should be declared as `void *'; the first argument to fwrite should be
58declared 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
61return type and the second argument type of signal() should be changed
62to be `void (*)(int)'.
63
64You can either change them in place, or copy them to some other
65directory and include that directory with a -I option.
66
67----------------------------------------------------------------------
68
69* The configure script fails on OS/390 Unix.
70
71There is a bug in the Language Environment (LE) whereby the test
72program for static destructors fails. You will see the message
73'configure: error: a working C++ compiler is required'
74
75Applying PTF UQ42006 is supposed to fix this, but the test program is
76still returning the wrong value (1). To work around this problem, you
77can comment out the following in the configure script (near line 956).
78This will effectively bypass the test (static constructors and
79destructors do actually work properly):
80
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
82#then
83 echo "$ac_t""yes" 1>&6
84#else
85# echo "configure: failed program was:" >&5
86# cat conftest.$ac_ext >&5
87# rm -fr conftest*
88# echo "$ac_t""no" 1>&6;{ echo "configure: error: a working C++ compiler is required" 1>&2; exit 1; }
89#fi
90
91----------------------------------------------------------------------
92
93* I get errors when I try to compile groff with DEC C++.
94
95Fix the declaration of write() in <unistd.h> so that the second
96argument is a const char *. Fix the declaration of open() in
97<sys/file.h> so that the first argument is a const char *.
98
99----------------------------------------------------------------------
100
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:
104
105 make: Fatal error: Don't know how to make target `assert.o'
106
107 or like this:
108
109 make: Fatal error: Can't find /u/src/groff/src/include/Makefile.sub': No such file or directory
110
111This occurs because GNU make and Unix make handle VPATH differently,
112and the groff build relies on GNU make's VPATH handling.
113
114Use GNU make to work around the problem. In Solaris 8, GNU make is
115on the Software Companion CD and is installed as /opt/sfw/bin/gmake.
116
117----------------------------------------------------------------------
118
119* On Ultrix, the make stops with the message
120
121 *** Error code 1
122
123 Stop.
124
125for no apparent reason.
126
127Use GNU make.
128
129----------------------------------------------------------------------
130
131* I'm having problems compiling groff on 386BSD 0.1.
132
133If you're using ash as /bin/sh, you'll need the following patch.
134
135*** gendef.sh.org Sun Jun 30 13:30:36 1991
136--- gendef.sh Sun Feb 28 10:23:49 1993
137***************
138*** 3,9 ****
--- 12 unchanged lines hidden (view full) ---
151! defs="#define $x"
152 shift
153 for def
154 do
155
156You'll also need to change dirnamemax.c so that it doesn't use
157pathconf().
158
159----------------------------------------------------------------------
160
161* While compiling on Xenix, ranlib libgroff.a fails.
162
163The system ranlib can't handle externals longer than 40 characters.
164Use the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1
165instead.
166
167----------------------------------------------------------------------
168
169* There are many empty `Makefile.dep' files. Is this a bug?
170
171No. Real dependency files are created with a `make depend' call.
172
173----------------------------------------------------------------------
174
175* Groff can't handle my troff document. It works fine with AT&T troff.
176
177Read the section on incompatibilities in gtroff(1). Try using the -C
178option. Alternatively there's the sed script in tmac/fixmacros.sed
179which will attempt to edit a file of macros so that it can be used
180with groff without the -C flag.
181
182----------------------------------------------------------------------
183
184* groff -Tdvi produces dvi files that use fonts at weird
185 magnifications.
186
187Yes, it does. You may need to compile fonts with Metafont at these
188magnifications. The CompileFonts script in the devdvi/generate
189directory may help you to do this. (It will take a *long* time.)
190
191----------------------------------------------------------------------
192
193* pic output is not centered horizontally; pictures sometimes run off
194 the bottom of the page.
195
196The macro package you are using is not supplying appropriate
197definitions of PS and PE. Give groff a -mpic option.
198
199----------------------------------------------------------------------
200
201* I'm having problems including PostScript illustrations using the
202 PSPIC macro.
203
204A PostScript document must meet three requirements in order to be
205included with the PSPIC macro: it must comply with the Adobe Document
206Structuring Conventions; it must contain a BoundingBox line; it must
207be ``well-behaved''. The BoundingBox line should be of the form:
208
209 %%BoundingBox: llx lly urx ury
210
211where llx, lly, urx, ury are the coordinates of the lower left x,
212lower left y, upper right x, upper right y of the bounding box of
213marks on the page expressed as integers in the default PostScript
214coordinate system (72 units per inch, origin at bottom left corner).
215A useful tactic is to print out the illustration by itself (you may
216need to add a `showpage' at the end), and physically measure the
217bounding box. For more detail on these requirements, read the
218specification of Encapsulated PostScript format. (This is available
219from the Adobe file server; send a message with a body of `help' to
220ps-file-server@adobe.com.)
221
222----------------------------------------------------------------------
223
224* I've configured groff for A4 paper, but gtroff still seems to think
225 that the length of a page (as returned by \n(.p) is 11 inches.
226
227This is intentional. The PAGE option is used only by grops. For
228compatibility with ditroff, the default page length in gtroff is
229always 11 inches. The page length can be changed with the `pl'
230request.
231
232----------------------------------------------------------------------
233
234* Groff doesn't use the font names I'm used to.
235
236Use the `ftr' request. See gtroff(1).
237
238----------------------------------------------------------------------
239
240* I get errors using the Unix -ms macros with groff -e -C.
241
242Apply this change:
243
244*** /usr/lib/ms/ms.eqn Tue Apr 25 02:14:28 1989
245--- ms.eqn Sun Nov 11 10:33:59 1990
246***************
247*** 22,29 ****
--- 11 unchanged lines hidden (view full) ---
259 .de EN
260! .if \\n(.k>0 .br
261 .di
262+ .ds 10 \\*(EZ\\
263 .rm EZ
264 .nr ZN \\n(dn
265 .if \\n(ZN>0 .if \\n(YE=0 .LP
266
267----------------------------------------------------------------------
268
269* gpic doesn't accept the syntax `chop N M' for chopping both ends of
270 a line.
271
272The correct syntax is `chop N chop M'.
273
274----------------------------------------------------------------------
275
276* With gpic -t, when I print `line ->; box' using a dvi to ps program,
277 the arrow head sticks through into the inside of the box.
278
279The dvi to ps program should be modified to set the line cap and line
280join parameters to 1 while printing tpic specials.
281
282----------------------------------------------------------------------
283
284* When I print the output groff -Tps, the output is always shifted up
285 by about 0.7 inches; I'm using 8.5x11 inch paper.
286
287Make sure that PAGE is defined to be `letter' in the top-level
288Makefile.
289
290----------------------------------------------------------------------
291
292* When I try to print the output of groff -Tps, I get no output at all
293 from the printer, and the log file shows the error
294 %%[ error: undefined; offendingcommand: BP ]%%
295 I'm using TranScript spooling software.
296
297This is a bug in the page reversal filter in early versions of
298TranScript. Change the `broken' parameter in
299/usr/local/lib/groff/font/devps/DESC to 7.
300
301----------------------------------------------------------------------
302
303* When I preview groff -Tps output using the Sun OpenWindows 2.0
304 pageview program, all the pages are displayed on top of each other.
305
306This is a defect in pageview. Change the `broken' parameter in
307/usr/local/lib/groff/font/devps/DESC to 2.
308
309----------------------------------------------------------------------
310
311* With groff -TX75, -TX100 or -X, I can only view the first page.
312
313The left mouse button brings up a menu that allows you to view other
314pages.
315
316----------------------------------------------------------------------
317
318* When I print the output of groff -Tdvi, I just get a black dot in
319 upper left corner.
320
321Some dvi drivers (notably early versions of xtex) do not correctly
322handle dvi files that use a resolution different from that used by dvi
323files produced by TeX. Try getting a more up to date driver.
324
325----------------------------------------------------------------------
326
327* I get lots of errors when I use groff with the AT&T -mm macros.
328
329The AT&T -mm macros need a few changes to work with groff; `make
330install.dwbmm' will copy your -mm macros to groff's macro directory
331and make the necessary changes. You may need to edit the commands for
332the install.mm target in the Makefile. Alternatively use the groff
333-mm macros.
334
335----------------------------------------------------------------------
336
337* gtroff doesn't understand lines like `.ce99' with no space between
338 the name of the request or macro and the arguments.
339
340gtroff requires a space between macro or request and its arguments
341because it allows the use of long names for macros and requests. You
342can use the -C option or the `cp' request to put gtroff into a
343compatibility mode in which it is not possible to use long names for
344macros but in which no space is required between macros and their
345arguments. The use of compatibility mode is strongly discouraged.
346
347----------------------------------------------------------------------
348
349* gtroff gives warnings about lines like
350 .ev \" a comment
351 (with a tab after the .ev).
352
353A tab character cannot be used as a substitute for a space character
354(except in one case: between a control character at the beginning of a
355line and the name of a macro or request). For example, in Unix troff
356
357 .ps \" restore the previous point size
358
359(with a tab after the .ps) will NOT restore the previous point-size;
360instead it will be silently ignored. Since this is very likely to be
361an error, gtroff can give a warning about it. If you want to align
362comments, you can do it like this:
363
364 .ev\" \" a comment
365
366----------------------------------------------------------------------
367
368* I don't like the page headers and footers produced by groff -man.
369
370There seem to be many different styles of page header and footer
371produced by different versions of the -man macros. You will need to
372modify macros/tmac.an to suit your personal taste. For example, if
373you want the center of the page header to say
374
375 System Programmer's Manual
376
377you will need to change the line
378
379 .el .ds an-extra3 \"System Programmer's Manual
380
381to
382
383 .el .ds an-extra3 System Programmer's Manual
384
385----------------------------------------------------------------------
386
387* While formatting a manual page, groff complains about not being able
388 to break lines. The problem seems to be caused by a line like:
389 .TP \w'label'+2
390
391The -man documentation says that the default scale indicator for TP
392macro is `n'. The groff -man macros implement this correctly, so that
393the argument will be evaluated as if it were
394
395 \w'label'n+2n
396
397The Unix -man macros don't implement this correctly (probably because
398it's hard to do in Unix troff); they just append `n' to the entire
399argument, so that it will be evaluated as if it were
400
401 \w'label'u+2n
402
403The solution is to fix the manual page:
404
405 .TP \w'label'u+2
406
407----------------------------------------------------------------------
408
409* I'm having problems formatting Ultrix man pages with groff -man.
410
411The Ultrix man pages use a number of non-standard extensions to the
412Unix man macros. One solution is to use the Ultrix -man macros with
413groff. Rename /usr/local/lib/groff/tmac/tmac.an to
414/usr/local/lib/groff/tmac/tmac.an.gnu, copy /usr/lib/tmac/tmac.an to
415/usr/local/lib/groff/tmac/tmac.an and apply the following patch (from
416Frank Wortner):
--- 16 unchanged lines hidden (view full) ---
433! .if \\$12 .if !\\$5 .ds ]F\^
434 .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
435 .el \\$3
436 .}f
437
438Another possible solution is to install tmac/man.ultrix as
439/usr/local/lib/groff/tmac/man.local.
440
441----------------------------------------------------------------------
442
443* I'm having problems formatting HP-UX 9.0 man pages with groff -man.
444
445Rename /usr/local/lib/groff/tmac/tmac.an to (for example)
446/usr/local/lib/groff/tmac/tmac.gan, copy HP's tmac.an into
447/usr/local/lib/groff/tmac/tmac.an, and either put `.cp 1' at the
448beginning or filter it (and any files it .so's) through
449tmac/fixmacros.sed.
450
451----------------------------------------------------------------------
452
453* I'm having problems formatting man pages produced by the perl
454 wrapman script.
455
456Some versions of wrapman have a superfluous blank line before the .TH
457line. This must be deleted. Then either use groff -C, or apply the
458following patch:
459
460*** wrapman.~2~ Sun Jan 19 12:10:24 1992
461--- wrapman Tue Aug 10 02:06:41 1993
462***************
--- 62 unchanged lines hidden (view full) ---
525 .nr % 0 \\" start at page 1
526! .\\"'; __END__ ##### From here on it's a standard manual page #####
527 .TH $PROG 1 "$month $mday, 19$year"
528 .SH NAME
529 $prog \\- whatever
530 .SH SYNOPSIS
531
532
533----------------------------------------------------------------------
534
535* When I preview documents using -TX75 or -TX100, the layout is not
536 the same as when I print the document with -Tps: the line and page
537 breaks come in different places.
538
539Use groff -X -Tps.
540
541----------------------------------------------------------------------
542
543* When I try to run gxditview, I get the error:
544 Error: Widget viewport has zero width and/or height
545
546This error means you haven't correctly installed the application
547defaults file, GXditview.ad; ``make install'' does this for you
548automatically, so either you didn't do ``make install'', or you don't
549have imake configured correctly.
550
551----------------------------------------------------------------------
552
553* groff uses up an enormous amount of memory processing large files.
554 I'm using 386BSD 0.1.
555
556386BSD includes an old version of g++, 1.39, which has a bug that
557causes a major memory leak in gtroff. Apply the following fix to g++
558and recompile groff:
559
560*** cplus-decl.c.~1~ Mon Aug 6 05:28:59 1990
561--- cplus-decl.c Wed Jun 5 08:55:04 1991
562***************
--- 17 unchanged lines hidden (view full) ---
580 get_identifier (OPERATOR_DELETE_FORMAT),
581! build_tree_list (NULL_TREE, current_class_decl),
582 NULL_TREE, LOOKUP_NORMAL);
583 else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
584 exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
585 else
586 exprstmt = 0;
587
588----------------------------------------------------------------------
589
590* Where can I get grap?
591
592Ted Faber <faber@lunabase.org> has written a freely available grap:
593
594 http://www.lunabase.org/~faber/Vault/software/grap/
595
596----------------------------------------------------------------------
597
598* How can I use groff with an old LaserJet printer that doesn't work
599 with groff -Tlj4?
600
601You have at least 3 options:
602
603- use groff -Tps with GNU Ghostscript;
604
605- use groff -Tdvi with a TeX .dvi to Laserjet driver;
606
607- use groff with the LaserJet driver in Chris Lewis' psroff package
608 (available for ftp from:
609 ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17).
610
611----------------------------------------------------------------------
612
613* Groff seems to generate level 3 Postscript, but my printer is only a
614 level 1 or 2 PostScript printer.
615
616In fact groff generates only level 1 PostScript. The `%!PS-Adobe-3.0'
617comment at the beginning of PostScript output generated by groff
618indicates that the file conforms to version 3.0 of the Adobe Document
619Structuring Conventions. The output generated by groff should be
620printable on any PostScript printer. Problems with groff output's not
621printing are most often caused by the spooling system.
622
623----------------------------------------------------------------------
624
625* The \n(st and \n(sb registers don't seem to work. I thought \w set
626 them to the height and depth of its argument, but the registers
627 always seem to be 0.
628
629\n(st and \n(sb aren't supposed to give the height and depth of the
630string rather they give the minimum and maximum vertical displacement
631of the baseline. For example for \v'2u'\v'-3u', \n(st will be 1 and
632\n(sb will be -2. The height and depth of the string is available in
633the \n[rst] and \n[rsb] registers: these are groff extensions.
634
635----------------------------------------------------------------------
636
637* On an SGI system, how can I make the man command use groff?
638
639From David Hinds <dhinds@allegro.stanford.edu> (some of these steps
640are unnecessary if you install with the `g' Makefile variable defined
641as empty):
642
643Create a script called 'eqn':
644
--- 68 unchanged lines hidden ---