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

I have some text tables on my module POD, e.g. Bencher::Scenario::Accessors::Get.

I'm thinking of showing a sortable HTML table (which contains some JavaScript) instead when the POD is rendered to HTML as in sites like metacpan.org. This will be done using =begin HTML ... =end HTML POD commands.

I'd also like that the text table is not displayed on HTML output, so the user is not seeing two tables (one text and one HTML). Any idea? Two of mine so far:

1) in the =begin HTML ... =end HTML snippet, hide the text table DOM element using some CSS or JS. But this will depend on how the POD is rendered to HTML, i.e. I can make it work on metacpan.org but it might not work on other sites like say search.cpan.org which might render the HTML differently.

2) put the text table in =begin man ... =end man *and* =begin text ... =end text. But this feels dirty. What about other output formats?

  • Comment on Only showing part of POD when not rendered as HTML

Replies are listed 'Best First'.
Re: Only showing part of POD when not rendered as HTML
by Anonymous Monk on Jun 26, 2016 at 21:04 UTC
    don't get fancy with it :D  =for html <script>turnFollowingTextTableIntoSortableHtmlTable(this);</script>
[reply]
[d/l]

      Yup, this is basically a variation of #1, where you need to know the DOM of the final HTML document.

      Perhaps there should be something like =for !HTML or =begin !HTML ... =end !HTML?

[reply]

        Yup, this is basically a variation of #1, where you need to know the DOM of the final HTML document.

        There are less than ten (like 2-6) pod to ?html things with anything resembling a user base, and only 2 are "popular"...

        So there is not a whole lot to know, you make the text, so make it easy, resulting DOM is either one target node <div>##tablestart ... ##tableend</div>

        or a bunch of siblings <p>##tablestart...<p>##tableend

        Both are easily found if you tag the table

        with jquery $(':contains("##tablestart")').each...text...replace...

        or xpath (jquery also has a plugin)  var iterator = document.evaluate('//*[ not(./*)  and  contains( ., "##tablestart")/ ]', document.body, null, XPathResult.UNORDERED_NODE_ITERATOR_TYPE, null ); ...

        Perhaps there should be something like =for !HTML or =begin !HTML ... =end !HTML?

        :) If you think you need that, you should generate the pod from some other template language ... if it doesn't drive you insane

        Yes, you could invent a =begin :format, but then you'd have to convince all those pod module authors to accept your solution, and all the users would have to upgrade .... seems like a nonstarter , pod is already too complex :)

[reply]
[d/l]
[select]

Back to Seekers of Perl Wisdom