perldoc output misbehaviour

[p5pRT]

Migrated from rt.perl.org#131762 (status was 'open')

Searchable as RT131762$

[p5pRT]

From zefram@fysh.org

Created by zefram@fysh.org

As has been discussed in some previous tickets, recent versions of
Pod​::Perldoc (and hence the perldoc(1) command) have bad behaviour
regarding the form of their output, particularly in a default invocation.
It is a problem that the perl core distro bundles a module with this
bad behaviour, and especially with it arising in a tool that forms such
an important part of the user experience. I'm opening this ticket to
track the specific issue of the core distro exhibiting misbehaviour in
this area. I think this should be a 5.28.0 blocker.

There have been several slightly different versions of the bad behaviour;
I'm not tying this ticket to any specific form of misbehaviour.
Problems have arisen in two main areas. Firstly, using by default a
formatter that doesn't produce properly plain (pageable) text output.
(The problem originally arose in switching the default from the ToMan
formatter to the ToTerm formatter, in Pod​::Perldoc 3.20.) Secondly,
since Pod​::Perldoc 3.25, dishonouring the user's pager configuration in
an attempt to address the first problem.

Various tickets (current and historical) regarding various versions of the
problem​: [rt.cpan.org #120229] [rt.cpan.org #98636] [rt.cpan.org #88204]
[perl #130759]
https://rt.cpan.org/Public/Bug/Display.html?id=120229
https://rt.cpan.org/Public/Bug/Display.html?id=98636
https://rt.cpan.org/Public/Bug/Display.html?id=88204
https://rt.perl.org/Public/Bug/Display.html?id=130759

Perl Info

Flags:
    category=library
    severity=medium
    module=Pod::Perldoc

Site configuration information for perl 5.27.1:

Configured by zefram at Wed Jun 21 07:42:17 BST 2017.

Summary of my perl5 (revision 5 version 27 subversion 1) configuration:
   
  Platform:
    osname=linux
    osvers=3.16.0-4-amd64
    archname=x86_64-linux-thread-multi
    uname='linux barba.rous.org 3.16.0-4-amd64 #1 smp debian 3.16.43-2 (2017-04-30) x86_64 gnulinux '
    config_args='-des -Dprefix=/home/zefram/usr/perl/perl_install/perl-5.27.1-i64-f52 -Duselargefiles -Dusethreads -Uafs -Ud_csh -Uusesfio -Uusenm -Duseshrplib -Dusedevel -Uversiononly -Ui_db'
    hint=recommended
    useposix=true
    d_sigaction=define
    useithreads=define
    usemultiplicity=define
    use64bitint=define
    use64bitall=define
    uselongdouble=undef
    usemymalloc=n
    default_inc_excludes_dot=define
    bincompat5005=undef
  Compiler:
    cc='cc'
    ccflags ='-D_REENTRANT -D_GNU_SOURCE -fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -D_FORTIFY_SOURCE=2'
    optimize='-O2'
    cppflags='-D_REENTRANT -D_GNU_SOURCE -fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include'
    ccversion=''
    gccversion='4.9.2'
    gccosandvers=''
    intsize=4
    longsize=8
    ptrsize=8
    doublesize=8
    byteorder=12345678
    doublekind=3
    d_longlong=define
    longlongsize=8
    d_longdbl=define
    longdblsize=16
    longdblkind=3
    ivtype='long'
    ivsize=8
    nvtype='double'
    nvsize=8
    Off_t='off_t'
    lseeksize=8
    alignbytes=8
    prototype=define
  Linker and Libraries:
    ld='cc'
    ldflags =' -fstack-protector-strong -L/usr/local/lib'
    libpth=/usr/local/lib /usr/lib/gcc/x86_64-linux-gnu/4.9/include-fixed /usr/include/x86_64-linux-gnu /usr/lib /lib/x86_64-linux-gnu /lib/../lib /usr/lib/x86_64-linux-gnu /usr/lib/../lib /lib
    libs=-lpthread -lnsl -ldb -ldl -lm -lcrypt -lutil -lc
    perllibs=-lpthread -lnsl -ldl -lm -lcrypt -lutil -lc
    libc=libc-2.19.so
    so=so
    useshrplib=true
    libperl=libperl.so
    gnulibc_version='2.19'
  Dynamic Linking:
    dlsrc=dl_dlopen.xs
    dlext=so
    d_dlsymun=undef
    ccdlflags='-Wl,-E -Wl,-rpath,/home/zefram/usr/perl/perl_install/perl-5.27.1-i64-f52/lib/5.27.1/x86_64-linux-thread-multi/CORE'
    cccdlflags='-fPIC'
    lddlflags='-shared -O2 -L/usr/local/lib -fstack-protector-strong'



@INC for perl 5.27.1:
    /home/zefram/usr/perl/perl_install/perl-5.27.1-i64-f52/lib/site_perl/5.27.1/x86_64-linux-thread-multi
    /home/zefram/usr/perl/perl_install/perl-5.27.1-i64-f52/lib/site_perl/5.27.1
    /home/zefram/usr/perl/perl_install/perl-5.27.1-i64-f52/lib/5.27.1/x86_64-linux-thread-multi
    /home/zefram/usr/perl/perl_install/perl-5.27.1-i64-f52/lib/5.27.1


Environment for perl 5.27.1:
    HOME=/home/zefram
    LANG (unset)
    LANGUAGE (unset)
    LD_LIBRARY_PATH (unset)
    LOGDIR (unset)
    PATH=/home/zefram/usr/perl/perl_install/perl-5.27.1-i64-f52/bin:/home/zefram/usr/perl/util:/home/zefram/pub/x86_64-unknown-linux-gnu/bin:/home/zefram/pub/common/bin:/usr/bin:/bin:/usr/local/bin:/usr/games
    PERL_BADLANG (unset)
    SHELL=/usr/bin/zsh

[p5pRT]

From zefram@fysh.org

I wrote​:

Pod​::Perldoc (and hence the perldoc(1) command) have bad behaviour
regarding the form of their output
...
I think this should be a 5.28.0 blocker.

Bump. We're halfway to contentious code freeze and this hasn't been
addressed. The current Pod​::Perldoc 3.28 still generates unpageable
output by default, and still makes unportable changes to pager
configuration. If this doesn't get fixed upstream soonish, we should
customise Pod​::Perldoc in blead in the obvious manner (default to ToText
renderer on all platforms, never call $formatter->pager_configuration).

-zefram

[p5pRT]

From zefram@fysh.org

I wrote​:

           If this doesn't get fixed upstream soonish\, we should

customise Pod​::Perldoc in blead in the obvious manner (default to ToText
renderer on all platforms, never call $formatter->pager_configuration).

I have implemented this customisation on branch
zefram/perldoc_portability. If there's no upstream movement and no
objections, I intend to merge this to blead in time for 5.27.5.

-zefram

[p5pRT]

From @xsawyerx

On 10/07/2017 06​:46 AM, Zefram wrote​:

I wrote​:

           If this doesn't get fixed upstream soonish\, we should

customise Pod​::Perldoc in blead in the obvious manner (default to ToText
renderer on all platforms, never call $formatter->pager_configuration).
I have implemented this customisation on branch
zefram/perldoc_portability. If there's no upstream movement and no
objections, I intend to merge this to blead in time for 5.27.5.

I will contact Mark Allen to discuss fixing Pod​::Perldoc entirely. This
can go in 5.27.5 and, at most, reverted afterwards if we could upgrade a
version of Pod​::Perldoc that fixes it.

Does that make sense?

[p5pRT]

The RT System itself - Status changed from 'new' to 'open'

[p5pRT]

From zefram@fysh.org

I wrote​:

I have implemented this customisation on branch
zefram/perldoc_portability. If there's no upstream movement and no
objections, I intend to merge this to blead in time for 5.27.5.

Now applied to blead as f2ee4cb.

-zefram

[jkeenan]

Zefram originally filed this ticket in 2017, but applied a patch that same year.

What remains to be done before we can close this ticket?

Thank you very much.
Jim Keenan

[khwilliamson]

No response in over 2 years, and a patch was applied; closing

[xsawyerx]

There's a long-running issue with the behavior of perldoc and its output. The most relevant ticket is probably briandfoy/pod-perldoc#36. Zefram provided specific feedback on finer points in restoring the handling of perldoc but I didn't get around to addressing them.