module-build-general

[Module::Build] should Pod::Readme vs. Pod::Text for README creation be a feature?

[Yitzchak Scott-T. <sth...@ef...>]

Just as META.yml can be forced to build with or without YAML by setting
the YAML_feature, shouldn't README creation depend on a feature?

The other discrepancy is that Pod::Readme is recommended but YAML is
not; seems to me both or neither should be listed in recommends: in
META.yml.  Same with the other feature-enabling modules.  If not,
what are the criteria for what goes in recommends: and what doesn't?

Re: [Module::Build] should Pod::Readme vs. Pod::Text for README creation be a feature?

[Randy W. S. <ml...@th...>]

Yitzchak Scott-Thoennes wrote:
> Just as META.yml can be forced to build with or without YAML by setting
> the YAML_feature, shouldn't README creation depend on a feature?
> 
> The other discrepancy is that Pod::Readme is recommended but YAML is
> not; seems to me both or neither should be listed in recommends: in
> META.yml.  Same with the other feature-enabling modules.  If not,
> what are the criteria for what goes in recommends: and what doesn't?

The requirement for creating README can't be properly expressed with 
current limitations; It depends on (Pod::Readme || Pod::Text). The best 
we can do is recommend one or both.

Features wouldn't be appropriate in this case, because we still have to 
explicitly test for the presence of one or the other of the modules. We 
can't query ::ConfigData to determine what method to use.

Randy.


Hmm, only ~40 unread mails or mails marked for follow-up left in my 
Module::Build folder...

Re: [Module::Build] should Pod::Readme vs. Pod::Text for README creation be a feature?

[Yitzchak Scott-T. <sth...@ef...>]

On Sat, Mar 04, 2006 at 10:06:19PM -0500, Randy W. Sims wrote:
> Yitzchak Scott-Thoennes wrote:
> >Just as META.yml can be forced to build with or without YAML by setting
> >the YAML_feature, shouldn't README creation depend on a feature?
> >
> >The other discrepancy is that Pod::Readme is recommended but YAML is
> >not; seems to me both or neither should be listed in recommends: in
> >META.yml.  Same with the other feature-enabling modules.  If not,
> >what are the criteria for what goes in recommends: and what doesn't?
> 
> The requirement for creating README can't be properly expressed with 
> current limitations; It depends on (Pod::Readme || Pod::Text). The best 
> we can do is recommend one or both.

Pod::Text has been in the core since 5.002.  But even if it wasn't,
Pod::Readme makes a better README file; Pod::Text is just a fallback.
Hence the recommendation.

I see a parallel with YAML; YAML makes a better META.yml than the
fallback, so it should be recommended.

Re: [Module::Build] should Pod::Readme vs. Pod::Text for README creation be a feature?

[Randy W. S. <Ra...@Th...>]

Yitzchak Scott-Thoennes wrote:
> On Sat, Mar 04, 2006 at 10:06:19PM -0500, Randy W. Sims wrote:
> 
>>Yitzchak Scott-Thoennes wrote:
>>
>>>Just as META.yml can be forced to build with or without YAML by setting
>>>the YAML_feature, shouldn't README creation depend on a feature?
>>>
>>>The other discrepancy is that Pod::Readme is recommended but YAML is
>>>not; seems to me both or neither should be listed in recommends: in
>>>META.yml.  Same with the other feature-enabling modules.  If not,
>>>what are the criteria for what goes in recommends: and what doesn't?
>>
>>The requirement for creating README can't be properly expressed with 
>>current limitations; It depends on (Pod::Readme || Pod::Text). The best 
>>we can do is recommend one or both.
> 
> 
> Pod::Text has been in the core since 5.002.  But even if it wasn't,
> Pod::Readme makes a better README file; Pod::Text is just a fallback.
> Hence the recommendation.
> 
> I see a parallel with YAML; YAML makes a better META.yml than the
> fallback, so it should be recommended.

Sorry, I guess I forgot about Pod::Text being in core. I can see the 
parallel. Would the attached patch be ok?

Can I also suggest a slight rewording of the auto_features descriptions? 
( s/^Can (.)/\u$1/ )

@@ -51,28 +51,28 @@
     auto_features => {
  		     YAML_support =>
  		     {
-		      description => "Can write fully-functional META.yml files",
+		      description => "Write fully-functional META.yml files",
  		      requires => { YAML => ' >= 0.35, != 0.49_01 ' },
  		     },
  		     README_support =>
  		     {
-		      description => "Can write improved README files",
+		      description => "Write improved README files",
  		      requires => { 'Pod::Readme' => '0.04', },
  		     },
  		     C_support =>
  		     {
-		      description => "Can compile/link C & XS code",
+		      description => "Compile/link C & XS code",
  		      requires   => { 'ExtUtils::CBuilder' => 0.15, },
  		      recommends => { 'ExtUtils::ParseXS'  => 1.02, },
  		     },
  		     manpage_support =>
  		     {
-		      description => "Can create Unix man pages",
+		      description => "Create Unix man pages",
  		      requires => { 'Pod::Man' => 0 },
  		     },
  		     HTML_support =>
  		     {
-		      description => "Can create HTML documentation",
+		      description => "Create HTML documentation",
  		      requires => { 'Pod::Html' => 0 },
  		     },
  		    },

Re: [Module::Build] should Pod::Readme vs. Pod::Text for README creation be a feature?

[Yitzchak Scott-T. <sth...@ef...>]

