Personally, I've always thought that Perl has a very natural and well-worn feel to it, and deserves a doc markup format that also feels natural. What works very well for me is [Markdown] (and [Pandoc]'s Markdown has mostly just the right additions, IMO).
[Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ (Note: Pandoc is written in Haskell. For anyone who's interested, I put up some quick notes on installing Haskell + Pandoc specifically onto Ubuntu 9.04 at <http://unexpected-vortices.com/docs/doc-notes/installing-pandoc.html>.) My own plan is to keep writing my docs in Pandoc Markdown (regardless of what language I'm working in at the moment), and if I *really* need POD or Pod, I'll just use Pandoc to convert them to some intermediate format, and then find a module on the CPAN to convert *that* to POD or Pod. I encourage others to do the same. Further, for API-style docs, I've been experimenting with extracting specifically-marked markdown-formatted code comments and then passing them through pandoc. For example, maybe something like this: #>>> # forage # ------ # # This function will hunt around for any # nuts that may or may not be present on # the system. # # *Warning:* Not compatible with most # squirrel-related modules. # # Args: # # * search-radius: default is 5 meters # * default behaviour if confronted by cat ... # #<<< sub forage { # ... } It's funny; the Python folks left their previous doc format (LaTeX), and went in the right direction (IMO), but ended up going with the less attractive [reST], rather than Markdown. [reST]: http://docutils.sourceforge.net/rst.html ---John
