byterock

Even more POD here on the Dist-Pen today.

I my last post I finally figured out how Pod::Weaver works, a template, weaver.ini file, that has 'Sections', [Name], [Author] etc, that you can change to create your POD document.

I wanted to test just how Pod::Weaver works so I replace '@default' in my 'weaver.ini' whith what the source code of Pod::Weaver::PluginBundle::Default said it was supplying;

[@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 if this really is a template I should be able to move things about in my 'weaver.ini 'and then see them move on the output POD. To that end I tried this

[@CorePrep]

[-SingleEncoding]

[Legal]

[Version]

[Generic / SYNOPSIS]

[Generic / DESCRIPTION]

[Name]

…

just to see what I might get. After a quick clean and built with good old 'dzil' my result was

=pod

=encoding UTF-8

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 by John Scoles.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007

=head1 VERSION

version 0.01

=head1 NAME

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

=head1 Datatbase::Accessor is not an ORM

=head1 Table Of Contents

...

=head1 AUTHOR

John Scoles

=cut

Sure enough I just created a really crappy POD document my POD bits were where I expected them, I real template cool.

Now a quick final word about the [@default]. It is not the only template or plug-inbundle found in the 'Pod::Weaver::PluginBundle' name-space. I made a count of just under fifty as of the time or writing.

You can basically use any one of these as a replacement for [@default] I find these come in one of two flavors'

1) Author bundles

These are the personal style templates, that should be in the 'Pod::Weaver::PluginBundle::Author::*' name-space, that some CPAN users have shared over the years. They are usually a good spot to find new ideas and examples of how to accomplish tasks.

They are easy to use just install them from CPAN sub out the [@default] with the appropriate name-space. For example

--[@default]

++[@Author::ETHER]

in you 'weaver.ini' file would set you up to create documents in Karen Etherige's style.

Sometimes authors do not include 'weaver.ini' file in their CPAN distribution as it is only needed if you intend to build a distribution. I usually go and have a look at the source repository of the modules where you should find the 'weaver.ini' and the original mark-up of POD.

2) Project Bundles
Some projects require that if you are going to be a contributor you will have to use their 'weaver.ini' file so the documentation is consistent in the project.
So far I have found only these two;
Pod::Weaver::PluginBundle::AMD
This is the POD standard for the AMD Operating System Research Center
Pod::Weaver::PluginBundle::BioPerl
This is the POD standard for BioPerl

As a final word, it seem the 'Pod::Weaver::PluginBundle::*' name-space is quite polluted with mostly Author template plug-ins as I found only one truly generic one;

Pod::Weaver::PluginBundle::NoAuthor

A template without the Author section

So please be kind if you want to get your style template out to CPAN use the 'Author' name-space.