Rendering POD to (not with!) templated files

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

Esteemed monks,

I wrote a small darkpan browser for $work and I have the following issue...

The app is built as a Dancer web app. One of the features is that module PODs (ours, or dependencies from CPAN's) should be rendered to HTML and displayed in a page. I use Pod::Simple::XHTML to do the heavy lifting here. Since I also want the app to be relocatable without breaking all the inter-POD links, I have done this:

    my $pod_renderer = Pod::Simple::XHTML->new;
    # this is going to be inserted in a larger document
    $pod_renderer->html_header('[% TAGS [- -] %]');
    $pod_renderer->html_footer('');
    # http://localhost:5000/mirror/integration/module/Acme::Foo
    $pod_renderer->perldoc_url_prefix('[- request.uri_base -]/mirror/[
+- selected_mirror -]/module/');
    $pod_renderer->output_string(\my $html);
    $pod_renderer->parse_file($module);
    # spew $html into a file on disk
[download]

(ignore the [- selected_mirror -] part, that's just because we have multiple Pinto instances and the app can generate links e.g. from the integration to preproduction releases of a module)

When rendering the full module page, I have a total of three (!) template rendering passes: once to turn the POD-rendered-as-template into HTML; once to render the regular .tt file, which includes the previously rendered HTML directly; and finally once because the .tt file has a layout and Dancer's template engine works like this.

The first pass (POD to .tt) uses custom TAGS because otherwise the Template.pm PODs would not render properly (they of course include lots of [% %] everywhere). [- -] turned out to be a very bad idea (USAGE: foobar [-optional]) and I need to fix this.

The second and third pass are just Dancer's standard template to HTML rendering. The module page has other things besides the rendered POD, so it needs to be its own template that somehow includes the templated POD...

I feel like the way I wrote it is now a cluster[beep] of badly thought-out fixes upon badly thought-out fixes. Have you guys done something like this? How did you do it? Alternatively, do you see a simpler/better solution?

Comment on Rendering POD to (not with!) templated files Download Code

Replies are listed 'Best First'.
Re: pod to template -- treating data as templates -- avoid it by Anonymous Monk on Jan 29, 2015 at 11:34 UTC
yeah, generating a template out of your pod document is something I would avoid request.uri_base gotta come from somewhere, so just give it to Pod::Simple::XHTML directly Or, you can always use Template::Plugin::Class ... or create your own plugin, and add it to your template .. Doesn't matter how many passes you make -- it takes as many as it takes	[reply]
Re^2: pod to template -- treating data as templates -- avoid it by pokki (Monk) on Jan 29, 2015 at 12:29 UTC
request.uri_base gotta come from somewhere, so just give it to Pod::Simple::XHTML directly So, generate the rendered POD dynamically? Right now it's pregenerated earlier (when the indexer, which is another process, notices that the package index has changed). That means I need to keep the distribution tarballs around though. I'll give it a try and see if that works.	[reply]
Re^3: pod to template -- treating data as templates -- avoid it by Anonymous Monk on Jan 30, 2015 at 00:12 UTC
So, generate the rendered POD dynamically? Sure, why not :) If you want to have absolute urls like `http://localhost:5000/mirror/integration/module/Acme::Foo`generating this stuff on demand makes sense to me:) But I don't see why you can't have relative urls like `Acme::Foo` so that when `http://localhost:5000/mirror/integration/module/Acme::Foo` serves Acme::Foo, all the links that are relative and correct and then you don't need to know the prefix `http://localhost:5000/mirror/integration/module/` in advance	[reply] [d/l] [select]