POD Web View
When developing a Perl module, I often want to get a quick preview of the documentation that I'm writing, just to see if everything is in order and how it turns out. I used to do this the old fashioned way, by generating an HTML file with pod2html or pod2cpanhtml and opening it in a browser, but I was hoping in this day and age there is an easier and better solution, preferably a web application.
Looking around, however, the only thing I could find was the pod2html page at the CPAN Search site, which allows you to upload a POD file, have it processed by pod2html, and displayed with CPAN style. I thought it might be a good idea to try building something more user-friendly, with features like editing POD in the browser, drag and drop file uploads, etc.
And what better time for a little project like this than a weekend when you're ill and not supposed to leave your apartment? Well, that's what my last weekend was like -- two days of coughing and coding, and here's the result: POD Web View.
The application allows you to upload a POD file, get it from a URL, or paste its contents and edit it on the fly. The generated HTML can be displayed in the style of your choice, mimicking how it would look on CPAN, MetaCPAN, or GitHub.
To give credit where it's due, the backend is built on Dancer and uses Pod::Simple::HTML to generate the HTML preview. The user interface is made with Twitter Bootstrap, a lot of JavaScript/jQuery code, and the amazing Ace editor.
I hope this will be useful for at least a few fellow Perl developers, like it already is for me. Please note that at this point this is still work in progress -- the backend code needs some more work (e.g. basic sanity checks), and there are a couple UI issues that I'm aware of (and likely a dozen more that I'm not). Anyway, be my guest and give it a try, and if you'd like to report an issue, or maybe help me with the development (more than welcome), I've put the project up on GitHub.
I blog about Perl.
Loving it!!
Two things:
1) The different styles look quite the same?
2) The markup of indented stuff (code) like e.g. often used in the SYNOPSIS does not really look like code
I'm going to use this defenitely.
Thanks!
Nice one! I'll definitely be using this.
Nice!
One suggestion, for people with wide monitors it would be nice to increase/remove the CSS max-width constraint on the container that holds the input/output panels?
E.g.
.container {
max-width: none;
}
That's dandy.
The "URL" doesn't work at all for me. The "Upload file" doesn't work, although the drag and drop worked.
Also, I noticed there were no problems with a very Unicode heavy pod file.
@Boris: The styles should not look the same, and code should look like code :) However, syntax highlighting currently only works with the MetaCPAN style. I'm wondering if it might not be displaying properly for you, for some reason -- can you send me a few screenshots of your browser?
@nickl: Yeah, I was thinking about that, will look into it. Currently you can use the "expanded view" button (above the preview) to display the HTML in a larger modal window.
@Ben: The URL feature first downloads the file to your browser, and is thus limited to sites that allow CORS. For instance, this URL should work: http://api.metacpan.org/source/YANICK/Dancer-1.3118/lib/Dancer/Introduction.pod
Anyway, I might change it so that the URL is passed to the server, which then does the download.
Cool x 3! Although preview is not as instant as Markdown (like we see on sites like SO), it's very helpful and convnenient to see live preview of POD.