|Subject:||wish: example in or near synopsis.|
I can see value here in decoupling where POD is stored in files and how it is presented. Just after (or during) the SYNOPSIS, I think it makes sense to show a brief example of what the input, output and processing code looks like. Something like what's in "t/eg" seems like it would be appropriate. The tool reminds me of how the darcs manual is organized. Some of the code for it is strewn throughout various files where it is intermixed with the code. The "make" system then has logic to collect and present all the documentation in the form of a manual. I could see a larger-sized Perl project using Pod::Weaver for that.