App::podweaver - Run Pod::Weaver on the files within a distribution.
App::podweaver provides a mechanism to run Pod::Weaver over the files within a distribution, without needing to use Dist::Zilla.
Where Dist::Zilla works on a copy of your source code, App::podweaver is intended to modify your source code directly, and as such it is highly recommended that you use the Pod::Weaver::PluginBundle::ReplaceBoilerplate plugin bundle so that you over-write existing POD sections, instead of the default Pod::Weaver behaviour of repeatedly appending.
You can configure the Pod::Weaver invocation by providinng a weaver.ini file in the root directory of your distribution.
Since the META.json/yml file is often generated with an abstract extracted from the POD, and App::podweaver expects a valid META file for some of the information to insert into the POD, there's a chicken-and-egg situation on the first invocation of either.
Running App::podweaver first should produce a POD with an abstract line populated from your # ABSTRACT: header, but without additional sections like version and authors. You can then generate your META file as per usual, and then run App::podweaver again to produce the missing sections:
$ ./Build distmeta
ERROR: Missing required field 'dist_abstract' for metafile
$ podweaver -v
No META.json or META.yml file found, are you running in a distribution directory?
$ ./Build distmeta
$ podweaver -v
This should only be neccessary on newly created distributions as both the META and the neccessary POD abstract should be present subsequently.
Runs Pod::Weaver on the given file, merges the generated Pod back into the appropriate place and writes the new file out.
App::podweaver->weave_file() returns App::podweaver::FAIL on failure, and either App::podweaver::SUCCESS_UNCHANGED or App::podweaver::SUCCESS_CHANGED on success, depending on whether changes needed to be made as a result of the weaving.
Currently these constants are not exportable.
The following options configure App::podweaver->weave_file():
The filename of the file to weave.
The Pod::Weaver instance to use for the weaving.
If set to a true value, no backup will be made of the original file.
If set to a true value, the modified file will be written to the original filename with .new appended, rather than overwriting the original.
If no $VERSION can be parsed from the file by Module::Metadata, the version supplied in dist_version will be used as a fallback.
Any additional options are passed untouched to Pod::Weaver.
Attempts to extract the information needed by Pod::Weaver about the distribution.
It does this by examining any META.json or META.yml file it finds, and by expanding various fields found within.
Valid options are:
Treats $directory as the root directory of the distribution, where the META.json or META.yml file should be found.
If not supplied, this will default to the current working directory.
If set, any @ sign in author emails will be replaced by a space, the given string, and a further space, in an attempt to confuse spammers.
For example antispam => 'NOSPAM' will transform an email of firstname.lastname@example.org into nobody NOSPAM 127.0.0.1.
antispam => 'NOSPAM'
nobody NOSPAM 127.0.0.1
Builds a Pod::Weaver instance, attemping to find a weaver.ini in the distribution root directory.
Treats $directory as the root directory of the distribution, where the weaver.ini file should be found.
Invokes File::Find::Rule, File::Find::Rule::VCS and File::Find::Rule::Perl to return a list of perl files that are candidates to run Pod::Weaver on in the lib, bin and script dirs of the distribution directory.
Treats $directory as the root directory of the distribution.
Rolls all the other methods together to run Pod::Weaver on the appropriate files within the distribution found in the current working directory.
Retrieves the Config::Tiny contents of the user's config file for the application, as found in the podweaver.ini file in the usual place for user configuration files for your OS.
(~/.app_podweaver/podweaver.ini for UNIX, ~/Local Settings/Application Data/App-podweaver/podweaver.ini under Windows.)
~/Local Settings/Application Data/App-podweaver/podweaver.ini
The whole bootstrap issue with META.json/yml is ugly.
Please report any bugs or feature requests to bug-app-podweaver at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-podweaver. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-app-podweaver at rt.cpan.org
You can find documentation for this module with the perldoc command.
You can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
Sam Graham <libapp-podweaver-perl BLAHBLAH illusori.co.uk>
This software is copyright (c) 2010-2011 by Sam Graham <libapp-podweaver-perl BLAHBLAH illusori.co.uk>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install App::podweaver, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.