/contrib/groff/PROBLEMS

  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
  8
  9Generic Problems
 10================
 11
 12
 13
 14* Displaying a man page on a terminal with/without my favourite pager
 15  only gives garbage.
 16
 17groff by default now uses SGR escape sequences (`ANSI color') to
 18control the display attributes (bold, underlined, colour) on TTYs. 
 19Some 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
 21understand SGR either.  There are three solutions to fix this, in order
 22of preference; please read the grotty man page for more details.
 23
 24The fourth and probably best option is to update your terminal program
 25and pager to versions which can handle SGR.
 26
 27  1. Set the GROFF_NO_SGR environment variable.
 28
 29  2. Pass option -c to grotty.
 30
 31  3. Append the following fragment to the `troffrc' file:
 32
 33
 34--- start ---
 35.if n \{\
 36.  nr _C \n(.C
 37.  cp 0
 38.
 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.
 43.
 44.  de sgr@dummy
 45.  .
 46.
 47.  rn wh wh@old
 48.
 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.
 53.  de1 no@sgr
 54.    if \\n[.P] \{\
 55.      if (\\n[.t] == \\n[.p]) \{\
 56.        rn wh@old wh
 57.        rm no@sgr
 58.        wh 0
 59.        sp \\n[.trunc]
 60.        nop \X'tty: sgr 0'
 61.        sp -1
 62.    \}\}
 63.  .
 64.
 65.  wh@old 0 no@sgr
 66.
 67.  \" The piggyback version to be appended to macros planted with the
 68.  \" modified `wh' request.
 69.  de1 no@sgr1
 70.    if \\n[.P] \{\
 71.      rn wh@old wh
 72.      ds no@sgr1
 73.      nop \X'tty: sgr 0'
 74.      sp -1
 75.    \}
 76.  .
 77.
 78.  \" We redefine the `wh' request so that `no@sgr1' is appended to
 79.  \" the trap macro.
 80.  de1 wh
 81.    am1 \\$2 sgr@dummy
 82.      no@sgr1
 83.    sgr@dummy
 84.    wh@old \\$1 \\$2
 85.  .
 86.
 87.  cp \n[_C]
 88.\}
 89--- end ---
 90
 91----------------------------------------------------------------------
 92
 93* The UTF-8 output of grotty has strange characters for the minus, the
 94  hyphen, and the right quote.  Why?
 95
 96The used Unicode characters (U+2212 for the minus sign and U+2010 for
 97the hyphen) are the correct ones, but many programs can't search them
 98properly.  The same is true for the right quote (U+201D).  To map those
 99characters back to the ASCII characters, insert the following code
100snippet into the `troffrc' configuration file:
101
102.if '\*[.T]'utf8' \{\
103.  char \- \N'45'
104.  char  - \N'45'
105.  char  ' \N'39'
106.\}
107
108
109----------------------------------------------------------------------
110
111* My document says that the current year is 19100, not 2000.
112
113In groff, as in traditional troff, the yr number register yields the
114year minus 1900.  Unfortunately, there is a longstanding bug in the
115Troff User's Manual <http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz>,
116which incorrectly claims that yr is the last two digits of the year.
117This claim was never true of either Unix troff or of groff.
118
119If your text looks like this:
120
121	.\" Wrong:
122	This document was formatted in 19\n(yr.
123
124you can correct it as follows:
125
126	This document was formatted in \n[year].
127
128or, if you want to be portable to older troff versions, as follows:
129
130	.nr y4 1900+\n(yr
131	This document was formatted in \n(y4.
132
133----------------------------------------------------------------------
134
135* groff can't handle my troff document.  It works fine with AT&T
136  troff.
137
138Read the section on incompatibilities in groff_diff(7).  Try using
139the -C option.  Alternatively there's the sed script
140`tmac/fixmacros.sed' which will attempt to edit a file of macros so
141that it can be used with groff without the -C flag.
142
143----------------------------------------------------------------------
144
145* gtroff doesn't understand lines like `.ce99' with no space between
146  the name of the request or macro and the arguments.
147
148gtroff requires a space between macro or request and its arguments
149because it allows the use of long names for macros and requests.  You
150can use the -C option or the `cp' request to put gtroff into a
151compatibility mode in which it is not possible to use long names for
152macros but in which no space is required between macros and their
153arguments.  The use of compatibility mode is strongly discouraged.
154
155----------------------------------------------------------------------
156
157* groff -Tdvi produces dvi files that use fonts at weird
158  magnifications.
159
160Yes, it does.  You may need to compile fonts with Metafont at these
161magnifications.  The CompileFonts script in the devdvi/generate
162directory may help you to do this.  (It will take a *long* time on
163slow computers.)
164
165----------------------------------------------------------------------
166
167* Groff doesn't use the font names I'm used to.
168
169Use the `ftr' request.  See groff_diff(7).
170
171----------------------------------------------------------------------
172
173* pic output is not centered horizontally; pictures sometimes run off
174  the bottom of the page.
175
176The macro package you are using is not supplying appropriate
177definitions of PS and PE.  Give groff a -mpic option.
178
179----------------------------------------------------------------------
180
181* gpic doesn't accept the syntax `chop N M' for chopping both ends of
182  a line.
183
184The correct syntax is `chop N chop M'.
185
186----------------------------------------------------------------------
187
188* With gpic -t, when I print `line ->; box' using a dvi to ps program,
189  the arrow head sticks through into the inside of the box.
190
191The dvi to ps program should be modified to set the line cap and line
192join parameters to 1 while printing tpic specials.
193
194----------------------------------------------------------------------
195
196* gtroff gives warnings about lines like
197  .ev	\" a comment
198  (with a tab after the .ev).
199
200A tab character cannot be used as a substitute for a space character
201(except in one case: between a control character at the beginning of a
202line and the name of a macro or request).  For example, in Unix troff
203
204  .ps	\" restore the previous point size
205
206(with a tab after the .ps) will NOT restore the previous point-size;
207instead it will be silently ignored.  Since this is very likely to be
208an error, gtroff can give a warning about it.  If you want to align
209comments, you can do it like this:
210
211  .ev\"				\" a comment
212
213----------------------------------------------------------------------
214
215* I don't like the page headers and footers produced by groff -man.
216
217There seem to be many different styles of page header and footer
218produced by different versions of the -man macros.  You will need to
219put modified macros from tmac/an-old.tmac into man.local.  More
220information is available in groff_man(7).
221
222----------------------------------------------------------------------
223
224* Where can I get grap?
225
226Ted Faber <faber@lunabase.org> has written a freely available grap:
227
228  http://www.lunabase.org/~faber/Vault/software/grap/
229
230----------------------------------------------------------------------
231
232* The \n(st and \n(sb registers don't seem to work.  I thought \w set
233  them to the height and depth of its argument, but the registers
234  always seem to be 0.
235
236\n(st and \n(sb aren't supposed to give the height and depth of the
237string rather they give the minimum and maximum vertical displacement
238of the baseline.  For example for \v'2u'\v'-3u', \n(st will be 1 and
239\n(sb will be -2.  The height and depth of the string is available in
240the \n[rst] and \n[rsb] registers: these are groff extensions.
241
242----------------------------------------------------------------------
243
244* While formatting a manual page, groff complains about not being able
245  to break lines.  The problem seems to be caused by a line like:
246  .TP \w'label'+2
247
248The -man documentation says that the default scale indicator for TP
249macro is `n'.  The groff -man macros implement this correctly, so that
250the argument will be evaluated as if it were
251
252  \w'label'n+2n
253
254The Unix -man macros don't implement this correctly (probably because
255it's hard to do in Unix troff); they just append `n' to the entire
256argument, so that it will be evaluated as if it were
257
258  \w'label'u+2n
259
260The solution is to fix the manual page:
261
262  .TP \w'label'u+2
263
264----------------------------------------------------------------------
265
266* I'm having problems formatting man pages produced by the perl
267  wrapman script.
268
269Some versions of wrapman have a superfluous blank line before the .TH
270line.  This must be deleted.  Then either use groff -C, or apply the
271following patch:
272
273*** wrapman.~2~	Sun Jan 19 12:10:24 1992
274--- wrapman	Tue Aug 10 02:06:41 1993
275***************
276*** 35,41 ****
277      $line1 .= <IN> if $line1 =~ /eval/;
278      $line1 .= <IN> if $line1 =~ /argv/;
279      $line2 = <IN>;
280!     next if $line2 eq "'di';\n";
281  
282      # Pull the old switcheroo.
283  
284--- 35,41 ----
285      $line1 .= <IN> if $line1 =~ /eval/;
286      $line1 .= <IN> if $line1 =~ /argv/;
287      $line2 = <IN>;
288!     next if $line2 eq "'di ';\n" || $line2 eq "'di';\n";
289  
290      # Pull the old switcheroo.
291  
292***************
293*** 49,56 ****
294  
295      print OUT $line1;
296      print OUT <<EOF;
297! 'di';
298! 'ig00';
299  #
300  # $header
301  #
302--- 49,58 ----
303  
304      print OUT $line1;
305      print OUT <<EOF;
306! 'di ';
307! 'ds 00 \\"';
308! 'eo ';
309! 'ig 00 ';
310  #
311  # $header
312  #
313***************
314*** 72,85 ****
315  
316      # These next few lines are legal in both Perl and nroff.
317  
318! $null.00;                       # finish .ig
319   
320  'di           \\" finish diversion--previous line must be blank
321  .nr nl 0-1    \\" fake up transition to first page again
322  .nr % 0         \\" start at page 1
323! '; __END__ ##### From here on it's a standard manual page #####
324  .TH $PROG 1 "$month $mday, 19$year"
325- .AT 3
326  .SH NAME
327  $prog \\- whatever
328  .SH SYNOPSIS
329--- 74,87 ----
330  
331      # These next few lines are legal in both Perl and nroff.
332  
333! $null.00 ;                      # finish .ig
334! 'ec \\';
335   
336  'di           \\" finish diversion--previous line must be blank
337  .nr nl 0-1    \\" fake up transition to first page again
338  .nr % 0         \\" start at page 1
339! .\\"'; __END__ ##### From here on it's a standard manual page #####
340  .TH $PROG 1 "$month $mday, 19$year"
341  .SH NAME
342  $prog \\- whatever
343  .SH SYNOPSIS
344
345----------------------------------------------------------------------
346
347* groff uses up an enormous amount of memory processing large files.
348  I'm using 386BSD 0.1.
349
350386BSD includes an old version of g++, 1.39, which has a bug that
351causes a major memory leak in gtroff.  Apply the following fix to g++
352and recompile groff:
353
354*** cplus-decl.c.~1~	Mon Aug  6 05:28:59 1990
355--- cplus-decl.c	Wed Jun  5 08:55:04 1991
356***************
357*** 7951,7961 ****
358  
359        /* At the end, call delete if that's what's requested.  */
360        if (TREE_GETS_DELETE (current_class_type))
361  	exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
362  				      get_identifier (OPERATOR_DELETE_FORMAT),
363! 				      build_tree_list (NULL_TREE, integer_zero_node),
364  				      NULL_TREE, LOOKUP_NORMAL);
365        else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
366  	exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
367        else
368  	exprstmt = 0;
369--- 7951,7961 ----
370  
371        /* At the end, call delete if that's what's requested.  */
372        if (TREE_GETS_DELETE (current_class_type))
373  	exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
374  				      get_identifier (OPERATOR_DELETE_FORMAT),
375! 				      build_tree_list (NULL_TREE, current_class_decl),
376  				      NULL_TREE, LOOKUP_NORMAL);
377        else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
378  	exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
379        else
380  	exprstmt = 0;
381
382
383
384Printing and Display Problems
385=============================
386
387
388
389* I'm having problems including PostScript illustrations (EPS) using
390  the PSPIC macro and/or \X'ps: import ...'.
391
392A PostScript document must meet three requirements in order to be
393included with the PSPIC macro: it must comply with the Adobe Document
394Structuring Conventions; it must contain a BoundingBox line; it must
395be `well-behaved'.  The BoundingBox line should be of the form:
396
397  %%BoundingBox: llx lly urx ury
398
399where llx, lly, urx, ury are the coordinates of the lower left x,
400lower left y, upper right x, upper right y of the bounding box of
401marks on the page expressed as integers in the default PostScript
402coordinate system (72 units per inch, origin at bottom left corner).
403
404The most convenient program to get the bounding box of a document is
405the `ps2epsi' script coming with GhostScript.
406
407If you can't use this program, another useful tactic is to print out
408the illustration by itself (you may need to add a `showpage' at the
409end), and physically measure the bounding box.  For more detail on
410these requirements, read the specification of Encapsulated PostScript
411format.  (This is available from the Adobe file server; send a message
412with a body of `help' to ps-file-server@adobe.com.)
413
414If an EPS file to be included via \X'ps: import' does not start with
415`%!PS-Adobe-...', gtroff will still include the file, but grops will
416not add any fonts to the generated output file that are listed in the
417EPS file, even though the files are listed in the `download' file and
418are available in the devps directory.
419
420----------------------------------------------------------------------
421
422* I've configured groff for A4 paper, but gtroff still seems to think
423  that the length of a page (as returned by `\n(.p') is 11 inches.
424
425This is intentional.  The PAGE option during configuration is used
426only by grops.  For compatibility with ditroff, the default page
427length in gtroff is always 11 inches.  The page length can be changed
428with the `pl' request.
429
430A convenient way to set paper dimensions is to use the -dpaper option
431of groff, together with proper -P options for the postprocessor
432(overriding the default).  For example, use the following for PS
433output on A4 paper in landscape orientation:
434
435  groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
436
437See groff_tmac(5) for more information.
438
439----------------------------------------------------------------------
440
441* When I print the output of groff -Tps, the output is always shifted
442  up by about 0.7 inches; I'm using 8.5x11 inch paper.
443
444Make sure that the paper size is `letter'.  See groff_tmac(5).
445
446----------------------------------------------------------------------
447
448* When I try to run gxditview, I get the error:
449  Error: Widget viewport has zero width and/or height
450
451This error means you haven't correctly installed the application
452defaults file, GXditview.ad; `make install' does this for you
453automatically, so either you didn't do `make install', or you haven't
454passed a good `--appresdir=<DIR>' argument to groff's configure script.
455
456See the X(7) man page for information how and where application resource
457files have to be located.  Look for the XAPPLRESDIR and XUSERFILESEARCHPATH
458environment variables.
459
460----------------------------------------------------------------------
461
462* When I preview documents using -TX75 or -TX100, the layout is not
463  the same as when I print the document with -Tps: the line and page
464  breaks come in different places.
465
466Use `groff -X -Tps'.
467
468----------------------------------------------------------------------
469
470* When I try to print the output of groff -Tps, I get no output at all
471  from the printer, and the log file shows the error
472  %%[ error: undefined; offendingcommand: BP ]%%
473  I'm using TranScript spooling software.
474
475This is a bug in the page reversal filter in early versions of
476TranScript.  Change the `broken' parameter in
477/usr/local/lib/groff/font/devps/DESC to 7.
478
479----------------------------------------------------------------------
480
481* When I preview groff -Tps output using the Sun OpenWindows 2.0
482  pageview program, all the pages are displayed on top of each other.
483
484This is a defect in pageview.  Change the `broken' parameter in
485/usr/local/lib/groff/font/devps/DESC to 2.
486
487----------------------------------------------------------------------
488
489* With groff -TX75, -TX100 or -X, I can only view the first page.
490
491The left mouse button brings up a menu that allows you to view other
492pages.
493
494----------------------------------------------------------------------
495
496* When I print the output of groff -Tdvi, I just get a black dot in
497  upper left corner.
498
499Some dvi drivers (notably early versions of xtex) do not correctly
500handle dvi files that use a resolution different from that used by dvi
501files produced by TeX.  Try getting a more up to date driver.
502
503----------------------------------------------------------------------
504
505* How can I use groff with an old LaserJet printer that doesn't work
506  with groff -Tlj4?
507
508You have at least 3 options:
509
510- use groff -Tps with GNU Ghostscript;
511
512- use groff -Tdvi with a TeX .dvi to Laserjet driver;
513
514- use groff with the LaserJet driver in Chris Lewis' psroff package
515  (available for ftp from:
516  ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17).
517
518----------------------------------------------------------------------
519
520* Groff seems to generate level 3 Postscript, but my printer is only a
521  level 1 or 2 PostScript printer.
522
523In fact groff generates only level 2 PostScript (or rather level 1
524with some extensions; see grops(1) for more information how to disable
525them).  The `%!PS-Adobe-3.0' comment at the beginning of PostScript
526output generated by groff indicates that the file conforms to
527version 3.0 of the Adobe Document Structuring Conventions.  The output
528generated by groff should be printable on any PostScript printer.
529Problems with groff output's not printing are most often caused by the
530spooling system.
531
532
533
534Platform-Dependent Macro Problems
535=================================
536
537
538
539* I get lots of errors when I use groff with the AT&T -mm macros.
540
541Use the groff -mm macros.
542
543----------------------------------------------------------------------
544
545* groff produces wrapper macros for `ms' and friends which call the
546  system's original macros.  Then, to get groff's ms macro package I
547  have to use `-mgs' instead `-ms'.  Can I avoid this?
548
549Yes.  Configure and compile groff as usual, but install it with
550
551  make install tmac_wrap=""
552
553Then no wrapper files are produced, and `-ms' will use groff's `ms'
554macros.
555
556----------------------------------------------------------------------
557
558* I'm having problems formatting HP-UX 9.0 man pages with groff -man.
559
560Copy HP's tmac.an into /usr/local/share/groff/site-tmac/an.tmac, and
561either put `.cp 1' at the beginning or filter it (and any files it
562.so's) through tmac/fixmacros.sed.
563
564----------------------------------------------------------------------
565
566* I get errors using the Unix -ms macros with groff -e -C.
567
568Apply this change:
569
570*** /usr/lib/ms/ms.eqn	Tue Apr 25 02:14:28 1989
571--- ms.eqn	Sun Nov 11 10:33:59 1990
572***************
573*** 22,29 ****
574  ..
575  .	\" EN - end of a displayed equation
576  .de EN
577! .if !\\*(10 .br
578  .di
579  .rm EZ
580  .nr ZN \\n(dn
581  .if \\n(ZN>0 .if \\n(YE=0 .LP
582--- 22,30 ----
583  ..
584  .	\" EN - end of a displayed equation
585  .de EN
586! .if \\n(.k>0 .br
587  .di
588+ .ds 10 \\*(EZ\\
589  .rm EZ
590  .nr ZN \\n(dn
591  .if \\n(ZN>0 .if \\n(YE=0 .LP
592
593----------------------------------------------------------------------
594
595* I'm having problems formatting Ultrix man pages with groff -man.
596
597The Ultrix man pages use a number of non-standard extensions to the
598Unix man macros.  One solution is to use the Ultrix -man macros with
599groff.  Copy /usr/lib/tmac/tmac.an to
600/usr/local/share/groff/site-tmac/an.tmac and apply the following patch
601(from Frank Wortner):
602
603*** /usr/local/lib/groff/tmac/tmac.an     Wed Sep  9 12:29:28 1992
604--- /usr/lib/tmac/tmac.an       Fri Jul 24 19:58:19 1992
605***************
606*** 489,495 ****
607  .     \" make special case of shift out of italic
608  .de }S
609  .ds ]F
610! .if \\$12 .if !\\$5 .ds ]F \^
611  .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
612  .el \\$3
613  .}f
614--- 489,495 ----
615  .     \" make special case of shift out of italic
616  .de }S
617  .ds ]F
618! .if \\$12 .if !\\$5 .ds ]F\^
619  .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
620  .el \\$3
621  .}f
622
623Another possible solution is to install tmac/man.ultrix as
624/usr/local/share/groff/site-tmac/man.local.
625
626----------------------------------------------------------------------
627
628* On an SGI system, how can I make the man command use groff?
629
630From David Hinds <dhinds@allegro.stanford.edu> (some of these steps
631are unnecessary if you install with the `g' Makefile variable defined
632as empty):
633
634Create a script called 'eqn':
635
636 > #! /bin/sh
637 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
638 > geqn $*
639
640and a script called 'neqn':
641
642 > #! /bin/sh
643 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
644 > geqn -Tascii $*
645
646and do:
647
648 > ln -s gnroff nroff
649
650and edit the end of the gnroff script to be:
651
652 > rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
653 > exec groff -Wall -mtty-char $T $opts $rest
654
655To get PostScript output from 'man -t', you also need to create a
656'psroff' script similar to 'nroff'.  Here are the context diffs:
657
658*** /usr/local/bin/nroff        Sat Feb 13 15:51:09 1993
659--- /usr/local/bin/psroff       Sat Feb 13 17:45:46 1993
660***************
661*** 1,8 ****
662  #! /bin/sh
663! # Emulate nroff with groff.
664
665  prog="$0"
666! T=-Tascii
667  opts=
668
669  for i
670--- 1,8 ----
671  #! /bin/sh
672! # Emulate psroff with groff.
673
674  prog="$0"
675! T=-Tps
676  opts=
677
678  for i
679***************
680*** 25,30 ****
681--- 25,33 ----
682        -Tascii|-Tlatin1)
683                T=$1
684                ;;
685+       -t)
686+               # ignore -- default is send to stdout
687+               ;;
688        -T*)
689                # ignore other devices
690                ;;
691***************
692*** 49,53 ****
693  rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
694
695  # This shell script is intended for use with man, so warnings are
696  # probably not wanted.  Also load nroff-style character definitions.
697! exec groff -Wall -mtty-char $T $opts $rest
698--- 52,56 ----
699  rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
700
701  # This shell script is intended for use with man, so warnings are
702! # probably not wanted.
703! exec groff -Wall $T $opts $rest
704
705
706
707Compilation Problems
708====================
709
710
711
712* Compilation dies with
713
714    y.tab.c: In function `int yyparse()':
715    y.tab.c: `size_t' undeclared in namespace `std'
716
717* bison reports conflicts (either on stderr or in the `pic.output'
718  file) while processing `pic.y', and the produced pic binary doesn't
719  work at all.
720
721You need bison version 1.875b or greater.  Alternatively, use yacc or
722byacc.
723
724----------------------------------------------------------------------
725
726* There are many empty `Makefile.dep' files.  Is this a bug?
727
728No.  Real dependency files are created with a `make depend' call.
729
730----------------------------------------------------------------------
731
732* On HP-UX, the compiler complains about missing symbol `alloca'.
733
734Say
735
736  export LDFLAGS=-lPW
737
738before starting the configure script.
739
740----------------------------------------------------------------------
741
742* The configure script fails on OS/390 (z/OS) Unix.
743
744[This has been fixed in z/OS V1R3 (aka OS/390 R13).]
745
746There is a bug in the Language Environment (LE) whereby the test
747program for static destructors fails.  You will see the message
748`configure: error: a working C++ compiler is required'
749
750Applying PTF UQ42006 is supposed to fix this, but the test program is
751still returning the wrong value (1).  To work around this problem, you
752can comment out the following in the configure script (near line 2029).
753This will effectively bypass the test (static constructors and
754destructors do actually work properly):
755
756#if { (eval echo "$as_me:2029: \"$ac_link\"") >&5
757#  (eval $ac_link) 2>&5
758#  ac_status=$?
759#  echo "$as_me:2032: \$? = $ac_status" >&5
760#  (exit $ac_status); } && { ac_try='./conftest$ac_exeext'
761#  { (eval echo "$as_me:2034: \"$ac_try\"") >&5
762#  (eval $ac_try) 2>&5
763#  ac_status=$?
764#  echo "$as_me:2037: \$? = $ac_status" >&5
765#  (exit $ac_status); }; }; then
766#  echo "$as_me:2039: result: yes" >&5
767#echo "${ECHO_T}yes" >&6
768#else
769#  echo "$as_me: program exited with status $ac_status" >&5
770#echo "$as_me: failed program was:" >&5
771#cat conftest.$ac_ext >&5
772#echo "$as_me:2045: result: no" >&5
773#echo "${ECHO_T}no" >&6;{ { echo "$as_me:2046: error: a working C++ compiler is required" >&5
774#echo "$as_me: error: a working C++ compiler is required" >&2;}
775#   { (exit 1); exit 1; }; }
776#fi
777
778----------------------------------------------------------------------
779
780* I get errors when I try to compile groff with DEC C++.
781
782Fix the declaration of write() in <unistd.h> so that the second
783argument is a const char *.  Fix the declaration of open() in
784<sys/file.h> so that the first argument is a const char *.
785
786----------------------------------------------------------------------
787
788* On a host using Unix make (e.g. Solaris), if you are compiling for
789  multiple architectures by building in a subdirectory, the make stops
790  with a message like this:
791
792    make: Fatal error: Don't know how to make target `assert.o'
793
794  or like this:
795
796    make: Fatal error: Can't find /u/src/groff/src/include/Makefile.sub': No such file or directory
797
798This occurs because GNU make and Unix make handle VPATH differently,
799and the groff build relies on GNU make's VPATH handling.
800
801Use GNU make <http://www.gnu.org/software/make/> to work around this.
802In Solaris 8 and 9, GNU make is on the Software Companion CD in
803package SFWgmake and is installed as /opt/sfw/bin/gmake.  Prebuilt
804versions of GNU make for Solaris are also available from
805sunfreeware.com.
806
807----------------------------------------------------------------------
808
809* On Ultrix, the make program stops with the message
810
811    *** Error code 1
812
813    Stop.
814
815  for no apparent reason.
816
817Use GNU make.
818
819----------------------------------------------------------------------
820
821* I'm having problems compiling groff on 386BSD 0.1.
822
823If you're using ash as /bin/sh, you'll need the following patch.
824
825*** gendef.sh.org	Sun Jun 30 13:30:36 1991
826--- gendef.sh	Sun Feb 28 10:23:49 1993
827***************
828*** 3,9 ****
829  file=$1
830  shift
831  
832! defs="#define $1"
833  shift
834  for def
835  do
836--- 3,10 ----
837  file=$1
838  shift
839  
840! x=$1
841! defs="#define $x"
842  shift
843  for def
844  do
845
846You'll also need to change dirnamemax.c so that it doesn't use
847pathconf().
848
849----------------------------------------------------------------------
850
851* While compiling on Xenix, ranlib libgroff.a fails.
852
853The system ranlib can't handle externals longer than 40 characters.
854Use the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1
855instead.
856
857----------------------------------------------------------------------
858
859* I get errors when I try to compile groff with Sun C++ version 3 or
860  earlier.
861
862Groff requires header files that are moderately compatible with AT&T
863C++ and ANSI C.  With some versions of Sun C++, the supplied header
864files need some of the following changes to meet this requirement:
865<string.h> must declare the mem* functions, (just add `#include
866<memory.h>' to <string.h>); the first argument to fopen and freopen
867should be declared as `const char *'; the first argument to fread
868should be declared as `void *'; the first argument to fwrite should be
869declared as `const void *'; malloc should be declared to return
870`void *'; in <alloca.h>, the declaration `extern "C" { void
871*__builtin_alloca(int); }' should be added; in <sys/signal.h> the
872return type and the second argument type of signal() should be changed
873to be `void (*)(int)'.
874
875You can either change them in place, or copy them to some other
876directory and include that directory with a -I option.
877
878----------------------------------------------------------------------
879
880* I get errors when I try to compile groff with Forte Development 6
881  or 6u1, or Sun C++ version 5.0 through 5.2.
882
883This is a known problem; see Sun bug #4301919.  See Sun patches
884109482, 109490, 109508, and 109509 for fixes.
885
886----------------------------------------------------------------------
887
888* I get warnings from the Sun linker while using gcc 3.4.0:
889
890  ld: warning: relocation error: R_SPARC_UA32:
891      file groff/src/libs/libgroff/libgroff.a(getopt.o): symbol optarg:
892      external symbolic relocation against non-allocatable
893      section .debug_info; cannot be processed at runtime:
894      relocation ignored
895
896This seems to be a known problem (Sun bugs #4910101 and #4910810,
897filed in September 2003; gcc bug #15599, filed May 2004) without a
898public fix as of this writing.  A work-around is to use option
899`-gstabs+' instead of `-g' (and a high probability that the output is
900only debuggable with gdb but not with Sun's debuggers).
901
902----------------------------------------------------------------------
903
904* I get lots of `numeric overflow' error messages whenever I run
905  groff; I compiled groff with AT&T C++ 2.0 with an ANSI C compiler.
906
907Make sure -DCFRONT_ANSI_BUG is included in DEFINES in the top-level
908Makefile.  If that doesn't solve the problem, define INT_MIN as
909-INT_MAX in libgroff/lib.h.
910
911----------------------------------------------------------------------
912
913* When compiling on MacOS X, groff compiles but does not run well,
914  especially `eqn', causing many `can't break line' messages.
915
916Use  ./configure CXX=g++2  then make as usual.