PROBLEMS: Resequence file.

Explain the order that it's in, to aid readers and, I hope, help
maintainers keep it in order.

Still to do: replace Git commit info with groff release info.

1 files changed, 588 insertions, 502 deletions

diff --git a/PROBLEMS b/PROBLEMS
index 102d85024..0b8490f22 100644
--- a/PROBLEMS
+++ b/PROBLEMS
@@ -17,60 +17,43 @@ Problems are organized into categories underscored with equals signs.
 * 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.
+
 
 General Problems
 ================
 
 
+[groff 405fe32847a598962dc3ad8469b9ed0bac4c50ba 2023-03-06]
 
-* 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
+* gdiffmk doesn't work on FreeBSD; I get errors from "expr".
 
-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.
+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.
 
-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.
+[groff 10274fb69e517b2c4b10fcd0ba3347e5bd0eefd7 2023-02-11]
 
-  2. Pass option '-c' to grotty (that is, add '-P-c' to groff's
-     command-line options).
+* gdiffmk doesn't work / its automated test fails.
 
-The third and probably best option is to use terminal and pager programs
-that handle standardized video terminal escape sequences well.
+A defect in GNU diffutils 3.9 (January 2023) causes gdiffmk to
+malfunction.  See <https://debbugs.gnu.org/db/61/61193.html>.
 
 ----------------------------------------------------------------------
 
+[groff 5195c5d7bf8df5478fce6714ea89844e9e228175 2003-07-21]
+
 * When viewing man pages, some characters on my UTF-8 terminal emulator
   look funny or copy-and-paste wrong.  Why?
 
@@ -108,27 +91,58 @@ character escape sequences '\(mi' or '\[mi]'.
 
 ----------------------------------------------------------------------
 
-* gdiffmk doesn't work / its automated test fails.
+[groff 5c1dfd65245b5769d514c4b6f78e6272f132e229 2003-07-18]
 
-A defect in GNU diffutils 3.9 (January 2023) causes gdiffmk to
-malfunction.  See <https://debbugs.gnu.org/db/61/61193.html>.
+* 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.
 
-* gdiffmk doesn't work on FreeBSD; I get errors from "expr".
+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.
 
-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.
+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
@@ -153,94 +167,7 @@ or, if you want to be portable to older troff versions, as follows:
 
 ----------------------------------------------------------------------
 
-* 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.
-
-----------------------------------------------------------------------
-
-* gtroff doesn't understand lines like `.ce99' with no space between
-  the name of the request or macro and the arguments.
-
-gtroff requires a space between macro or request and its arguments
-because it allows the use of long names for macros and requests.  You
-can use the -C option or the `cp' request to put gtroff into a
-compatibility mode in which it is not possible to use long names for
-macros but in which no space is required between macros and their
-arguments.  The use of compatibility mode is strongly discouraged.
-
-----------------------------------------------------------------------
-
-* groff -Tdvi produces dvi files that use fonts at weird
-  magnifications.
-
-Yes, it does.  You may need to compile fonts with Metafont at these
-magnifications.  The CompileFonts script in the devdvi/generate
-directory may help you to do this.  (It takes a *long* time on slow
-computers.)
-
-----------------------------------------------------------------------
-
-* Groff doesn't use the font names I'm used to.
-
-Use the `ftr' request.  See groff_diff(7).
-
-----------------------------------------------------------------------
-
-* 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.
-
-----------------------------------------------------------------------
-
-* gpic doesn't accept the syntax `chop N M' for chopping both ends of
-  a line.
-
-The correct syntax is `chop N chop M'.
-
-----------------------------------------------------------------------
-
-* With gpic -t, when I print `line ->; box' using a dvi to ps program,
-  the arrow head sticks through into the inside of the box.
-
-The dvi to ps program should be modified to set the line cap and line
-join parameters to 1 while printing tpic specials.
-
-----------------------------------------------------------------------
-
-* gtroff gives warnings about lines like
-  .ev	\" a comment
-  (with a tab after the .ev).
-
-A tab character cannot be used as a substitute for a space character
-(except in one case: between a control character at the beginning of a
-line and the name of a macro or request).  For example, in Unix troff
-
-  .ps	\" restore the previous point size
-
-(with a tab after the .ps) 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).
-
-----------------------------------------------------------------------
+[groff 1.09]
 
 * Where can I get grap?
 
