Bug #88204 for Pod-Perldoc: default output is broken

Wed Aug 28 07:29:36 2013 zefram [...] fysh.org - Ticket created

Subject:	default output is broken
Date:	Wed, 28 Aug 2013 12:29:19 +0100
To:	bug-Pod-Perldoc [...] rt.cpan.org
From:	Zefram <zefram [...] fysh.org>

With Pod::Perldoc 3.20, the pod rendering is using ANSI escape sequences to achieve bolding. My pager, less(1), duly shows me "ESC[1m" all over the place. The "ESC"s are bolded; the text that the pod renderer wanted bolded is not. This is a relatively bad experience compared to Pod::Perldoc 3.19, which uses the older overstrike convention, which less(1) by default renders as bolding. Hypothetically, Pod::Perldoc could produce better output by recognising that my pager is less(1) and giving it the -R option. But I think that route would be a mistake. The -R option does not cause less(1) to render ANSI escapes: it causes less(1) to *pass them through* to the terminal. So it's only correct for some terminals. (Admittedly a high proportion of terminals in practice, but it's a huge new unchecked assumption.) I think it would be more sensible to retain the 3.19 behaviour of using overstriking for bolding. Not only because this is actually rendered by less(1). It also has the advantage that if it is passed directly to a terminal then it produces sane output regardless of the terminal type. -zefram

Sun Jan 05 21:42:00 2014 mrallen1 [...] yahoo.com - Correspondence added

On Wed Aug 28 07:29:36 2013, zefram@fysh.org wrote: Show quoted text

> With Pod::Perldoc 3.20, the pod rendering is using ANSI escape sequences > to achieve bolding. My pager, less(1), duly shows me "ESC[1m" all > over the place. The "ESC"s are bolded; the text that the pod renderer > wanted bolded is not. This is a relatively bad experience compared to > Pod::Perldoc 3.19, which uses the older overstrike convention, which > less(1) by default renders as bolding. > > Hypothetically, Pod::Perldoc could produce better output by recognising > that my pager is less(1) and giving it the -R option. But I think that > route would be a mistake. The -R option does not cause less(1) to render > ANSI escapes: it causes less(1) to *pass them through* to the terminal. > So it's only correct for some terminals. (Admittedly a high proportion > of terminals in practice, but it's a huge new unchecked assumption.) > > I think it would be more sensible to retain the 3.19 behaviour of using > overstriking for bolding. Not only because this is actually rendered > by less(1). It also has the advantage that if it is passed directly to > a terminal then it produces sane output regardless of the terminal type. > > -zefram

Thanks for the report. Yes, the default renderer changed to ANSI in 3.20 for the best possible UTF8 support. I will investigate making ANSI work better with less using overstrike as you suggest. I also note that the previous renderer is still available if you prefer to use the pod -> man -> {ntg}roff -> your pager pipeline. One way to make this change "permanent" for your environment is to set the PERLDOC environment variable to something like "-oman" in your shell RC file(s). Thanks.

Sun Jan 05 21:42:00 2014 The RT System itself - Status changed from 'new' to 'open'

Mon Feb 13 09:19:33 2017 jkeenan [...] cpan.org - Reference to perl ticket #130759 added

Mon Feb 13 09:20:42 2017 jkeenan [...] cpan.org - Correspondence added

On Sun Jan 05 21:42:00 2014, mallen wrote: Show quoted text

> On Wed Aug 28 07:29:36 2013, zefram@fysh.org wrote:

