view release on metacpan or  search on metacpan

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

     summary => 'Modules that predict the future',
     description => <<'_',

This list catalogs modules that predict the future. Yes, the future is
unpredictable. But we can try anyway, right?

_
     entries => [
         {
             module => 'Zorb',
             summary => 'Contact the API for the strange crystal Zorb',
             description => <<'_',

This module is an API client to Zorb, a strange crystal that supposedly fell
from the sky in 2017 near Ozark, that can change color depending on what you
feed to it. The API connects to Zorb API server managed by Crooks, Inc.

_
         },
         {
             module => 'Madame::Zita',
             summary => 'Ask Madame Zita the fortune teller',
         },
     ],
 };

For more examples, see existing C<Acme::CPANModules::*> modules on 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::CPANModules>. It will create an C<=head2 Included
modules> section which is POD rendering of your module list so users reading
your module's documentation can immediately read your list.

=head1 RECOMMENDATIONS

=head2 module name

An Acme::CPANModules module is named under C<Acme::CPANModules::> namespace.

A personal list should go under your CPAN ID's subnamespace, e.g.
C<Acme::CPANModules::YOURCPANID::Favorite> or
C<Acme::CPANModules::YOURCPANID::Avoided>.

Avoid having C<Modules> in the name as it is superfluous, e.g.
C<Acme::CPANModules::TextTable> instead of
C<Acme::CPANModules::TextTableModules>.

Verb is preferrably written in present participle form, e.g. for a list of
modules that parse JSON: C<Acme::CPANModules::ParsingJSON> instead of
C<Acme::CPANModules::ParseJSON>.

Noun that refers to the modules (entries) is preferrably written in plural
forms, e.g. C<Acme::CPANModules::JSONParsers> instead of
C<Acme::CPANModules::JSONParser>.

=head2 list summary

The list summary normally becomes the Acme::CPANModules module's Abstract.

It is recommended to start the summary with "List of modules which/that" or
"List of my ... modules" to make it clearer that the Acme::CPANModules module
only contains a list of other modules, instead of an actual implementation.

Some preferred examples:

Some non-preferred examples:

=head2 entry rating

Should only be used for personal lists.

=head2 module bundle name

A distribution that contains several C<Acme::CPANModules::*> modules should be
named C<Acme-CPANModulesBundle-*>.

In general, an C<Acme::CPANModulesBundle::> module should be named like an
C<Acme::CPANModules::*> module. See recommendations in L</"module name">.

=head2 module bundle abstract

An C<Acme::CPANModulesBundle::> module should have abstract that begins with
"Bundle of ...".

=head2 other modules

Other suggested namespaces:

=over

=item * C<Acme::CPANModulesUtil::>,

Utility modules that do not contain lists of modules themselves.

=item * C<Acme::CPANModulesUtilBundle::>,

For distribution that contains several C<Acme::CPANModulesUtil::*> modules.

=item * C<Acme::CPANModulesRole::>

For role related to C<Acme::CPANModules>.

=item * C<Acme::CPANModulesRoleBundle::>

For distribution that contains several C<Acme::CPANModulesRole::> modules.

=back

=head1 USING ACME::CPANMODULES MODULES

You can install the L<cpanmodules> CLI script (from the L<App::cpanmodules>
distribution). It can list installed Acme::CPANModules modules and view list
entries. To install all modules listed on an Acme::CPANModules module, you can
do something like:

 % cpanmodules ls-entries Org | cpanm -n

Putting similar/related modules together in an Acme::CPANModules 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.