On Sat, Mar 04, 2006 at 11:28:34PM -0500, Randy W. Sims wrote:
> Yitzchak Scott-Thoennes wrote:
> >On Sat, Mar 04, 2006 at 10:06:19PM -0500, Randy W. Sims wrote:
> >
> >>Yitzchak Scott-Thoennes wrote:
> >>
> >>>Just as META.yml can be forced to build with or without YAML by setting
> >>>the YAML_feature, shouldn't README creation depend on a feature?
> >>>
> >>>The other discrepancy is that Pod::Readme is recommended but YAML is
> >>>not; seems to me both or neither should be listed in recommends: in
> >>>META.yml.  Same with the other feature-enabling modules.  If not,
> >>>what are the criteria for what goes in recommends: and what doesn't?
> >>
> >>The requirement for creating README can't be properly expressed with 
> >>current limitations; It depends on (Pod::Readme || Pod::Text). The best 
> >>we can do is recommend one or both.
> >
> >
> >Pod::Text has been in the core since 5.002.  But even if it wasn't,
> >Pod::Readme makes a better README file; Pod::Text is just a fallback.
> >Hence the recommendation.
> >
> >I see a parallel with YAML; YAML makes a better META.yml than the
> >fallback, so it should be recommended.
> 
> Sorry, I guess I forgot about Pod::Text being in core. I can see the 
> parallel. Would the attached patch be ok?

I'd rather see YAML added to recommends than Pod::Readme removed.
Seems to me they both fit the mission statement of recommends.
(But I'm wishing more and more Module::Build had started out as
separate user and author distributions.)
 
> Can I also suggest a slight rewording of the auto_features descriptions? 
> ( s/^Can (.)/\u$1/ )

Fine with me.  I went to check how config_data displays these and was
a little surprised to see that it didn't.

Re: [Module::Build] should Pod::Readme vs. Pod::Text for README creation be a feature?

[Randy W. S. <ml...@th...>]

Yitzchak Scott-Thoennes wrote:
> On Sat, Mar 04, 2006 at 11:28:34PM -0500, Randy W. Sims wrote:
>> Yitzchak Scott-Thoennes wrote:
>>> On Sat, Mar 04, 2006 at 10:06:19PM -0500, Randy W. Sims wrote:
>>>
>>>> Yitzchak Scott-Thoennes wrote:
>>>>
>>>>> Just as META.yml can be forced to build with or without YAML by setting
>>>>> the YAML_feature, shouldn't README creation depend on a feature?
>>>>>
>>>>> The other discrepancy is that Pod::Readme is recommended but YAML is
>>>>> not; seems to me both or neither should be listed in recommends: in
>>>>> META.yml.  Same with the other feature-enabling modules.  If not,
>>>>> what are the criteria for what goes in recommends: and what doesn't?
>>>> The requirement for creating README can't be properly expressed with 
>>>> current limitations; It depends on (Pod::Readme || Pod::Text). The best 
>>>> we can do is recommend one or both.
>>>
>>> Pod::Text has been in the core since 5.002.  But even if it wasn't,
>>> Pod::Readme makes a better README file; Pod::Text is just a fallback.
>>> Hence the recommendation.
>>>
>>> I see a parallel with YAML; YAML makes a better META.yml than the
>>> fallback, so it should be recommended.
>> Sorry, I guess I forgot about Pod::Text being in core. I can see the 
>> parallel. Would the attached patch be ok?
> 
> I'd rather see YAML added to recommends than Pod::Readme removed.

That's not what you said in your initial mail: ;)

 >>>Yitzchak Scott-Thoennes wrote:
> Just as META.yml can be forced to build with or without YAML by setting
> the YAML_feature, shouldn't README creation depend on a feature?
<<<

> Seems to me they both fit the mission statement of recommends.

I guess it could go either way. I tend to favor features because it 
gives the author has a chance to describe to the user exactly what 
functionality is disabled because of which missing dependencies.

> (But I'm wishing more and more Module::Build had started out as
> separate user and author distributions.)

This has come up before, though it's been a while. And with some of the 
recent discussion, I've been thinking about more myself for the last 
week or so. It could be done I suppose, just installing stubs for the 
authoring actions that used the developer bundle if present or printed 
instructions if not. Maybe we can put this on the wish-list, at least 
for discussion, for 0.32 or so (after XS improvements & recursive builds).

>> Can I also suggest a slight rewording of the auto_features descriptions? 
>> ( s/^Can (.)/\u$1/ )
> 
> Fine with me.  I went to check how config_data displays these and was
> a little surprised to see that it didn't.

Yeah, I think this should go on the TODO list, unless someone wants to 
provide a patch?

Randy.

Re: [Module::Build] should Pod::Readme vs. Pod::Text for README creation be a feature?

[Yitzchak Scott-T. <sth...@ef...>]

On Mon, Mar 06, 2006 at 06:10:34PM -0500, Randy W. Sims wrote:
> Yitzchak Scott-Thoennes wrote:
> >I'd rather see YAML added to recommends than Pod::Readme removed.
> 
> That's not what you said in your initial mail: ;)
> 
> >>>Yitzchak Scott-Thoennes wrote:
> >Just as META.yml can be forced to build with or without YAML by setting
> >the YAML_feature, shouldn't README creation depend on a feature?
> <<<
> 
> >Seems to me they both fit the mission statement of recommends.
>  
> I guess it could go either way. I tend to favor features because it 
> gives the author has a chance to describe to the user exactly what 
> functionality is disabled because of which missing dependencies.

I don't see any problem with having both.  recommends is for build
tools to be able to suggest installing modules that allow the fullest
feature-set.  features allow an author to set their personal policy,
and have things croak if there are missing modules rather than falling
back to something less capable.