Bug 236092

Summary:	lang/perl5.28: perldoc lacks formatting (bold/underline)
Product:	Ports & Packages	Reporter:	Andrew Daugherity <andrew.daugherity>
Component:	Individual Port(s)	Assignee:	Mathieu Arnold <mat>
Status:	Closed FIXED
Severity:	Affects Some People	Flags:	bugzilla: maintainer-feedback? (mat)
Priority:	---
Version:	Latest
Hardware:	Any
OS:	Any

Description Andrew Daugherity 2019-02-27 22:19:24 UTC

After upgrading to perl 5.28, the man pages displayed by perldoc (e.g. 'perldoc Digest') or via Perl scripts making use of pod2usage lack formatting such as bold and underlining.  In fact, text which used to be underlined is now wrapped in *asterisks* (bold text is just displayed as normal text.)

This is apparently due to an upstream change in Perl, and I found a Debian bug report about it: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=917530

They propose two possible workarounds:
    export PERLDOC=-oTerm PERLDOC_PAGER='less -R' # works like Stretch, Jessie
    export PERLDOC=-oMan                          # works like Wheezy

Here are my findings for various perldoc output settings:
-oMan does not work at all on FreeBSD, presumably because we use mandoc instead?

-oTerm displays a properly-formatted page if PERLDOC_PAGER (or equivalent PAGER or LESS env vars) is set; without that, you see escape codes (similar to bug #162463).  On a system still on Perl 5.26, -oTerm works properly without any additional setting (I think it's always invoking 'less -R', and the upstream change for 5.28 no longer does that?).

-otext (on all versions) produces the output now seen by default in 5.28, e.g. "*underlined text*".

-omandoc produces the same output as -otext on 5.28, but on 5.26 it produces formatted output like -oterm.  Is mandoc the default output on FreeBSD?

Comment 1 Mathieu Arnold freebsd_committer

2019-03-12 16:09:59 UTC

There is no Pod::Perldoc::ToMandoc, so it -omandoc is ignored and goes to default.

Comment 2 Mathieu Arnold freebsd_committer

2019-03-12 16:17:46 UTC

Ok, so, running "perldoc -onroff perlvar|mandoc -man" gets what should be the default, let's see how I can make that work.

Comment 3 Andrew Daugherity 2019-03-12 16:54:20 UTC

Yeah, I later discovered how to trace with env PERLDOCDEBUG=1 and found that there was no actual "mandoc" formatter; rather, with nonexistent perldoc -oFoo formatters, it falls back to Term on 5.26 but Text on 5.28.  Additionally the pager previously defaulted to 'less -R' behavior but no longer does.

"perldoc -onroff ... | mandoc -man" gives me plaintext output (similar to -otext, but without *underlining* indicated), but changing that to '... | mandoc -man -a' displays correctly formatted.  However -a seems to force formatting, even when not in a tty (e.g. redirected to a file).

Thanks for looking into this...

Comment 4 Mathieu Arnold freebsd_committer

2019-03-12 16:57:38 UTC

I pushed an update to lang/perl5-devel with a tentative patch, let me know if it works for you.

Comment 5 commit-hook freebsd_committer

2019-03-12 16:57:58 UTC

A commit references this bug:

Author: mat
Date: Tue Mar 12 16:56:55 UTC 2019
New revision: 495471
URL: https://svnweb.freebsd.org/changeset/ports/495471

Log:
  Put back a default non dumb pod formatter, and fix a probable bug in
  the mandoc formatter.

  PR:		236092 [1]
  Reported by:	Andrew Daugherity

Changes:
  head/lang/perl5-devel/Makefile
  head/lang/perl5-devel/files/patch-cpan_Pod-Perldoc_lib_Pod_Perldoc.pm
  head/lang/perl5-devel/files/patch-cpan_Pod-Perldoc_lib_Pod_Perldoc_ToMan.pm

Comment 6 Andrew Daugherity 2019-03-12 18:24:58 UTC

Works great, thanks!

Comment 7 commit-hook freebsd_committer

2019-03-14 21:13:30 UTC

A commit references this bug:

Author: mat
Date: Thu Mar 14 21:13:02 UTC 2019
New revision: 495738
URL: https://svnweb.freebsd.org/changeset/ports/495738

Log:
  Put back a default non dumb pod formatter [1], and fix a probable bug in
  the mandoc formatter.

  PR:		236092 [1]
  Reported by:	Andrew Daugherity

Changes:
  head/lang/perl5.28/Makefile
  head/lang/perl5.28/files/patch-cpan_Pod-Perldoc_lib_Pod_Perldoc.pm
  head/lang/perl5.28/files/patch-cpan_Pod-Perldoc_lib_Pod_Perldoc_ToMan.pm