From maj-git@mail.fortinbras.us

Created by maj-git@fortinbras.us

This is a bug report for perl from maj-git@​fortinbras.us,
generated with the help of perlbug 1.40 running under perl 5.24.4.

-----------------------------------------------------------------
The rendering of perlapi on metacpan

https://metacpan.org/pod/distribution/perl/autodoc.pl

appears to be highly confused. There is a lot of plain code appearing
prior to the NAME section. No section appears describing the api calls
themselves.

thanks

Flags:
     category=docs
     severity=medium

Site configuration information for perl 5.24.4:

Configured by maj at Mon Apr 23 18:30:22 PDT 2018.

Summary of my perl5 (revision 5 version 24 subversion 4) configuration:

   Platform:
     osname=darwin, osvers=16.7.0, archname=darwin-2level
     uname='darwin dobby 16.7.0 darwin kernel version 16.7.0: tue jan 30 
11:27:06 pst 2018; root:xnu-3789.73.11~1release_x86_64 x86_64 '
     config_args='-de 
-Dprefix=/Users/maj/perl5/perlbrew/perls/perl-5.24.4 
-Aeval:scriptdir=/Users/maj/perl5/perlbrew/perls/perl-5.24.4/bin'
     hint=recommended, useposix=true, d_sigaction=define
     useithreads=undef, usemultiplicity=undef
     use64bitint=define, use64bitall=define, uselongdouble=undef
     usemymalloc=n, bincompat5005=undef
   Compiler:
     cc='cc', ccflags ='-fno-common -DPERL_DARWIN 
-mmacosx-version-min=10.12 -fno-strict-aliasing -pipe 
-fstack-protector-strong -I/usr/local/include -DPERL_USE_SAFE_PUTENV',
     optimize='-O3',
     cppflags='-fno-common -DPERL_DARWIN -mmacosx-version-min=10.12 
-fno-strict-aliasing -pipe -fstack-protector-strong 
-I/usr/local/include'
     ccversion='', gccversion='4.2.1 Compatible Apple LLVM 9.0.0 
(clang-900.0.39.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 =' -mmacosx-version-min=10.12 
-fstack-protector-strong -L/usr/local/lib'
     libpth=/usr/local/lib 
/Library/Developer/CommandLineTools/usr/lib/clang/9.0.0/lib 
/Library/Developer/CommandLineTools/usr/lib /usr/lib
     libs=-lpthread -ldbm -ldl -lm -lutil -lc
     perllibs=-lpthread -ldl -lm -lutil -lc
     libc=, so=dylib, useshrplib=false, libperl=libperl.a
     gnulibc_version=''
   Dynamic Linking:
     dlsrc=dl_dlopen.xs, dlext=bundle, d_dlsymun=undef, ccdlflags=' '
     cccdlflags=' ', lddlflags=' -mmacosx-version-min=10.12 -bundle 
-undefined dynamic_lookup -L/usr/local/lib -fstack-protector-strong'

Locally applied patches:
     Devel::PatchPerl 1.48


@INC for perl 5.24.4:
     
/Users/maj/perl5/perlbrew/perls/perl-5.24.4/lib/site_perl/5.24.4/darwin-2level
     /Users/maj/perl5/perlbrew/perls/perl-5.24.4/lib/site_perl/5.24.4
     /Users/maj/perl5/perlbrew/perls/perl-5.24.4/lib/5.24.4/darwin-2level
     /Users/maj/perl5/perlbrew/perls/perl-5.24.4/lib/5.24.4


Environment for perl 5.24.4:
     DYLD_LIBRARY_PATH (unset)
     HOME=/Users/maj
     LANG=en_US.UTF-8
     LANGUAGE (unset)
     LD_LIBRARY_PATH (unset)
     LOGDIR (unset)
     
PATH=/Users/maj/perl5/perlbrew/bin:/Users/maj/perl5/perlbrew/perls/perl-5.24.4/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/MacGPG2/bin:/opt/X11/bin
     PERLBREW_HOME=/Users/maj/.perlbrew
     PERLBREW_MANPATH=/Users/maj/perl5/perlbrew/perls/perl-5.24.4/man
     
PERLBREW_PATH=/Users/maj/perl5/perlbrew/bin:/Users/maj/perl5/perlbrew/perls/perl-5.24.4/bin
     PERLBREW_PERL=perl-5.24.4
     PERLBREW_ROOT=/Users/maj/perl5/perlbrew
     PERLBREW_SHELLRC_VERSION=0.82
     PERLBREW_VERSION=0.82
     PERL_BADLANG (unset)
     SHELL=/bin/bash

From @jkeenan

On Sun, 04 Nov 2018 20​:33​:07 GMT, maj-git@​mail.fortinbras.us wrote​:

This is a bug report for perl from maj-git@​fortinbras.us,
generated with the help of perlbug 1.40 running under perl 5.24.4.

-----------------------------------------------------------------
The rendering of perlapi on metacpan

https://metacpan.org/pod/distribution/perl/autodoc.pl

appears to be highly confused. There is a lot of plain code appearing
prior to the NAME section. No section appears describing the api calls
themselves.

thanks

Confirmed. This is a program internal to the Perl 5 core distribution which, strictly speaking, has no public documentation. Because autodoc.pl generates files in .pod format, it has a long stretch of text in a heredoc which is in POD-like format. That's probably confusing what metacpan.org does.

Perl 5 Porters doesn't have any direct control over metacpan.org, so we'll have to discuss a solution with that site's maintainers. I have opened this ticket​:

metacpan/metacpan-web#2118

Thank you very much.
Jim Keenan

--
James E Keenan (jkeenan@​cpan.org)

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

From @xsawyerx

On 11/5/18 12​:51 AM, James E Keenan via RT wrote​:

On Sun, 04 Nov 2018 20​:33​:07 GMT, maj-git@​mail.fortinbras.us wrote​:

This is a bug report for perl from maj-git@​fortinbras.us,
generated with the help of perlbug 1.40 running under perl 5.24.4.

-----------------------------------------------------------------
The rendering of perlapi on metacpan

https://metacpan.org/pod/distribution/perl/autodoc.pl

appears to be highly confused. There is a lot of plain code appearing
prior to the NAME section. No section appears describing the api calls
themselves.

thanks

Confirmed. This is a program internal to the Perl 5 core distribution which, strictly speaking, has no public documentation. Because autodoc.pl generates files in .pod format, it has a long stretch of text in a heredoc which is in POD-like format. That's probably confusing what metacpan.org does.

Perl 5 Porters doesn't have any direct control over metacpan.org, so we'll have to discuss a solution with that site's maintainers. I have opened this ticket​:

metacpan/metacpan-web#2118

I have replied to that ticket with some questions.

I think we should resolve this on the Perl side. One suggestion is to
render the perlapi POD files during the release cycle and not
compilation, which I think makes sense. We could ship static POD files
for the API.

From @iabyn

On Sat, Nov 10, 2018 at 11​:30​:49AM +0200, Sawyer X wrote​:

The rendering of perlapi on metacpan

https://metacpan.org/pod/distribution/perl/autodoc.pl

appears to be highly confused. There is a lot of plain code appearing
prior to the NAME section. No section appears describing the api calls
themselves.

thanks

Confirmed. This is a program internal to the Perl 5 core distribution which, strictly speaking, has no public documentation. Because autodoc.pl generates files in .pod format, it has a long stretch of text in a heredoc which is in POD-like format. That's probably confusing what metacpan.org does.

Perl 5 Porters doesn't have any direct control over metacpan.org, so we'll have to discuss a solution with that site's maintainers. I have opened this ticket​:

metacpan/metacpan-web#2118

I have replied to that ticket with some questions.

I think we should resolve this on the Perl side. One suggestion is to
render the perlapi POD files during the release cycle and not
compilation, which I think makes sense. We could ship static POD files
for the API.

I have just pushed v5.29.4-88-g6a4c4cd41c, which escapes any pod in
autodoc.pl.

I'm not keen on messing with when perlapi.pod is generated, nor
how/whether perldelta.pod is a link.

--
"I do not resent criticism, even when, for the sake of emphasis,
it parts for the time with reality".
  -- Winston Churchill, House of Commons, 22nd Jan 1941.

From @tonycoz

On Mon, 19 Nov 2018 04​:44​:50 -0800, davem wrote​:

On Sat, Nov 10, 2018 at 11​:30​:49AM +0200, Sawyer X wrote​:

I think we should resolve this on the Perl side. One suggestion is to
render the perlapi POD files during the release cycle and not
compilation, which I think makes sense. We could ship static POD
files
for the API.

I have just pushed v5.29.4-88-g6a4c4cd41c, which escapes any pod in
autodoc.pl.

I'm not keen on messing with when perlapi.pod is generated, nor
how/whether perldelta.pod is a link.

I agree.

Ideally this would go on perldoc.perl.org, but that's very out of date (none of 5.28.[01], 5.26.[23], 5.24.[1-3] are available.

Tony

The remaining problems with this issue are covered by #13415