view release on metacpan or  search on metacpan

lib/Acme/CPANLists.pm  view on Meta::CPAN

package Acme::CPANLists;

our $DATE = '2016-12-28'; # DATE
our $VERSION = '0.90.6'; # VERSION

1;
# ABSTRACT: CPAN lists

__END__

=pod

=encoding UTF-8

=head1 NAME

Acme::CPANLists - CPAN lists

=head1 VERSION

This document describes version 0.90.6 of Acme::CPANLists (from Perl distribution Acme-CPANLists), released on 2016-12-28.

=head1 SYNOPSIS

Acme::CPANLists is yet another way to organize CPAN modules/authors into various
"lists".

=head1 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 L<CPAN
Ratings|http://cpanratings.perl.org/> (where users rate and review a
distribution) or L<MetaCPAN|https://metacpan.org/> (which has a C<++> feature
where logged-in users can press a button to C<++> a module and the website will
tally the number of C<++>'s a distribution has) help to some extent. There are
also various blog posts by Perl programmers which review modules, e.g. L<CPAN
Module Reviews by Neil Bowers|http://neilb.org/reviews/>.

For categorizing CPAN authors, there are also the L<Acme::CPANAuthors> project,
complete with L<its own website|http://acme.cpanauthors.org/>.

Acme::CPANLists is another way to help. One creates an
C<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).

=head1 SPECIFICATION VERSION

0.090

=head1 CREATING AN ACME::CPANLISTS MODULE

The first step is to decide on a name of the module. It must be under the
C<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: L<Acme::CPANLists::PERLANCAR>. But I
recommend that you put each list into a separate module under your CPAN ID
subpackage, for example: L<Acme::CPANLists::PERLANCAR::Unbless> or
L<Acme::CPANLists::PERLANCAR::Task::PickingRandomLinesFromFile>.

Inside the module, the two main package variables you have to declare are:

 our @Author_Lists = ( ... );
 our @Module_Lists = ( ... );

Obviously enough, C<@Author_Lists> contains author lists while C<@Module_Lists>
contains module lists.

Each author/module list is just a hash structure (L<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',