NAME
    Acme::CPANModules - CPAN modules

SPECIFICATION VERSION
    0.1.0

VERSION
    This document describes version 0.1.4 of Acme::CPANModules (from Perl
    distribution Acme-CPANModules), released on 2019-11-26.

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 <http://cpanratings.perl.org/> (where users
    rate and review a distribution) or MetaCPAN <https://metacpan.org/>
    (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 <http://neilb.org/reviews/>.

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

    Acme::CPANModules is another mechanism to help, to let someone
    categorize modules in whatever way she likes.

    A related website/online service for "CPAN modules" is coming (when I
    eventually get to it :-), or perhaps when I get some help).

CREATING AN ACME::CPANMODULES MODULE
    The first step is to decide on a name of the module. It must be under
    the "Acme::CPANModules::" namespace. I recommend that you prefix your
    module with your CPAN ID, e.g. Acme::CPANModules::PERLANCAR::Unbless or
    Acme::CPANModules::PERLANCAR::Task::PickingRandomLinesFromFile.

    Inside the module, you must declare a hash named $LIST:

     our $LIST = {
         ...
     };

    The names of the keys in the hash must follow DefHash convention. The
    basic structure is this:

     # an example module list
     {
         summary => 'My favorite modules',
         description => <<'_',
     (Some longer description, in Markdown format)

     This is just a list of my favorite modules.
     _

         ## define features to be used by entries. this can be used to generate a
         ## feature comparison matrix among the entries.
         # entry_features => { # optional
         #     feature1 => 'Summary of feature1',
         #     feature2 => 'Summary of feature2',
         #     ...
         # },

         entries => [
             {...},
             ...
         ],

         ## specify Bencher scenario properties; "bench_" prefix will be removed
         ## when creating scenario record. see Bencher for more details.
         # bench_datasets => [ ... ],
         # bench_extra_modules => [ ... ],

         ## optional. Instruct cpanmodules script to not show the entries when
         ## viewing the list. This is sometimes convenient when the description
         ## already mentions all the entries.
         #'x.app.cpanmodules.show_entries' => 0,

     }

    Each entry is another DefHash:

     # an example module 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

         ## specify which features this entry supports/doesn't support. this can be
         ## used to generate feature comparison matrix. see
         ## Acme::CPANModulesUtil::FeatureMatrix.
         # features => {
         #     feature1 => 1,
         #     feature2 => 0,
         #     feature4 => {value=>0, summary=>'Irrelevant because foo bar'},
         #     ...
         # },

         ## specify Bencher scenario participant's properties; "bench_" prefix will
         ## be removed when creating participant record.
         # bench_code => sub { ... }, # or
         # bench_code_template => 'Data::Dump::dump(<data>)',
         # ...

     }

    That's it. After you have completed your list, publish your
    Acme::CPANModules 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::CPANModules. It will create an "=head2
    Included modules" section which is POD rendering of your module list so
    users reading your module's documentation can immediately read your
    list.

USING ACME::CPANMODULES MODULES
    As said earlier, a website/online service that collects and indexes all
    Acme::CPANModules modules on CPAN is coming in the future.

    In the meantime, you can install the cpanmodules CLI script (from the
    App::cpanmodules distribution). It can list installed Acme::CPANModules
    modules and view list entries.

    Putting similar/related modules together in an Acme::CPANModules can
    also help the lcpan script find related modules ("lcpan related-mods").
    See the lcpan documentation or "lcpan related-mods --help" for more
    details.

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

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

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

    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.

SEE ALSO
    "Acme::CPANModules::*" modules

    cpanmodules from App::cpanmodules

    Bencher

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2019, 2018 by perlancar@cpan.org.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

