POD: embedding/linking/displaying html and images on metacpan and github

LanX has asked for the wisdom of the Perl Monks concerning the following question:

Am I wrong or did metacpan "break" some extended display options cpan.org had?

Like:

(distribution) internal hyper links with L<...>

embedded images

display .html files as html and not raw

On a similar note, github is using README as main entry page and allows using README.pod as alternative to markdown.

But while markdown seems to allow internal links and images this seems hard in pod.

I can't figure out how to write a L<> to link to the main module.

I suppose this is due to ambiguous definition of POD standard.

edit

Example: Emacs::PDE used to link in SEE ALSO to extensive html docs inside the distribution.

These links are broken now, going manually to the html files only shows the raw text for me.

update

OK the link L<lisp/doc/pde/index.html> doesn't use a scheme like html: I suppose this used to work in the old times.

lisp is interpreted as a module name.

On github prepending a ./ will not search a relative path inside the distribution.

Cheers Rolf
_{(addicted to the Perl Programming Language :)

Wikisyntax for the Monastery
FootballPerl is like chess, only without the dice}

Comment on POD: embedding/linking/displaying html and images on metacpan and github Select or Download Code

Replies are listed 'Best First'.
Re: POD: embedding/linking/displaying html and images on metacpan and github by Corion (Patriarch) on Mar 18, 2019 at 13:40 UTC
For me, linking to (external) links works using the protocol (`https://` in this case): `L<https://rt.cpan.org/Public/Dist/Display.html?Name=WWW-Mechanize-Chro +me>` [download] Linking to (external) images still works, as exhibited by Spreadsheet::WriteExcel: `=begin html <center> <img src="http://homepage.eircom.net/~jmcnamara/perl/data_validation.j +pg" alt="The output from the above example"/> </center> =end html` [download] So, it seems that Emacs::PDE fell prey to the changes in the POD renderer, but things should be fixable. If you want to use dist-relative `https://` links, I think you can use the following as the target: `L<https://metacpan.org/pod/distribution/Emacs-PDE/lisp/doc/pde/index.h +tml> - PDE User Guide` [download] ... but MetaCPAN doesn't seem to render the HTML files as HTML, which I suppose is an anti-spam measure.	[reply] [d/l] [select]
Re^2: POD: embedding/linking/displaying html and images on metacpan and github by LanX (Saint) on Mar 18, 2019 at 13:55 UTC
> L<https://metacpan.org/pod/distribution/Emacs-PDE/lisp/doc/pde/index.html> - PDE User Guide Well ... my aim was to write multi-file hypertext which renders well on disk, metacpan and github. Your solution will link from local or github to metacpan. My imagined solution would be a distribution relative path inside L<> I thought I saw this already in the past, i.e. Module PODs linking to other internal pages generated from POD (expample, tutorial, tests, ...) Maybe this could be fixed by introducing a new scheme, something like `dist:` or `relative:` ? Cheers Rolf _{(addicted to the Perl Programming Language :) Wikisyntax for the Monastery FootballPerl is like chess, only without the dice}	[reply] [d/l] [select]
Re: POD: embedding/linking/displaying html and images on metacpan and github by LanX (Saint) on Mar 18, 2019 at 13:24 UTC
I found this older discussion POD L<> and relative links? saying that L<> has no support for internal relative path. :/ Question: can I preview the rendering on metacpan prior to publishing? update Another nice resource is Perl::Examples::POD::Link Cheers Rolf _{(addicted to the Perl Programming Language :) Wikisyntax for the Monastery FootballPerl is like chess, only without the dice}	[reply]
Re^2: POD: embedding/linking/displaying html and images on metacpan and github by hippo (Archbishop) on Mar 18, 2019 at 13:53 UTC
You can paste or upload the POD into the POD Renderer to see how MetaCPAN will handle it.	[reply]
Re^3: POD: embedding/linking/displaying html and images on metacpan and github by stevieb (Canon) on Mar 18, 2019 at 18:27 UTC
That's pretty damned cool, I honestly had no idea that existed! How many times did my POD look perfectly fine locally, just to find that after a release to the CPAN (after a rigorous pre-release cycle) that I had to touch up POD issues. Regarding the testing of links in POD (a bit off topic), in at least one of my distributions that uses links between several docs within the distribution (with some external to eg github pages), I took to using Test::Pod::LinkCheck (as an author/release-only test file). Works well, and advises loudly when I've messed up a POD link (which happens often). It will also find links that used to work, but no longer do.	[reply]
Re^3: POD: embedding/linking/displaying html and images on metacpan and github by LanX (Saint) on Mar 18, 2019 at 13:57 UTC
great thanks! :) Cheers Rolf _{(addicted to the Perl Programming Language :) Wikisyntax for the Monastery FootballPerl is like chess, only without the dice}	[reply]
Re: POD: embedding/linking/displaying html and images on metacpan and github (=for html workaround) by LanX (Saint) on Mar 18, 2019 at 14:24 UTC
FWIW: it's possible to render a relative link in metacpan at least in the pod-renderer `=for html <a href='./pod/Emacs::PDE'>Emacs::PDE relative<a>` [download] if this can be consistently used in local viewers (man pagers) / github and metacpan is an open question. update tested on github, this works `=for html See <a href="./lib/MODULE.pod">module's documentation</a>` But you need to statically create the .pod beforehand. Cheers Rolf _{(addicted to the Perl Programming Language :) Wikisyntax for the Monastery FootballPerl is like chess, only without the dice}	[reply] [d/l] [select]