view release on metacpan or  search on metacpan

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

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',
     description => <<'_',
 (Some longer description, in Markdown format)

 This is just a list of my favorite authors.
 _
     entries => [
         {...},
         ...
     ],

Each entry is another, similar hash structure (L<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 L<Dist::Zilla> to release your distribution, this
L<Pod::Weaver> plugin might be useful for you:
L<Pod::Weaver::Plugin::Acme::CPANLists>. It will create an C<AUTHOR LISTS> and
C<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.

=head1 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 L<acme-cpanlists> CLI script (from the
L<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
L<lcpan> script find related modules (C<lcpan related-mods>). See the lcpan
documentation or C<lcpan related-mods --help> for more details.

=head1 HOMEPAGE

Please visit the project's homepage at L<https://metacpan.org/release/Acme-CPANLists>.

=head1 SOURCE

Source repository is at L<https://github.com/perlancar/perl-Acme-CPANLists>.

=head1 BUGS

Please report any bugs or feature requests on the bugtracker website L<https://rt.cpan.org/Public/Dist/Display.html?Name=Acme-CPANLists>

When submitting a bug or request, please include a test-file or a
patch to an existing test-file that illustrates the bug or desired
feature.

=head1 SEE ALSO