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?

In reply to Rendering POD to (not with!) templated files by pokki

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.