byterock

Still stuck in Section mode here at the Dist-Pen

Carrying from my last post today I am going to look at the [Contributors] section plug-in. This particular plug-in is of little value so for to my 'Database::Accessor' project as I have no other people working on it with me but one can always dream big that I may have some helpers as time goes on. So it is is work a look.

I wanted to see if anyone else is using this plug-in so I did a Reverse Dependency look up and found that there are thirty-six other distributions that use this so I have few places where I can go an peek and see how it is being used.

This is another closely tied plug-in with Dist-Zilla with a number of options on how to import the content for the Section. Like the [Name] plug-in you need to get a list of contributors into you meta files somehow and that list is stored under the 'x_contributors' key.

Apart from just hard-coding the meta files there are a few other ways to get your values in there. There is a specific plug-in [Meta::Contributors] for Dist::Zilla as well if you are like me and have your source up on git you could use the [ContributorsFromGit] now at this point in the game I am just going to try some of the simpler methods.

The easiest for a project an early stage project like mine is just to add in the 'contributor' directly in the file concerned.

# : Bill Bloggins - <bill@bloggins.org>

we have see things like this before with the [Name] section. Now It is the usual install of the plug-in and then in the 'weaver.ini' file;

[Authors]

[Contributors]

[Availability]

The one point to remember here is that this Plug-in will only add that 'Contributors' section to what it thinks is the main Module and it will only look for the '# CONTRIBUTORS' in that source files so anything I add to my '.POD' or other 'source' files will just be ignored.
So if I add this to my Accessor.pm file

 # ABSTRACT: CRUD Interface for any DB

 # Dist::Zilla: +PkgVersion

 # CONTRIBUTORS: bloggingsb - Bill Bloggins - <bill@bloggins.org>

and at the same time I add in one '# CONTRIBUTORS' to the “Database::Accessor::Types” file;

# ABSTRACT: A Types Role for Database::Accessor:

# CONTRIBUTORS: mrtypes - Mr Types - <type@types.org>

and if I now give this the very tired dzil, clean ~build I will get

=head1 CONTRIBUTOR

=for stopwords bloggingsb - Bill Bloggins

bloggingsb - Bill Bloggins - <bill@bloggins.org>

only on the Accessor.pm file.
So If I want to acknowledge some one else in I will have to add in a second line in the Accessor.pm file like this

# CONTRIBUTORS: bloggingsb - Bill Bloggins - <bill@bloggins.org>

# CONTRIBUTORS: mrtypes - Mr Types - <type@types.org>

and I would get this output;

=head1 CONTRIBUTORS

=for stopwords bloggingsb - Bill Bloggins mrtypes Mr Types

=over 4

=item *

bloggingsb - Bill Bloggins - <bill@bloggins.org>

=item *

mrtypes - Mr Types - <type@types.org>

=back

You will also notice that this plug-in recognized that I had more that one contributor and added the plural from for me.
As I mentioned earlier there is the [Meta::Contributors] Dist::Zilla plug-in I could also use however this is no different than adding

[Contributors]

contributors = bloggingsb - Bill Bloggins - <bill@bloggins.org>

contributors = mrtypes - Mr Types - <type@types.org>

in my 'weaver.ini' file. The only difference is you would get the 'x_contributors' in your meta files which could be useful for some.
This plug-in has the standard 'head' attribute it you want it to say something else rather than 'Contributors'. Just be careful with it as you have to make sure you header works with and without an 's' on the end. If I used 'Thank You' it would come out 'Thank Yous' if I had more than one name in my list. Expect a call from the grammar police in that case.
The 'all_modules' attribute lets you add this section to each of the modules in your system be they POD or Source so I can use this attribute like this

[Authors]

[Contributors]

all_modules=1

in my 'weaver.ini' file and then with the '# CONTRIBUTORS:' I can get my contributors by page as in 'Mauual.pod' where I have this

=head1 CONTRIBUTOR

=for stopwords mrpod – Mr POD

mrpod - Mr POD - <mrpod@pod.com>

after I added

# ABSTRACT: What is Database::Accessor, and how do I use it?

++# CONTRIBUTORS: rpod - Mr POD - <mrpod@pod.com>

at the top of that file. When using this with the [Meta::Contributors] you will get all of the content supplied by the meta keys and any-other ' CONTRIBUTORS' you might of entered on the page.

One last point for this Plug-in is that is comes with a number of links to projects that use it so you can look at other ways to play with this.