Initial revision

1 files changed, 575 insertions, 0 deletions

diff --git a/PROBLEMS b/PROBLEMS
new file mode 100644
index 00000000..dbadbdee
--- /dev/null
+++ b/PROBLEMS
@@ -0,0 +1,575 @@
+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.
+
+* 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.
+
+* 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 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 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'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.
+
+* 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
+  System Programmer's Manual
+you will need to change the line
+  .el .ds an-extra3 \"System Programmer's Manual
+to
+  .el .ds an-extra3 System 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