summaryrefslogtreecommitdiffstats
path: root/PROBLEMS
diff options
context:
space:
mode:
Diffstat (limited to 'PROBLEMS')
-rw-r--r--PROBLEMS1321
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: