head	1.1;
branch	1.1.1;
access;
symbols
	RELENG_8_4:1.1.1.7.0.30
	RELENG_9_1_0_RELEASE:1.1.1.7
	RELENG_9_1:1.1.1.7.0.28
	RELENG_9_1_BP:1.1.1.7
	RELENG_8_3_0_RELEASE:1.1.1.7
	RELENG_8_3:1.1.1.7.0.26
	RELENG_8_3_BP:1.1.1.7
	RELENG_9_0_0_RELEASE:1.1.1.7
	RELENG_9_0:1.1.1.7.0.24
	RELENG_9_0_BP:1.1.1.7
	RELENG_9:1.1.1.7.0.22
	RELENG_9_BP:1.1.1.7
	RELENG_7_4_0_RELEASE:1.1.1.7
	RELENG_8_2_0_RELEASE:1.1.1.7
	RELENG_7_4:1.1.1.7.0.20
	RELENG_7_4_BP:1.1.1.7
	RELENG_8_2:1.1.1.7.0.18
	RELENG_8_2_BP:1.1.1.7
	RELENG_8_1_0_RELEASE:1.1.1.7
	RELENG_8_1:1.1.1.7.0.16
	RELENG_8_1_BP:1.1.1.7
	RELENG_7_3_0_RELEASE:1.1.1.7
	RELENG_7_3:1.1.1.7.0.14
	RELENG_7_3_BP:1.1.1.7
	RELENG_8_0_0_RELEASE:1.1.1.7
	RELENG_8_0:1.1.1.7.0.12
	RELENG_8_0_BP:1.1.1.7
	RELENG_8:1.1.1.7.0.10
	RELENG_8_BP:1.1.1.7
	RELENG_7_2_0_RELEASE:1.1.1.7
	RELENG_7_2:1.1.1.7.0.8
	RELENG_7_2_BP:1.1.1.7
	RELENG_7_1_0_RELEASE:1.1.1.7
	RELENG_6_4_0_RELEASE:1.1.1.6.12.1
	RELENG_7_1:1.1.1.7.0.6
	RELENG_7_1_BP:1.1.1.7
	RELENG_6_4:1.1.1.6.12.1.0.8
	RELENG_6_4_BP:1.1.1.6.12.1
	RELENG_7_0_0_RELEASE:1.1.1.7
	RELENG_6_3_0_RELEASE:1.1.1.6.12.1
	RELENG_7_0:1.1.1.7.0.4
	RELENG_7_0_BP:1.1.1.7
	RELENG_6_3:1.1.1.6.12.1.0.6
	RELENG_6_3_BP:1.1.1.6.12.1
	RELENG_7:1.1.1.7.0.2
	RELENG_7_BP:1.1.1.7
	RELENG_6_2_0_RELEASE:1.1.1.6.12.1
	RELENG_6_2:1.1.1.6.12.1.0.4
	RELENG_6_2_BP:1.1.1.6.12.1
	RELENG_5_5_0_RELEASE:1.1.1.6
	RELENG_5_5:1.1.1.6.0.16
	RELENG_5_5_BP:1.1.1.6
	RELENG_6_1_0_RELEASE:1.1.1.6.12.1
	RELENG_6_1:1.1.1.6.12.1.0.2
	RELENG_6_1_BP:1.1.1.6.12.1
	RELENG_6_0_0_RELEASE:1.1.1.6
	v1_19_2:1.1.1.7
	RELENG_6_0:1.1.1.6.0.14
	RELENG_6_0_BP:1.1.1.6
	RELENG_6:1.1.1.6.0.12
	RELENG_6_BP:1.1.1.6
	RELENG_5_4_0_RELEASE:1.1.1.6
	RELENG_5_4:1.1.1.6.0.10
	RELENG_5_4_BP:1.1.1.6
	RELENG_4_11_0_RELEASE:1.1.1.2.2.4
	RELENG_4_11:1.1.1.2.2.4.0.6
	RELENG_4_11_BP:1.1.1.2.2.4
	RELENG_5_3_0_RELEASE:1.1.1.6
	RELENG_5_3:1.1.1.6.0.8
	RELENG_5_3_BP:1.1.1.6
	RELENG_5:1.1.1.6.0.6
	RELENG_5_BP:1.1.1.6
	RELENG_4_10_0_RELEASE:1.1.1.2.2.4
	RELENG_4_10:1.1.1.2.2.4.0.4
	RELENG_4_10_BP:1.1.1.2.2.4
	RELENG_5_2_1_RELEASE:1.1.1.6
	RELENG_5_2_0_RELEASE:1.1.1.6
	RELENG_5_2:1.1.1.6.0.4
	RELENG_5_2_BP:1.1.1.6
	RELENG_4_9_0_RELEASE:1.1.1.2.2.4
	RELENG_4_9:1.1.1.2.2.4.0.2
	RELENG_4_9_BP:1.1.1.2.2.4
	RELENG_5_1_0_RELEASE:1.1.1.6
	RELENG_5_1:1.1.1.6.0.2
	RELENG_5_1_BP:1.1.1.6
	v1_19:1.1.1.6
	RELENG_4_8_0_RELEASE:1.1.1.2.2.3
	RELENG_4_8:1.1.1.2.2.3.0.2
	RELENG_4_8_BP:1.1.1.2.2.3
	RELENG_5_0_0_RELEASE:1.1.1.5
	RELENG_5_0:1.1.1.5.0.2
	RELENG_5_0_BP:1.1.1.5
	v1_18_1:1.1.1.5
	RELENG_4_7_0_RELEASE:1.1.1.2.2.2
	RELENG_4_7:1.1.1.2.2.2.0.8
	RELENG_4_7_BP:1.1.1.2.2.2
	RELENG_4_6_2_RELEASE:1.1.1.2.2.2
	RELENG_4_6_1_RELEASE:1.1.1.2.2.2
	RELENG_4_6_0_RELEASE:1.1.1.2.2.2
	RELENG_4_6:1.1.1.2.2.2.0.6
	RELENG_4_6_BP:1.1.1.2.2.2
	RELENG_4_5_0_RELEASE:1.1.1.2.2.2
	RELENG_4_5:1.1.1.2.2.2.0.4
	RELENG_4_5_BP:1.1.1.2.2.2
	RELENG_4_4_0_RELEASE:1.1.1.2.2.2
	RELENG_4_4:1.1.1.2.2.2.0.2
	RELENG_4_4_BP:1.1.1.2.2.2
	v1_17_2:1.1.1.4
	RELENG_4_3_0_RELEASE:1.1.1.2.2.1
	RELENG_4_3:1.1.1.2.2.1.0.2
	RELENG_4_3_BP:1.1.1.2.2.1
	v1_17:1.1.1.4
	v1_16_1:1.1.1.3
	RELENG_4_2_0_RELEASE:1.1.1.2
	RELENG_4_1_1_RELEASE:1.1.1.2
	PRE_SMPNG:1.1.1.2
	RELENG_4_1_0_RELEASE:1.1.1.2
	RELENG_3_5_0_RELEASE:1.1.1.1.4.1
	RELENG_4_0_0_RELEASE:1.1.1.2
	RELENG_4:1.1.1.2.0.2
	RELENG_4_BP:1.1.1.2
	v1_15:1.1.1.2
	RELENG_3_4_0_RELEASE:1.1.1.1
	RELENG_3_3_0_RELEASE:1.1.1.1
	RELENG_3_2_PAO:1.1.1.1.0.6
	RELENG_3_2_PAO_BP:1.1.1.1
	RELENG_3_2_0_RELEASE:1.1.1.1
	v1_11:1.1.1.1
	RELENG_3_1_0_RELEASE:1.1.1.1
	RELENG_3:1.1.1.1.0.4
	RELENG_3_BP:1.1.1.1
	RELENG_2_2_8_RELEASE:1.1.1.1
	RELENG_3_0_0_RELEASE:1.1.1.1
	RELENG_2_2_7_RELEASE:1.1.1.1
	RELENG_2_2_6_RELEASE:1.1.1.1
	RELENG_2_2_5_RELEASE:1.1.1.1
	RELENG_2_2_2_RELEASE:1.1.1.1
	RELENG_2_2_1_RELEASE:1.1.1.1
	RELENG_2_2_0_RELEASE:1.1.1.1
	RELENG_2_2:1.1.1.1.0.2
	RELENG_2_2_BP:1.1.1.1
	v1_10:1.1.1.1
	FSF:1.1.1;
locks; strict;
comment	@# @;


1.1
date	96.09.07.16.17.57;	author pst;	state Exp;
branches
	1.1.1.1;
next	;

1.1.1.1
date	96.09.07.16.17.57;	author pst;	state Exp;
branches
	1.1.1.1.4.1;
next	1.1.1.2;

1.1.1.2
date	2000.01.12.09.48.11;	author asmodai;	state Exp;
branches
	1.1.1.2.2.1;
next	1.1.1.3;

1.1.1.3
date	2000.12.05.18.49.20;	author ru;	state Exp;
branches;
next	1.1.1.4;

1.1.1.4
date	2001.04.17.12.11.28;	author ru;	state Exp;
branches;
next	1.1.1.5;

1.1.1.5
date	2002.10.11.08.52.00;	author ru;	state Exp;
branches;
next	1.1.1.6;

1.1.1.6
date	2003.05.01.13.09.48;	author ru;	state Exp;
branches
	1.1.1.6.12.1;
next	1.1.1.7;

1.1.1.7
date	2005.10.20.10.45.16;	author ru;	state Exp;
branches
	1.1.1.7.30.1;
next	;

1.1.1.1.4.1
date	2000.03.09.20.06.04;	author asmodai;	state Exp;
branches;
next	;

1.1.1.2.2.1
date	2000.12.07.09.48.11;	author ru;	state Exp;
branches;
next	1.1.1.2.2.2;

1.1.1.2.2.2
date	2001.04.26.17.32.39;	author ru;	state Exp;
branches;
next	1.1.1.2.2.3;

1.1.1.2.2.3
date	2003.02.14.15.21.44;	author ru;	state Exp;
branches;
next	1.1.1.2.2.4;

1.1.1.2.2.4
date	2003.06.26.13.13.12;	author ru;	state Exp;
branches;
next	;

1.1.1.6.12.1
date	2005.11.15.22.06.18;	author ru;	state Exp;
branches;
next	;

1.1.1.7.30.1
date	2005.10.20.10.45.16;	author svnexp;	state dead;
branches;
next	1.1.1.7.30.2;

1.1.1.7.30.2
date	2013.03.28.13.01.12;	author svnexp;	state Exp;
branches;
next	;


desc
@@


1.1
log
@Initial revision
@
text
@This file describes various problems that have been encountered in
compiling, installing and running groff.  Suggestions for additions or
other improvements to this file are welcome.

