[Module-build-checkins] Module-Build/website META-spec.html,1.5,1.6 META-spec.pod,1.2,1.3
Status: Beta
Brought to you by:
kwilliams
Menu
▾
▴
[Module-build-checkins] Module-Build/website META-spec.html,1.5,1.6 META-spec.pod,1.2,1.3
|
From: Ken W. <kwi...@us...> - 2005-07-27 04:08:20
|
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 |
