Semantic POD

I was working on some POD processing code when I went down the rabbit hole finding the proper module for handling POD files and created a draft just by listing a bunch of modules for POD processing.

But then this question popped up again:

I am probably missing something fundamental, but I don't understand why are there no semantic pod markups? I mean such as =method , =function, =attribute etc. Instead of that we use =head2, =head3, =item in a rather arbitrary way. Which means it is harder to display them in a similar way across modules.

Alberto Simões pointed me to Pod::Weaver which collects =method and =attr tags and puts them under =head1 or =head2 tags, but that's just made me wonder even more.


I wonder how pod could tell the pod translator which formatter to use. Like:

=encoding utf8

=translator Pod::Semantic


This could then pick up whatever you wanted to do with the Pod. There's a way to do this from the command line, but we shouldn't have to know any of that.

Hi Gabor

Thanx for the detective work in finding all those pod modules.

I take the # to be an indicator of how many people felt dissatisfied enough to scratch their itches.

I think pod is sufficiently structured that storing it in a tree is the best in-memory representation. Then, there should be 1 reader and N writers.

And it's the lack of a tree module in core which has previously stopped me from adopting any pod-oriented modules (unless there's one which doesn't have Tree in its name, which is what I searched for). Supporting ancient Perls is of course also a complicating factor - as always.

Separating code from pod is also something we all have to keep in mind.

I have no problem with new markup (=method etc) in pod, but don't look forward to a fight over the details. And new markup impacts on the code 'v' pod question.

I suggest you create a slightly more formal proposal about which extensions you'd like to see, and perhaps how they would be mapped in a pod2text and pod2html rendering.

Leave a comment

About Gábor Szabó - גאבור סבו

user-pic I blog about Perl.