[Module-build-checkins] Module-Build/lib/Module/Build Authoring.pod,1.18,1.19

[Ken W. <kwi...@us...>]

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()