Yeah, except that none of your examples would work. You have to put blank lines before and after each POD directive. Having an =item with a label, but no text, confuses most processors.

There are a lot of dark corners in POD. I am constantly reminding people when to indent, and when not to. I think POD violates a lot of the DWIM'ness of perl, because a lot of times POD does something really weird. Especially if you forget to put new lines in or something like that.

Today one of my co-workers put a blank space on a line after some pod directive. Well, that doesn't work, but it is not clear why (unless you are using cperl-mode, and have those annoying underscores showing up all over your code). Hey, this isn't Python; whitespace shouldn't matter! :)

That said, I always use POD, because that's all there is. pod2usage is great, too. But I wish we had something like JavaDoc, which is SO much easier to use, and it generates better output, too. Java has a head start as a strongly typed language, of course. But why can't we have =sub, =param, and =return tokens in POD?

-Mike