> > With Pod::Perldoc 3.20, the pod rendering is using ANSI escape > > sequences > > to achieve bolding. My pager, less(1), duly shows me "ESC[1m" all > > over the place. The "ESC"s are bolded; the text that the pod > > renderer > > wanted bolded is not. This is a relatively bad experience compared > > to > > Pod::Perldoc 3.19, which uses the older overstrike convention, which > > less(1) by default renders as bolding. > > > > Hypothetically, Pod::Perldoc could produce better output by > > recognising > > that my pager is less(1) and giving it the -R option. But I think > > that > > route would be a mistake. The -R option does not cause less(1) to > > render > > ANSI escapes: it causes less(1) to *pass them through* to the > > terminal. > > So it's only correct for some terminals. (Admittedly a high > > proportion > > of terminals in practice, but it's a huge new unchecked assumption.) > > > > I think it would be more sensible to retain the 3.19 behaviour of > > using > > overstriking for bolding. Not only because this is actually rendered > > by less(1). It also has the advantage that if it is passed directly > > to > > a terminal then it produces sane output regardless of the terminal > > type. > > > > -zefram

> > Thanks for the report. Yes, the default renderer changed to ANSI in > 3.20 > for the best possible UTF8 support. > > I will investigate making ANSI work better with less using overstrike > as you > suggest. > > I also note that the previous renderer is still available if you > prefer to use the > pod -> man -> {ntg}roff -> your pager pipeline. > > One way to make this change "permanent" for your environment is to > set the PERLDOC environment variable to something like "-oman" in > your shell RC file(s). > > Thanks.

Please see https://rt.perl.org/Ticket/Display.html?id=130759 for a related bug report.

Tue Aug 22 16:13:51 2017 ether [...] cpan.org - Correspondence added

On 2013-08-28 04:29:36, zefram@fysh.org wrote: Show quoted text

> With Pod::Perldoc 3.20, the pod rendering is using ANSI escape sequences > to achieve bolding. My pager, less(1), duly shows me "ESC[1m" all > over the place. The "ESC"s are bolded; the text that the pod renderer > wanted bolded is not. This is a relatively bad experience compared to > Pod::Perldoc 3.19, which uses the older overstrike convention, which > less(1) by default renders as bolding.

I have a similar problem, that I've bisected to the 3.19->3.20 upgrade. I now see 'perldoc' pages like this (with no bolding): 1NAME1 perlunitut - Perl Unicode Tutorial my LESS environment variable is: "-icMR" which worked fine with version 3.19. Please let me know what other diagnostic information I can provide.

Tue Aug 22 16:21:31 2017 ether [...] cpan.org - Correspondence added

On 2017-08-22 13:13:51, ETHER wrote: Show quoted text

> On 2013-08-28 04:29:36, zefram@fysh.org wrote:

> > With Pod::Perldoc 3.20, the pod rendering is using ANSI escape > > sequences > > to achieve bolding. My pager, less(1), duly shows me "ESC[1m" all > > over the place. The "ESC"s are bolded; the text that the pod > > renderer > > wanted bolded is not. This is a relatively bad experience compared > > to > > Pod::Perldoc 3.19, which uses the older overstrike convention, which > > less(1) by default renders as bolding.

> > I have a similar problem, that I've bisected to the 3.19->3.20 > upgrade. I now see 'perldoc' pages like this (with no bolding): > > 1NAME1 > perlunitut - Perl Unicode Tutorial > > my LESS environment variable is: "-icMR" which worked fine with > version 3.19. > > Please let me know what other diagnostic information I can provide.

I bisected this issue to: https://github.com/mrallen1/Pod-Perldoc/commit/6d635d58a3

Tue Aug 22 17:52:08 2017 ether [...] cpan.org - Correspondence added

On 2017-08-22 13:13:51, ETHER wrote: Show quoted text

> I have a similar problem, that I've bisected to the 3.19->3.20 > upgrade. I now see 'perldoc' pages like this (with no bolding): > > 1NAME1 > perlunitut - Perl Unicode Tutorial

mauke helped me figure out that my termcap settings are broken -- so the 3.20 change was relevant because instead of sending output through nroff, it now sends to the terminal directly, ergo it now gets mangled. I'm not sure if I agree that changing the default behaviour here was a good idea though.

Wed Apr 04 14:12:04 2018 ether [...] cpan.org - Correspondence added

For anyone coming here looking for a workaround: set PERLDOC=-oman in your shell!