Bug #50259 for Task: Documentation fixes to Task.pm

While reading the POD in Task.pm, I came across a few grammar errors and run-on sentences. The attached patch against Task.pm addresses them.

diff --git a/Task.pm b/Task.pm index 31d170c..95bb630 100644 --- a/Task.pm +++ b/Task.pm @@ -5,7 +5,7 @@ use strict; use vars qw{$VERSION}; BEGIN { - $VERSION = '1.04'; + $VERSION = '1.04'; } 1; @@ -20,36 +20,36 @@ Task - The successor to Bundle:: for installing sets of modules =head1 SYNOPSIS - ### In Makefile.PL - use inc::Module::Install; - - name 'Task-Foo'; - abstract 'Install the most common Foo modules'; - author 'Adam Kennedy <adamk@cpan.org>'; - version_from 'lib/Task/Foo.pm'; - license 'perl'; - - # All the things we need for Foo - requires 'perl' => '5.005'; - requires 'Carp' => 0; - requires 'File::Basename' => 0; - requires 'Storable' => 0; - requires 'Params::Util' => '0.06'; - - WriteAll; - - - - ### In lib/Task/Foo.pm - package Task::Foo; - - use strict; - use vars qw{$VERSION}; - BEGIN { - $VERSION = '1.00'; - } - - 1; +In C<Makefile.PL>: + + use inc::Module::Install; + + name 'Task-Foo'; + abstract 'Install the most common Foo modules'; + author 'Adam Kennedy <adamk@cpan.org>'; + version_from 'lib/Task/Foo.pm'; + license 'perl'; + + # All the things we need for Foo + requires 'perl' => '5.005'; + requires 'Carp' => 0; + requires 'File::Basename' => 0; + requires 'Storable' => 0; + requires 'Params::Util' => '0.06'; + + WriteAll; + +In C<lib/Task/Foo.pm>: + + package Task::Foo; + + use strict; + use vars '$VERSION'; + BEGIN { + $VERSION = '1.00'; + } + + 1; =head1 DESCRIPTION @@ -63,73 +63,76 @@ modules/version pairs to be installed. Although it has done a reasonably good job, C<Bundle::> modules suffer from some problems. -Firstly, C<Bundle::> functionality is fairly magical. The C<Bundle::> magic -needs to be specially implemented by the CPAN client, and a C<Bundle::> -dist is treated differently to every other type of dist. +=over 4 -It provides only static dependencies. That is, it only provides a -specific set of dependencies, and you cannot change the list depending -on the platform (for example, installing an extra Win32:: module if -the bundle is being installed on Windows). +=item 1. -Finally, it exists only in CPAN. It is not possible to take a C<Bundle::> +C<Bundle::> functionality is fairly magical. The C<Bundle::> magic needs to +be specially implemented by the CPAN client, and a C<Bundle::> dist is +treated differently to every other type of dist. + +=item 2. + +C<Bundle::> provides only static dependencies. That is, it only provides a +specific set of dependencies, and you cannot change the list depending on +the platform (for example, installing an extra C<Win32::> module if the +bundle is being installed on Windows). + +=item 3. + +C<Bundle::> exists only in CPAN. It is not possible to take a C<Bundle::> dist and just install it, because Makefile.PL files are irrelevant for C<Bundle::> dists. -The irony now is that an ordinary module has far more flexible and -powerful dependency capabilities than C<Bundle::> distributions. And because -the functionality is hard-coded into the CPAN clients for the entire -C<Bundle::> namespace, moving beyond the current situation is going to -mean a change of namespace. +=back + +The irony now is that an ordinary module has far more flexible and powerful +dependency capabilities than C<Bundle::> distributions. Because the +functionality is hard-coded into the CPAN clients for the entire +C<Bundle::> namespace, moving beyond the current situation is going to mean +a change of namespace. =head2 Requirements for a C<Bundle::> Successor The C<Task::> namespace (modeled off the Debian packages of the same name) is used to provide similar functionality to the traditional -C<Bundle::> namespace, but without the need to magic and special -client-side support in order to have them work. +C<Bundle::> namespace, but without the need for magic and special +client-side support. A C<Task::> module is implemented as a normal .pm module, with only a version defined. That .pm module itself should NOT load in all the dependencies. This implementation as a module allows normal Perl tools to be able -to load the module and check it's version to confirm you have the -required modules, without the need for a CPAN client involved. +to load the module and check its version to confirm you have the +required modules. A CPAN client is not required. -Instead of using a magic POD format, the dependency specification -is implemented using the Makefile.PL, as you would for any other -module. - -This also means that if the Task needs to check for the existence of -a non-Perl application, or some other dependency, it can be done as well. - -And you can adapt the dependencies based on the configuration of the -system. +Instead of using a magic POD format, the dependency specification is +implemented using the C<Makefile.PL> file, as you would with any other +module. This also means that if the Task needs to check for the existence +of a non-Perl application, or some other dependency, it can be done as +well; you can adapt dependencies based on the configuration of the system. For example, if a module is upgraded to repair a critical bug that applies -only for Windows platform, you can use two alternate versions based on +only to the Windows platform, you can use two alternate versions based on platform detection code, rather than needing to apply the highest version in all cases. -This "normal" implementation also means that C<Bundle::> modules can be created -privately and no longer need to be stored in CPAN, opening up the bundling -capability to companies and other non-public users. +This "normal" implementation also means that C<Bundle::> modules can be +created privately. They no longer need to be stored in CPAN, which opens +up the ability to bundle to companies and other non-public users. -You should also be able to do things like encode the full dependencies for -you web application as a private C<Task::> dist and send this tarball to the -hosting company. - -Their admin can then use the dist to install the required modules from CPAN -and you can be far more certain that the required modules have been -installed than in the traditional case. +It should also be possible to do things like I<e.g.> encode the full +dependencies for your web application as a private C<Task::> dist and send +this tarball to the hosting company. Their admin can then use the dist to +install the required modules from CPAN, making it far more certain that the +required modules have been installed. =head2 Implementation At this time the preferred implementation is done using L<Module::Install>. - -L<Module::Install> allows a much more simplified syntax, and bundles the -required "Do What I Mean" functionality in the distribution itself. +It allows a much more simplified syntax, and bundles the required "Do What +I Mean" functionality in the distribution itself. This bundling removes many assumptions on what may or may not be installed on the the destination system, as the installation logic can @@ -146,9 +149,8 @@ Please note that this L<Task> class provides no functionality in and of itself, and your C<Task::> distributions do not need to inherit from it. In general, you also should not need to provide any test scripts for your -C<Task::> distribution, although you may wish to add tests to validate the -correct installation if you wish (another option not available in C<Bundle::> -distributions). +C<Task::> distribution. You may wish to add tests to validate the correct +installation, another option not available in C<Bundle::> distributions. =head1 SUPPORT