@@ -274,33 +201,7 @@ in the \n[rst] and \n[rsb] registers; these are groff extensions.
 
 ----------------------------------------------------------------------
 
-* While formatting a manual page, groff complains about not being able
-  to break lines.  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).
-
-----------------------------------------------------------------------
+[groff 1.08]
 
 * I'm having problems formatting man pages produced by the perl
   wrapman script.
@@ -383,6 +284,8 @@ following patch:
 
 ----------------------------------------------------------------------
 
+[groff 1.07]
+
 * groff uses up an enormous amount of memory processing large files.
   I'm using 386BSD 0.1.
 
@@ -418,6 +321,156 @@ and recompile groff:
         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:
+
+*** /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
@@ -425,6 +478,56 @@ 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 ...'.
 
@@ -484,29 +587,6 @@ Make sure that the paper format is "letter".  See groff_tmac(5).
 
 ----------------------------------------------------------------------
 
-* When I try to run gxditview, I get the error:
-  Error: Widget viewport has zero width and/or height
-
-This error means you haven't correctly installed the application
-defaults file, GXditview.ad; `make install' does this for you
-automatically, so either you didn't do `make install', or you haven't
-passed a good `--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.
-
-----------------------------------------------------------------------
-
-* When I preview documents using -TX75 or -TX100, the layout is not
-  the same as when I print the document with -Tps: the line and page
-  breaks come in different places.
-
-Use `groff -X -Tps'.
-
-----------------------------------------------------------------------
-
 * When I try to print the output of groff -Tps, I get no output at all
   from the printer, and the log file shows the error
   %%[ error: undefined; offendingcommand: BP ]%%
@@ -543,32 +623,11 @@ files produced by TeX.  Try getting a more up to date driver.
 
 ----------------------------------------------------------------------
 
-* How can I use groff with an old LaserJet printer that doesn't work
-  with groff -Tlj4?
-
-You have at least 3 options:
-
-- use groff -Tps with GNU Ghostscript;
-
-- use groff -Tdvi with a TeX .dvi to LaserJet driver;
-
-- use groff with the LaserJet driver in Chris Lewis' psroff package
-  (available for ftp from:
-  ftp.uunet.ca:/distrib/chris_lewis/psroff3.0pl17).
-
-----------------------------------------------------------------------
-
-* Groff seems to generate level 3 Postscript, but my printer is only a
-  level 1 or 2 PostScript printer.
+* 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.
 
-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.
+Use `groff -X -Tps'.
 
 
 
@@ -577,11 +636,7 @@ Platform-Dependent Macro Problems
 
 
 
-* I get lots of errors when I use groff with the AT&T -mm macros.
-
-Use the groff -mm macros.
-
-----------------------------------------------------------------------
+[groff 92feb549bb17ba935188f5a3f123ce30ced54311 2001-04-13]
 
 * groff produces wrapper macros for `ms' and friends which call the
   system's original macros.  Then, to get groff's ms macro package I
@@ -596,75 +651,7 @@ macros.
 
 ----------------------------------------------------------------------
 
