SYNOPSIS
Acme::CPANLists is yet another way to organize CPAN modules/authors
into various "lists".
SPECIFICATION VERSION
0.090
DESCRIPTION
With the multitude of modules that are available on CPAN, it is
sometimes difficult for a user to choose an appropriate module for a
task or find other modules related in some ways to a module. Various
projects like CPAN Ratings (where users
rate and review a distribution) or MetaCPAN
(which has a ++ feature where logged-in users can press a button to ++
a module and the website will tally the number of ++'s a distribution
has) help to some extent. There are also various blog posts by Perl
programmers which review modules, e.g. CPAN Module Reviews by Neil
Bowers .
For categorizing CPAN authors, there are also the Acme::CPANAuthors
project, complete with its own website .
Acme::CPANLists is another way to help. One creates an
Acme::CPANLists::SOMENAME module, and inside it puts lists of CPAN
modules and authors with their descriptions/reviews/ratings. The
creator of the list is free to organize her list in whatever way she
likes.
A related website/online service for "CPAN lists" is coming (when I
eventually get to it :-), or perhaps when I get some help).
CREATING AN ACME::CPANLISTS MODULE
The first step is to decide on a name of the module. It must be under
the Acme::CPANLists:: namespace. Since, unlike in Acme::CPANAuthors, a
module can contain multiple lists, you can just use your CPAN ID for
the module, even if you want to create many lists, for example:
Acme::CPANLists::PERLANCAR.
Inside the module, the two main package variables you have to declare
are:
our @Author_Lists = ( ... );
our @Module_Lists = ( ... );
Obviously enough, @Author_Lists contains author lists while
@Module_Lists contains module lists.
Each author/module list is just a hash structure (DefHash). The basic
structure is this:
# an example author list
{
#id => 'GUID', # optional, can be set to ease list identification/referral
summary => 'My favorite modules',
description => <<_,
(Some longer description, in Markdown format)
This is just a list of my favorite modules.
_
entries => [
{...},
...
],
}
# an example module list
{
#id => 'GUID', # optional, can be set to ease list identification/referral
summary => 'My favorite authors',
description => <<'_',
(Some longer description, in Markdown format)
This is just a list of my favorite authors.
_
entries => [
{...},
...
],
Each entry is another, similar hash structure (DefHash):
# an example author list entry
{
author => 'RJBS',
summary => 'Kick-ass projects',
description => <<'_',
He is my favorite author because he starts some kick-ass projects which I
use daily, one of which is Dist::Zilla. It has saved me so much time, as
well wasted countless, because by using Dist::Zilla I am motivated to
release lots and lots of Perl modules.
_
# rating => 10, # optional, on a 1-10 scale
# alternate_authors => ['SOMEONE', 'ANOTHER'], # optional, if you want to express alternate author(s)
}
# an example module list entry
{
module => 'Data::Dump',
summary => 'Pretty output',
description => <<'_',
Data::Dump is my favorite dumping module because it outputs Perl code that
is pretty and readable.
_
# rating => 10, # optional, on a 1-10 scale
# alternate_modules => [...], # if you are reviewing an undesirable module and want to suggest better alternative(s)
# related_modules => ['Data::Dump::Color', 'Data::Dumper'], # if you want to specify related modules that are not listed on the other entries of the same list
}
That's it. After you have completed your lists, publish your
Acme::CPANLists module to CPAN.
If you are using Dist::Zilla to release your distribution, this
Pod::Weaver plugin might be useful for you:
Pod::Weaver::Plugin::Acme::CPANLists. It will create an AUTHOR LISTS
and MODULE LISTS POD sections which are POD rendering of your
author/module lists so users reading your module's documentation can
immediately read your lists.
USING ACME::CPANLISTS MODULES
As said earlier, a website/online service that collects and indexes all
Acme::CPANLists modules on CPAN is coming in the future.
In the meantime, you can install the acme-cpanlists CLI script (from
the App::AcmeCpanlists distribution). It can list installed
Acme::CPANLists modules and view the entries of a list.
Putting similar/related modules together in an Acme::CPANLists can also
help the lcpan script find related modules (lcpan related-mods). See
the lcpan documentation or lcpan related-mods --help for more details.
SEE ALSO
Acme::CPANLists::* modules
acme-cpanlists from App::AcmeCpanlists