byterock

Good Meal day here in the Dist-Pen

So in my last post I had a look at a the little more complex [Version] section plug-in for Pod::Weaver and Dist::Zilla. How the user can change the format of the section and even use some passed in variable, identified with a '%' in a section template.

Today we are going to look at one of the Meat and Potato sections the [Region]. This section allows you to place you own custom section or 'region' where-ever you want in your document. This is accomplished by using Pod::Weaver 'tags' which are simply text starting with a ':'

To start a 'region' one just needs to add

=begin :prelude


then your content you wanted and obviously to end it you just enter

=end :prelude 

The ':' tag can be anything you want as long as it contains no spaces and matches with the end tag. The reason I chose ':prelude' is that it found in the default template I am playing with;

[Region  / prelude]

The above never did anything to my existing POD as I have no ':prelude' tag present. I do not really want a what a prelude section. What I would like is a 'header' section so I can add this to my POD

=begin :manual_header


This is the Database Accessor Manual

=end :manual_header

I also want it to come before my 'Version' section so I change my 'weaver.ini' to

...

++[Region  / manual_header]

[Version]

...

and for fun I put that block of POD at the very bottom of my documents and my result was

=head1 Name


Database::Accessor::Manual - What is Database::Accessor, and how do I use it?

This is the Database Accessor Manual

=head1 Version

so there is my 'Region' section right where I want it above the 'Version' section.

You may have as many of these 'region' sections as you like as long as the names are different. As demonstrated above you can place you 'Region' anywhere you want in your document and weaver will place it in the correct place for

This plug-in has a few attributes I will look at the 'required' attribute first. As the name indicates it makes having this section in your pod required. You build will fail with a nasty warning if you try. This is an excellent way to ensure that any required POD for projects is included.

The 'flatten' attribute when set to 0 (false) it will print out the pod command rather than he strait pod so I get

=for :manual_header This is the Database Accessor Manual

after a build.

The 'allow_nonpod' attribute when set to 1 (true) will tell Pod::Weaver that you are using something other than POD in the region, HTML for example.

The 'region_name' is a little less convenient way to enter the name of your 'Region' as

[Region / manual_header]

and

[Region]

region_name = manual_header

are equivalent.

That is the 'Region' section in a nutshell an quick an easy way to add in custom sections or regions to you POD template.