-* I'm having problems formatting HP-UX 9.0 man pages with groff -man.
-
-Copy HP's tmac.an into /usr/local/share/groff/site-tmac/an.tmac, and
-either put `.cp 1' at the beginning or filter it (and any files it
-.so's) through tmac/fixmacros.sed.
-
-----------------------------------------------------------------------
-
-* I get errors using the Unix -ms macros with groff -e -C.
-
-Apply this change:
-
-*** /usr/lib/ms/ms.eqn	Tue Apr 25 02:14:28 1989
---- ms.eqn	Sun Nov 11 10:33:59 1990
-***************
-*** 22,29 ****
-  ..
-  .	\" EN - end of a displayed equation
-  .de EN
-! .if !\\*(10 .br
-  .di
-  .rm EZ
-  .nr ZN \\n(dn
-  .if \\n(ZN>0 .if \\n(YE=0 .LP
---- 22,30 ----
-  ..
-  .	\" EN - end of a displayed equation
-  .de EN
-! .if \\n(.k>0 .br
-  .di
-+ .ds 10 \\*(EZ\\
-  .rm EZ
-  .nr ZN \\n(dn
-  .if \\n(ZN>0 .if \\n(YE=0 .LP
-
-----------------------------------------------------------------------
-
-* I'm having problems formatting Ultrix man pages with groff -man.
-
-The Ultrix man pages use a number of non-standard extensions to the
-Unix man macros.  One solution is to use the Ultrix -man macros with
-groff.  Copy /usr/lib/tmac/tmac.an to
-/usr/local/share/groff/site-tmac/an.tmac and apply the following patch
-(from Frank Wortner):
-
-*** /usr/local/lib/groff/tmac/tmac.an     Wed Sep  9 12:29:28 1992
---- /usr/lib/tmac/tmac.an       Fri Jul 24 19:58:19 1992
-***************
-*** 489,495 ****
-  .     \" make special case of shift out of italic
-  .de }S
-  .ds ]F
-! .if \\$12 .if !\\$5 .ds ]F \^
-  .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
-  .el \\$3
-  .}f
---- 489,495 ----
-  .     \" make special case of shift out of italic
-  .de }S
-  .ds ]F
-! .if \\$12 .if !\\$5 .ds ]F\^
-  .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
-  .el \\$3
-  .}f
-
-Another possible solution is to install tmac/man.ultrix as
-/usr/local/share/groff/site-tmac/man.local.
-
-----------------------------------------------------------------------
+[groff 1.09]
 
 * On an SGI system, how can I make the man command use groff?
 
@@ -743,86 +730,95 @@ To get PostScript output from `man -t', you also need to create a
 ! # probably not wanted.
 ! exec groff -Wall $T $opts $rest
 
+----------------------------------------------------------------------
 
+[groff 1.08]
 
-Compilation Problems
-====================
+* I'm having problems formatting HP-UX 9.0 man pages with groff -man.
 