* I get lots of `numeric overflow' error messages whenever I run
groff; I compiled groff with AT&T C++ 2.0 with an ANSI C compiler.

Make sure -DCFRONT_ANSI_BUG is included in DEFINES in the top-level
Makefile.  If that doesn't solve the problem, define INT_MIN as
-INT_MAX in libgroff/lib.h.

* I get errors when I try to compile groff with Sun C++ version 3 or
earlier.

Groff requires header files that are moderately compatible with AT&T
C++ and ANSI C.  With some versions of Sun C++, the supplied header
files need some of the following changes to meet this requirement:
<string.h> must declare the mem* functions, (just add `#include
<memory.h>' to <string.h>); the first argument to fopen and freopen
should be declared as `const char *'; the first argument to fread
should be declared as `void *'; the first argument to fwrite should be
declared as `const void *'; malloc should be declared to return `void
*'; in <alloca.h>, the declaration `extern "C" { void
*__builtin_alloca(int); }' should be added; declarations of getopt(),
optarg, optind and opterr should be added to <stdlib.h>; in
<sys/signal.h> the return type and the second argument type of
signal() should be changed to be `void (*)(int)'.

You can either change them in place, or copy them to some other
directory and include that directory with a -I option.

* I get errors when I try to compile groff with DEC C++.

Fix the declaration of write() in <unistd.h> so that the second
argument is a const char *.  Fix the declaration of open() in
<sys/file.h> so that the first argument is a const char *.

* On Ultrix, the make stops with the message

  *** Error code 1

  Stop.

for no apparent reason.

Use GNU make.

* I'm having problems compiling groff on 386BSD 0.1.

If you're using ash as /bin/sh, you'll need the following patch.

*** gendef.sh.org	Sun Jun 30 13:30:36 1991
--- gendef.sh	Sun Feb 28 10:23:49 1993
***************
*** 3,9 ****
  file=$1
  shift
  
! defs="#define $1"
  shift
  for def
  do
--- 3,10 ----
  file=$1
  shift
  
! x=$1
! defs="#define $x"
  shift
  for def
  do

You'll also need to change dirnamemax.c so that it doesn't use
pathconf().

* While compiling on Xenix, ranlib libgroff.a fails.

The system ranlib can't handle externals longer than 40 characters.
Use the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1
instead.

* Groff can't handle my troff document. It works fine with AT&T troff.

Read the section on incompatibilities in gtroff(1).  Try using the -C
option.  Alternatively there's the sed script in tmac/fixmacros.sed
which will attempt to edit a file of macros so that it can be used
with groff without the -C flag.

* groff -Tdvi produces dvi files that use fonts at weird magnifications.

Yes, it does.  You may need to compile fonts with Metafont at these
magnifications. The CompileFonts script in the devdvi/generate
directory may help you to do this. (It will take a *long* time.)

* pic output is not centered horizontally; pictures sometimes run off
the bottom of the page.

The macro package you are using is not supplying appropriate definitions
of PS and PE.  Give groff a -mpic option.

* I'm having problems including PostScript illustrations using the PSPIC
macro.

A PostScript document must meet three requirements in order to be
included with the PSPIC macro: it must comply with the Adobe Document
Structuring Conventions; it must contain a BoundingBox line; it must
be ``well-behaved''.  The BoundingBox line should be of the form:

  %%BoundingBox: llx lly urx ury

where llx, lly, urx, ury are the coordinates of the lower left x,
lower left y, upper right x, upper right y of the bounding box of
marks on the page expressed as integers in the default PostScript
coordinate system (72 units per inch, origin at bottom left corner).
A useful tactic is to print out the illustration by itself (you may
need to add a `showpage' at the end), and physically measure the
bounding box.  For more detail on these requirements, read the
specification of Encapsulated PostScript format.  (This is available
from the Adobe file server; send a message with a body of `help' to
ps-file-server@@adobe.com.)

* I've configured groff for A4 paper, but gtroff still seems to think
that the length of a page (as returned by \n(.p) is 11 inches.

This is intentional.  The PAGE option is used only by grops.  For
compatibility with ditroff, the default page length in gtroff is
always 11 inches.  The page length can be changed with the `pl'
request.

* Groff doesn't use the font names I'm used to.

Use the `ftr' request.  See gtroff(1).

* I get errors using the Unix -ms macros with groff -e -C.

Apply this change:

*** /usr/lib/ms/ms.eqn	Tue Apr 25 02:14:28 1989
--- ms.eqn	Sun Nov 11 10:33:59 1990
***************
*** 22,29 ****
  ..
  .	\" EN - end of a displayed equation
  .de EN
! .if !\\*(10 .br
  .di
  .rm EZ
  .nr ZN \\n(dn
  .if \\n(ZN>0 .if \\n(YE=0 .LP
--- 22,30 ----
  ..
  .	\" EN - end of a displayed equation
  .de EN
! .if \\n(.k>0 .br
  .di
+ .ds 10 \\*(EZ\\
  .rm EZ
  .nr ZN \\n(dn
  .if \\n(ZN>0 .if \\n(YE=0 .LP


* gpic doesn't accept the syntax `chop N M' for chopping both ends of a
line.

The correct syntax is `chop N chop M'.

* With gpic -t, when I print `line ->; box' using a dvi to ps
program, the arrow head sticks through into the inside of the box.

The dvi to ps program should be modified to set the line cap and
line join parameters to 1 while printing tpic specials.

* When I print the output groff -Tps, the output is always shifted up
by about 0.7 inches; I'm using 8.5x11 inch paper.

Make sure that PAGE is defined to be `letter' in the top-level
Makefile.

* When I try to print the output of groff -Tps, I get no output at all
from the printer, and the log file shows the error
%%[ error: undefined; offendingcommand: BP ]%%
I using TranScript spooling software.

This is a bug in the page reversal filter in early versions of
TranScript.  Change the `broken' parameter in
/usr/local/lib/groff/font/devps/DESC to 7.

* When I preview groff -Tps output using the Sun OpenWindows 2.0 pageview
program, all the pages are displayed on top of each other.

This is a defect in pageview.  Change the `broken' parameter in
/usr/local/lib/groff/font/devps/DESC to 2.

* With groff -TX75, -TX100or -X, I can only view the first page.

The left mouse button brings up a menu that allows you to view other
pages.

* When I print the output of groff -Tdvi, I just get a black dot in
upper left corner.

Some dvi drivers (notably early versions of xtex) do not correctly
handle dvi files that use a resolution different from that used by dvi
files produced by TeX.  Try getting a more up to date driver.

* I get lots of errors when I use groff with the AT&T -mm macros.

The AT&T -mm macros need a few changes to work with groff; `make
install.dwbmm' will copy your -mm macros to groff's macro directory
and make the necessary changes.  You may need to edit the commands for
the install.mm target in the Makefile.  Alternatively use the groff
-mm macros.

* gtroff doesn't understand lines like `.ce99' with no space between
the name of the request or macro and the arguments.

Gtroff requires a space between macro or request and its arguments
because it allows the use of long names for macros and requests.  You
can use the -C option or the `cp' request to put gtroff into a
compatibility mode in which it is not possible to use long names for
macros but in which no space is required between macros and their
arguments.  The use of compatibility mode is strongly discouraged.

* gtroff gives warnings about lines like
  .ev	\" a comment
(with a tab after the .ev).

A tab character cannot be used as a substitute for a space character
(except in one case: between a control character at the beginning of a
line and the name of a macro or request).  For example, in Unix troff
  .ps	\" restore the previous point size
(with a tab after the .ps) will NOT restore the previous point-size;
instead it will be silently ignored.  Since this is very likely to be
an error, gtroff can give a warning about it.  If you want to align
comments, you can do it like this:
  .ev\"				\" a comment

* I don't like the page headers and footers produced by groff -man.

There seem to be many different styles of page header and footer
produced by different versions of the -man macros.  You will need to
modify macros/tmac.an to suit your personal taste.  For example, if
you want the center of the page header to say
  UNIX Programmer's Manual
you will need to change the line
  .el .ds an-extra3 \"UNIX Programmer's Manual
to
  .el .ds an-extra3 UNIX Programmer's Manual

* While formatting a manual page, groff complains about not being able to
break lines.  The problem seems to be caused by a line like:
  .TP \w'label'+2

The -man documentation says that the default scale indicator for TP
macro is `n'.  The groff -man macros implement this correctly, so that
the argument will be evaluated as if it were
  \w'label'n+2n
The Unix -man macros don't implement this correctly (probably because
it's hard to do in Unix troff); they just append `n' to the entire
argument, so that it will be evaluated as if it were
  \w'label'u+2n
The solution is to fix the manual page:
  .TP \w'label'u+2

* I'm having problems formatting Ultrix man pages with groff -man.

The Ultrix man pages use a number of non-standard extensions to the
Unix man macros.  One solution is to use the Ultrix -man macros with
groff.  Rename /usr/local/lib/groff/tmac/tmac.an to
/usr/local/lib/groff/tmac/tmac.an.gnu, copy /usr/lib/tmac/tmac.an to
/usr/local/lib/groff/tmac/tmac.an and apply the following patch (from
Frank Wortner):

*** /usr/local/lib/groff/tmac/tmac.an     Wed Sep  9 12:29:28 1992
--- /usr/lib/tmac/tmac.an       Fri Jul 24 19:58:19 1992
***************
*** 489,495 ****
  .     \" make special case of shift out of italic
  .de }S
  .ds ]F
! .if \\$12 .if !\\$5 .ds ]F \^
  .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
  .el \\$3
  .}f
--- 489,495 ----
  .     \" make special case of shift out of italic
  .de }S
  .ds ]F
! .if \\$12 .if !\\$5 .ds ]F\^
  .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
  .el \\$3
  .}f

Another possible solution is to install tmac/man.ultrix as
/usr/local/lib/groff/tmac/man.local.

* I'm having problems formatting HP-UX 9.0 man pages with groff -man.

Rename /usr/local/lib/groff/tmac/tmac.an to (for example)
/usr/local/lib/groff/tmac/tmac.gan, copy HP's tmac.an into
/usr/local/lib/groff/tmac/tmac.an, and either put `.cp 1' at the
beginning or filter it (and any files it .so's) through
tmac/fixmacros.sed.

* I'm having problems formatting man pages produced by the perl
wrapman script.

Some versions of wrapman have a superfluous blank line before the .TH
line.  This must be deleted.  Then either use groff -C, or apply the
following patch:

*** wrapman.~2~	Sun Jan 19 12:10:24 1992
--- wrapman	Tue Aug 10 02:06:41 1993
***************
*** 35,41 ****
      $line1 .= <IN> if $line1 =~ /eval/;
      $line1 .= <IN> if $line1 =~ /argv/;
      $line2 = <IN>;
!     next if $line2 eq "'di';\n";
  
      # Pull the old switcheroo.
  
--- 35,41 ----
      $line1 .= <IN> if $line1 =~ /eval/;
      $line1 .= <IN> if $line1 =~ /argv/;
      $line2 = <IN>;
!     next if $line2 eq "'di ';\n" || $line2 eq "'di';\n";
  
      # Pull the old switcheroo.
  
***************
*** 49,56 ****
  
      print OUT $line1;
      print OUT <<EOF;
! 'di';
! 'ig00';
  #
  # $header
  #
--- 49,58 ----
  
      print OUT $line1;
      print OUT <<EOF;
! 'di ';
! 'ds 00 \\"';
! 'eo ';
! 'ig 00 ';
  #
  # $header
  #
***************
*** 72,85 ****
  
      # These next few lines are legal in both Perl and nroff.
  
! $null.00;                       # finish .ig
   
  'di           \\" finish diversion--previous line must be blank
  .nr nl 0-1    \\" fake up transition to first page again
  .nr % 0         \\" start at page 1
! '; __END__ ##### From here on it's a standard manual page #####
  .TH $PROG 1 "$month $mday, 19$year"
- .AT 3
  .SH NAME
  $prog \\- whatever
  .SH SYNOPSIS
--- 74,87 ----
  
      # These next few lines are legal in both Perl and nroff.
  
! $null.00 ;                      # finish .ig
! 'ec \\';
   
  'di           \\" finish diversion--previous line must be blank
  .nr nl 0-1    \\" fake up transition to first page again
  .nr % 0         \\" start at page 1
! .\\"'; __END__ ##### From here on it's a standard manual page #####
  .TH $PROG 1 "$month $mday, 19$year"
  .SH NAME
  $prog \\- whatever
  .SH SYNOPSIS


* When I preview documents using -TX75 or -TX100, the layout is not the same
as when I print the document with -Tps: the line and page breaks come
in different places.

Use groff -X -Tps.

* When I try to run gxditview, I get the error:
Error: Widget viewport has zero width and/or height

This error means you haven't correctly installed the application
defaults file, GXditview.ad; ``make install'' does this for you
automatically, so either you didn't do ``make install'', or you don't
have imake configured correctly.

* groff uses up an enormous amount of memory processing large files.
I'm using 386BSD 0.1.

386BSD includes an old version of g++, 1.39, which has a bug that
causes a major memory leak in gtroff.  Apply the following fix to g++
and recompile groff:

*** cplus-decl.c.~1~	Mon Aug  6 05:28:59 1990
--- cplus-decl.c	Wed Jun  5 08:55:04 1991
***************
*** 7951,7961 ****
  
        /* At the end, call delete if that's what's requested.  */
        if (TREE_GETS_DELETE (current_class_type))
  	exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
  				      get_identifier (OPERATOR_DELETE_FORMAT),
! 				      build_tree_list (NULL_TREE, integer_zero_node),
  				      NULL_TREE, LOOKUP_NORMAL);
        else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
  	exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
        else
  	exprstmt = 0;
--- 7951,7961 ----
  
        /* At the end, call delete if that's what's requested.  */
        if (TREE_GETS_DELETE (current_class_type))
  	exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
  				      get_identifier (OPERATOR_DELETE_FORMAT),
! 				      build_tree_list (NULL_TREE, current_class_decl),
  				      NULL_TREE, LOOKUP_NORMAL);
        else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
  	exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
        else
  	exprstmt = 0;

* Where can I get grap?

Grap is not freely available, but there is a nawk script implementing
an extended subset of grap available for ftp as
ftp.informatik.uni-rostock.de:/pub/local/software/prag-1.0.shar.gz.

* How can I use groff with an old LaserJet printer that doesn't work
with groff -Tlj4?

You have at least 3 options:

- use groff -Tps with GNU Ghostscript;

- use groff -Tdvi with a TeX .dvi to Laserjet driver;

- use groff with the LaserJet driver in Chris Lewis' psroff package
(available for ftp from:
ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17).

* Groff seems to generate level 3 Postscript, but my printer is only a
level 1 or 2 PostScript printer.

In fact groff generates only level 1 PostScript.  The `%!PS-Adobe-3.0'
comment at the beginning of PostScript output generated by groff
indicates that the file conforms to version 3.0 of the Adobe Document
Structuring Conventions.  The output generated by groff should be
printable on any PostScript printer.  Problems with groff output's not
printing are most often caused by the spooling system.

