Bug#917530: perldoc formatting unfortunately degraded by upstream compatability fix

[Niko Tyni]

On Fri, Dec 28, 2018 at 04:32:47AM -0500, Anthony DeRobertis wrote:
> Package: perl-doc
> Version: 5.28.1-3
> Severity: normal

> In f2ee4cb897ec9dd3338abcd0e9a42cb41ce9a173[0] upstream worked around
> reported issues with perldoc by changing the default formatter to ToText
> (from ToTerm) and also getting rid of automatically setting pager
> options (like -R to less). 
> 
> This, of course, also removed all bold/underline/etc. from the output,
> making perldoc less readable.
> 
> - From reading through the various related bugs (e.g., [1]) it seems like
> they switched away from using groff (via ToMan) because Mac OS Sierra
> has a groff without Unicode support. That obviously doesn't apply to
> Debian, so it seems we could have nice rendering without any pager
> workarounds just by changing the default back to Pod::Perldoc::ToMan.

Hi, thanks for the report.

While I wasn't thrilled about the ToText upstream change myself, diverging
from upstream here is not very attractive at least as long as the default
is not configurable at build time but needs patching. The buster freeze
is also uncomfortably near.

The ToMan backend has #752185 reported so we'd be reintroducing that
for the default behaviour. Not sure how much we care about non-UTF8
locales nowadays however.

There also seems to be trouble with UTF-8 characters in the ToMan backend,
cf. 'perldoc -oMan perltw'. I suppose the backend would need to be patched
to use the Pod::Man 'utf8' option. (#401089 is related; we're currently
patching the src:perl build to do that when generating the man pages.)

> Or at least a note in README.Debian about adding something like one of
> these to .bashrc:
> 
>     export PERLDOC=-oTerm PERLDOC_PAGER='less -R' # works like Stretch, Jessie
>     export PERLDOC=-oMan                          # works like Wheezy

I'm fine with adding something like this fwiw (though I'd rather leave out
the .bashrc part and just say something about setting those environment
variables.)
-- 
Niko Tyni   ntyni at debian.org