NAME Acme::CPANModules - CPAN modules SPECIFICATION VERSION 0.1.0 VERSION This document describes version 0.1.3 of Acme::CPANModules (from Perl distribution Acme-CPANModules), released on 2019-11-20. 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::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 => [ ... ], } 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()', # ... } 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 . SOURCE Source repository is at . BUGS Please report any bugs or feature requests on the bugtracker website 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 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.