* tmac/groff_tmac.man, man/groff.man, man/roff.man: Fixing @MANxEXT@
[s-roff.git] / PROBLEMS
blob67307cff6faadf9fa8f4508e4321f379a1e57d56
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:
17         .\" Wrong:
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:
26         .nr y4 1900+\n(yr
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
41   or 5.1.
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
49   earlier.
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 You must apply fix pack PTF UQ42006 which fixes a C++ compiler bug.
73 ----------------------------------------------------------------------
75 * I get errors when I try to compile groff with DEC C++.
77 Fix the declaration of write() in <unistd.h> so that the second
78 argument is a const char *.  Fix the declaration of open() in
79 <sys/file.h> so that the first argument is a const char *.
81 ----------------------------------------------------------------------
83 * On Ultrix, the make stops with the message
85   *** Error code 1
87   Stop.
89 for no apparent reason.
91 Use GNU make.
93 ----------------------------------------------------------------------
95 * I'm having problems compiling groff on 386BSD 0.1.
97 If you're using ash as /bin/sh, you'll need the following patch.
99 *** gendef.sh.org       Sun Jun 30 13:30:36 1991
100 --- gendef.sh   Sun Feb 28 10:23:49 1993
101 ***************
102 *** 3,9 ****
103   file=$1
104   shift
105   
106 ! defs="#define $1"
107   shift
108   for def
109   do
110 --- 3,10 ----
111   file=$1
112   shift
113   
114 ! x=$1
115 ! defs="#define $x"
116   shift
117   for def
118   do
120 You'll also need to change dirnamemax.c so that it doesn't use
121 pathconf().
123 ----------------------------------------------------------------------
125 * While compiling on Xenix, ranlib libgroff.a fails.
127 The system ranlib can't handle externals longer than 40 characters.
128 Use the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1
129 instead.
131 ----------------------------------------------------------------------
133 * Groff can't handle my troff document. It works fine with AT&T troff.
135 Read the section on incompatibilities in gtroff(1).  Try using the -C
136 option.  Alternatively there's the sed script in tmac/fixmacros.sed
137 which will attempt to edit a file of macros so that it can be used
138 with groff without the -C flag.
140 ----------------------------------------------------------------------
142 * groff -Tdvi produces dvi files that use fonts at weird
143   magnifications.
145 Yes, it does.  You may need to compile fonts with Metafont at these
146 magnifications.  The CompileFonts script in the devdvi/generate
147 directory may help you to do this.  (It will take a *long* time.)
149 ----------------------------------------------------------------------
151 * pic output is not centered horizontally; pictures sometimes run off
152   the bottom of the page.
154 The macro package you are using is not supplying appropriate
155 definitions of PS and PE.  Give groff a -mpic option.
157 ----------------------------------------------------------------------
159 * I'm having problems including PostScript illustrations using the
160   PSPIC macro.
162 A PostScript document must meet three requirements in order to be
163 included with the PSPIC macro: it must comply with the Adobe Document
164 Structuring Conventions; it must contain a BoundingBox line; it must
165 be ``well-behaved''.  The BoundingBox line should be of the form:
167   %%BoundingBox: llx lly urx ury
169 where llx, lly, urx, ury are the coordinates of the lower left x,
170 lower left y, upper right x, upper right y of the bounding box of
171 marks on the page expressed as integers in the default PostScript
172 coordinate system (72 units per inch, origin at bottom left corner).
173 A useful tactic is to print out the illustration by itself (you may
174 need to add a `showpage' at the end), and physically measure the
175 bounding box.  For more detail on these requirements, read the
176 specification of Encapsulated PostScript format.  (This is available
177 from the Adobe file server; send a message with a body of `help' to
178 ps-file-server@adobe.com.)
180 ----------------------------------------------------------------------
182 * I've configured groff for A4 paper, but gtroff still seems to think
183   that the length of a page (as returned by \n(.p) is 11 inches.
185 This is intentional.  The PAGE option is used only by grops.  For
186 compatibility with ditroff, the default page length in gtroff is
187 always 11 inches.  The page length can be changed with the `pl'
188 request.
190 ----------------------------------------------------------------------
192 * Groff doesn't use the font names I'm used to.
194 Use the `ftr' request.  See gtroff(1).
196 ----------------------------------------------------------------------
198 * I get errors using the Unix -ms macros with groff -e -C.
200 Apply this change:
202 *** /usr/lib/ms/ms.eqn  Tue Apr 25 02:14:28 1989
203 --- ms.eqn      Sun Nov 11 10:33:59 1990
204 ***************
205 *** 22,29 ****
206   ..
207   .     \" EN - end of a displayed equation
208   .de EN
209 ! .if !\a\\*(10\a\a .br
210   .di
211   .rm EZ
212   .nr ZN \\n(dn
213   .if \\n(ZN>0 .if \\n(YE=0 .LP
214 --- 22,30 ----
215   ..
216   .     \" EN - end of a displayed equation
217   .de EN
218 ! .if \\n(.k>0 .br
219   .di
220 + .ds 10 \\*(EZ\\
221   .rm EZ
222   .nr ZN \\n(dn
223   .if \\n(ZN>0 .if \\n(YE=0 .LP
225 ----------------------------------------------------------------------
227 * gpic doesn't accept the syntax `chop N M' for chopping both ends of
228   a line.
230 The correct syntax is `chop N chop M'.
232 ----------------------------------------------------------------------
234 * With gpic -t, when I print `line ->; box' using a dvi to ps program,
235   the arrow head sticks through into the inside of the box.
237 The dvi to ps program should be modified to set the line cap and line
238 join parameters to 1 while printing tpic specials.
240 ----------------------------------------------------------------------
242 * When I print the output groff -Tps, the output is always shifted up
243   by about 0.7 inches; I'm using 8.5x11 inch paper.
245 Make sure that PAGE is defined to be `letter' in the top-level
246 Makefile.
248 ----------------------------------------------------------------------
250 * When I try to print the output of groff -Tps, I get no output at all
251   from the printer, and the log file shows the error
252   %%[ error: undefined; offendingcommand: BP ]%%
253   I'm using TranScript spooling software.
255 This is a bug in the page reversal filter in early versions of
256 TranScript.  Change the `broken' parameter in
257 /usr/local/lib/groff/font/devps/DESC to 7.
259 ----------------------------------------------------------------------
261 * When I preview groff -Tps output using the Sun OpenWindows 2.0
262   pageview program, all the pages are displayed on top of each other.
264 This is a defect in pageview.  Change the `broken' parameter in
265 /usr/local/lib/groff/font/devps/DESC to 2.
267 ----------------------------------------------------------------------
269 * With groff -TX75, -TX100 or -X, I can only view the first page.
271 The left mouse button brings up a menu that allows you to view other
272 pages.
274 ----------------------------------------------------------------------
276 * When I print the output of groff -Tdvi, I just get a black dot in
277   upper left corner.
279 Some dvi drivers (notably early versions of xtex) do not correctly
280 handle dvi files that use a resolution different from that used by dvi
281 files produced by TeX.  Try getting a more up to date driver.
283 ----------------------------------------------------------------------
285 * I get lots of errors when I use groff with the AT&T -mm macros.
287 The AT&T -mm macros need a few changes to work with groff; `make
288 install.dwbmm' will copy your -mm macros to groff's macro directory
289 and make the necessary changes.  You may need to edit the commands for
290 the install.mm target in the Makefile.  Alternatively use the groff
291 -mm macros.
293 ----------------------------------------------------------------------
295 * gtroff doesn't understand lines like `.ce99' with no space between
296   the name of the request or macro and the arguments.
298 gtroff requires a space between macro or request and its arguments
299 because it allows the use of long names for macros and requests.  You
300 can use the -C option or the `cp' request to put gtroff into a
301 compatibility mode in which it is not possible to use long names for
302 macros but in which no space is required between macros and their
303 arguments.  The use of compatibility mode is strongly discouraged.
305 ----------------------------------------------------------------------
307 * gtroff gives warnings about lines like
308   .ev   \" a comment
309   (with a tab after the .ev).
311 A tab character cannot be used as a substitute for a space character
312 (except in one case: between a control character at the beginning of a
313 line and the name of a macro or request).  For example, in Unix troff
315   .ps   \" restore the previous point size
317 (with a tab after the .ps) will NOT restore the previous point-size;
318 instead it will be silently ignored.  Since this is very likely to be
319 an error, gtroff can give a warning about it.  If you want to align
320 comments, you can do it like this:
322   .ev\"                         \" a comment
324 ----------------------------------------------------------------------
326 * I don't like the page headers and footers produced by groff -man.
328 There seem to be many different styles of page header and footer
329 produced by different versions of the -man macros.  You will need to
330 modify macros/tmac.an to suit your personal taste.  For example, if
331 you want the center of the page header to say
333   System Programmer's Manual
335 you will need to change the line
337   .el .ds an-extra3 \"System Programmer's Manual
341   .el .ds an-extra3 System Programmer's Manual
343 ----------------------------------------------------------------------
345 * While formatting a manual page, groff complains about not being able
346   to break lines.  The problem seems to be caused by a line like:
347   .TP \w'label'+2
349 The -man documentation says that the default scale indicator for TP
350 macro is `n'.  The groff -man macros implement this correctly, so that
351 the argument will be evaluated as if it were
353   \w'label'n+2n
355 The Unix -man macros don't implement this correctly (probably because
356 it's hard to do in Unix troff); they just append `n' to the entire
357 argument, so that it will be evaluated as if it were
359   \w'label'u+2n
361 The solution is to fix the manual page:
363   .TP \w'label'u+2
365 ----------------------------------------------------------------------
367 * I'm having problems formatting Ultrix man pages with groff -man.
369 The Ultrix man pages use a number of non-standard extensions to the
370 Unix man macros.  One solution is to use the Ultrix -man macros with
371 groff.  Rename /usr/local/lib/groff/tmac/tmac.an to
372 /usr/local/lib/groff/tmac/tmac.an.gnu, copy /usr/lib/tmac/tmac.an to
373 /usr/local/lib/groff/tmac/tmac.an and apply the following patch (from
374 Frank Wortner):
376 *** /usr/local/lib/groff/tmac/tmac.an     Wed Sep  9 12:29:28 1992
377 --- /usr/lib/tmac/tmac.an       Fri Jul 24 19:58:19 1992
378 ***************
379 *** 489,495 ****
380   .     \" make special case of shift out of italic
381   .de }S
382   .ds ]F
383 ! .if \\$12 .if !\\$5 .ds ]F \^
384   .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
385   .el \\$3
386   .}f
387 --- 489,495 ----
388   .     \" make special case of shift out of italic
389   .de }S
390   .ds ]F
391 ! .if \\$12 .if !\\$5 .ds ]F\^
392   .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
393   .el \\$3
394   .}f
396 Another possible solution is to install tmac/man.ultrix as
397 /usr/local/lib/groff/tmac/man.local.
399 ----------------------------------------------------------------------
401 * I'm having problems formatting HP-UX 9.0 man pages with groff -man.
403 Rename /usr/local/lib/groff/tmac/tmac.an to (for example)
404 /usr/local/lib/groff/tmac/tmac.gan, copy HP's tmac.an into
405 /usr/local/lib/groff/tmac/tmac.an, and either put `.cp 1' at the
406 beginning or filter it (and any files it .so's) through
407 tmac/fixmacros.sed.
409 ----------------------------------------------------------------------
411 * I'm having problems formatting man pages produced by the perl
412   wrapman script.
414 Some versions of wrapman have a superfluous blank line before the .TH
415 line.  This must be deleted.  Then either use groff -C, or apply the
416 following patch:
418 *** wrapman.~2~ Sun Jan 19 12:10:24 1992
419 --- wrapman     Tue Aug 10 02:06:41 1993
420 ***************
421 *** 35,41 ****
422       $line1 .= <IN> if $line1 =~ /eval/;
423       $line1 .= <IN> if $line1 =~ /argv/;
424       $line2 = <IN>;
425 !     next if $line2 eq "'di';\n";
426   
427       # Pull the old switcheroo.
428   
429 --- 35,41 ----
430       $line1 .= <IN> if $line1 =~ /eval/;
431       $line1 .= <IN> if $line1 =~ /argv/;
432       $line2 = <IN>;
433 !     next if $line2 eq "'di ';\n" || $line2 eq "'di';\n";
434   
435       # Pull the old switcheroo.
436   
437 ***************
438 *** 49,56 ****
439   
440       print OUT $line1;
441       print OUT <<EOF;
442 ! 'di';
443 ! 'ig00';
444   #
445   # $header
446   #
447 --- 49,58 ----
448   
449       print OUT $line1;
450       print OUT <<EOF;
451 ! 'di ';
452 ! 'ds 00 \\"';
453 ! 'eo ';
454 ! 'ig 00 ';
455   #
456   # $header
457   #
458 ***************
459 *** 72,85 ****
460   
461       # These next few lines are legal in both Perl and nroff.
462   
463 ! $null.00;                       # finish .ig
464    
465   'di           \\" finish diversion--previous line must be blank
466   .nr nl 0-1    \\" fake up transition to first page again
467   .nr % 0         \\" start at page 1
468 ! '; __END__ ##### From here on it's a standard manual page #####
469   .TH $PROG 1 "$month $mday, 19$year"
470 - .AT 3
471   .SH NAME
472   $prog \\- whatever
473   .SH SYNOPSIS
474 --- 74,87 ----
475   
476       # These next few lines are legal in both Perl and nroff.
477   
478 ! $null.00 ;                      # finish .ig
479 ! 'ec \\';
480    
481   'di           \\" finish diversion--previous line must be blank
482   .nr nl 0-1    \\" fake up transition to first page again
483   .nr % 0         \\" start at page 1
484 ! .\\"'; __END__ ##### From here on it's a standard manual page #####
485   .TH $PROG 1 "$month $mday, 19$year"
486   .SH NAME
487   $prog \\- whatever
488   .SH SYNOPSIS
491 ----------------------------------------------------------------------
493 * When I preview documents using -TX75 or -TX100, the layout is not
494   the same as when I print the document with -Tps: the line and page
495   breaks come in different places.
497 Use groff -X -Tps.
499 ----------------------------------------------------------------------
501 * When I try to run gxditview, I get the error:
502   Error: Widget viewport has zero width and/or height
504 This error means you haven't correctly installed the application
505 defaults file, GXditview.ad; ``make install'' does this for you
506 automatically, so either you didn't do ``make install'', or you don't
507 have imake configured correctly.
509 ----------------------------------------------------------------------
511 * groff uses up an enormous amount of memory processing large files.
512   I'm using 386BSD 0.1.
514 386BSD includes an old version of g++, 1.39, which has a bug that
515 causes a major memory leak in gtroff.  Apply the following fix to g++
516 and recompile groff:
518 *** cplus-decl.c.~1~    Mon Aug  6 05:28:59 1990
519 --- cplus-decl.c        Wed Jun  5 08:55:04 1991
520 ***************
521 *** 7951,7961 ****
522   
523         /* At the end, call delete if that's what's requested.  */
524         if (TREE_GETS_DELETE (current_class_type))
525         exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
526                                       get_identifier (OPERATOR_DELETE_FORMAT),
527 !                                     build_tree_list (NULL_TREE, integer_zero_node),
528                                       NULL_TREE, LOOKUP_NORMAL);
529         else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
530         exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
531         else
532         exprstmt = 0;
533 --- 7951,7961 ----
534   
535         /* At the end, call delete if that's what's requested.  */
536         if (TREE_GETS_DELETE (current_class_type))
537         exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
538                                       get_identifier (OPERATOR_DELETE_FORMAT),
539 !                                     build_tree_list (NULL_TREE, current_class_decl),
540                                       NULL_TREE, LOOKUP_NORMAL);
541         else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
542         exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
543         else
544         exprstmt = 0;
546 ----------------------------------------------------------------------
548 * Where can I get grap?
550 Ted Faber <faber@lunabase.org> has written a freely available grap:
552   http://www.lunabase.org/~faber/Vault/software/grap/
554 ----------------------------------------------------------------------
556 * How can I use groff with an old LaserJet printer that doesn't work
557   with groff -Tlj4?
559 You have at least 3 options:
561 - use groff -Tps with GNU Ghostscript;
563 - use groff -Tdvi with a TeX .dvi to Laserjet driver;
565 - use groff with the LaserJet driver in Chris Lewis' psroff package
566   (available for ftp from:
567   ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17).
569 ----------------------------------------------------------------------
571 * Groff seems to generate level 3 Postscript, but my printer is only a
572   level 1 or 2 PostScript printer.
574 In fact groff generates only level 1 PostScript.  The `%!PS-Adobe-3.0'
575 comment at the beginning of PostScript output generated by groff
576 indicates that the file conforms to version 3.0 of the Adobe Document
577 Structuring Conventions.  The output generated by groff should be
578 printable on any PostScript printer.  Problems with groff output's not
579 printing are most often caused by the spooling system.
581 ----------------------------------------------------------------------
583 * The \n(st and \n(sb registers don't seem to work.  I thought \w set
584   them to the height and depth of its argument, but the registers
585   always seem to be 0.
587 \n(st and \n(sb aren't supposed to give the height and depth of the
588 string rather they give the minimum and maximum vertical displacement
589 of the baseline.  For example for \v'2u'\v'-3u', \n(st will be 1 and
590 \n(sb will be -2.  The height and depth of the string is available in
591 the \n[rst] and \n[rsb] registers: these are groff extensions.
593 ----------------------------------------------------------------------
595 * On an SGI system, how can I make the man command use groff?
597 From David Hinds <dhinds@allegro.stanford.edu> (some of these steps
598 are unnecessary if you install with the `g' Makefile variable defined
599 as empty):
601 Create a script called 'eqn':
603  > #!/bin/sh
604  > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
605  > geqn $*
607 and a script called 'neqn':
609  > #!/bin/sh
610  > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
611  > geqn -Tascii $*
613 and do:
615  > ln -s gnroff nroff
617 and edit the end of the gnroff script to be:
619  > rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
620  > exec groff -Wall -mtty-char $T $opts $rest
622 To get PostScript output from 'man -t', you also need to create a
623 'psroff' script similar to 'nroff'.  Here are the context diffs:
625 *** /usr/local/bin/nroff        Sat Feb 13 15:51:09 1993
626 --- /usr/local/bin/psroff       Sat Feb 13 17:45:46 1993
627 ***************
628 *** 1,8 ****
629   #!/bin/sh
630 ! # Emulate nroff with groff.
632   prog="$0"
633 ! T=-Tascii
634   opts=
636   for i
637 --- 1,8 ----
638   #!/bin/sh
639 ! # Emulate psroff with groff.
641   prog="$0"
642 ! T=-Tps
643   opts=
645   for i
646 ***************
647 *** 25,30 ****
648 --- 25,33 ----
649         -Tascii|-Tlatin1)
650                 T=$1
651                 ;;
652 +       -t)
653 +               # ignore -- default is send to stdout
654 +               ;;
655         -T*)
656                 # ignore other devices
657                 ;;
658 ***************
659 *** 49,53 ****
660   rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
662   # This shell script is intended for use with man, so warnings are
663   # probably not wanted.  Also load nroff-style character definitions.
664 ! exec groff -Wall -mtty-char $T $opts $rest
665 --- 52,56 ----
666   rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
668   # This shell script is intended for use with man, so warnings are
669 ! # probably not wanted.
670 ! exec groff -Wall $T $opts $rest