+Copy HP's tmac.an into /usr/local/share/groff/site-tmac/an.tmac, and
+either put `.cp 1' at the beginning or filter it (and any files it
+.so's) through tmac/fixmacros.sed.
 
+----------------------------------------------------------------------
 
-* I get warnings from afmtodit about names already being mapped.
+[groff 1.07]
 
-afmtodit: AGL name 'Delta' already mapped to groff name '*D'; ignoring AGL name 'uni0394'
+* I'm having problems formatting Ultrix man pages with groff -man.
 
-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'.
+The Ultrix man pages use a number of non-standard extensions to the
+Unix man macros.  One solution is to use the Ultrix -man macros with
+groff.  Copy /usr/lib/tmac/tmac.an to
+/usr/local/share/groff/site-tmac/an.tmac and apply the following patch
+(from Frank Wortner):
 
-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.
+*** /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.
 
 ----------------------------------------------------------------------
 
-* I get warnings about special characters in the groff_char(7) man page.
+[groff 1.01]
 
-troff:man/groff_char.7:1000: warning: can't find special character '.j'
-troff:man/groff_char.7:1407: warning: can't find special character 'vA'
-troff:man/groff_char.7:1531: warning: can't find special character 'bs'
-troff:man/groff_char.7:1697: warning: can't find special character '-+'
-troff:man/groff_char.7:1746: warning: can't find special character 'coproduct'
-troff:man/groff_char.7:1839: warning: can't find special character '+e'
+* I get lots of errors when I use groff with the AT&T -mm macros.
 
-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).
+Use the groff -mm macros.
 
-----------------------------------------------------------------------
 
-* 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)
+Compilation Problems
+====================
 
-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.
 
-----------------------------------------------------------------------
 
-* I get a lot of warnings about "sprintf" on macOS.
+[groff c70e3c4bfbb202f9f6a2ae1426637550ed8de023 2023-03-06]
 
-Apple has decided to treat the sprintf() standard C library function as
-deprecated even though the C standard itself has not.
+* The "initialization_is_quiet" test fails on my GNU/Hurd or NetBSD box.
 
-https://developer.apple.com/forums/thread/714675
+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 make(1) failure involving grep and the groff_man.7.man.in file
-  on Solaris 11.
+[groff 4fecf105c34ee7e3ed24f494bd4217b7237c5859 2023-02-25]
 
-Solaris make(1) has a bug easily exhibited by the following Makefile.
+* I get a build failure on Cygwin / a system using newlib and GCC 11.
 
-all:
-	! false
+  "newlib" defines a function called "utoa" which conflicts with a
+  static (file scope-local) function in src/libs/libxutil/XFontName.c.
 
-Use GNU make instead; it may be available in /opt/csw/bin/gmake.
+  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
 
 ----------------------------------------------------------------------
 
+[groff 434e2b0606ade1736437d8a9be43e8852895c71d 2023-02-22]
+
 * The "check-default-foundry" test fails when I run "make check".
 
 Your Ghostscript installation may have its fonts embedded in the
@@ -840,14 +836,31 @@ overcome this problem.
 
 ----------------------------------------------------------------------
 
-* The "initialization_is_quiet" test fails on my GNU/Hurd or NetBSD box.
+[groff 3b04beb92e63cb9d108256ca37cc92446966c89a 2023-02-19]
 
-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 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.
+
+----------------------------------------------------------------------
+
+[groff 19afc98d213c86504a5475786987c6f86c6817fa 2023-02-09]
+
 * Tests fail when I run "make check" on Solaris 10 or 11.
 
 The test suite expects a POSIX-conforming shell and utilities.  Solaris
@@ -922,21 +935,32 @@ Some test failures remain expected on Solaris 10.
 
 ----------------------------------------------------------------------
 
-* I get a build failure on Cygwin / a system using newlib and GCC 11.
+[groff 1f4817f375354f062d3b4fdfbc0c52e2676e267b 2022-07-15]
 
-  "newlib" defines a function called "utoa" which conflicts with a
-  static (file scope-local) function in src/libs/libxutil/XFontName.c.
+* I get warnings from afmtodit about names already being mapped.
 
-  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.
+afmtodit: AGL name 'Delta' already mapped to groff name '*D'; ignoring AGL name 'uni0394'
 
-  $ make distclean
-  $ ./configure --without-x
+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.
 
 ----------------------------------------------------------------------
 
+[groff 49b611f1135cbf7f18b656bb445a291d48dd5c86 2022-05-22]
+
 * I am building from the Git repository, using 'autoreconf' from a GNU
   Autoconf release earlier than 2.69, and I get this.
 
@@ -951,6 +975,152 @@ Ignore this.  It doesn't occur in more recent versions of 'autoreconf'.
 
 ----------------------------------------------------------------------
 
+[groff 0d371991136a081c57131cad87380cc4aef64169 2022-05-15]
+
+* I get warnings about special characters in the groff_char(7) man page.
+
+troff:man/groff_char.7:1000: warning: can't find special character '.j'
+troff:man/groff_char.7:1407: warning: can't find special character 'vA'
+troff:man/groff_char.7:1531: warning: can't find special character 'bs'
+troff:man/groff_char.7:1697: warning: can't find special character '-+'
+troff:man/groff_char.7:1746: warning: can't find special character 'coproduct'
+troff:man/groff_char.7:1839: warning: can't find special character '+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 8a4d69839faa14deb1a5a204e7c28fd85806511c 2015-12-26]
+
+* 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 dfdf0c0bb887010bd0047409c954e5d7a6d55d05 2014-09-04]
+
+* Configuration on MacOS X 10.6 doesn't succeed.
+
+Use
+
+  ./configure CXX=g++-4.2
+
+----------------------------------------------------------------------
+
+[groff 6b3c51ebb4e3dbcb294f9c23d9ec0624b5beb4ee 2010-01-23]
+
+* 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 26f1dfcd080e834617302c7a94423d02d17e15a7 2004-05-25]
+
+* 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 ee83e4fd48e50d10967b02e06f128a1452f183b7 2002-11-07]
+
+* 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 3371324496b9ba0efb65e0c66340ca7f99a8bb56 2002-02-07]
+
 * Compilation dies with
 
     y.tab.c: In function `int yyparse()':
