Update of /cvsroot/module-build/Module-Build/lib/Module/Build
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv8587/lib/Module/Build
Modified Files:
Authoring.pod
Log Message:
Tweaks to dispatch() and depends_on() docs
Index: Authoring.pod
===================================================================
RCS file: /cvsroot/module-build/Module-Build/lib/Module/Build/Authoring.pod,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -d -r1.18 -r1.19
--- Authoring.pod 3 Nov 2005 01:15:16 -0000 1.18
+++ Authoring.pod 5 Nov 2005 15:48:55 -0000 1.19
@@ -929,12 +929,19 @@
Invokes the named action or list of actions in sequence. Using this
method is preferred to calling the action explicitly because it
performs some internal record-keeping, and it ensures that the same
-action is not invoked multiple times.
+action is not invoked multiple times (note: in future versions of
+Module::Build it's conceivable that this run-only-once mechanism will
+be changed to something more intelligent).
-This method is intended to be used by Module::Build subclasses when
-defining custom actions that depend on other sub-actions. If you need
-to invoke an action outside of the build process, see L<dispatch>
-below.
+Note that the name of this method is something of a misnomer; it
+should really be called something like
+C<invoke_actions_unless_already_invoked()> or something, but for
+better or worse (perhaps better!) we were still thinking in
+C<make>-like dependency terms when we created this method.
+
+See also C<dispatch()>. The main distinction between the two is that
+C<depends_on()> is meant to call an action from inside another action,
+whereas C<dispatch()> is meant to set the very top action in motion.
=item dir_contains($first_dir, $second_dir)
@@ -955,15 +962,12 @@
$mb->dispatch('foo', verbose => 1, args => { my_option => 'value' });
This method is intended to be used to programmatically invoke build
-actions. I.e. It's primarily to be used by applications controlling
-Module::Build based builds rather than by subclasses. If you need to
-invoke an action from within a F<Build.PL> script or a subclass, see
-L<depends_on> above.
+actions, e.g. by applications controlling Module::Build-based builds
+rather than by subclasses.
-Unlike C<< depends_on() >>, this method resets the list of previously
-invoked actions, so actions in a previous C<< dispatch() >> call will
-be invoked again in subsequent calls. However, within a single call
-actions are still run only a single time.
+See also C<depends_on()>. The main distinction between the two is that
+C<depends_on()> is meant to call an action from inside another action,
+whereas C<dispatch()> is meant to set the very top action in motion.
=item dist_dir()
|
