groff 'an.tmac' missing and/or broken in 2015Q4

[jblachly]

Background: Amazon aws cli client uses groff to parse its help text output. It uses the command line groff -man -T ascii < filewithhelptext | less -R (or whatever pager). I have attached a test groff file from the Amazon awscli package that should be parsed and displayed as above. The expect behavior is a typical manpage style document. On smartos, you get a mostly-empty page.

man_contents.txt

groff being an ancient utility uses the old style -man as equivalent of -m man but it accomplishes it using trickery; there is a macro package an.tmac that should be installed in smartos' pkgin installed version, but it is missing in the expected directory, and another directory contains wha tI think is an incorrect version: there is a file elsewhere installed called an.tmac in /opt/local/lib/groff/site-tmac but it is not the right one that should exist in /opt/local/share/groff/1.22.3/tmac.

I tested this on NetBSD-6.1.5 using pkgin with pkgsrc 2015Q4 and the behavior was correct, and an.tmac was correctly installed in /usr/pkg/share/groff/1.22.3/tmac

Comparing the NetBSD version and the smartos version, they are almost identical, both beginning (ignoring comment lines)

.do mso andoc.tmac

whereas the smartos version then enters compatibility mode and invokes another script:

.cp 1
.so /usr/share/lib/tmac/an

and that second script may be what's breaking the display.

[jperkin]

Thanks, will take a look. It's worth noting that if you do use -m man instead of -man then you get the expected output.

[jperkin]

So, yes, this appears to be mostly due to the compatibility mode. If you comment out .cp 1 then you get a mostly readable page, just with a few output issues. If you also comment out the loading of the system an macros then you get the same output as on NetBSD, OSX, etc.

Note that this issue isn't specific to pkgsrc. The native groff on OmniOS is also built in exactly the same way and exhibits the same problems. And again, nullifying /usr/lib/groff/site-tmac/an.tmac on OmniOS ensures the AWS page is displayed correctly.

Now, I can easily change the pkgsrc package to not install these system macro wrappers which would solve the immediate problem, but I'd first like confirmation that there isn't an issue that should be fixed in the illumos macro packages, as it'd be nice for this to work with the native groff on OmniOS etc too. I'd also like to know what side-effects there may be by not including the native macros (now that we have mandoc in illumos we no longer use groff for displaying manual pages on SmartOS, but there may be other use-cases I'm not aware of).

My knowledge of this stuff is mostly non-existant, so cc'ing @jclulow @richlowe @rmustacc @danmcd for their input.

Current summary:

• groff -man -T ascii < man_contents.txt | less -R is broken.
• groff -m man -T ascii < man_contents.txt | less -R works fine.
• groff -man ... with .cp 1 removed from groff's an.tmac mostly works.
• groff -man ... with .so /usr/share/lib/tmac/an also removed from groff's an.tmac works fine.

Thanks.

[danmcd]

I'm not very knowledgeable about this either, but I can say the the OmniOS groff has only one tiny patch over stock (argument casting change), and is up to the latest (1.22.3) as is pkgsrc. Whatever folks decide to do, I'll gladly fix the OmniOS groff if needed, however.

[jblachly]

FWIW, the Amazon people patched aws-cli to work around this issue (by issuing -m man instead of -man), but still the groff from pkgsrc specifically on this platform is broken; on NetBSD groff from pkgsrc works correctly.

[mamash]

Github autoclose, re-opening.

[rmustacc]

github autoclose, re-opening