@@ -965,11 +1135,7 @@ byacc.
 
 ----------------------------------------------------------------------
 
-* There are many empty `Makefile.dep' files.  Is this a bug?
-
-No.  Real dependency files are created with a `make depend' call.
-
-----------------------------------------------------------------------
+[groff e73d5afff5595b13052180c8cc5f402bff39131e 2000-12-06]
 
 * On HP-UX, the compiler complains about missing symbol `alloca'.
 
@@ -981,6 +1147,39 @@ before starting the configure script.
 
 ----------------------------------------------------------------------
 
+[groff 2e836ac7d3d9264efb9ae5a06bfe8c7149e22eac 2000-07-21]
+
+* 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.
+
+----------------------------------------------------------------------
+
+[groff 5af19087eef2de233075c39a1479e11c8fcbe3e9 2000-05-28]
+
+* There are many empty `Makefile.dep' files.  Is this a bug?
+
+No.  Real dependency files are created with a `make depend' call.
+
+----------------------------------------------------------------------
+
+[groff fbd6cbb8ac7a42fdf219ff087b5b1e98cdeb7c68 2000-04-30]
+
 * The configure script fails on OS/390 (z/OS) Unix.
 
 [This has been fixed in z/OS V1R3 (aka OS/390 R13).]
@@ -1019,46 +1218,17 @@ destructors do actually work properly):
 
 ----------------------------------------------------------------------
 
-* 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 *.
-
-----------------------------------------------------------------------
+[groff 1.15]
 
-* 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.
+* I get errors when I try to compile groff with Forte Development 6
+  or 6u1, or Sun C++ version 5.0 through 5.2.
 
-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.
+This is a known problem; see Sun bug #4301919.  See Sun patches
+109482, 109490, 109508, and 109509 for fixes.
 
 ----------------------------------------------------------------------
 
-* On Ultrix, the make program stops with the message
-
-    *** Error code 1
-
-    Stop.
-
-  for no apparent reason.
-
-Use GNU make.
-
-----------------------------------------------------------------------
+[groff 1.08]
 
 * I'm having problems compiling groff on 386BSD 0.1.
 
@@ -1098,6 +1268,30 @@ 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.
 
@@ -1117,115 +1311,7 @@ to be `void (*)(int)'.
 You can either change them in place, or copy them to some other
 directory and include that directory with a -I option.
 
-----------------------------------------------------------------------
-
-* I get errors when I try to compile groff with Forte Development 6
-  or 6u1, or Sun C++ version 5.0 through 5.2.
-
-This is a known problem; see Sun bug #4301919.  See Sun patches
-109482, 109490, 109508, and 109509 for fixes.
-
-----------------------------------------------------------------------
-
-* I get warnings from the Sun linker while using gcc 3.4.0:
-
-  ld: warning: relocation error: R_SPARC_UA32:
-      file groff/src/libs/libgroff/libgroff.a(getopt.o): symbol optarg:
-      external symbolic relocation against non-allocatable
-      section .debug_info; cannot be processed at runtime:
-      relocation ignored
-
-This seems to be a known problem (Sun bugs #4910101 and #4910810,
-filed in September 2003; gcc bug #15599, filed May 2004) without a
-public fix as of this writing.  A work-around is to use option
-`-gstabs+' instead of `-g' (and a high probability that the output is
-only debuggable with gdb but not with Sun's debuggers).
-
-----------------------------------------------------------------------
-
-* 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.
-
-----------------------------------------------------------------------
-
-* 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.
-
-----------------------------------------------------------------------
-
-* Configuration on MacOS X 10.6 doesn't succeed.
-
-Use
-
-  ./configure CXX=g++-4.2
-
-----------------------------------------------------------------------
-
-* 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.
 
 ##### Editor settings
 Local Variables: