Pod to HTML
OK, so there were already a thousand solutions for converting pod to HTML, but I wasn't especially happy with any of them. Things I wanted were:
- Clean-looking XHTML and/or HTML5 output.
- Unicode support. ☻
- Good syntax highlighting for Perl code samples within the pod.
- Links to metacpan.org by default rather than search.cpan.org.
And so I've cobbled together a solution using Pod::Simple, PPI::HTML, HTML::HTML5::Parser, HTML::HTML5::Writer, XML::LibXML::PrettyPrint and Moo, and released it as TOBYINK::Pod::HTML.
Here's the example from the synopsis section:
1: #!/usr/bin/perl 2: 3: use strict; 4: use warnings; 5: use TOBYINK::Pod::HTML; 6: 7: my $pod2html = "TOBYINK::Pod::HTML"->new( 8: pretty => 1, # nicely indented HTML 9: code_highlighting => 1, # use PPI::HTML 10: code_line_numbers => undef, 11: code_styles => { # some CSS 12: comment => 'color:green', 13: keyword => 'font-weight:bold', 14: } 15: ); 16: 17: print $pod2html->file_to_html(__FILE__);
There's a basic command-line script pod2html-tobyink supplied with it.
Oh, and this blog post was written as pod and converted to HTML.
I'm tobyink on CPAN, IRC and PerlMonks. 
I submitted a patch a while back to fix module links to use metacpan.org, but it was rejected as "too soon" -- https://github.com/theory/pod-simple/pull/36
You can help revive this by speaking up in favour on the pod-people list.
The Mojolicious core module Mojolicious::Plugin::PODRenderer might get close to all those requirements. Then again I'm not so sure how useful it would be. Perhaps I'll tinker and see.
The Mojolicious core module Mojolicious::Plugin::PODRenderer might get close to all those requirements. Then again I'm not so sure how useful it would be. Perhaps I'll tinker and see.
I always wonder why Perl coder still stick to POD. It is limited and ugly at the latest when you have used Markdown syntax. Ok, POD is better than Javadoc but a pain to use for serious documenting.
Jakob, its because POD lives in our toolchain. perldoc, search.cpan, metacpan all handle them. And with custom pod formatters you can do really cool stuff; PDL has added many formats to the pdldoc POD reader which are useful to us. Markdown is nice, but it can be far too simple, and its not integrated in our toolchain. Heck even GitHub renders POD!
Jakob, Joel: Additionally, I’ve read in the colophon of multiple O’Reilly books that they were written in Pod—or an extended version of Pod—and given to the publisher in that format. I’d be surprised to see this done in Markdown without drastic extensions to the point where it is no longer Markdown. (A quick search shows that such an extension exists, it’s called MultiMarkdown and is aimed at book and article publication.) Also, although there are some books like The Little MongoDB Book written in Markdown, I think this is an exception where richer formatting and layout aren’t needed.
POD is fine, except for its (bulleted and itemised) list syntax. (Definition lists are fine too.) It’s a little uglier than Markdown in its inline sequences, but has more of them and is more flexible overall (e.g. markup is allowed inside
C<>sequences). I like both… except the list thing, which bites.(I wonder if there is any chance we can hope for POD to gain better list syntax… maybe via an approach like Dist::Zilla it could be introduced in such a way that old infrastructure continues to work. (That is what makes it hard to add significant features to POD.))
Aristotle, as usual, hits the nail on its head. The list syntax is horrible. Everything else about POD is pretty much acceptable.
I have one more thing to (add|ask). Is there a way to collapse (a la orgmode) POD sections in Emacs? That's the other (out of two) pet peeves of mine regarding POD.
Have a look at Pandoc. It's got tasteful enhancements to original Markdown. Great for writing documentation.
I dunno.
For simple bullet/numbered lists, Markdown is fine. But if each list item has multiple paragraphs interspersed with code samples, I'd say Pod is a more attractive prospect.