Dist::Zilla Hates Leftovers

Well POD post-ette day again here in the Dist-Pen

In my last post I had a look at the [Collect] section plug-in and how you can use it to gather up similar parts of your POD in to one section in a document. Useful when you want to keep the POD next to the code but you have a mix of function attributes and subs in the code for other valid reasons.

Today I am looking aI would guess would be the simplest plug-in to use [Leftovers]. As the name implies it dump any Pod that has not been put into another section.

In the case of the [@Default] template it is here;

...
[Leftovers]
[Region  / postlude]
[Authors]
[Legal]
Now in my present POD I only have one left over bit

=head1 Datatbase::Accessor is not an ORM
and with the above default you see it show ups just before the [Authors] section

 Check out older version at ...

=head1 Datatbase::Accessor is not an ORM

=head1 AUTHOR
So I do not like that as I want that a little earlier in my POD so I will stick that here in my template

[Region  / manual_header]
++[Leftovers]
[Collect / Table Of Contents]
and then when I give it the good old clean and build with dzil I get

This is the Database Accessor Manual

=head1 Datatbase::Accessor is not an ORM
…
Pod::Weaver collects leftovers in sequence so if I add this anywhere in my POD say at the very bottom

=end :manual_header

++=head2 Installation Guide
++Stick in the floppy disk; flip when prompted

=cut
and if I re-buit, the resultant POD would look like this

=head1 Datatbase::Accessor is not an ORM

=head2 Installation Guide
Stick in the floppy disk; flip when prompted
...


There are no attributes for this plug-in and like most plug-ins you can have only one of them in a template.

When you see that your POD is being rendered in the wrong place it is most likely this plug-in is gathering up that content and placing it in its section of the template. This is a good debugging tool as one can see where things are falling though the cracks as you build up your POD. In this case you may want to move this section to the bottom of you template while you work out what goes where.

If you are missing complete sections of POD you most likely forgot to add this plug-in to your template.

53ced7d624515.image.jpg

Leave a comment

About byterock

user-pic Long time Perl guy, a few CPAN mods allot of work on DBD::Oracle and a few YAPC presentations