Adding upstream version 1.23.0.upstream/1.23.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1321 insertions, 0 deletions

diff --git a/PROBLEMS b/PROBLEMS
new file mode 100644
index 0000000..c40d499
--- /dev/null
+++ b/PROBLEMS
@@ -0,0 +1,1321 @@
+    Copyright 1989-2023 Free Software Foundation, Inc.
+
+    Copying and distribution of this file, with or without modification,
+    are permitted in any medium without royalty provided the copyright
+    notice and this notice are preserved.
+
+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.
+
+----------------------------------------------------------------------
+
+Problems are organized into categories underscored with equals signs.
+
+* General Problems
+* Printing and Display Problems
+* Platform-Dependent Macro Problems
+* Compilation Problems
+
+Within each category, items are organized in reverse chronological order
+(that is, with the most recent first).  groff version numbers
+corresponding to their inclusion in this file are included as
+guideposts.  Entries have been revised for clarity in the years since.
+
+In the following discussions, several references to "/usr/local" are
+made.  You should read this directory name as the destination directory
+you set up with the "--prefix" option to groff's "configure" script.
+
+
+General Problems
+================
+
+
+[groff 1.23.0]
+
+* gdiffmk doesn't work / its automated test fails.
+
+Some portability issues are known to affect groff's gdiffmk utility.
+
+- A defect in GNU diffutils 3.9 (January 2023) causes gdiffmk to
+  malfunction and its automated test to fail.  See
+  <https://debbugs.gnu.org/db/61/61193.html>.
+
+- gdiffmk does not work with BusyBox diff (which does not implement GNU
+  diff's "-D" option).
+
+- gdiffmk does not work on FreeBSD due to specifics of that platform's
+  expr(1) implementation.
+
+  gdiffmk uses the expr(1) command to parse its arguments.  FreeBSD has
+  extended the syntax of its expr command in a non-backward compatible
+  way that it claims better conforms with POSIX's utility syntax
+  guidelines with respect to option processing: however, POSIX mandates
+  no options for expr.  Other implementations of expr do not support
+  traditional Unix-style options ('-a', '-b', ...), and perhaps as a
+  consequence do not follow FreeBSD's interpretation of the guidelines.
+  You way want to set $EXPR_COMPAT in your shell environment.  We hope
+  to have a workaround for this behavior in a future release.
+
+----------------------------------------------------------------------
+
+* The `PDFPIC` macro doesn't work / its automated test fails.
+
+  FAIL: tmac/tests/pdfpic_does-not-choke-on-bad-pdfinfo-output.sh
+
+Due to a limitation (shared by AT&T troff) in the way the `sy` request
+constructs a C string argument to the C library's system(3) function,
+groff requires a GNU sed(1) extension that interprets "\n" as a newline
+in the replacement text of the 's' command.  (We might enhance GNU
+troff's `sy` request to avoid this dependency in the future.)  We have
+observed this problem on Solaris 10 and 11 and Mac OS X 10.11.6, but not
+macOS 12: the last's sed supports the extension in question.
+
+Install GNU sed in the default $PATH as "gsed" and edit
+tmac/pdfpic.tmac.  On line 172, change "sed" to "gsed".  Alternatively,
+you can use the absolute path to GNU sed's location.  (`system()`
+sanitizes $PATH to avoid privilege escalation.)  Then (re-)make the
+"check" target or format your PDFPIC-employing document again.
+
+----------------------------------------------------------------------
+
+[groff 1.19.2]
+
+* When viewing man pages, some characters on my UTF-8 terminal emulator
+  look funny or copy-and-paste wrong.  Why?
+
+Some Unicode Basic Latin ("ASCII") input characters are mapped to
+non-Basic Latin code points in output for consistency with other output
+devices, like PDF.  See groff_man_style(7) and groff_char(7) for correct
+input conventions and background.  If you use the correct groff special
+character escape sequences to input them, you will get correct output no
+matter what device the input is formatted for.
+
+However, many man pages are written in ignorance of the correct special
+characters to obtain the desired glyphs.  You can conceal these errors
+by adding the following to your site-local man(7) configuration.  The
+file is called "man.local"; its installation directory depends on how
+groff was configured when it was built.
+
+--- start ---
+.if '\*[.T]'utf8' \{\
+.  char ' \[aq]
+.  char - \-
+.  char ^ \[ha]
+.  char ` \[ga]
+.  char ~ \[ti]
+.\}
+--- end ---
+
+You may also wish to do the same for "mdoc.local".
+
+In man pages (only), groff maps the minus sign special character '\-' to
+the Basic Latin hyphen-minus (U+002D) because man pages require this
+glyph and there is no historically established *roff input character,
+ordinary or special, for obtaining it when a hyphen and minus sign are
+both separately available.  To obtain a true minus sign, use the special
+character escape sequences '\(mi' or '\[mi]'.
+
+----------------------------------------------------------------------
+
+* Displaying a man page on a terminal with/without my favorite pager
+  shows garbage.
+
+groff's terminal output driver, grotty, by default uses ISO 6429/ECMA-48
+escape sequences understood by video terminals and their emulators,
+rather than the overstriking sequences implemented for typewriter-like
+terminals used in the 1960s and 1970s.  These escape sequences control
+display attributes like bold and italic or oblique typefaces,
+underlining, foreground and background color selection, and hyperlink
+marking.  Terminal emulators that claim compatibility with the DEC
+VT100, Linux console driver, or xterm should ignore well-formed escape
+sequences that they are not able to support, but some implementations
+are buggy.
+
+Furthermore, the popular "less" pager by default assumes that its input
+will use overstriking sequences.  (This is a surprising choice, as users
+of paper terminals had no need for pager programs; to "scroll back", the
+operator would simply physically pull up the spool of ejected paper to
+read it.)  less(1) must instead be given the '-R' option to interpret
+escape sequences used by video terminals.  Be aware that the
+overstriking convention is inescapably ambiguous in some output
+sequences.  See the grotty(1) man page.
+
+Hyperlink support in terminal emulators is a relatively new initiative
+(as of 2022) employing a sequence known as "OSC 8".
+  https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
+
+Due to the feature's young age, the man and mdoc macro packages have a
+configuration switch for hyperlink support, and it may be disabled in
+your site's man.local and mdoc.local files.  Use a command like
+  printf '\033]8;;man:grotty(1)\033\\grotty(1)\033]8;;\033\\\n' | more
+to check your terminal and pager for OSC 8 support.  If you see
+"grotty(1)" and no additional garbage characters, then you may wish to
+edit those site files to remove any lines that disable this feature.
+
+There are a couple of workarounds if you prefer or require overstriking
+sequences rather than ISO 6429/ECMA-48 escape sequences.
+
+  1. Set the GROFF_NO_SGR environment variable to any value.
+
+  2. Pass option '-c' to grotty (that is, add '-P-c' to groff's
+     command-line options).
+
+The third and probably best option is to use terminal and pager programs
+that handle standardized video terminal escape sequences well.
+
+----------------------------------------------------------------------
+
+[groff 1.16]
+
+* 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, the Bell Labs document "Troff User's
+Manual" (Computing Science Technical Report #54) incorrectly claims that
+yr is the last two digits of the year.  This claim has never been true
+AT&T troff nor 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 1.09]
+
+* Where can I get grap?
+
+Ted Faber <faber@lunabase.org> has written a freely available grap:
+
+  http://www.lunabase.org/~faber/Vault/software/grap/
+
+You need version 1.42 or newer.
+
+----------------------------------------------------------------------
+
+* 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 don't give the height and depth of the argument to \w,
+but the maximum vertical displacements of the text baseline above
+(\n(st) and below (\n(sb) its original position.  Consider an example
+where no text is formatted, but small vertical motions are used.
+
+  \w"\v'-1u'\v'3u'"
+  .tm st=\n(st, sb=\n(sb
+    st=1, sb=-2
+
+Observe that the sign convention of these registers is opposite that of
+relative vertical motion.  (This is how Documenter's Workbench troff
+and Heirloom Doctools troff work as well.)
+
+The height and depth of formatted text in the \w argument are available
+in the \n[rst] and \n[rsb] registers; these are groff extensions.
+
+----------------------------------------------------------------------
+
+[groff 1.08]
+
+* 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 1.07]
+
+* 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;
+
+----------------------------------------------------------------------
+
+[groff 1.06]
+
+* 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 attempts 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 takes a *long* time on slow
+computers.)
+
+----------------------------------------------------------------------
+
+[groff 1.01]
+
+* gpic 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.
+
+----------------------------------------------------------------------
+
+* Groff doesn't use the font names I'm used to.
+
+Use the `ftr' request.  See groff_diff(7).
+
+----------------------------------------------------------------------
+
+* I get errors using the Unix -ms macros with groff -e -C.
+
+Apply this change.  Be careful of copying and pasting it; literal BEL
+characters (Control+G) appear in the source--this is an AT&T troff idiom
+in output comparisons that is never necessary in GNU troff.
+
+*** /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.
+
+----------------------------------------------------------------------
+
+* 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) does NOT restore the previous point-size;
+instead it is 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 need to put
+modified macros from tmac/an.tmac into man.local.  More information is
+available in groff_man(7).
+
+----------------------------------------------------------------------
+
+* While formatting a manual page, groff complains about not being able
+  to break lines.  A line like the following seems to cause this.
+    .TP \w'label'+2
+
+The groff_man(7) man page says that the default scaling unit for the
+`TP` macro is 'n' (ens), and that is how the groff man macros are
+implemented.  Consequently, the macro argument above is evaluated
+equivalently to this expression.
+
+  \w'label'n+2n
+
+AT&T troff's man macros don't implement this correctly (probably because
+it's hard to do in that troff); instead, they append 'n' to the entire
+argument, so that it is evaluated as if it were written as follows.
+
+  \w'label'u+2n
+
+The solution is to fix the manual page.
+
+  .TP \w'label'u+2
+
+It might be better still to avoid such computations in macro arguments,
+however; programs that are not *roff formatters that attempt to
+interpret man pages can lack the ability to interpret numeric
+expressions.  See section "Portability" of groff_man_style(7).
+
+
+
+Printing and Display Problems
+=============================
+
+
+
+[groff 1.09]
+
+* 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.
+
+----------------------------------------------------------------------
+
+[groff 1.04]
+
+* 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 `--appdefdir=<DIR>' argument to groff's configure
+script.
+
+See the X(7) man page for information how and where application
+defaults files have to be located.  Look for the XAPPLRESDIR and
+XUSERFILESEARCHPATH environment variables.
+
+----------------------------------------------------------------------
+
+[groff 1.01]
+
+* 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 still includes the file, but grops does 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 AT&T troff, the default page
+length in GNU troff 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 command for
+PostScript output on A4 paper in landscape orientation.
+
+  groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
+
+See groff(1) and 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 format is "letter".  See groff_tmac(5).
+
+----------------------------------------------------------------------
+
+* 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.  You can also press <space> and <backspace> to advance and
+retreat the current page view, respectively.
+
+----------------------------------------------------------------------
+
+* 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.
+
+----------------------------------------------------------------------
+
+* 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'.
+
+
+
+Platform-Dependent Macro Problems
+=================================
+
+
+
+[groff 1.17]
+
+* 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' uses groff's `ms'
+macros.
+
+----------------------------------------------------------------------
+
+[groff 1.09]
+
+* 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
+
+----------------------------------------------------------------------
+
+[groff 1.08]
+
+* 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.
+
+----------------------------------------------------------------------
+
+[groff 1.07]
+
+* 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.  [To be fair, SunOS did too, albeit not as many; see
+groff_man(7).  groff embraced SunOS's extensions early on, but not
+Ultrix's. --GBR in 2023]  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.
+
+----------------------------------------------------------------------
+
+[groff 1.01]
+
+* I get lots of errors when I use groff with the AT&T -mm macros.
+
+Use the groff -mm macros.
+
+
+
+Compilation Problems
+====================
+
+
+
+[groff 1.23.0]
+
+* The "initialization_is_quiet" test fails on my NetBSD box.
+
+This is a known problem.  We haven't tracked down the cause yet, but
+have improved the reporting of the test output in hopes that we can
+isolate it in a future release.
+
+----------------------------------------------------------------------
+
+* I get a build failure on Cygwin / a system using newlib and GCC 11.
+
+"newlib" defines a function called "utoa" which conflicts with a static
+(file scope-local) function in src/libs/libxutil/XFontName.c.
+
+We expect to fix this in the near future; in the meantime, you can patch
+the file to rename the function (and update its call sites) or, if you
+don't require the "gxditview" output previewer or "xtotroff" utility,
+you can build groff without X11 support.
+
+  $ make distclean
+  $ ./configure --without-x
+
+----------------------------------------------------------------------
+
+* The "check-default-foundry" test fails when I run "make check".
+
+Your Ghostscript installation may have its fonts embedded in the
+executable; this can be discerned by searching for the pattern "%rom%"
+in its search path.
+
+  $ gs -h | grep '%rom%'
+
+The consequence is that gropdf(1) will be unable to embed fonts into PDF
+files it generates (apart from groff's "EURO" font) when the default
+foundry is used.  This is the same outcome as if Ghostscript were not
+installed at all.  If you install URW fonts (see "INSTALL.extra"), you
+will be able to embed them all by using the "U" foundry with gropdf to
+overcome this problem.
+
+----------------------------------------------------------------------
+
+* I get a lot of warnings about "sprintf" on macOS.
+
+Apple has decided to treat the sprintf() standard C library function as
+deprecated even though the C standard itself has not.
+
+https://developer.apple.com/forums/thread/714675
+
+----------------------------------------------------------------------
+
+* I get a make(1) failure involving grep and the groff_man.7.man.in file
+  on Solaris 11.
+
+Solaris make(1) has a bug easily exhibited by the following Makefile.
+
+all:
+	! false
+
+Use GNU make instead; it may be available in /opt/csw/bin/gmake.
+
+----------------------------------------------------------------------
+
+* Tests fail when I run "make check" on Solaris 10 or 11.
+
+The test suite expects a POSIX-conforming shell and utilities.  Solaris
+10 does not offer these in the default $PATH.  We try to use features
+standardized no later than POSIX Issue 4 (1994).  Unfortunately even
+that is too recent for some implementations.  Solaris 11 has a (mostly)
+conforming shell.  It may help to ensure that "/usr/xpg6/bin" and
+"/usr/xpg4/bin" precede "/usr/bin" in the $PATH when building groff.
+
+For Solaris 10, it is necessary to modify the shell-based test scripts
+in place to use a conforming shell.  Here is an example.
+
+  $ gsed -i -e '1s@#!/bin/sh@#!/usr/xpg4/bin/sh@' \
+      `find . -name '*.sh' | grep /tests/`
+  $ PATH=/usr/xpg4/bin:$PATH gmake check
+
+Some test failures remain expected on Solaris 10 and/or 11.
+
+1.  FAIL: contrib/hdtbl/examples/test-hdtbl.sh
+
+    /usr/bin/tr on Solaris 10 is non-conforming with the POSIX Issue 4
+    standard.  It furthermore issues anonymous diagnostics, saying only
+    "Bad string".
+
+    Install tr from GNU coreutils in the $PATH.  Edit line 57 of each of
+    contrib/hdtbl/examples/fonts_x.in and
+    contrib/hdtbl/examples/fonts_n.in.  Change "tr" to "gtr".
+    Alternatively, you can use the absolute path to GNU tr's location.
+    Re-run "gmake check" as above.  (Some files will be rebuilt.)
+
+    The tr commands in /usr/xpg4/bin and /usr/xpg6/bin also work, but
+    the documents constructed from the above inputs use groff's `pso`
+    request, which wraps the standard C library `popen()` function,
+    which sanitizes $PATH to avoid privilege escalation, thus making it
+    likely that the non-conforming tr in /usr/bin will be found first.
+
+2.  FAIL: src/roff/groff/tests/initialization_is_quiet.sh
+    FAIL: src/roff/groff/tests/msoquiet_works.sh
+    FAIL: src/roff/groff/tests/soquiet_works.sh
+
+    (The first of these might be SKIPped instead.)
+
+    /usr/xpg4/bin/sh is non-conforming with the POSIX Issue 4 standard,
+    despite its name.  Its "unset" builtin is buggy.  (The /usr/bin/sh
+    in Solaris 11 does not have this problem.)
+
+    These tests use the "unset" shell builtin command to prevent
+    environment variables from confounding test results.
+
+    POSIX says "[u]nsetting a variable ... that was not previously set
+    is not considered an error and will not cause the shell to abort."
+
+    Nevertheless this builtin returns an error exit status in this
+    circumstance.
+
+    $ /usr/xpg4/bin/sh -c 'unset _NON_EXISTENT_XYZ; echo $?'
+    1
+
+    You may disregard these failures, edit the test scripts to append
+    "|| true" to the "unset" commands, or change the scripts to use GNU
+    Bash or some other POSIX-conforming shell as illustrated above.
+
+----------------------------------------------------------------------
+
+* I get warnings from afmtodit about names already being mapped.
+
+afmtodit: AGL name 'Delta' already mapped to groff name '*D'; ignoring AGL name 'uni0394'
+
+You can ignore these if they're in the form shown above, where the
+ignored AGL name is 'uniXXXX' and 'XXXX' is four hexadecimal digits.
+The Adobe Glyph List (AGL) has its own names for glyphs; they are often
+different from groff's special character names.  The afmtodit program is
+constructing a mapping from groff special character names to AGL names;
+this can be a one-to-one or many-to-one mapping, but one-to-many will
+not work, so afmtodit discards the excessive mappings.  The example you
+see above is telling you that the groff font description that afmtodit
+is writing cannot map the groff special character '*D' to both 'Delta'
+and 'uni0394'.
+
+Which, if any, such warnings you see depends on the version of the URW
+fonts you are building groff against.  See the '--with-urw-fonts-dir'
+option to the "configure" script, and the afmtodit(1) and groff_char(7)
+man pages for more background.
+
+----------------------------------------------------------------------
+
+* I am building from the Git repository, using 'autoreconf' from a GNU
+  Autoconf release earlier than 2.69, and I get this.
+
+  /usr/share/aclocal/gtkglextmm-1.2.m4:225:
+    warning: underquoted definition of AC_GTKGLEXTMM_SUPPORTS_MULTIHEAD
+  /usr/share/aclocal/gtkglextmm-1.2.m4:225:
+    run info '(automake)Extending aclocal'
+  /usr/share/aclocal/gtkglextmm-1.2.m4:225:
+    or see http://www.gnu.org/software/automake/manual/automake.html#Extending-aclocal
+
+Ignore this.  It doesn't occur in more recent versions of 'autoreconf'.
+
+----------------------------------------------------------------------
+
+* I get warnings about special characters in the groff_char(7) man page.
+
+troff:man/groff_char.7:1033: warning: special character '.j' not defined
+
+  (...and similar for 'vA', 'bs', '-+', 'coproduct', and '+e'.)
+
+You can ignore these.  groff defines a handful of special characters for
+which historical PostScript fonts usually did not possess glyphs.
+Except for 'bs' (the Bell System logo), we hope to provide fallbacks or
+a supplementary PostScript font in groff in the future (as was done for
+the Euro glyph).
+
+----------------------------------------------------------------------
+
+* I get warnings about the "vasnprintf" function.
+
+lib/vasnprintf.c: In function 'vasnprintf':
+lib/vasnprintf.c:5268:27: warning: format not a string literal, argument types not checked [-Wformat-nonliteral]
+(and similar)
+
+The groff source tree includes gnulib, the GNU portability library
+<https://www.gnu.org/software/gnulib/>.  These warnings are about its
+source code and that project's responsibility to resolve.  We expect a
+future release of gnulib to do so.
+
+----------------------------------------------------------------------
+
+[groff 1.22.4]
+
+* When compiling on NetBSD, make issues warnings like
+
+  Warning: line 28: Unable to locate font(s)
+  URWGothicL-Demi,a010015l.pfb on the given path(s)
+
+  and
+
+  Warning: line 77: Failed to create groff font 'U-AB' by running
+  afmtodit
+
+In this case install the package "urw-fonts":
+
+  pkgin install urw-fonts
+
+and make the font path known to ghostscript, e.g. with (ksh):
+
+  export GS_LIB=/usr/pkg/share/fonts/urw
+
+----------------------------------------------------------------------
+
+* Currently (December 2015) building groff fails on NetBSD and
+  FreeBSD with the message:
+
+  make[1]: don't know how to make contrib/chem/chem.1. Stop
+
+The reason is a bug in the make(1) tool used on those systems related
+to .SUFFIXES lines.
+
+A temporary workaround is to change the Makefile line
+
+  .SUFFIXES: .roff .in .ps .mom .pdf .me .ms .ps .html .txt .texi \
+    .dvi .pdf .xhtml .man .c .cpp .log .o .obj .sed .sin \
+    .test .test$(EXEEXT) .trs .ypp
+
+into
+
+  .SUFFIXES: .man .roff .in .ps .mom .pdf .me .ms .ps .html .txt \
+    .texi .dvi .pdf .xhtml .c .cpp .log .o .obj .sed .sin \
+    .test .test$(EXEEXT) .trs .ypp
+
+(put .man at begin of the list).
+
+The bug is reported to the maintainer of the make(1) tool of those
+systems.
+
+----------------------------------------------------------------------
+
+[groff 1.22.3]
+
+* Configuration on MacOS X 10.6 doesn't succeed.
+
+Use
+
+  ./configure CXX=g++-4.2
+
+----------------------------------------------------------------------
+
+[groff 1.21]
+
+* In MacOS X, I want to completely replace the groff that came with
+  the system.
+
+Use
+
+  ./configure --prefix=/usr --mandir=/usr/share/man
+
+then
+
+  make
+  make install
+
+Note that subsequent system updates may replace your groff.
+
+----------------------------------------------------------------------
+
+[groff 1.19.2]
+
+* 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).
+
+----------------------------------------------------------------------
+
+[groff 1.19]
+
+* When compiling on MacOS X 10.2, 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.
+
+----------------------------------------------------------------------
+
+[groff 1.18.0]
+
+* 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.
+
+----------------------------------------------------------------------
+
+[groff 1.17]
+
+* On HP-UX, the compiler complains about missing symbol `alloca'.
+
+Say
+
+  export LDFLAGS=-lPW
+
+before starting the configure script.
+
+----------------------------------------------------------------------
+
+[groff 1.16.1]
+
+* 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.
+
+----------------------------------------------------------------------
+
+* There are many empty `Makefile.dep' files.  Is this a bug?
+
+No.  Real dependency files are created with a `make depend' call.
+
+----------------------------------------------------------------------
+
+[groff 1.16]
+
+* 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 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 effectively bypasses 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
+
+----------------------------------------------------------------------
+
+[groff 1.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.
+
+----------------------------------------------------------------------
+
+[groff 1.08]
+
+* 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 1.07]
+
+* 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 program stops with the message
+
+    *** Error code 1
+
+    Stop.
+
+  for no apparent reason.
+
+Use GNU make.
+
+----------------------------------------------------------------------
+
+[groff 1.01]
+
+* 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.
+
+
+
+##### Editor settings
+Local Variables:
+fill-column: 72
+mode: text
+End:
+vim: set autoindent textwidth=72: