search

Perl / perl5

🐪 The Perl programming language
https://dev.perl.org/perl5/
Other
1.97k stars 560 forks source link

The rendering of perlapi on metacpan #16741

Closed p5pRT closed 5 years ago

p5pRT commented 6 years ago

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

Searchable as RT133638$

p5pRT commented 6 years ago

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

Perl Info ``` 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 ```
p5pRT commented 6 years ago

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​:

https://github.com/metacpan/metacpan-web/issues/2118

Thank you very much. Jim Keenan

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

p5pRT commented 6 years ago

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

p5pRT commented 6 years ago

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​:

https://github.com/metacpan/metacpan-web/issues/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.

p5pRT commented 5 years ago

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​:

https://github.com/metacpan/metacpan-web/issues/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.

p5pRT commented 5 years ago

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

khwilliamson commented 5 years ago

The remaining problems with this issue are covered by #13415