* The \n(st and \n(sb registers don't seem to work.  I thought \w set
them to the height and depth of its argument, but the registers always
seem to be 0.

\n(st and \n(sb aren't supposed to give the height and depth of the
string rather they give the minimum and maximum vertical displacement
of the baseline.  For example for \v'2u'\v'-3u', \n(st will be 1 and
\n(sb will be -2.  The height and depth of the string is available in
the \n[rst] and \n[rsb] registers: these are groff extensions.

* On an SGI system, how can I make the man command use groff?

From David Hinds <dhinds@@allegro.stanford.edu> (some of these steps
are unnecessary if you install with the `g' Makefile variable defined
as empty):

Create a script called 'eqn':

 > #!/bin/sh
 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
 > geqn $*

and a script called 'neqn':

 > #!/bin/sh
 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
 > geqn -Tascii $*

and do:

 > ln -s gnroff nroff

and edit the end of the gnroff script to be:

 > rest=`echo ${1+"$@@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
 > exec groff -Wall -mtty-char $T $opts $rest

To get PostScript output from 'man -t', you also need to create a
'psroff' script similar to 'nroff'.  Here are the context diffs:

*** /usr/local/bin/nroff        Sat Feb 13 15:51:09 1993
--- /usr/local/bin/psroff       Sat Feb 13 17:45:46 1993
***************
*** 1,8 ****
  #!/bin/sh
! # Emulate nroff with groff.

  prog="$0"
! T=-Tascii
  opts=

  for i
--- 1,8 ----
  #!/bin/sh
! # Emulate psroff with groff.

  prog="$0"
! T=-Tps
  opts=

  for i
***************
*** 25,30 ****
--- 25,33 ----
        -Tascii|-Tlatin1)
                T=$1
                ;;
+       -t)
+               # ignore -- default is send to stdout
+               ;;
        -T*)
                # ignore other devices
                ;;
***************
*** 49,53 ****
  rest=`echo ${1+"$@@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`

  # This shell script is intended for use with man, so warnings are
  # probably not wanted.  Also load nroff-style character definitions.
! exec groff -Wall -mtty-char $T $opts $rest
--- 52,56 ----
  rest=`echo ${1+"$@@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`

  # This shell script is intended for use with man, so warnings are
! # probably not wanted.
! exec groff -Wall $T $opts $rest
@


1.1.1.1
log
@Virgin import of FSF groff v1.10
@
text
@@


1.1.1.1.4.1
log
@MFC: groff 1.15
@
text
@a11 5
* I get errors when I try to compile groff with Sun C++ version 5.0 or 5.1.

This is a known problem; see Sun bug #4301919.  As of this writing, no
patch is available.  Use GCC 2.95.2 or later instead.

d182 1
a182 1
I'm using TranScript spooling software.
d194 1
a194 1
* With groff -TX75, -TX100 or -X, I can only view the first page.
d244 1
a244 1
  System Programmer's Manual
d246 1
a246 1
  .el .ds an-extra3 \"System Programmer's Manual
d248 1
a248 1
  .el .ds an-extra3 System Programmer's Manual
@


1.1.1.2
log
@Virgin import of FSF groff v1.15
@
text
@a11 5
* I get errors when I try to compile groff with Sun C++ version 5.0 or 5.1.

This is a known problem; see Sun bug #4301919.  As of this writing, no
patch is available.  Use GCC 2.95.2 or later instead.

d182 1
a182 1
I'm using TranScript spooling software.
d194 1
a194 1
* With groff -TX75, -TX100 or -X, I can only view the first page.
d244 1
a244 1
  System Programmer's Manual
d246 1
a246 1
  .el .ds an-extra3 \"System Programmer's Manual
d248 1
a248 1
  .el .ds an-extra3 System Programmer's Manual
@


1.1.1.2.2.1
log
@MFC: Upgrade to Groff 1.16.1.
@
text
@a4 26
----------------------------------------------------------------------

* My document says that the current year is 19100, not 2000.

In groff, as in traditional troff, the yr number register yields the
year minus 1900.  Unfortunately, there is a longstanding bug in the
Troff User's Manual <http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz>,
which incorrectly claims that yr is the last two digits of the year.
This claim was never true of either Unix troff or of groff.

If your text looks like this:

	.\" Wrong:
	This document was formatted in 19\n(yr.

you can correct it as follows:

	This document was formatted in \n[year].

or, if you want to be portable to older troff versions, as follows:

	.nr y4 1900+\n(yr
	This document was formatted in \n(y4.

----------------------------------------------------------------------

d6 1
a6 1
  groff; I compiled groff with AT&T C++ 2.0 with an ANSI C compiler.
d12 1
a12 4
----------------------------------------------------------------------

* I get errors when I try to compile groff with Sun C++ version 5.0
  or 5.1.
a16 2
----------------------------------------------------------------------

d18 1
a18 1
  earlier.
d27 6
a32 5
declared as `const void *'; malloc should be declared to return
`void *'; in <alloca.h>, the declaration `extern "C" { void
*__builtin_alloca(int); }' should be added; in <sys/signal.h> the
return type and the second argument type of signal() should be changed
to be `void (*)(int)'.
a36 26
----------------------------------------------------------------------

* The configure script fails on OS/390 Unix.

There is a bug in the Language Environment (LE) whereby the test
program for static destructors fails.  You will see the message
'configure: error: a working C++ compiler is required'

Applying PTF UQ42006 is supposed to fix this, but the test program is
still returning the wrong value (1).  To work around this problem, you
can comment out the following in the configure script (near line 956).
This will effectively bypass the test (static constructors and
destructors do actually work properly):

#if { (eval echo configure:957: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext} && (./conftest; exit) 2>/dev/null
#then
  echo "$ac_t""yes" 1>&6
#else
#  echo "configure: failed program was:" >&5
#  cat conftest.$ac_ext >&5
#  rm -fr conftest*
#  echo "$ac_t""no" 1>&6;{ echo "configure: error: a working C++ compiler is required" 1>&2; exit 1; }
#fi

----------------------------------------------------------------------

a42 20
----------------------------------------------------------------------

* On a host using Unix make (e.g. Solaris), if you are compiling for
  multiple architectures by building in a subdirectory, the make stops
  with a message like this:

    make: Fatal error: Don't know how to make target `assert.o'

  or like this:

    make: Fatal error: Can't find /u/src/groff/src/include/Makefile.sub': No such file or directory

This occurs because GNU make and Unix make handle VPATH differently,
and the groff build relies on GNU make's VPATH handling.

Use GNU make to work around the problem.  In Solaris 8, GNU make is
on the Software Companion CD and is installed as /opt/sfw/bin/gmake.

----------------------------------------------------------------------

a52 2
----------------------------------------------------------------------

a80 2
----------------------------------------------------------------------

a86 8
----------------------------------------------------------------------

* There are many empty `Makefile.dep' files.  Is this a bug?

No.  Real dependency files are created with a `make depend' call.

----------------------------------------------------------------------

d94 1
a94 4
----------------------------------------------------------------------

* groff -Tdvi produces dvi files that use fonts at weird
  magnifications.
d97 2
a98 4
magnifications.  The CompileFonts script in the devdvi/generate
directory may help you to do this.  (It will take a *long* time.)

----------------------------------------------------------------------
d101 1
a101 1
  the bottom of the page.
d103 2
a104 2
The macro package you are using is not supplying appropriate
definitions of PS and PE.  Give groff a -mpic option.
d106 2
a107 4
----------------------------------------------------------------------

* I'm having problems including PostScript illustrations using the
  PSPIC macro.
a126 2
----------------------------------------------------------------------

d128 1
a128 1
  that the length of a page (as returned by \n(.p) is 11 inches.
a134 2
----------------------------------------------------------------------

a138 2
----------------------------------------------------------------------

a165 1
----------------------------------------------------------------------
d167 2
a168 2
* gpic doesn't accept the syntax `chop N M' for chopping both ends of
  a line.
d172 2
a173 1
----------------------------------------------------------------------
d175 2
a176 7
* With gpic -t, when I print `line ->; box' using a dvi to ps program,
  the arrow head sticks through into the inside of the box.

The dvi to ps program should be modified to set the line cap and line
join parameters to 1 while printing tpic specials.

----------------------------------------------------------------------
d179 1
a179 1
  by about 0.7 inches; I'm using 8.5x11 inch paper.
a183 2
----------------------------------------------------------------------

d185 3
a187 3
  from the printer, and the log file shows the error
  %%[ error: undefined; offendingcommand: BP ]%%
  I'm using TranScript spooling software.
d193 2
a194 4
----------------------------------------------------------------------

* When I preview groff -Tps output using the Sun OpenWindows 2.0
  pageview program, all the pages are displayed on top of each other.
a198 2
----------------------------------------------------------------------

a203 2
----------------------------------------------------------------------

d205 1
a205 1
  upper left corner.
a210 2
----------------------------------------------------------------------

a218 2
----------------------------------------------------------------------

d220 1
a220 1
  the name of the request or macro and the arguments.
d222 1
a222 1
gtroff requires a space between macro or request and its arguments
a228 2
----------------------------------------------------------------------

d231 1
a231 1
  (with a tab after the .ev).
a235 1

a236 1

a240 1

a242 2
----------------------------------------------------------------------

a248 1

a249 1

a250 1

a251 1

a252 1

d255 2
a256 4
----------------------------------------------------------------------

* While formatting a manual page, groff complains about not being able
  to break lines.  The problem seems to be caused by a line like:
a261 1

a262 1

a265 1

a266 1

a267 1

a269 2
----------------------------------------------------------------------

a301 2
----------------------------------------------------------------------

a309 2
----------------------------------------------------------------------

d311 1
a311 1
  wrapman script.
d390 3
a392 5
----------------------------------------------------------------------

* When I preview documents using -TX75 or -TX100, the layout is not
  the same as when I print the document with -Tps: the line and page
  breaks come in different places.
a395 2
----------------------------------------------------------------------

d397 1
a397 1
  Error: Widget viewport has zero width and/or height
a403 2
----------------------------------------------------------------------

d405 1
a405 1
  I'm using 386BSD 0.1.
a438 2
----------------------------------------------------------------------

d441 3
a443 5
Ted Faber <faber@@lunabase.org> has written a freely available grap:

  http://www.lunabase.org/~faber/Vault/software/grap/

----------------------------------------------------------------------
d446 1
a446 1
  with groff -Tlj4?
d455 2
a456 4
  (available for ftp from:
  ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17).

----------------------------------------------------------------------
d459 1
a459 1
  level 1 or 2 PostScript printer.
a467 2
----------------------------------------------------------------------

d469 2
a470 2
  them to the height and depth of its argument, but the registers
  always seem to be 0.
a476 2

----------------------------------------------------------------------
@


1.1.1.2.2.2
log
@MFC: Upgrade to Groff 1.17.
@
text
@d121 1
a121 1
    *** Error code 1
d123 1
a123 1
    Stop.
d125 1
a125 1
  for no apparent reason.
d175 1
a175 1
* Groff can't handle my troff document.  It works fine with AT&T troff.
d178 1
a178 1
option.  Alternatively there's the sed script `tmac/fixmacros.sed'
d189 1
a189 2
directory may help you to do this.  (It will take a *long* time on
slow computers.)
d225 1
a225 1
  that the length of a page (as returned by `\n(.p') is 11 inches.
a233 13
* groff produces wrapper macros for `ms' and friends which call the
  system's original macros.  Then, to get groff's ms macro package I
  have to use `-mgs' instead `-ms'.  Can I avoid this?

Yes.  Configure and compile groff as usual, but install it with

  make install tmac_wrap=""

Then no wrapper files are produced, and `-ms' will use groff's `ms'
macros.

----------------------------------------------------------------------

d236 1
a236 1
Use the `ftr' request.  See (g)troff(1).
d329 5
a333 1
Use the groff -mm macros.
d372 1
a372 1
modify tmac/an-old.tmac to suit your personal taste.  For example, if
d413 4
a416 3
groff.  Copy /usr/lib/tmac/tmac.an to
/usr/local/share/groff/site-tmac/an.tmac and apply the following patch
(from Frank Wortner):
d439 1
a439 1
/usr/local/share/groff/site-tmac/man.local.
d445 5
a449 13
Copy HP's tmac.an into /usr/local/share/groff/site-tmac/an.tmac, and
either put `.cp 1' at the beginning or filter it (and any files it .so's)
through tmac/fixmacros.sed.

----------------------------------------------------------------------

* On HP-UX, the compiler complains about missing symbol `alloca'.

Say

  export LDFLAGS=-lPW

before starting the configure script.
@


1.1.1.2.2.3
log
@MFC: Groff 1.18.1.
@
text
@a6 7


Generic Problems
================



d31 145
a175 2
* groff can't handle my troff document.  It works fine with AT&T
  troff.
a183 12
* gtroff doesn't understand lines like `.ce99' with no space between
  the name of the request or macro and the arguments.

gtroff requires a space between macro or request and its arguments
because it allows the use of long names for macros and requests.  You
can use the -C option or the `cp' request to put gtroff into a
compatibility mode in which it is not possible to use long names for
macros but in which no space is required between macros and their
arguments.  The use of compatibility mode is strongly discouraged.

----------------------------------------------------------------------

d194 54
d254 3
a256 2
* pic output is not centered horizontally; pictures sometimes run off
  the bottom of the page.
d258 22
a279 2
The macro package you are using is not supplying appropriate
definitions of PS and PE.  Give groff a -mpic option.
d298 61
a396 20
* Where can I get grap?

Ted Faber <faber@@lunabase.org> has written a freely available grap:

  http://www.lunabase.org/~faber/Vault/software/grap/

----------------------------------------------------------------------

* The \n(st and \n(sb registers don't seem to work.  I thought \w set
  them to the height and depth of its argument, but the registers
  always seem to be 0.

\n(st and \n(sb aren't supposed to give the height and depth of the
string rather they give the minimum and maximum vertical displacement
of the baseline.  For example for \v'2u'\v'-3u', \n(st will be 1 and
\n(sb will be -2.  The height and depth of the string is available in
the \n[rst] and \n[rsb] registers: these are groff extensions.

----------------------------------------------------------------------

d419 51
d549 19
a604 100


Printing and Display Problems
=============================



* I'm having problems including PostScript illustrations (EPS) using
  the PSPIC macro and/or \X'ps: import ...'.

A PostScript document must meet three requirements in order to be
included with the PSPIC macro: it must comply with the Adobe Document
Structuring Conventions; it must contain a BoundingBox line; it must
be ``well-behaved''.  The BoundingBox line should be of the form:

  %%BoundingBox: llx lly urx ury

where llx, lly, urx, ury are the coordinates of the lower left x,
lower left y, upper right x, upper right y of the bounding box of
marks on the page expressed as integers in the default PostScript
coordinate system (72 units per inch, origin at bottom left corner).

The most convenient program to get the bounding box of a document is
the `ps2epsi' script coming with GhostScript.

If you can't use this program, another useful tactic is to print out
the illustration by itself (you may need to add a `showpage' at the
end), and physically measure the bounding box.  For more detail on
these requirements, read the specification of Encapsulated PostScript
format.  (This is available from the Adobe file server; send a message
with a body of `help' to ps-file-server@@adobe.com.)

If an EPS file to be included via \X'ps: import' does not start with
%!PS-Adobe-...', gtroff will still include the file, but grops will
not add any fonts to the generated output file that are listed in the
EPS file, even though the files are listed in the `download' file and
are available in the devps directory.

----------------------------------------------------------------------

* I've configured groff for A4 paper, but gtroff still seems to think
  that the length of a page (as returned by `\n(.p') is 11 inches.

This is intentional.  The PAGE option is used only by grops.  For
compatibility with ditroff, the default page length in gtroff is
always 11 inches.  The page length can be changed with the `pl'
request.

----------------------------------------------------------------------

* When I print the output groff -Tps, the output is always shifted up
  by about 0.7 inches; I'm using 8.5x11 inch paper.

Make sure that PAGE is defined to be `letter' in the top-level
Makefile.

----------------------------------------------------------------------

* When I try to run gxditview, I get the error:
  Error: Widget viewport has zero width and/or height

This error means you haven't correctly installed the application
defaults file, GXditview.ad; ``make install'' does this for you
automatically, so either you didn't do ``make install'', or you don't
have imake configured correctly.

----------------------------------------------------------------------

* When I preview documents using -TX75 or -TX100, the layout is not
  the same as when I print the document with -Tps: the line and page
  breaks come in different places.

Use groff -X -Tps.

----------------------------------------------------------------------

* When I try to print the output of groff -Tps, I get no output at all
  from the printer, and the log file shows the error
  %%[ error: undefined; offendingcommand: BP ]%%
  I'm using TranScript spooling software.

This is a bug in the page reversal filter in early versions of
TranScript.  Change the `broken' parameter in
/usr/local/lib/groff/font/devps/DESC to 7.

----------------------------------------------------------------------

* When I preview groff -Tps output using the Sun OpenWindows 2.0
  pageview program, all the pages are displayed on top of each other.

This is a defect in pageview.  Change the `broken' parameter in
/usr/local/lib/groff/font/devps/DESC to 2.

----------------------------------------------------------------------

* With groff -TX75, -TX100 or -X, I can only view the first page.

The left mouse button brings up a menu that allows you to view other
pages.

d607 3
a609 2
* When I print the output of groff -Tdvi, I just get a black dot in
  upper left corner.
d611 1
a611 3
Some dvi drivers (notably early versions of xtex) do not correctly
handle dvi files that use a resolution different from that used by dvi
files produced by TeX.  Try getting a more up to date driver.
a639 11


Platform-Dependent Macro Problems
=================================



* I get lots of errors when I use groff with the AT&T -mm macros.

Use the groff -mm macros.

d642 3
a644 3
* groff produces wrapper macros for `ms' and friends which call the
  system's original macros.  Then, to get groff's ms macro package I
  have to use `-mgs' instead `-ms'.  Can I avoid this?
d646 5
a650 76
Yes.  Configure and compile groff as usual, but install it with

  make install tmac_wrap=""

Then no wrapper files are produced, and `-ms' will use groff's `ms'
macros.

----------------------------------------------------------------------

* I'm having problems formatting HP-UX 9.0 man pages with groff -man.

Copy HP's tmac.an into /usr/local/share/groff/site-tmac/an.tmac, and
either put `.cp 1' at the beginning or filter it (and any files it
.so's) through tmac/fixmacros.sed.

----------------------------------------------------------------------

* I get errors using the Unix -ms macros with groff -e -C.

Apply this change:

*** /usr/lib/ms/ms.eqn	Tue Apr 25 02:14:28 1989
--- ms.eqn	Sun Nov 11 10:33:59 1990
***************
*** 22,29 ****
  ..
  .	\" EN - end of a displayed equation
  .de EN
! .if !\\*(10 .br
  .di
  .rm EZ
  .nr ZN \\n(dn
  .if \\n(ZN>0 .if \\n(YE=0 .LP
--- 22,30 ----
  ..
  .	\" EN - end of a displayed equation
  .de EN
! .if \\n(.k>0 .br
  .di
+ .ds 10 \\*(EZ\\
  .rm EZ
  .nr ZN \\n(dn
  .if \\n(ZN>0 .if \\n(YE=0 .LP

----------------------------------------------------------------------

* I'm having problems formatting Ultrix man pages with groff -man.

The Ultrix man pages use a number of non-standard extensions to the
Unix man macros.  One solution is to use the Ultrix -man macros with
groff.  Copy /usr/lib/tmac/tmac.an to
/usr/local/share/groff/site-tmac/an.tmac and apply the following patch
(from Frank Wortner):

*** /usr/local/lib/groff/tmac/tmac.an     Wed Sep  9 12:29:28 1992
--- /usr/lib/tmac/tmac.an       Fri Jul 24 19:58:19 1992
***************
*** 489,495 ****
  .     \" make special case of shift out of italic
  .de }S
  .ds ]F
! .if \\$12 .if !\\$5 .ds ]F \^
  .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
  .el \\$3
  .}f
--- 489,495 ----
  .     \" make special case of shift out of italic
  .de }S
  .ds ]F
! .if \\$12 .if !\\$5 .ds ]F\^
  .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
  .el \\$3
  .}f

Another possible solution is to install tmac/man.ultrix as
/usr/local/share/groff/site-tmac/man.local.
a729 183



Compilation Problems
====================



* Compilation dies with

    y.tab.c: In function `int yyparse()':
    y.tab.c: `size_t' undeclared in namespace `std'

This is a bug in bison 1.32.  Don't use this version.  1.28 or 1.33 works
fine.  Alternatively, use yacc or byacc.

----------------------------------------------------------------------

* There are many empty `Makefile.dep' files.  Is this a bug?

No.  Real dependency files are created with a `make depend' call.

----------------------------------------------------------------------

* On HP-UX, the compiler complains about missing symbol `alloca'.

Say

  export LDFLAGS=-lPW

before starting the configure script.

----------------------------------------------------------------------

* The configure script fails on OS/390 (z/OS) Unix.

[This has been fixed in z/OS V1R3 (aka OS/390 R13).]

There is a bug in the Language Environment (LE) whereby the test
program for static destructors fails.  You will see the message
`configure: error: a working C++ compiler is required'

Applying PTF UQ42006 is supposed to fix this, but the test program is
still returning the wrong value (1).  To work around this problem, you
can comment out the following in the configure script (near line 2029).
This will effectively bypass the test (static constructors and
destructors do actually work properly):

#if { (eval echo "$as_me:2029: \"$ac_link\"") >&5
#  (eval $ac_link) 2>&5
#  ac_status=$?
#  echo "$as_me:2032: \$? = $ac_status" >&5
#  (exit $ac_status); } && { ac_try='./conftest$ac_exeext'
#  { (eval echo "$as_me:2034: \"$ac_try\"") >&5
#  (eval $ac_try) 2>&5
#  ac_status=$?
#  echo "$as_me:2037: \$? = $ac_status" >&5
#  (exit $ac_status); }; }; then
#  echo "$as_me:2039: result: yes" >&5
#echo "${ECHO_T}yes" >&6
#else
#  echo "$as_me: program exited with status $ac_status" >&5
#echo "$as_me: failed program was:" >&5
#cat conftest.$ac_ext >&5
#echo "$as_me:2045: result: no" >&5
#echo "${ECHO_T}no" >&6;{ { echo "$as_me:2046: error: a working C++ compiler is required" >&5
#echo "$as_me: error: a working C++ compiler is required" >&2;}
#   { (exit 1); exit 1; }; }
#fi

----------------------------------------------------------------------

* I get errors when I try to compile groff with DEC C++.

Fix the declaration of write() in <unistd.h> so that the second
argument is a const char *.  Fix the declaration of open() in
<sys/file.h> so that the first argument is a const char *.

----------------------------------------------------------------------

* On a host using Unix make (e.g. Solaris), if you are compiling for
  multiple architectures by building in a subdirectory, the make stops
  with a message like this:

    make: Fatal error: Don't know how to make target `assert.o'

  or like this:

    make: Fatal error: Can't find /u/src/groff/src/include/Makefile.sub': No such file or directory

This occurs because GNU make and Unix make handle VPATH differently,
and the groff build relies on GNU make's VPATH handling.

Use GNU make to work around the problem.  In Solaris 8, GNU make is
on the Software Companion CD and is installed as /opt/sfw/bin/gmake.

----------------------------------------------------------------------

* On Ultrix, the make stops with the message

    *** Error code 1

    Stop.

  for no apparent reason.

Use GNU make.

----------------------------------------------------------------------

* I'm having problems compiling groff on 386BSD 0.1.

If you're using ash as /bin/sh, you'll need the following patch.

*** gendef.sh.org	Sun Jun 30 13:30:36 1991
--- gendef.sh	Sun Feb 28 10:23:49 1993
***************
*** 3,9 ****
  file=$1
  shift
  
! defs="#define $1"
  shift
  for def
  do
--- 3,10 ----
  file=$1
  shift
  
! x=$1
! defs="#define $x"
  shift
  for def
  do

You'll also need to change dirnamemax.c so that it doesn't use
pathconf().

----------------------------------------------------------------------

* While compiling on Xenix, ranlib libgroff.a fails.

The system ranlib can't handle externals longer than 40 characters.
Use the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1
instead.

----------------------------------------------------------------------

* I get errors when I try to compile groff with Sun C++ version 3 or
  earlier.

Groff requires header files that are moderately compatible with AT&T
C++ and ANSI C.  With some versions of Sun C++, the supplied header
files need some of the following changes to meet this requirement:
<string.h> must declare the mem* functions, (just add `#include
<memory.h>' to <string.h>); the first argument to fopen and freopen
should be declared as `const char *'; the first argument to fread
should be declared as `void *'; the first argument to fwrite should be
declared as `const void *'; malloc should be declared to return
`void *'; in <alloca.h>, the declaration `extern "C" { void
*__builtin_alloca(int); }' should be added; in <sys/signal.h> the
return type and the second argument type of signal() should be changed
to be `void (*)(int)'.

You can either change them in place, or copy them to some other
directory and include that directory with a -I option.

----------------------------------------------------------------------

* I get errors when I try to compile groff with Sun C++ version 5.0
  or 5.1.

This is a known problem; see Sun bug #4301919.  As of this writing, no
patch is available.  Use GCC 2.95.2 or later instead.

----------------------------------------------------------------------

* I get lots of `numeric overflow' error messages whenever I run
  groff; I compiled groff with AT&T C++ 2.0 with an ANSI C compiler.

Make sure -DCFRONT_ANSI_BUG is included in DEFINES in the top-level
Makefile.  If that doesn't solve the problem, define INT_MIN as
-INT_MAX in libgroff/lib.h.
@


1.1.1.2.2.4
log
@MFC: GNU Groff 1.19.
@
text
@d41 4
a44 4
Read the section on incompatibilities in groff_diff(7).  Try using
the -C option.  Alternatively there's the sed script
`tmac/fixmacros.sed' which will attempt to edit a file of macros so
that it can be used with groff without the -C flag.
d72 1
a72 1
Use the `ftr' request.  See groff_diff(7).
d122 12
a133 2
put modified macros from tmac/an-old.tmac into man.local.  More
information is available in groff_man(7).
d338 4
a341 13
This is intentional.  The PAGE option during configuration is used
only by grops.  For compatibility with ditroff, the default page
length in gtroff is always 11 inches.  The page length can be changed
with the `pl' request.

A convenient way to set paper dimensions is to use the -dpaper option
of groff, together with proper -P options for the postprocessor
(overriding the default).  For example, use the following for PS
output on A4 paper in landscape orientation:

  groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps

See groff_tmac(5) for more information.
d345 2
a346 2
* When I print the output of groff -Tps, the output is always shifted
  up by about 0.7 inches; I'm using 8.5x11 inch paper.
d348 2
a349 1
Make sure that the paper size is `letter'.  See groff_tmac(5).
d424 6
a429 8
In fact groff generates only level 2 PostScript (or rather level 1
with some extensions; see grops(1) for more information how to disable
them).  The `%!PS-Adobe-3.0' comment at the beginning of PostScript
output generated by groff indicates that the file conforms to
version 3.0 of the Adobe Document Structuring Conventions.  The output
generated by groff should be printable on any PostScript printer.
Problems with groff output's not printing are most often caused by the
spooling system.
d616 2
a617 6
* bison reports conflicts (either on stderr or in the `pic.output'
  file) while processing `pic.y', and the produced pic binary doesn't
  work at all.

You need bison version 1.875b or greater.  Alternatively, use yacc or
byacc.
a785 6

----------------------------------------------------------------------

* When compiling on MacOS X, groff compiles but does not run well.

Use  ./configure CXX=g++2  then make as usual.
@


1.1.1.3
log
@Virgin import of FSF groff v1.16.1
@
text
@a4 26
----------------------------------------------------------------------

* My document says that the current year is 19100, not 2000.

In groff, as in traditional troff, the yr number register yields the
year minus 1900.  Unfortunately, there is a longstanding bug in the
Troff User's Manual <http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz>,
which incorrectly claims that yr is the last two digits of the year.
This claim was never true of either Unix troff or of groff.

If your text looks like this:

	.\" Wrong:
	This document was formatted in 19\n(yr.

you can correct it as follows:

	This document was formatted in \n[year].

or, if you want to be portable to older troff versions, as follows:

	.nr y4 1900+\n(yr
	This document was formatted in \n(y4.

----------------------------------------------------------------------

d6 1
a6 1
  groff; I compiled groff with AT&T C++ 2.0 with an ANSI C compiler.
d12 1
a12 4
----------------------------------------------------------------------

* I get errors when I try to compile groff with Sun C++ version 5.0
  or 5.1.
a16 2
----------------------------------------------------------------------

d18 1
a18 1
  earlier.
d27 6
a32 5
declared as `const void *'; malloc should be declared to return
`void *'; in <alloca.h>, the declaration `extern "C" { void
*__builtin_alloca(int); }' should be added; in <sys/signal.h> the
return type and the second argument type of signal() should be changed
to be `void (*)(int)'.
a36 26
----------------------------------------------------------------------

* The configure script fails on OS/390 Unix.

There is a bug in the Language Environment (LE) whereby the test
program for static destructors fails.  You will see the message
'configure: error: a working C++ compiler is required'

Applying PTF UQ42006 is supposed to fix this, but the test program is
still returning the wrong value (1).  To work around this problem, you
can comment out the following in the configure script (near line 956).
This will effectively bypass the test (static constructors and
destructors do actually work properly):

#if { (eval echo configure:957: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext} && (./conftest; exit) 2>/dev/null
#then
  echo "$ac_t""yes" 1>&6
#else
#  echo "configure: failed program was:" >&5
#  cat conftest.$ac_ext >&5
#  rm -fr conftest*
#  echo "$ac_t""no" 1>&6;{ echo "configure: error: a working C++ compiler is required" 1>&2; exit 1; }
#fi

----------------------------------------------------------------------

a42 20
----------------------------------------------------------------------

* On a host using Unix make (e.g. Solaris), if you are compiling for
  multiple architectures by building in a subdirectory, the make stops
  with a message like this:

    make: Fatal error: Don't know how to make target `assert.o'

  or like this:

    make: Fatal error: Can't find /u/src/groff/src/include/Makefile.sub': No such file or directory

This occurs because GNU make and Unix make handle VPATH differently,
and the groff build relies on GNU make's VPATH handling.

Use GNU make to work around the problem.  In Solaris 8, GNU make is
on the Software Companion CD and is installed as /opt/sfw/bin/gmake.

----------------------------------------------------------------------

a52 2
----------------------------------------------------------------------

a80 2
----------------------------------------------------------------------

a86 8
----------------------------------------------------------------------

* There are many empty `Makefile.dep' files.  Is this a bug?

No.  Real dependency files are created with a `make depend' call.

----------------------------------------------------------------------

d94 1
a94 4
----------------------------------------------------------------------

* groff -Tdvi produces dvi files that use fonts at weird
  magnifications.
d97 2
a98 4
magnifications.  The CompileFonts script in the devdvi/generate
directory may help you to do this.  (It will take a *long* time.)

----------------------------------------------------------------------
d101 1
a101 1
  the bottom of the page.
d103 2
a104 2
The macro package you are using is not supplying appropriate
definitions of PS and PE.  Give groff a -mpic option.
d106 2
a107 4
----------------------------------------------------------------------

* I'm having problems including PostScript illustrations using the
  PSPIC macro.
a126 2
----------------------------------------------------------------------

d128 1
a128 1
  that the length of a page (as returned by \n(.p) is 11 inches.
a134 2
----------------------------------------------------------------------

a138 2
----------------------------------------------------------------------

a165 1
----------------------------------------------------------------------
d167 2
a168 2
* gpic doesn't accept the syntax `chop N M' for chopping both ends of
  a line.
d172 2
a173 1
----------------------------------------------------------------------
d175 2
a176 7
* With gpic -t, when I print `line ->; box' using a dvi to ps program,
  the arrow head sticks through into the inside of the box.

The dvi to ps program should be modified to set the line cap and line
join parameters to 1 while printing tpic specials.

----------------------------------------------------------------------
d179 1
a179 1
  by about 0.7 inches; I'm using 8.5x11 inch paper.
a183 2
----------------------------------------------------------------------

d185 3
a187 3
  from the printer, and the log file shows the error
  %%[ error: undefined; offendingcommand: BP ]%%
  I'm using TranScript spooling software.
d193 2
a194 4
----------------------------------------------------------------------

* When I preview groff -Tps output using the Sun OpenWindows 2.0
  pageview program, all the pages are displayed on top of each other.
a198 2
----------------------------------------------------------------------

a203 2
----------------------------------------------------------------------

d205 1
a205 1
  upper left corner.
a210 2
----------------------------------------------------------------------

a218 2
----------------------------------------------------------------------

d220 1
a220 1
  the name of the request or macro and the arguments.
d222 1
a222 1
gtroff requires a space between macro or request and its arguments
a228 2
----------------------------------------------------------------------

d231 1
a231 1
  (with a tab after the .ev).
a235 1

a236 1

a240 1

a242 2
----------------------------------------------------------------------

a248 1

a249 1

a250 1

a251 1

a252 1

d255 2
a256 4
----------------------------------------------------------------------

* While formatting a manual page, groff complains about not being able
  to break lines.  The problem seems to be caused by a line like:
a261 1

a262 1

a265 1

a266 1

a267 1

a269 2
----------------------------------------------------------------------

a301 2
----------------------------------------------------------------------

a309 2
----------------------------------------------------------------------

d311 1
a311 1
  wrapman script.
d390 3
a392 5
----------------------------------------------------------------------

* When I preview documents using -TX75 or -TX100, the layout is not
  the same as when I print the document with -Tps: the line and page
  breaks come in different places.
a395 2
----------------------------------------------------------------------

d397 1
a397 1
  Error: Widget viewport has zero width and/or height
a403 2
----------------------------------------------------------------------

d405 1
a405 1
  I'm using 386BSD 0.1.
a438 2
----------------------------------------------------------------------

d441 3
a443 5
Ted Faber <faber@@lunabase.org> has written a freely available grap:

  http://www.lunabase.org/~faber/Vault/software/grap/

----------------------------------------------------------------------
d446 1
a446 1
  with groff -Tlj4?
d455 2
a456 4
  (available for ftp from:
  ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17).

----------------------------------------------------------------------
d459 1
a459 1
  level 1 or 2 PostScript printer.
a467 2
----------------------------------------------------------------------

d469 2
a470 2
  them to the height and depth of its argument, but the registers
  always seem to be 0.
a476 2

----------------------------------------------------------------------
@


1.1.1.4
log
@Virgin import of FSF groff v1.17
@
text
@d121 1
a121 1
    *** Error code 1
d123 1
a123 1
    Stop.
d125 1
a125 1
  for no apparent reason.
d175 1
a175 1
* Groff can't handle my troff document.  It works fine with AT&T troff.
d178 1
a178 1
option.  Alternatively there's the sed script `tmac/fixmacros.sed'
d189 1
a189 2
directory may help you to do this.  (It will take a *long* time on
slow computers.)
d225 1
a225 1
  that the length of a page (as returned by `\n(.p') is 11 inches.
a233 13
* groff produces wrapper macros for `ms' and friends which call the
  system's original macros.  Then, to get groff's ms macro package I
  have to use `-mgs' instead `-ms'.  Can I avoid this?

Yes.  Configure and compile groff as usual, but install it with

  make install tmac_wrap=""

Then no wrapper files are produced, and `-ms' will use groff's `ms'
macros.

----------------------------------------------------------------------

d236 1
a236 1
Use the `ftr' request.  See (g)troff(1).
d329 5
a333 1
Use the groff -mm macros.
d372 1
a372 1
modify tmac/an-old.tmac to suit your personal taste.  For example, if
d413 4
a416 3
groff.  Copy /usr/lib/tmac/tmac.an to
/usr/local/share/groff/site-tmac/an.tmac and apply the following patch
(from Frank Wortner):
d439 1
a439 1
/usr/local/share/groff/site-tmac/man.local.
d445 5
a449 13
Copy HP's tmac.an into /usr/local/share/groff/site-tmac/an.tmac, and
either put `.cp 1' at the beginning or filter it (and any files it .so's)
through tmac/fixmacros.sed.

----------------------------------------------------------------------

* On HP-UX, the compiler complains about missing symbol `alloca'.

Say

  export LDFLAGS=-lPW

before starting the configure script.
@


1.1.1.5
log
@Virgin import of FSF groff v1.18.1
@
text
@a6 7


Generic Problems
================



d31 145
a175 2
* groff can't handle my troff document.  It works fine with AT&T
  troff.
a183 12
* gtroff doesn't understand lines like `.ce99' with no space between
  the name of the request or macro and the arguments.

gtroff requires a space between macro or request and its arguments
because it allows the use of long names for macros and requests.  You
can use the -C option or the `cp' request to put gtroff into a
compatibility mode in which it is not possible to use long names for
macros but in which no space is required between macros and their
arguments.  The use of compatibility mode is strongly discouraged.

----------------------------------------------------------------------

d194 54
d254 3
a256 2
* pic output is not centered horizontally; pictures sometimes run off
  the bottom of the page.
d258 22
a279 2
The macro package you are using is not supplying appropriate
definitions of PS and PE.  Give groff a -mpic option.
d298 61
a396 20
* Where can I get grap?

Ted Faber <faber@@lunabase.org> has written a freely available grap:

  http://www.lunabase.org/~faber/Vault/software/grap/

----------------------------------------------------------------------

* The \n(st and \n(sb registers don't seem to work.  I thought \w set
  them to the height and depth of its argument, but the registers
  always seem to be 0.

\n(st and \n(sb aren't supposed to give the height and depth of the
string rather they give the minimum and maximum vertical displacement
of the baseline.  For example for \v'2u'\v'-3u', \n(st will be 1 and
\n(sb will be -2.  The height and depth of the string is available in
the \n[rst] and \n[rsb] registers: these are groff extensions.

----------------------------------------------------------------------

d419 51
d549 19
a604 100


Printing and Display Problems
=============================



* I'm having problems including PostScript illustrations (EPS) using
  the PSPIC macro and/or \X'ps: import ...'.

A PostScript document must meet three requirements in order to be
included with the PSPIC macro: it must comply with the Adobe Document
Structuring Conventions; it must contain a BoundingBox line; it must
be ``well-behaved''.  The BoundingBox line should be of the form:

  %%BoundingBox: llx lly urx ury

where llx, lly, urx, ury are the coordinates of the lower left x,
lower left y, upper right x, upper right y of the bounding box of
marks on the page expressed as integers in the default PostScript
coordinate system (72 units per inch, origin at bottom left corner).

The most convenient program to get the bounding box of a document is
the `ps2epsi' script coming with GhostScript.

If you can't use this program, another useful tactic is to print out
the illustration by itself (you may need to add a `showpage' at the
end), and physically measure the bounding box.  For more detail on
these requirements, read the specification of Encapsulated PostScript
format.  (This is available from the Adobe file server; send a message
with a body of `help' to ps-file-server@@adobe.com.)

If an EPS file to be included via \X'ps: import' does not start with
%!PS-Adobe-...', gtroff will still include the file, but grops will
not add any fonts to the generated output file that are listed in the
EPS file, even though the files are listed in the `download' file and
are available in the devps directory.

----------------------------------------------------------------------

* I've configured groff for A4 paper, but gtroff still seems to think
  that the length of a page (as returned by `\n(.p') is 11 inches.

This is intentional.  The PAGE option is used only by grops.  For
compatibility with ditroff, the default page length in gtroff is
always 11 inches.  The page length can be changed with the `pl'
request.

----------------------------------------------------------------------

* When I print the output groff -Tps, the output is always shifted up
  by about 0.7 inches; I'm using 8.5x11 inch paper.

Make sure that PAGE is defined to be `letter' in the top-level
Makefile.

----------------------------------------------------------------------

* When I try to run gxditview, I get the error:
  Error: Widget viewport has zero width and/or height

This error means you haven't correctly installed the application
defaults file, GXditview.ad; ``make install'' does this for you
automatically, so either you didn't do ``make install'', or you don't
have imake configured correctly.

----------------------------------------------------------------------

* When I preview documents using -TX75 or -TX100, the layout is not
  the same as when I print the document with -Tps: the line and page
  breaks come in different places.

Use groff -X -Tps.

----------------------------------------------------------------------

* When I try to print the output of groff -Tps, I get no output at all
  from the printer, and the log file shows the error
  %%[ error: undefined; offendingcommand: BP ]%%
  I'm using TranScript spooling software.

This is a bug in the page reversal filter in early versions of
TranScript.  Change the `broken' parameter in
/usr/local/lib/groff/font/devps/DESC to 7.

----------------------------------------------------------------------

* When I preview groff -Tps output using the Sun OpenWindows 2.0
  pageview program, all the pages are displayed on top of each other.

This is a defect in pageview.  Change the `broken' parameter in
/usr/local/lib/groff/font/devps/DESC to 2.

----------------------------------------------------------------------

* With groff -TX75, -TX100 or -X, I can only view the first page.

The left mouse button brings up a menu that allows you to view other
pages.

d607 3
a609 2
* When I print the output of groff -Tdvi, I just get a black dot in
  upper left corner.
d611 1
a611 3
Some dvi drivers (notably early versions of xtex) do not correctly
handle dvi files that use a resolution different from that used by dvi
files produced by TeX.  Try getting a more up to date driver.
a639 11


Platform-Dependent Macro Problems
=================================



* I get lots of errors when I use groff with the AT&T -mm macros.

Use the groff -mm macros.

d642 3
a644 3
* groff produces wrapper macros for `ms' and friends which call the
  system's original macros.  Then, to get groff's ms macro package I
  have to use `-mgs' instead `-ms'.  Can I avoid this?
d646 5
a650 76
Yes.  Configure and compile groff as usual, but install it with

  make install tmac_wrap=""

Then no wrapper files are produced, and `-ms' will use groff's `ms'
macros.

----------------------------------------------------------------------

* I'm having problems formatting HP-UX 9.0 man pages with groff -man.

Copy HP's tmac.an into /usr/local/share/groff/site-tmac/an.tmac, and
either put `.cp 1' at the beginning or filter it (and any files it
.so's) through tmac/fixmacros.sed.

----------------------------------------------------------------------

* I get errors using the Unix -ms macros with groff -e -C.

Apply this change:

*** /usr/lib/ms/ms.eqn	Tue Apr 25 02:14:28 1989
--- ms.eqn	Sun Nov 11 10:33:59 1990
***************
*** 22,29 ****
  ..
  .	\" EN - end of a displayed equation
  .de EN
! .if !\\*(10 .br
  .di
  .rm EZ
  .nr ZN \\n(dn
  .if \\n(ZN>0 .if \\n(YE=0 .LP
--- 22,30 ----
  ..
  .	\" EN - end of a displayed equation
  .de EN
! .if \\n(.k>0 .br
  .di
+ .ds 10 \\*(EZ\\
  .rm EZ
  .nr ZN \\n(dn
  .if \\n(ZN>0 .if \\n(YE=0 .LP

----------------------------------------------------------------------

* I'm having problems formatting Ultrix man pages with groff -man.

The Ultrix man pages use a number of non-standard extensions to the
Unix man macros.  One solution is to use the Ultrix -man macros with
groff.  Copy /usr/lib/tmac/tmac.an to
/usr/local/share/groff/site-tmac/an.tmac and apply the following patch
(from Frank Wortner):

*** /usr/local/lib/groff/tmac/tmac.an     Wed Sep  9 12:29:28 1992
--- /usr/lib/tmac/tmac.an       Fri Jul 24 19:58:19 1992
***************
*** 489,495 ****
  .     \" make special case of shift out of italic
  .de }S
  .ds ]F
! .if \\$12 .if !\\$5 .ds ]F \^
  .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
  .el \\$3
  .}f
--- 489,495 ----
  .     \" make special case of shift out of italic
  .de }S
  .ds ]F
! .if \\$12 .if !\\$5 .ds ]F\^
  .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
  .el \\$3
  .}f

Another possible solution is to install tmac/man.ultrix as
/usr/local/share/groff/site-tmac/man.local.
a729 183



Compilation Problems
====================



* Compilation dies with

    y.tab.c: In function `int yyparse()':
    y.tab.c: `size_t' undeclared in namespace `std'

This is a bug in bison 1.32.  Don't use this version.  1.28 or 1.33 works
fine.  Alternatively, use yacc or byacc.

----------------------------------------------------------------------

* There are many empty `Makefile.dep' files.  Is this a bug?

No.  Real dependency files are created with a `make depend' call.

----------------------------------------------------------------------

* On HP-UX, the compiler complains about missing symbol `alloca'.

Say

  export LDFLAGS=-lPW

before starting the configure script.

----------------------------------------------------------------------

* The configure script fails on OS/390 (z/OS) Unix.

[This has been fixed in z/OS V1R3 (aka OS/390 R13).]

There is a bug in the Language Environment (LE) whereby the test
program for static destructors fails.  You will see the message
`configure: error: a working C++ compiler is required'

Applying PTF UQ42006 is supposed to fix this, but the test program is
still returning the wrong value (1).  To work around this problem, you
can comment out the following in the configure script (near line 2029).
This will effectively bypass the test (static constructors and
destructors do actually work properly):

#if { (eval echo "$as_me:2029: \"$ac_link\"") >&5
#  (eval $ac_link) 2>&5
#  ac_status=$?
#  echo "$as_me:2032: \$? = $ac_status" >&5
#  (exit $ac_status); } && { ac_try='./conftest$ac_exeext'
#  { (eval echo "$as_me:2034: \"$ac_try\"") >&5
#  (eval $ac_try) 2>&5
#  ac_status=$?
#  echo "$as_me:2037: \$? = $ac_status" >&5
#  (exit $ac_status); }; }; then
#  echo "$as_me:2039: result: yes" >&5
#echo "${ECHO_T}yes" >&6
#else
#  echo "$as_me: program exited with status $ac_status" >&5
#echo "$as_me: failed program was:" >&5
#cat conftest.$ac_ext >&5
#echo "$as_me:2045: result: no" >&5
#echo "${ECHO_T}no" >&6;{ { echo "$as_me:2046: error: a working C++ compiler is required" >&5
#echo "$as_me: error: a working C++ compiler is required" >&2;}
#   { (exit 1); exit 1; }; }
#fi

----------------------------------------------------------------------

* I get errors when I try to compile groff with DEC C++.

Fix the declaration of write() in <unistd.h> so that the second
argument is a const char *.  Fix the declaration of open() in
<sys/file.h> so that the first argument is a const char *.

----------------------------------------------------------------------

* On a host using Unix make (e.g. Solaris), if you are compiling for
  multiple architectures by building in a subdirectory, the make stops
  with a message like this:

    make: Fatal error: Don't know how to make target `assert.o'

  or like this:

    make: Fatal error: Can't find /u/src/groff/src/include/Makefile.sub': No such file or directory

This occurs because GNU make and Unix make handle VPATH differently,
and the groff build relies on GNU make's VPATH handling.

Use GNU make to work around the problem.  In Solaris 8, GNU make is
on the Software Companion CD and is installed as /opt/sfw/bin/gmake.

----------------------------------------------------------------------

* On Ultrix, the make stops with the message

    *** Error code 1

    Stop.

  for no apparent reason.

Use GNU make.

----------------------------------------------------------------------

* I'm having problems compiling groff on 386BSD 0.1.

If you're using ash as /bin/sh, you'll need the following patch.

*** gendef.sh.org	Sun Jun 30 13:30:36 1991
--- gendef.sh	Sun Feb 28 10:23:49 1993
***************
*** 3,9 ****
  file=$1
  shift
  
! defs="#define $1"
  shift
  for def
  do
--- 3,10 ----
  file=$1
  shift
  
! x=$1
! defs="#define $x"
  shift
  for def
  do

You'll also need to change dirnamemax.c so that it doesn't use
pathconf().

----------------------------------------------------------------------

* While compiling on Xenix, ranlib libgroff.a fails.

The system ranlib can't handle externals longer than 40 characters.
Use the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1
instead.

----------------------------------------------------------------------

* I get errors when I try to compile groff with Sun C++ version 3 or
  earlier.

Groff requires header files that are moderately compatible with AT&T
C++ and ANSI C.  With some versions of Sun C++, the supplied header
files need some of the following changes to meet this requirement:
<string.h> must declare the mem* functions, (just add `#include
<memory.h>' to <string.h>); the first argument to fopen and freopen
should be declared as `const char *'; the first argument to fread
should be declared as `void *'; the first argument to fwrite should be
declared as `const void *'; malloc should be declared to return
`void *'; in <alloca.h>, the declaration `extern "C" { void
*__builtin_alloca(int); }' should be added; in <sys/signal.h> the
return type and the second argument type of signal() should be changed
to be `void (*)(int)'.

You can either change them in place, or copy them to some other
directory and include that directory with a -I option.

----------------------------------------------------------------------

* I get errors when I try to compile groff with Sun C++ version 5.0
  or 5.1.

This is a known problem; see Sun bug #4301919.  As of this writing, no
patch is available.  Use GCC 2.95.2 or later instead.

----------------------------------------------------------------------

* I get lots of `numeric overflow' error messages whenever I run
  groff; I compiled groff with AT&T C++ 2.0 with an ANSI C compiler.

Make sure -DCFRONT_ANSI_BUG is included in DEFINES in the top-level
Makefile.  If that doesn't solve the problem, define INT_MIN as
-INT_MAX in libgroff/lib.h.
@


1.1.1.6
log
@Virgin import of FSF groff v1.19
@
text
@d41 4
a44 4
Read the section on incompatibilities in groff_diff(7).  Try using
the -C option.  Alternatively there's the sed script
`tmac/fixmacros.sed' which will attempt to edit a file of macros so
that it can be used with groff without the -C flag.
d72 1
a72 1
Use the `ftr' request.  See groff_diff(7).
d122 12
a133 2
put modified macros from tmac/an-old.tmac into man.local.  More
information is available in groff_man(7).
d338 4
a341 13
This is intentional.  The PAGE option during configuration is used
only by grops.  For compatibility with ditroff, the default page
length in gtroff is always 11 inches.  The page length can be changed
with the `pl' request.

A convenient way to set paper dimensions is to use the -dpaper option
of groff, together with proper -P options for the postprocessor
(overriding the default).  For example, use the following for PS
output on A4 paper in landscape orientation:

  groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps

See groff_tmac(5) for more information.
d345 2
a346 2
* When I print the output of groff -Tps, the output is always shifted
  up by about 0.7 inches; I'm using 8.5x11 inch paper.
d348 2
a349 1
Make sure that the paper size is `letter'.  See groff_tmac(5).
d424 6
a429 8
In fact groff generates only level 2 PostScript (or rather level 1
with some extensions; see grops(1) for more information how to disable
them).  The `%!PS-Adobe-3.0' comment at the beginning of PostScript
output generated by groff indicates that the file conforms to
version 3.0 of the Adobe Document Structuring Conventions.  The output
generated by groff should be printable on any PostScript printer.
Problems with groff output's not printing are most often caused by the
spooling system.
d616 2
a617 6
* bison reports conflicts (either on stderr or in the `pic.output'
  file) while processing `pic.y', and the produced pic binary doesn't
  work at all.

You need bison version 1.875b or greater.  Alternatively, use yacc or
byacc.
a785 6

----------------------------------------------------------------------

* When compiling on MacOS X, groff compiles but does not run well.

Use  ./configure CXX=g++2  then make as usual.
@


1.1.1.6.12.1
log
@MFC: Groff 1.19.2.
@
text
@a13 97
* Displaying a man page on a terminal with/without my favourite pager
  only gives garbage.

groff by default now uses SGR escape sequences (`ANSI color') to
control the display attributes (bold, underlined, colour) on TTYs. 
Some terminals (e.g. `kterm') don't understand SGR, and some pagers
(e.g. older versions of `less' or `less' without the -R option) don't
understand SGR either.  There are three solutions to fix this, in order
of preference; please read the grotty man page for more details.

The fourth and probably best option is to update your terminal program
and pager to versions which can handle SGR.

  1. Set the GROFF_NO_SGR environment variable.

  2. Pass option -c to grotty.

  3. Append the following fragment to the `troffrc' file:


--- start ---
.if n \{\
.  nr _C \n(.C
.  cp 0
.
.  \" The following code sets a top-of-page trap to disable grotty's TTY
.  \" mode.  Since neither \X nor .output can be used before the first
.  \" page has started, we must use a trap.  To make it work with troff's
.  \" -o option, we wait until the first printed page.
.
.  de sgr@@dummy
.  .
.
.  rn wh wh@@old
.
.  \" The stand-alone version.  If no other trap is set, we can safely
.  \" insert the truncated vertical space caused by the trap (if any).
.  \" Otherwise we assume that the document's main macro package takes
.  \" care of that.  As soon as the trap has been executed, it is removed.
.  de1 no@@sgr
.    if \\n[.P] \{\
.      if (\\n[.t] == \\n[.p]) \{\
.        rn wh@@old wh
.        rm no@@sgr
.        wh 0
.        sp \\n[.trunc]
.        nop \X'tty: sgr 0'
.        sp -1
.    \}\}
.  .
.
.  wh@@old 0 no@@sgr
.
.  \" The piggyback version to be appended to macros planted with the
.  \" modified `wh' request.
.  de1 no@@sgr1
.    if \\n[.P] \{\
.      rn wh@@old wh
.      ds no@@sgr1
.      nop \X'tty: sgr 0'
.      sp -1
.    \}
.  .
.
.  \" We redefine the `wh' request so that `no@@sgr1' is appended to
.  \" the trap macro.
.  de1 wh
.    am1 \\$2 sgr@@dummy
.      no@@sgr1
.    sgr@@dummy
.    wh@@old \\$1 \\$2
.  .
.
.  cp \n[_C]
.\}
--- end ---

----------------------------------------------------------------------

* The UTF-8 output of grotty has strange characters for the minus, the
  hyphen, and the right quote.  Why?

The used Unicode characters (U+2212 for the minus sign and U+2010 for
the hyphen) are the correct ones, but many programs can't search them
properly.  The same is true for the right quote (U+201D).  To map those
characters back to the ASCII characters, insert the following code
snippet into the `troffrc' configuration file:

.if '\*[.T]'utf8' \{\
.  char \- \N'45'
.  char  - \N'45'
.  char  ' \N'39'
.\}


----------------------------------------------------------------------

d298 1
a298 1
be `well-behaved'.  The BoundingBox line should be of the form:
d318 1
a318 1
`%!PS-Adobe-...', gtroff will still include the file, but grops will
d355 3
a357 7
defaults file, GXditview.ad; `make install' does this for you
automatically, so either you didn't do `make install', or you haven't
passed a good `--appresdir=<DIR>' argument to groff's configure script.

See the X(7) man page for information how and where application resource
files have to be located.  Look for the XAPPLRESDIR and XUSERFILESEARCHPATH
environment variables.
d365 1
a365 1
Use `groff -X -Tps'.
d535 1
a535 1
 > #! /bin/sh
d541 1
a541 1
 > #! /bin/sh
d561 1
a561 1
  #! /bin/sh
d570 1
a570 1
  #! /bin/sh
d700 2
a701 5
Use GNU make <http://www.gnu.org/software/make/> to work around this.
In Solaris 8 and 9, GNU make is on the Software Companion CD in
package SFWgmake and is installed as /opt/sfw/bin/gmake.  Prebuilt
versions of GNU make for Solaris are also available from
sunfreeware.com.
d705 1
a705 1
* On Ultrix, the make program stops with the message
d776 2
a777 15
* I get errors when I try to compile groff with Forte Development 6
  or 6u1, or Sun C++ version 5.0 through 5.2.

This is a known problem; see Sun bug #4301919.  See Sun patches
109482, 109490, 109508, and 109509 for fixes.

----------------------------------------------------------------------

* I get warnings from the Sun linker while using gcc 3.4.0:

  ld: warning: relocation error: R_SPARC_UA32:
      file groff/src/libs/libgroff/libgroff.a(getopt.o): symbol optarg:
      external symbolic relocation against non-allocatable
      section .debug_info; cannot be processed at runtime:
      relocation ignored
d779 2
a780 5
This seems to be a known problem (Sun bugs #4910101 and #4910810,
filed in September 2003; gcc bug #15599, filed May 2004) without a
public fix as of this writing.  A work-around is to use option
`-gstabs+' instead of `-g' (and a high probability that the output is
only debuggable with gdb but not with Sun's debuggers).
d793 1
a793 2
* When compiling on MacOS X, groff compiles but does not run well,
  especially `eqn', causing many `can't break line' messages.
@


1.1.1.7
log
@Virgin import of FSF groff v1.19.2
@
text
@a13 97
* Displaying a man page on a terminal with/without my favourite pager
  only gives garbage.

groff by default now uses SGR escape sequences (`ANSI color') to
control the display attributes (bold, underlined, colour) on TTYs. 
Some terminals (e.g. `kterm') don't understand SGR, and some pagers
(e.g. older versions of `less' or `less' without the -R option) don't
understand SGR either.  There are three solutions to fix this, in order
of preference; please read the grotty man page for more details.

The fourth and probably best option is to update your terminal program
and pager to versions which can handle SGR.

  1. Set the GROFF_NO_SGR environment variable.

  2. Pass option -c to grotty.

  3. Append the following fragment to the `troffrc' file:


--- start ---
.if n \{\
.  nr _C \n(.C
.  cp 0
.
.  \" The following code sets a top-of-page trap to disable grotty's TTY
.  \" mode.  Since neither \X nor .output can be used before the first
.  \" page has started, we must use a trap.  To make it work with troff's
.  \" -o option, we wait until the first printed page.
.
.  de sgr@@dummy
.  .
.
.  rn wh wh@@old
.
.  \" The stand-alone version.  If no other trap is set, we can safely
.  \" insert the truncated vertical space caused by the trap (if any).
.  \" Otherwise we assume that the document's main macro package takes
.  \" care of that.  As soon as the trap has been executed, it is removed.
.  de1 no@@sgr
.    if \\n[.P] \{\
.      if (\\n[.t] == \\n[.p]) \{\
.        rn wh@@old wh
.        rm no@@sgr
.        wh 0
.        sp \\n[.trunc]
.        nop \X'tty: sgr 0'
.        sp -1
.    \}\}
.  .
.
.  wh@@old 0 no@@sgr
.
.  \" The piggyback version to be appended to macros planted with the
.  \" modified `wh' request.
.  de1 no@@sgr1
.    if \\n[.P] \{\
.      rn wh@@old wh
.      ds no@@sgr1
.      nop \X'tty: sgr 0'
.      sp -1
.    \}
.  .
.
.  \" We redefine the `wh' request so that `no@@sgr1' is appended to
.  \" the trap macro.
.  de1 wh
.    am1 \\$2 sgr@@dummy
.      no@@sgr1
.    sgr@@dummy
.    wh@@old \\$1 \\$2
.  .
.
.  cp \n[_C]
.\}
--- end ---

----------------------------------------------------------------------

* The UTF-8 output of grotty has strange characters for the minus, the
  hyphen, and the right quote.  Why?

The used Unicode characters (U+2212 for the minus sign and U+2010 for
the hyphen) are the correct ones, but many programs can't search them
properly.  The same is true for the right quote (U+201D).  To map those
characters back to the ASCII characters, insert the following code
snippet into the `troffrc' configuration file:

.if '\*[.T]'utf8' \{\
.  char \- \N'45'
.  char  - \N'45'
.  char  ' \N'39'
.\}


----------------------------------------------------------------------

d298 1
a298 1
be `well-behaved'.  The BoundingBox line should be of the form:
d318 1
a318 1
`%!PS-Adobe-...', gtroff will still include the file, but grops will
d355 3
a357 7
defaults file, GXditview.ad; `make install' does this for you
automatically, so either you didn't do `make install', or you haven't
passed a good `--appresdir=<DIR>' argument to groff's configure script.

See the X(7) man page for information how and where application resource
files have to be located.  Look for the XAPPLRESDIR and XUSERFILESEARCHPATH
environment variables.
d365 1
a365 1
Use `groff -X -Tps'.
d535 1
a535 1
 > #! /bin/sh
d541 1
a541 1
 > #! /bin/sh
d561 1
a561 1
  #! /bin/sh
d570 1
a570 1
  #! /bin/sh
d700 2
a701 5
Use GNU make <http://www.gnu.org/software/make/> to work around this.
In Solaris 8 and 9, GNU make is on the Software Companion CD in
package SFWgmake and is installed as /opt/sfw/bin/gmake.  Prebuilt
versions of GNU make for Solaris are also available from
sunfreeware.com.
d705 1
a705 1
* On Ultrix, the make program stops with the message
d776 2
a777 15
* I get errors when I try to compile groff with Forte Development 6
  or 6u1, or Sun C++ version 5.0 through 5.2.

This is a known problem; see Sun bug #4301919.  See Sun patches
109482, 109490, 109508, and 109509 for fixes.

----------------------------------------------------------------------

* I get warnings from the Sun linker while using gcc 3.4.0:

  ld: warning: relocation error: R_SPARC_UA32:
      file groff/src/libs/libgroff/libgroff.a(getopt.o): symbol optarg:
      external symbolic relocation against non-allocatable
      section .debug_info; cannot be processed at runtime:
      relocation ignored
d779 2
a780 5
This seems to be a known problem (Sun bugs #4910101 and #4910810,
filed in September 2003; gcc bug #15599, filed May 2004) without a
public fix as of this writing.  A work-around is to use option
`-gstabs+' instead of `-g' (and a high probability that the output is
only debuggable with gdb but not with Sun's debuggers).
d793 1
a793 2
* When compiling on MacOS X, groff compiles but does not run well,
  especially `eqn', causing many `can't break line' messages.
@


1.1.1.7.30.1
log
@file PROBLEMS was added on branch RELENG_8_4 on 2013-03-28 13:01:12 +0000
@
text
@d1 916
@


1.1.1.7.30.2
log
@## SVN ## Exported commit - http://svnweb.freebsd.org/changeset/base/248810
## SVN ## CVS IS DEPRECATED: http://wiki.freebsd.org/CvsIsDeprecated
@
text
@a0 916
This file describes various problems that have been encountered in
compiling, installing and running groff.  Suggestions for additions or
other improvements to this file are welcome.

----------------------------------------------------------------------



Generic Problems
================



* Displaying a man page on a terminal with/without my favourite pager
  only gives garbage.

groff by default now uses SGR escape sequences (`ANSI color') to
control the display attributes (bold, underlined, colour) on TTYs. 
Some terminals (e.g. `kterm') don't understand SGR, and some pagers
(e.g. older versions of `less' or `less' without the -R option) don't
understand SGR either.  There are three solutions to fix this, in order
of preference; please read the grotty man page for more details.

The fourth and probably best option is to update your terminal program
and pager to versions which can handle SGR.

  1. Set the GROFF_NO_SGR environment variable.

  2. Pass option -c to grotty.

  3. Append the following fragment to the `troffrc' file:


--- start ---
.if n \{\
.  nr _C \n(.C
.  cp 0
.
.  \" The following code sets a top-of-page trap to disable grotty's TTY
.  \" mode.  Since neither \X nor .output can be used before the first
.  \" page has started, we must use a trap.  To make it work with troff's
.  \" -o option, we wait until the first printed page.
.
.  de sgr@@dummy
.  .
.
.  rn wh wh@@old
.
.  \" The stand-alone version.  If no other trap is set, we can safely
.  \" insert the truncated vertical space caused by the trap (if any).
.  \" Otherwise we assume that the document's main macro package takes
.  \" care of that.  As soon as the trap has been executed, it is removed.
.  de1 no@@sgr
.    if \\n[.P] \{\
.      if (\\n[.t] == \\n[.p]) \{\
.        rn wh@@old wh
.        rm no@@sgr
.        wh 0
.        sp \\n[.trunc]
.        nop \X'tty: sgr 0'
.        sp -1
.    \}\}
.  .
.
.  wh@@old 0 no@@sgr
.
.  \" The piggyback version to be appended to macros planted with the
.  \" modified `wh' request.
.  de1 no@@sgr1
.    if \\n[.P] \{\
.      rn wh@@old wh
.      ds no@@sgr1
.      nop \X'tty: sgr 0'
.      sp -1
.    \}
.  .
.
.  \" We redefine the `wh' request so that `no@@sgr1' is appended to
.  \" the trap macro.
.  de1 wh
.    am1 \\$2 sgr@@dummy
.      no@@sgr1
.    sgr@@dummy
.    wh@@old \\$1 \\$2
.  .
.
.  cp \n[_C]
.\}
--- end ---

----------------------------------------------------------------------

* The UTF-8 output of grotty has strange characters for the minus, the
  hyphen, and the right quote.  Why?

The used Unicode characters (U+2212 for the minus sign and U+2010 for
the hyphen) are the correct ones, but many programs can't search them
properly.  The same is true for the right quote (U+201D).  To map those
characters back to the ASCII characters, insert the following code
snippet into the `troffrc' configuration file:

.if '\*[.T]'utf8' \{\
.  char \- \N'45'
.  char  - \N'45'
.  char  ' \N'39'
.\}


----------------------------------------------------------------------

* My document says that the current year is 19100, not 2000.

In groff, as in traditional troff, the yr number register yields the
year minus 1900.  Unfortunately, there is a longstanding bug in the
Troff User's Manual <http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz>,
which incorrectly claims that yr is the last two digits of the year.
This claim was never true of either Unix troff or of groff.

If your text looks like this:

	.\" Wrong:
	This document was formatted in 19\n(yr.

you can correct it as follows:

	This document was formatted in \n[year].

or, if you want to be portable to older troff versions, as follows:

	.nr y4 1900+\n(yr
	This document was formatted in \n(y4.

----------------------------------------------------------------------

* groff can't handle my troff document.  It works fine with AT&T
  troff.

Read the section on incompatibilities in groff_diff(7).  Try using
the -C option.  Alternatively there's the sed script
`tmac/fixmacros.sed' which will attempt to edit a file of macros so
that it can be used with groff without the -C flag.

----------------------------------------------------------------------

* gtroff doesn't understand lines like `.ce99' with no space between
  the name of the request or macro and the arguments.

gtroff requires a space between macro or request and its arguments
because it allows the use of long names for macros and requests.  You
can use the -C option or the `cp' request to put gtroff into a
compatibility mode in which it is not possible to use long names for
macros but in which no space is required between macros and their
arguments.  The use of compatibility mode is strongly discouraged.

----------------------------------------------------------------------

* groff -Tdvi produces dvi files that use fonts at weird
  magnifications.

Yes, it does.  You may need to compile fonts with Metafont at these
magnifications.  The CompileFonts script in the devdvi/generate
directory may help you to do this.  (It will take a *long* time on
slow computers.)

----------------------------------------------------------------------

* Groff doesn't use the font names I'm used to.

Use the `ftr' request.  See groff_diff(7).

----------------------------------------------------------------------

* pic output is not centered horizontally; pictures sometimes run off
  the bottom of the page.

The macro package you are using is not supplying appropriate
definitions of PS and PE.  Give groff a -mpic option.

----------------------------------------------------------------------

* gpic doesn't accept the syntax `chop N M' for chopping both ends of
  a line.

The correct syntax is `chop N chop M'.

----------------------------------------------------------------------

* With gpic -t, when I print `line ->; box' using a dvi to ps program,
  the arrow head sticks through into the inside of the box.

The dvi to ps program should be modified to set the line cap and line
join parameters to 1 while printing tpic specials.

----------------------------------------------------------------------

* gtroff gives warnings about lines like
  .ev	\" a comment
  (with a tab after the .ev).

A tab character cannot be used as a substitute for a space character
(except in one case: between a control character at the beginning of a
line and the name of a macro or request).  For example, in Unix troff

  .ps	\" restore the previous point size

(with a tab after the .ps) will NOT restore the previous point-size;
instead it will be silently ignored.  Since this is very likely to be
an error, gtroff can give a warning about it.  If you want to align
comments, you can do it like this:

  .ev\"				\" a comment

----------------------------------------------------------------------

* I don't like the page headers and footers produced by groff -man.

There seem to be many different styles of page header and footer
produced by different versions of the -man macros.  You will need to
put modified macros from tmac/an-old.tmac into man.local.  More
information is available in groff_man(7).

----------------------------------------------------------------------

* Where can I get grap?

Ted Faber <faber@@lunabase.org> has written a freely available grap:

  http://www.lunabase.org/~faber/Vault/software/grap/

----------------------------------------------------------------------

* The \n(st and \n(sb registers don't seem to work.  I thought \w set
  them to the height and depth of its argument, but the registers
  always seem to be 0.

\n(st and \n(sb aren't supposed to give the height and depth of the
string rather they give the minimum and maximum vertical displacement
of the baseline.  For example for \v'2u'\v'-3u', \n(st will be 1 and
\n(sb will be -2.  The height and depth of the string is available in
the \n[rst] and \n[rsb] registers: these are groff extensions.

----------------------------------------------------------------------

* While formatting a manual page, groff complains about not being able
  to break lines.  The problem seems to be caused by a line like:
  .TP \w'label'+2

The -man documentation says that the default scale indicator for TP
macro is `n'.  The groff -man macros implement this correctly, so that
the argument will be evaluated as if it were

  \w'label'n+2n

The Unix -man macros don't implement this correctly (probably because
it's hard to do in Unix troff); they just append `n' to the entire
argument, so that it will be evaluated as if it were

  \w'label'u+2n

The solution is to fix the manual page:

  .TP \w'label'u+2

----------------------------------------------------------------------

* I'm having problems formatting man pages produced by the perl
  wrapman script.

Some versions of wrapman have a superfluous blank line before the .TH
line.  This must be deleted.  Then either use groff -C, or apply the
following patch:

*** wrapman.~2~	Sun Jan 19 12:10:24 1992
--- wrapman	Tue Aug 10 02:06:41 1993
***************
*** 35,41 ****
      $line1 .= <IN> if $line1 =~ /eval/;
      $line1 .= <IN> if $line1 =~ /argv/;
      $line2 = <IN>;
!     next if $line2 eq "'di';\n";
  
      # Pull the old switcheroo.
  
--- 35,41 ----
      $line1 .= <IN> if $line1 =~ /eval/;
      $line1 .= <IN> if $line1 =~ /argv/;
      $line2 = <IN>;
!     next if $line2 eq "'di ';\n" || $line2 eq "'di';\n";
  
      # Pull the old switcheroo.
  
***************
*** 49,56 ****
  
      print OUT $line1;
      print OUT <<EOF;
! 'di';
! 'ig00';
  #
  # $header
  #
--- 49,58 ----
  
      print OUT $line1;
      print OUT <<EOF;
! 'di ';
! 'ds 00 \\"';
! 'eo ';
! 'ig 00 ';
  #
  # $header
  #
***************
*** 72,85 ****
  
      # These next few lines are legal in both Perl and nroff.
  
! $null.00;                       # finish .ig
   
  'di           \\" finish diversion--previous line must be blank
  .nr nl 0-1    \\" fake up transition to first page again
  .nr % 0         \\" start at page 1
! '; __END__ ##### From here on it's a standard manual page #####
  .TH $PROG 1 "$month $mday, 19$year"
- .AT 3
  .SH NAME
  $prog \\- whatever
  .SH SYNOPSIS
--- 74,87 ----
  
      # These next few lines are legal in both Perl and nroff.
  
! $null.00 ;                      # finish .ig
! 'ec \\';
   
  'di           \\" finish diversion--previous line must be blank
  .nr nl 0-1    \\" fake up transition to first page again
  .nr % 0         \\" start at page 1
! .\\"'; __END__ ##### From here on it's a standard manual page #####
  .TH $PROG 1 "$month $mday, 19$year"
  .SH NAME
  $prog \\- whatever
  .SH SYNOPSIS

----------------------------------------------------------------------

* groff uses up an enormous amount of memory processing large files.
  I'm using 386BSD 0.1.

386BSD includes an old version of g++, 1.39, which has a bug that
causes a major memory leak in gtroff.  Apply the following fix to g++
and recompile groff:

*** cplus-decl.c.~1~	Mon Aug  6 05:28:59 1990
--- cplus-decl.c	Wed Jun  5 08:55:04 1991
***************
*** 7951,7961 ****
  
        /* At the end, call delete if that's what's requested.  */
        if (TREE_GETS_DELETE (current_class_type))
  	exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
  				      get_identifier (OPERATOR_DELETE_FORMAT),
! 				      build_tree_list (NULL_TREE, integer_zero_node),
  				      NULL_TREE, LOOKUP_NORMAL);
        else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
  	exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
        else
  	exprstmt = 0;
--- 7951,7961 ----
  
        /* At the end, call delete if that's what's requested.  */
        if (TREE_GETS_DELETE (current_class_type))
  	exprstmt = build_method_call (build1 (NOP_EXPR, TYPE_POINTER_TO (current_class_type), error_mark_node),
  				      get_identifier (OPERATOR_DELETE_FORMAT),
! 				      build_tree_list (NULL_TREE, current_class_decl),
  				      NULL_TREE, LOOKUP_NORMAL);
        else if (TYPE_USES_VIRTUAL_BASECLASSES (current_class_type))
  	exprstmt = build_x_delete (ptr_type_node, current_class_decl, 0);
        else
  	exprstmt = 0;



Printing and Display Problems
=============================



* I'm having problems including PostScript illustrations (EPS) using
  the PSPIC macro and/or \X'ps: import ...'.

A PostScript document must meet three requirements in order to be
included with the PSPIC macro: it must comply with the Adobe Document
Structuring Conventions; it must contain a BoundingBox line; it must
be `well-behaved'.  The BoundingBox line should be of the form:

  %%BoundingBox: llx lly urx ury

where llx, lly, urx, ury are the coordinates of the lower left x,
lower left y, upper right x, upper right y of the bounding box of
marks on the page expressed as integers in the default PostScript
coordinate system (72 units per inch, origin at bottom left corner).

The most convenient program to get the bounding box of a document is
the `ps2epsi' script coming with GhostScript.

If you can't use this program, another useful tactic is to print out
the illustration by itself (you may need to add a `showpage' at the
end), and physically measure the bounding box.  For more detail on
these requirements, read the specification of Encapsulated PostScript
format.  (This is available from the Adobe file server; send a message
with a body of `help' to ps-file-server@@adobe.com.)

If an EPS file to be included via \X'ps: import' does not start with
`%!PS-Adobe-...', gtroff will still include the file, but grops will
not add any fonts to the generated output file that are listed in the
EPS file, even though the files are listed in the `download' file and
are available in the devps directory.

----------------------------------------------------------------------

* I've configured groff for A4 paper, but gtroff still seems to think
  that the length of a page (as returned by `\n(.p') is 11 inches.

This is intentional.  The PAGE option during configuration is used
only by grops.  For compatibility with ditroff, the default page
length in gtroff is always 11 inches.  The page length can be changed
with the `pl' request.

A convenient way to set paper dimensions is to use the -dpaper option
of groff, together with proper -P options for the postprocessor
(overriding the default).  For example, use the following for PS
output on A4 paper in landscape orientation:

  groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps

See groff_tmac(5) for more information.

----------------------------------------------------------------------

* When I print the output of groff -Tps, the output is always shifted
  up by about 0.7 inches; I'm using 8.5x11 inch paper.

Make sure that the paper size is `letter'.  See groff_tmac(5).

----------------------------------------------------------------------

* When I try to run gxditview, I get the error:
  Error: Widget viewport has zero width and/or height

This error means you haven't correctly installed the application
defaults file, GXditview.ad; `make install' does this for you
automatically, so either you didn't do `make install', or you haven't
passed a good `--appresdir=<DIR>' argument to groff's configure script.

See the X(7) man page for information how and where application resource
files have to be located.  Look for the XAPPLRESDIR and XUSERFILESEARCHPATH
environment variables.

----------------------------------------------------------------------

* When I preview documents using -TX75 or -TX100, the layout is not
  the same as when I print the document with -Tps: the line and page
  breaks come in different places.

Use `groff -X -Tps'.

----------------------------------------------------------------------

* When I try to print the output of groff -Tps, I get no output at all
  from the printer, and the log file shows the error
  %%[ error: undefined; offendingcommand: BP ]%%
  I'm using TranScript spooling software.

This is a bug in the page reversal filter in early versions of
TranScript.  Change the `broken' parameter in
/usr/local/lib/groff/font/devps/DESC to 7.

----------------------------------------------------------------------

* When I preview groff -Tps output using the Sun OpenWindows 2.0
  pageview program, all the pages are displayed on top of each other.

This is a defect in pageview.  Change the `broken' parameter in
/usr/local/lib/groff/font/devps/DESC to 2.

----------------------------------------------------------------------

* With groff -TX75, -TX100 or -X, I can only view the first page.

The left mouse button brings up a menu that allows you to view other
pages.

----------------------------------------------------------------------

* When I print the output of groff -Tdvi, I just get a black dot in
  upper left corner.

Some dvi drivers (notably early versions of xtex) do not correctly
handle dvi files that use a resolution different from that used by dvi
files produced by TeX.  Try getting a more up to date driver.

----------------------------------------------------------------------

* How can I use groff with an old LaserJet printer that doesn't work
  with groff -Tlj4?

You have at least 3 options:

- use groff -Tps with GNU Ghostscript;

- use groff -Tdvi with a TeX .dvi to Laserjet driver;

- use groff with the LaserJet driver in Chris Lewis' psroff package
  (available for ftp from:
  ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17).

----------------------------------------------------------------------

* Groff seems to generate level 3 Postscript, but my printer is only a
  level 1 or 2 PostScript printer.

In fact groff generates only level 2 PostScript (or rather level 1
with some extensions; see grops(1) for more information how to disable
them).  The `%!PS-Adobe-3.0' comment at the beginning of PostScript
output generated by groff indicates that the file conforms to
version 3.0 of the Adobe Document Structuring Conventions.  The output
generated by groff should be printable on any PostScript printer.
Problems with groff output's not printing are most often caused by the
spooling system.



Platform-Dependent Macro Problems
=================================



* I get lots of errors when I use groff with the AT&T -mm macros.

Use the groff -mm macros.

----------------------------------------------------------------------

* groff produces wrapper macros for `ms' and friends which call the
  system's original macros.  Then, to get groff's ms macro package I
  have to use `-mgs' instead `-ms'.  Can I avoid this?

Yes.  Configure and compile groff as usual, but install it with

  make install tmac_wrap=""

Then no wrapper files are produced, and `-ms' will use groff's `ms'
macros.

----------------------------------------------------------------------

* I'm having problems formatting HP-UX 9.0 man pages with groff -man.

Copy HP's tmac.an into /usr/local/share/groff/site-tmac/an.tmac, and
either put `.cp 1' at the beginning or filter it (and any files it
.so's) through tmac/fixmacros.sed.

----------------------------------------------------------------------

* I get errors using the Unix -ms macros with groff -e -C.

Apply this change:

*** /usr/lib/ms/ms.eqn	Tue Apr 25 02:14:28 1989
--- ms.eqn	Sun Nov 11 10:33:59 1990
***************
*** 22,29 ****
  ..
  .	\" EN - end of a displayed equation
  .de EN
! .if !\\*(10 .br
  .di
  .rm EZ
  .nr ZN \\n(dn
  .if \\n(ZN>0 .if \\n(YE=0 .LP
--- 22,30 ----
  ..
  .	\" EN - end of a displayed equation
  .de EN
! .if \\n(.k>0 .br
  .di
+ .ds 10 \\*(EZ\\
  .rm EZ
  .nr ZN \\n(dn
  .if \\n(ZN>0 .if \\n(YE=0 .LP

----------------------------------------------------------------------

* I'm having problems formatting Ultrix man pages with groff -man.

The Ultrix man pages use a number of non-standard extensions to the
Unix man macros.  One solution is to use the Ultrix -man macros with
groff.  Copy /usr/lib/tmac/tmac.an to
/usr/local/share/groff/site-tmac/an.tmac and apply the following patch
(from Frank Wortner):

*** /usr/local/lib/groff/tmac/tmac.an     Wed Sep  9 12:29:28 1992
--- /usr/lib/tmac/tmac.an       Fri Jul 24 19:58:19 1992
***************
*** 489,495 ****
  .     \" make special case of shift out of italic
  .de }S
  .ds ]F
! .if \\$12 .if !\\$5 .ds ]F \^
  .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
  .el \\$3
  .}f
--- 489,495 ----
  .     \" make special case of shift out of italic
  .de }S
  .ds ]F
! .if \\$12 .if !\\$5 .ds ]F\^
  .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
  .el \\$3
  .}f

Another possible solution is to install tmac/man.ultrix as
/usr/local/share/groff/site-tmac/man.local.

----------------------------------------------------------------------

* On an SGI system, how can I make the man command use groff?

From David Hinds <dhinds@@allegro.stanford.edu> (some of these steps
are unnecessary if you install with the `g' Makefile variable defined
as empty):

Create a script called 'eqn':

 > #! /bin/sh
 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
 > geqn $*

and a script called 'neqn':

 > #! /bin/sh
 > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
 > geqn -Tascii $*

and do:

 > ln -s gnroff nroff

and edit the end of the gnroff script to be:

 > rest=`echo ${1+"$@@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`
 > exec groff -Wall -mtty-char $T $opts $rest

To get PostScript output from 'man -t', you also need to create a
'psroff' script similar to 'nroff'.  Here are the context diffs:

*** /usr/local/bin/nroff        Sat Feb 13 15:51:09 1993
--- /usr/local/bin/psroff       Sat Feb 13 17:45:46 1993
***************
*** 1,8 ****
  #! /bin/sh
! # Emulate nroff with groff.

  prog="$0"
! T=-Tascii
  opts=

  for i
--- 1,8 ----
  #! /bin/sh
! # Emulate psroff with groff.

  prog="$0"
! T=-Tps
  opts=

  for i
***************
*** 25,30 ****
--- 25,33 ----
        -Tascii|-Tlatin1)
                T=$1
                ;;
+       -t)
+               # ignore -- default is send to stdout
+               ;;
        -T*)
                # ignore other devices
                ;;
***************
*** 49,53 ****
  rest=`echo ${1+"$@@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`

  # This shell script is intended for use with man, so warnings are
  # probably not wanted.  Also load nroff-style character definitions.
! exec groff -Wall -mtty-char $T $opts $rest
--- 52,56 ----
  rest=`echo ${1+"$@@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'`

  # This shell script is intended for use with man, so warnings are
! # probably not wanted.
! exec groff -Wall $T $opts $rest



Compilation Problems
====================



* Compilation dies with

    y.tab.c: In function `int yyparse()':
    y.tab.c: `size_t' undeclared in namespace `std'

* bison reports conflicts (either on stderr or in the `pic.output'
  file) while processing `pic.y', and the produced pic binary doesn't
  work at all.

You need bison version 1.875b or greater.  Alternatively, use yacc or
byacc.

----------------------------------------------------------------------

* There are many empty `Makefile.dep' files.  Is this a bug?

No.  Real dependency files are created with a `make depend' call.

----------------------------------------------------------------------

* On HP-UX, the compiler complains about missing symbol `alloca'.

Say

  export LDFLAGS=-lPW

before starting the configure script.

----------------------------------------------------------------------

* The configure script fails on OS/390 (z/OS) Unix.

[This has been fixed in z/OS V1R3 (aka OS/390 R13).]

There is a bug in the Language Environment (LE) whereby the test
program for static destructors fails.  You will see the message
`configure: error: a working C++ compiler is required'

Applying PTF UQ42006 is supposed to fix this, but the test program is
still returning the wrong value (1).  To work around this problem, you
can comment out the following in the configure script (near line 2029).
This will effectively bypass the test (static constructors and
destructors do actually work properly):

#if { (eval echo "$as_me:2029: \"$ac_link\"") >&5
#  (eval $ac_link) 2>&5
#  ac_status=$?
#  echo "$as_me:2032: \$? = $ac_status" >&5
#  (exit $ac_status); } && { ac_try='./conftest$ac_exeext'
#  { (eval echo "$as_me:2034: \"$ac_try\"") >&5
#  (eval $ac_try) 2>&5
#  ac_status=$?
#  echo "$as_me:2037: \$? = $ac_status" >&5
#  (exit $ac_status); }; }; then
#  echo "$as_me:2039: result: yes" >&5
#echo "${ECHO_T}yes" >&6
#else
#  echo "$as_me: program exited with status $ac_status" >&5
#echo "$as_me: failed program was:" >&5
#cat conftest.$ac_ext >&5
#echo "$as_me:2045: result: no" >&5
#echo "${ECHO_T}no" >&6;{ { echo "$as_me:2046: error: a working C++ compiler is required" >&5
#echo "$as_me: error: a working C++ compiler is required" >&2;}
#   { (exit 1); exit 1; }; }
#fi

----------------------------------------------------------------------

* I get errors when I try to compile groff with DEC C++.

Fix the declaration of write() in <unistd.h> so that the second
argument is a const char *.  Fix the declaration of open() in
<sys/file.h> so that the first argument is a const char *.

----------------------------------------------------------------------

* On a host using Unix make (e.g. Solaris), if you are compiling for
  multiple architectures by building in a subdirectory, the make stops
  with a message like this:

    make: Fatal error: Don't know how to make target `assert.o'

  or like this:

    make: Fatal error: Can't find /u/src/groff/src/include/Makefile.sub': No such file or directory

This occurs because GNU make and Unix make handle VPATH differently,
and the groff build relies on GNU make's VPATH handling.

Use GNU make <http://www.gnu.org/software/make/> to work around this.
In Solaris 8 and 9, GNU make is on the Software Companion CD in
package SFWgmake and is installed as /opt/sfw/bin/gmake.  Prebuilt
versions of GNU make for Solaris are also available from
sunfreeware.com.

----------------------------------------------------------------------

* On Ultrix, the make program stops with the message

    *** Error code 1

    Stop.

  for no apparent reason.

Use GNU make.

----------------------------------------------------------------------

* I'm having problems compiling groff on 386BSD 0.1.

If you're using ash as /bin/sh, you'll need the following patch.

*** gendef.sh.org	Sun Jun 30 13:30:36 1991
--- gendef.sh	Sun Feb 28 10:23:49 1993
***************
*** 3,9 ****
  file=$1
  shift
  
! defs="#define $1"
  shift
  for def
  do
--- 3,10 ----
  file=$1
  shift
  
! x=$1
! defs="#define $x"
  shift
  for def
  do

You'll also need to change dirnamemax.c so that it doesn't use
pathconf().

----------------------------------------------------------------------

* While compiling on Xenix, ranlib libgroff.a fails.

The system ranlib can't handle externals longer than 40 characters.
Use the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1
instead.

----------------------------------------------------------------------

* I get errors when I try to compile groff with Sun C++ version 3 or
  earlier.

Groff requires header files that are moderately compatible with AT&T
C++ and ANSI C.  With some versions of Sun C++, the supplied header
files need some of the following changes to meet this requirement:
<string.h> must declare the mem* functions, (just add `#include
<memory.h>' to <string.h>); the first argument to fopen and freopen
should be declared as `const char *'; the first argument to fread
should be declared as `void *'; the first argument to fwrite should be
declared as `const void *'; malloc should be declared to return
`void *'; in <alloca.h>, the declaration `extern "C" { void
*__builtin_alloca(int); }' should be added; in <sys/signal.h> the
return type and the second argument type of signal() should be changed
to be `void (*)(int)'.

You can either change them in place, or copy them to some other
directory and include that directory with a -I option.

----------------------------------------------------------------------

* I get errors when I try to compile groff with Forte Development 6
  or 6u1, or Sun C++ version 5.0 through 5.2.

This is a known problem; see Sun bug #4301919.  See Sun patches
109482, 109490, 109508, and 109509 for fixes.

----------------------------------------------------------------------

* I get warnings from the Sun linker while using gcc 3.4.0:

  ld: warning: relocation error: R_SPARC_UA32:
      file groff/src/libs/libgroff/libgroff.a(getopt.o): symbol optarg:
      external symbolic relocation against non-allocatable
      section .debug_info; cannot be processed at runtime:
      relocation ignored

This seems to be a known problem (Sun bugs #4910101 and #4910810,
filed in September 2003; gcc bug #15599, filed May 2004) without a
public fix as of this writing.  A work-around is to use option
`-gstabs+' instead of `-g' (and a high probability that the output is
only debuggable with gdb but not with Sun's debuggers).

----------------------------------------------------------------------

* I get lots of `numeric overflow' error messages whenever I run
  groff; I compiled groff with AT&T C++ 2.0 with an ANSI C compiler.

Make sure -DCFRONT_ANSI_BUG is included in DEFINES in the top-level
Makefile.  If that doesn't solve the problem, define INT_MIN as
-INT_MAX in libgroff/lib.h.

----------------------------------------------------------------------

* When compiling on MacOS X, groff compiles but does not run well,
  especially `eqn', causing many `can't break line' messages.

Use  ./configure CXX=g++2  then make as usual.
@


