module-build-checkins

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

Update of /cvsroot/module-build/Module-Build/website
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv21842/website

Modified Files:
	META-spec.html META-spec.pod 
Log Message:
Transform 'index' into 'provides', and add a caveat about 'no_index'


Index: META-spec.html
===================================================================
RCS file: /cvsroot/module-build/Module-Build/website/META-spec.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- META-spec.html	26 Jul 2005 22:20:35 -0000	1.5
+++ META-spec.html	27 Jul 2005 04:07:55 -0000	1.6
@@ -35,15 +35,7 @@
 		<li><a href="#conflicts">conflicts</a></li>
 		<li><a href="#dynamic_config">dynamic_config</a></li>
 		<li><a href="#private">private</a></li>
-		<li><a href="#index">index</a></li>
-		<ul>
-
-			<li><a href="#file">file</a></li>
-			<li><a href="#dir">dir</a></li>
-			<li><a href="#package">package</a></li>
-			<li><a href="#namespace">namespace</a></li>
-		</ul>
-
+		<li><a href="#provides">provides</a></li>
 		<li><a href="#no_index">no_index</a></li>
 		<ul>
 
@@ -360,40 +352,32 @@
 <a href="#no_index">no_index</a>.  See below.</p>
 <p>
 </p>
-<h2><a name="index">index</a></h2>
+<h2><a name="provides">provides</a></h2>
 <p>Example:</p>
 <pre>
-  index:
-    file:
-    - My/Module.pm
-    dir:
-    - My/Private
-    package:
-    - My::Module::Stuff
-    namespace:
-    - My::Module::Stuff</pre>
-<p>(Spec 1.1) [optional] A YAML mapping that describes any files,
-directories, packages, and namespaces that are to be indexed. Anything
-that is not explicitly listed here will be ignored by most compliant
-searches and indexers.</p>
-<p>
-</p>
-<h3><a name="file">file</a></h3>
-<p>(Spec 1.1) [optional] Include any listed file(s).</p>
-<p>
-</p>
-<h3><a name="dir">dir</a></h3>
-<p>(Spec 1.1) [optional] Include everything below the listed
-directory(ies).</p>
-<p>
-</p>
-<h3><a name="package">package</a></h3>
-<p>(Spec 1.1) [optional] Include the listed package(s).</p>
-<p>
-</p>
-<h3><a name="namespace">namespace</a></h3>
-<p>(Spec 1.1) [optional] Includes everything below the listed namespace(s),
-but <em>not</em> the listed <code>namespace(s)</code> its self.</p>
+  provides:
+    Foo::Bar:
+      file: lib/Foo/Bar.pm
+      version: 0.27_02
+    Foo::Bar::Blah:
+      file: lib/Foo/Bar/Blah.pm
+    Foo::Bar::Baz:
+      file: lib/Foo/Bar/Baz.pm
+      version: 0.3</pre>
+<p>(Spec 1.1) [optional] A YAML mapping that describes all packages
+provided by this distribution.  This information can be (and, in some
+cases, is) used by distribution and automation mechanisms like PAUSE,
+CPAN, and search.cpan.org to build indexes saying in which
+distribution various packages can be found.</p>
+<p>When using tools like <code>Module::Build</code> that can generate the
+<code>provides</code> mapping for your distribution automatically, make sure you
+examine what it generates to make sure it makes sense - indexers will
+usually trust the <code>provides</code> field if it's present, rather than
+scanning through the distribution files themselves to figure out
+packages and versions.  This is a good thing, because it means you can
+use the <code>provides</code> field to tell the indexers precisely what you want
+indexed about your distribution, rather than relying on them to
+essentially guess what you want indexed.</p>
 <p>
 </p>
 <h2><a name="no_index">no_index</a></h2>
@@ -411,7 +395,11 @@
 <p>(Spec 1.1) [optional] A YAML mapping that describes any files,
 directories, packages, and namespaces that are private
 (i.e. implementation artifacts) that are not of interest to searching
-and indexing tools.</p>
+and indexing tools.  This is useful when no <code>provides</code> field is
+present.</p>
+<p><em>(Note: I'm not actually sure who looks at this field, or exactly
+what they do with it.  This spec could be off in some way from actual
+usage.)</em></p>
 <p>
 </p>
 <h3><a name="file">file</a></h3>

Index: META-spec.pod
===================================================================
RCS file: /cvsroot/module-build/Module-Build/website/META-spec.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- META-spec.pod	26 Jul 2005 22:20:36 -0000	1.2
+++ META-spec.pod	27 Jul 2005 04:07:55 -0000	1.3
@@ -321,42 +321,35 @@
 I<(Deprecated)> (Spec 1.0) [optional] This field has been renamed to
 L</"no_index">.  See below.
 
-=head2 index
+=head2 provides
 
 Example:
 
-  index:
-    file:
-    - My/Module.pm
-    dir:
-    - My/Private
-    package:
-    - My::Module::Stuff
-    namespace:
-    - My::Module::Stuff
-
-(Spec 1.1) [optional] A YAML mapping that describes any files,
-directories, packages, and namespaces that are to be indexed. Anything
-that is not explicitly listed here will be ignored by most compliant
-searches and indexers.
-
-=head3 file
-
-(Spec 1.1) [optional] Include any listed file(s).
-
-=head3 dir
-
-(Spec 1.1) [optional] Include everything below the listed
-directory(ies).
-
-=head3 package
-
-(Spec 1.1) [optional] Include the listed package(s).
+  provides:
+    Foo::Bar:
+      file: lib/Foo/Bar.pm
+      version: 0.27_02
+    Foo::Bar::Blah:
+      file: lib/Foo/Bar/Blah.pm
+    Foo::Bar::Baz:
+      file: lib/Foo/Bar/Baz.pm
+      version: 0.3
 
-=head3 namespace
+(Spec 1.1) [optional] A YAML mapping that describes all packages
+provided by this distribution.  This information can be (and, in some
+cases, is) used by distribution and automation mechanisms like PAUSE,
+CPAN, and search.cpan.org to build indexes saying in which
+distribution various packages can be found.
 
-(Spec 1.1) [optional] Includes everything below the listed namespace(s),
-but I<not> the listed namespace(s) its self.
+When using tools like C<Module::Build> that can generate the
+C<provides> mapping for your distribution automatically, make sure you
+examine what it generates to make sure it makes sense - indexers will
+usually trust the C<provides> field if it's present, rather than
+scanning through the distribution files themselves to figure out
+packages and versions.  This is a good thing, because it means you can
+use the C<provides> field to tell the indexers precisely what you want
+indexed about your distribution, rather than relying on them to
+essentially guess what you want indexed.
 
 =head2 no_index
 
@@ -375,7 +368,12 @@
 (Spec 1.1) [optional] A YAML mapping that describes any files,
 directories, packages, and namespaces that are private
 (i.e. implementation artifacts) that are not of interest to searching
-and indexing tools.
+and indexing tools.  This is useful when no C<provides> field is
+present.
+
+I<(Note: I'm not actually sure who looks at this field, or exactly
+what they do with it.  This spec could be off in some way from actual
+usage.)>
 
 =head3 file