...when rendering some man pages, such as those of ncurses.
I did not manage (nor seriously attempt) to identify the root cause of
this bug. ncurses's use of `SH` and `SS` man(7) macros is
unremarkable.[1] I cannot account for why the less(1) man page renders
fine and ncurses pages like insstr(3) do not. But render badly they do,
emitting *roff logic as formatted output.
```
$ 9 nroff -man $(man -w insstr) | grep -F .ss | cat -v
"'''if^GNAME^GSYNOPSIS^G .ss 18 NAME
"'''if^GSYNOPSIS^GSYNOPSIS^G .ss 18 SYNOPSIS
"'''if^GDESCRIPTION^GSYNOPSIS^G .ss 18 DESCRIPTION
"'''if^GRETURN^GSYNOPSIS^G .ss 18 RETURN VALUE
"'''if^GNOTES^GSYNOPSIS^G .ss 18 NOTES
"'''if^GEXTENSIONS^GSYNOPSIS^G .ss 18 EXTENSIONS
"'''if^GPORTABILITY^GSYNOPSIS^G .ss 18 PORTABILITY
"'''if^GHISTORY^GSYNOPSIS^G .ss 18 HISTORY
"'''if^GSEE^GSYNOPSIS^G .ss 18 SEE ALSO
```
With this patch:
```
$ 9 nroff -man $(man -w insstr) | grep -F .ss | cat -v | grep . || echo NO OUTPUT
NO OUTPUT
```
I do observe that the problem seems to correspond to the only use in the
package of the old-fashioned `'''` commenting convention _within a macro
definition_. I have a notion of how GNU troff works, but little about
AT&T troff. That said, if I were to try to get to the bottom of this
problem, I'd look into if and how the no-break command character is
handled differently in copy mode. I see nothing in CSTR #54 to suggest
that the command characters have different meanings in copy mode and its
complement.[2]
My solution is to use idiomatic comment syntax inside macro definitions.
[1] d5dc8a4a7c/man/curs_insstr.3x (L47)
[2] unnamed in AT&T documentation but which I term "interpretation mode"
in groff
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
This tells bin/man to set the register L to very high to avoid pagination
and updates tmac/tmac.an to use that value, if it's set, to set the page
length. This is per Plan 9's rc/bin/man and sys/lib/tmac/tmac.an.
The overloading of IR emits magic \X'...' sequences that turn into HTML manual links.
But not all such IR invocations should be manual links;
those had to be written to avoid the IR macro before.
Worse, the \X'...' ending the IR causes troff to emit only a single space after a period.
Defining a new IM macro for manual references fixes both problems.
Fixes#441.
