view release on metacpan or  search on metacpan

lib/Dist/Zilla/Stash/PodWeaver.pm  view on Meta::CPAN

=head1 USAGE

The attributes should be separated from the plugin name with a dot:
C<PluginName.attributes>.
The PluginName will be passed to
C<< Pod::Weaver::Config::Assembler->expand_package() >>
so the PluginName should include the leading character
to identify its type:

=over 4

=item *

C<> (no character) (Pod::Weaver::Section::I<Name>)

=item *

C<-> Plugin (Pod::Weaver::Plugin::I<Name>)

=item *

C<@> Bundle (Pod::Weaver::PluginBundle::I<Name>)

=item *

C<+> Full Package Name (I<Name>)

An ini config line cannot start with an I< = >
so this module will convert any lines that start with I< + > to I< = >.

=back

For example

  Complaints.use_fake_email = 1

Would set the 'use_fake_email' attribute to '1'
for the [fictional] I<Pod::Weaver::Section::Complaints> plugin.

  -StopWords.include = Flibberoloo

Would add 'Flibberoloo' to the list of stopwords
added by the L<Pod::Weaver::Plugin::StopWords> plugin.

  +Some::Other::Module.silly = 1

Would set the 'silly' flag to true on I<Some::Other::Module>.

=head1 METHODS

=head2 expand_package

Expand shortened package monikers to the full package name.

Changes leading I<+> to I<=> and then passes the value to
I<expand_package> in L<Pod::Weaver::Config::Assembler>.

See L</USAGE> for a description.

=head1 BUGS AND LIMITATIONS

=over

=item *

Arguments can only be specified in a F<dist.ini> stash once,
even if the plugin would normally allow multiple entries
in a F<weaver.ini>.  Since the arguments are dynamic (unknown to the class)
the class cannot specify which arguments should accept multiple values.

To work around this you can add brackets (and subscripts)
to config lines to specify that an attribute is an array:

  Plugin.attr[0] = first
  Plugin.attr[1] = second

See L<Config::MVP::Slicer/CONFIGURATION SYNTAX> for more information.

=item *

Including the package name gives the options a namespace
(instead of trying to set the I<include> attribute for 2 different plugins).

Unfortunately this does not automatically set the options on the plugins.
The plugins need to know to use this stash.

So if you'd like to be able to use this stash with a L<Pod::Weaver>
plugin that doesn't support it, please contact that plugin's author(s)
and let them know about this module.

If you are a L<Pod::Weaver> plugin author,
have a look at
L<Dist::Zilla::Role::Stash::Plugins/get_stashed_config> and
L<Dist::Zilla::Role::Stash::Plugins/merge_stashed_config>
to see easy ways to get values from this stash.

Please contact me (and/or send patches) if something doesn't work
like you think it should.

=back

=head1 SUPPORT

=head2 Perldoc

You can find documentation for this module with the perldoc command.

  perldoc Dist::Zilla::Stash::PodWeaver

=head2 Websites

The following websites have more information about this module, and may be of help to you. As always,
in addition to those websites please use your favorite search engine to discover more resources.

=over 4

=item *

Search CPAN