byterock

It is still POD day here at the Dist-Pen

I spent the day trying to get a little deeper into POD::Weaver to understand how it works rather than just aping the three lines I have seen in the odd tutorial or should I say tuturial-ette;

[@Default]


[-Transformer / List]

transformer = List

The fist thing to know about POD::Weaver is if you want to use it any deeper than the above then don't bother going to its home-page on CPAN there is not much there to get started on.

Not faulting the documentation at all it is quite comprehensive and perfect if you are going to create a project like podweaver.

If you are like the 99% of the rest of us you just want to use it within Dist::Zilla, your are little out of luck. You really have to put your thinking cap on if you are going to get anywhere.

My guess is that Karen has been too busy documenting the rest of CPAN and doesn't have time to write up a tutorial for this one. Oh well one can't have everything.

So to start the most important thing to remember is that POD::Weaver is a template system, and its template is the 'weaver.ini' file. In my previous post I just used the '@Default' template which is as follows;

[@CorePrep]

[-SingleEncoding]

[Name]

[Version]

[Region  / prelude]

[Generic / SYNOPSIS]

[Generic / DESCRIPTION]

[Generic / OVERVIEW]

[Collect / ATTRIBUTES]

command = attr

[Collect / METHODS]

command = method

[Collect / FUNCTIONS]

command = func

[Leftovers]

[Region  / postlude]

[Authors]

[Legal]

Now for the 25 cent tour, i.e. if you strip out all the '[]' and other stuff you will see all the standard layout of a typical CPAN POD

Name  

Version

Synopsis

Description

…

and thus you have your template. Now in that template each of the items in a '[]' is what Pod Weaver calls a 'Section' which is really just the same sort of plug-in one sees in Dist::Zilla.

However in Pod::Weaver 'sections' exists under there own name-space, So if you want to find the code for the [Name] section on CPAN you would it at 'Pod::Weaver::Section::Name' on CPAN, the same holds true for the other sections like [Version] and [Authors].

Each 'Section' will attempt to transform what you have in you POD file to what it thinks it should look like. In essence a template within template. All of the section plug-in work much the same they look for some sort of trigger in you POD and then act on it.

In the above '@Default' there is one true plug-in entry, i.e. in the 'Plugin' name-space, [-Single Encoding]. This and other plug-ins are denote by a '-' in front of the name.

So to end the 25 cent tour, the Dist::Zilla, [PodWeaver] sequentially processes your '.pm' and '.pod' files using either the default template or one you supply. In that template there are 'Sections' that will act on imputed file to create the desired effect for that section and produce the final POD document.

You think you would be able to find the above some-place on CPAN but I havn't, anyway now that’s enough for today.