Rendering of autodoc.pl in perl distribution is bad

[jkeenan]

This was originally filed as a bug in the Perl 5 core distribution's issue queue at: https://rt.perl.org/Ticket/Display.html?id=133638. At issue is this page on metacpan.org: https://metacpan.org/pod/distribution/perl/autodoc.pl

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

autodoc.pl is the program used for automatic generation of certain POD files within the core distribution such as pod/perlapi.pod. As such it contains what might be described as a custom heredoc that contains POD-formatted text. This quasi-POD apparently confuses POD renderers.

autodoc.pl, strictly speaking, has no public documentation. So perhaps it should not be rendered on metacpan.org. (It appears not to be rendered at perldoc.perl.org.)

Let's discuss.

Thank you very much. Jim Keenan

[Grinnz]

Metacpan assumes any pod it finds in .pm or .pl is documentation for that file. You can avoid this misclassification with tricks like fatpacker uses: prefix all lines in the heredoc with extra spaces, and remove those spaces afterwards.

[haarg]

MetaCPAN provides a view of what exists in release tarballs. This is the same for perl releases. It doesn't do a build process, so any generated files will not be available. It doesn't have any real way of knowing that the pod in autodoc.pl is not real pod. MetaCPAN doesn't really have any special cases for perl compared to other dists.

Preventing autodoc.pl from showing up in the documentation list could be done either by adding a special case to our indexing process, or on the p5p side by modifying script to not have valid pod inside it, like @Grinnz suggested. That doesn't solve the problem of getting the documentation to show up though.

One way to solve that would be for the perl release process to generate or update the perlapi.pod file, rather than leaving it to compile time. There are some other similar things that would also be improvements, like copying the perldelta.pod file to the version specific perl5280delta.pod (or whatever version) file.

Theoretically MetaCPAN could compile perl and use the generated pod files. But that is a significant amount of extra work, both in the infrastructure to do the compiles, and in terms of how the files would be stored and indexed. MetaCPAN currently does not have the concept of a file that doesn't exist directly in a release tarball.

[haarg]

#1628 related

[xsawyerx]

You note that while we can prevent autodoc.pl from appearing the documentation list by indenting the POD inside it, still won't prevent the POD from being rendered and I'm confused by it. Is it because it will render the POD even if it's indented?

I think rendering the documentation during the release cycle is achievable, but why do you suggesting copying the perldelta.pod to its new location pre-release? What does that address?

I think we should resolve this on the perl side and not MetaCPAN side.

[Grinnz]

I think you misinterpreted; indenting the POD will both prevent it from being rendered as POD and showing up as a documentation file. It does not solve the problem of displaying the correct POD for 'perlapi'.

[Grinnz]

Copying the perldelta to its new location would mean that https://metacpan.org/pod/perl5280delta would be linkable while it's still the latest stable release of Perl - linking to https://metacpan.org/pod/perldelta is not very useful since it will change in the future.

[xsawyerx]

Oh, I see. So we need two changes:

• Create documentation for perlapi. We can do that, even if all it explains is what it does and says these are not the documentations you are looking for.
• Indent the POD and then remove it, so it doesn't get detected.

Isn't the whole point of perldelta to reflect the latest - and current - one?

[Grinnz]

Create documentation for perlapi.

This would be best solved by generating perlapi.pod at release time if that's possible.

Isn't the whole point of perldelta to reflect the latest - and current - one?

Yes, which is useful for 'perldoc perldelta' or looking for what's changed only in the latest release, but not for linking to a specific change in a release of Perl.

[Grinnz]

The accidental rendering of autodoc.pl should be fixed (in future releases) by https://perl5.git.perl.org/perl.git/commitdiff/6a4c4cd4 thanks to Dave M.