Bug #15563 for ExtUtils-ModuleMaker: Discrepancy between documentation and results re author information

Sun Nov 06 08:39:43 2005 jkeenan [...] cpan.org - Ticket created

Subject:

Discrepancy between documentation and results re author information

The documentation for ExtUtils::ModuleMaker.pm (section USAGE; subsection "Use of Public Methods within a Perl Program/new/Arguments Related to the Module's Author") asserts that if the user elects *not* to provide values for attributes CPANID, WEBSITE and ORGANIZATION, "...then the line will not be added to the documentation." Visual inspection of lib/*.pm files created with modulemaker reveals that, in those circumstances, a line *is* added to the documentation, albeit an all-whitespace line. This should be fixed so that the author data contains no visually blank lines.

Sun Nov 06 09:58:41 2005 jkeenan [...] cpan.org - Correspondence added

From:

JKEENAN

[JKEENAN - Sun Nov 6 08:39:43 2005]: The situation is actually worse than described previously. The EU::MM::Initializers:: validate_values() method called within new() does a modest check on the well-formedness of CPANID and WEBSITE but dies if these are undefined. Since, per documentation, the user is not required to enter values for these attributes, these deaths are unnecessary.

Thu Dec 29 21:19:13 2005 jkeenan [...] cpan.org - Correspondence added 20 min

[JKEENAN - Sun Nov 6 09:58:41 2005]: Show quoted text

> [JKEENAN - Sun Nov 6 08:39:43 2005]: > > The situation is actually worse than described previously. The > EU::MM::Initializers:: > validate_values() method called within new() does a modest check on > the well-formedness of > CPANID and WEBSITE but dies if these are undefined. Since, per > documentation, the user is > not required to enter values for these attributes, these deaths are > unnecessary.

Whoops! I thought I had fixed it in 0.44 but I haven't. Try again.

Thu Dec 29 21:19:14 2005 jkeenan [...] cpan.org - Given to JKEENAN

Wed May 02 15:48:24 2018 jkeenan [...] cpan.org - Correspondence added

On Sun Nov 06 09:58:41 2005, JKEENAN wrote: Show quoted text

> [JKEENAN - Sun Nov 6 08:39:43 2005]: > > The situation is actually worse than described previously. The > EU::MM::Initializers:: > validate_values() method called within new() does a modest check on > the well-formedness of > CPANID and WEBSITE but dies if these are undefined. Since, per > documentation, the user is > not required to enter values for these attributes, these deaths are > unnecessary.

Seventeen-and-a-half years later ... I realize this comment is a red herring -- or at least somewhat pink. At the point in the EU::MM constructor where validate_values() is called, both CPANID and WEBSITE have been populated, at least with default values which are dummy copy. So in these two stanzas in validate_values(): ##### CPANID => [ q{CPAN IDs are 3-9 characters}, eval { $self->{CPANID} and $self->{CPANID} !~ m/^\w{3,9}$/; }, ], ... WEBSITE => [ q{WEBSITEs should start with an "http:" or "https:"}, eval { $self->{WEBSITE} and $self->{WEBSITE} !~ m{https?://.*}; }, ], ##### ... the first part of the 'and' condition will always be Perl-true -- which means only the second part of the 'and' condition affects validation. If a user supplies a value for EMAIL or WEBSITE which cannot pass these simple tests, then a swift death is in order.

Wed May 02 15:49:05 2018 jkeenan [...] cpan.org - Correspondence added

On Wed May 02 15:48:24 2018, JKEENAN wrote: Show quoted text

> On Sun Nov 06 09:58:41 2005, JKEENAN wrote:

> > [JKEENAN - Sun Nov 6 08:39:43 2005]: > > > > The situation is actually worse than described previously. The > > EU::MM::Initializers:: > > validate_values() method called within new() does a modest check on > > the well-formedness of > > CPANID and WEBSITE but dies if these are undefined. Since, per > > documentation, the user is > > not required to enter values for these attributes, these deaths are > > unnecessary.

> > Seventeen-and-a-half years later ... I realize this comment is a red > herring -- or at least somewhat pink.

Actually, only twelve-and-a-half years later! Show quoted text

> > At the point in the EU::MM constructor where validate_values() is > called, both CPANID and WEBSITE have been populated, at least with > default values which are dummy copy. So in these two stanzas in > validate_values(): > > ##### > CPANID => [ > q{CPAN IDs are 3-9 characters}, > eval { $self->{CPANID} and $self->{CPANID} !~ m/^\w{3,9}$/; }, > ], > ... > WEBSITE => [ > q{WEBSITEs should start with an "http:" or "https:"}, > eval { $self->{WEBSITE} and $self->{WEBSITE} !~ m{https?://.*}; }, > ], > ##### > > ... the first part of the 'and' condition will always be Perl-true -- > which means only the second part of the 'and' condition affects > validation. If a user supplies a value for EMAIL or WEBSITE which > cannot pass these simple tests, then a swift death is in order.

Wed May 02 16:15:36 2018 jkeenan [...] cpan.org - Correspondence added

On Sun Nov 06 08:39:43 2005, JKEENAN wrote: Show quoted text

> The documentation for ExtUtils::ModuleMaker.pm (section USAGE; > subsection "Use of Public Methods within a Perl Program/new/Arguments > Related to the Module's Author") asserts that if the user elects *not* > to provide values for attributes CPANID, WEBSITE and ORGANIZATION, > "...then the line will not be added to the documentation." Visual > inspection of lib/*.pm files created with modulemaker reveals that, in > those circumstances, a line *is* added to the documentation, albeit an > all-whitespace line. This should be fixed so that the author data > contains no visually blank lines.

Case 1: Each of CPANID, WEBSITE and ORGANIZATION is explicitly set to a Perl-false value. [modulemaker] 540 $ grep -A10 -E '^\$mod\s' rt-15563.pl $mod = ExtUtils::ModuleMaker->new( NAME => $module_name, COMPACT => 1, CPANID => 0, WEBSITE => 0, ORGANIZATION => 0, ); $mod->complete_build(); [modulemaker] 541 $ perl rt-15563.pl [modulemaker] 542 $ grep -A8 AUTHOR Foo-Bar/lib/Foo/Bar.pm =head1 AUTHOR A. U. Thor a.u.thor@a.galaxy.far.far.away =head1 COPYRIGHT This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ##### Result: CPANID, WEBSITE and ORGANIZATION are omitted, as intended, with no extra whitespace. ################### Case 2: At least one of CPANID, WEBSITE or ORGANIZATION is omitted. E.g., omit CPANID: [modulemaker] 543 $ grep -A10 -E '^\$mod\s' rt-15563.pl $mod = ExtUtils::ModuleMaker->new( NAME => $module_name, COMPACT => 1, WEBSITE => 0, ORGANIZATION => 0, ); $mod->complete_build(); __END__ [modulemaker] 544 $ perl rt-15563.pl [modulemaker] 545 $ grep -A8 AUTHOR Foo-Bar/lib/Foo/Bar.pm =head1 AUTHOR A. U. Thor CPAN ID: MODAUTHOR a.u.thor@a.galaxy.far.far.away =head1 COPYRIGHT This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the ##### Result: CPANID is populated from default values. WEBSITE and ORGANIZATION are omitted, as intended, with no extra whitespace. ###################

Subject:

rt-15563.pl

#!/usr/bin/env perl use 5.14.0; use warnings; use Data::Dumper;$Data::Dumper::Indent=1; use Data::Dump ( qw| dd pp| ); use Carp; use ExtUtils::ModuleMaker; use File::Path qw( rmtree ); my $mod; my @components = qw| Foo Bar |; my $module_name = join('::' => @components); my $dist_name = join('-' => @components); rmtree($dist_name) if (-d $dist_name); $mod = ExtUtils::ModuleMaker->new( NAME => $module_name, COMPACT => 1, CPANID => 0, WEBSITE => 0, ORGANIZATION => 0, ); $mod->complete_build(); __END__

Wed May 02 16:21:49 2018 jkeenan [...] cpan.org - Cc jkeenan@pobox.com added

Wed May 02 21:58:12 2018 jkeenan [...] cpan.org - Correspondence added

On Wed May 02 16:15:36 2018, JKEENAN wrote: Show quoted text

> On Sun Nov 06 08:39:43 2005, JKEENAN wrote:

> > The documentation for ExtUtils::ModuleMaker.pm (section USAGE; > > subsection "Use of Public Methods within a Perl Program/new/Arguments > > Related to the Module's Author") asserts that if the user elects > > *not* > > to provide values for attributes CPANID, WEBSITE and ORGANIZATION, > > "...then the line will not be added to the documentation." Visual > > inspection of lib/*.pm files created with modulemaker reveals that, > > in > > those circumstances, a line *is* added to the documentation, albeit > > an > > all-whitespace line. This should be fixed so that the author data > > contains no visually blank lines.

> > > Case 1: Each of CPANID, WEBSITE and ORGANIZATION is explicitly set to > a Perl-false value. > > [modulemaker] 540 $ grep -A10 -E '^\$mod\s' rt-15563.pl > $mod = ExtUtils::ModuleMaker->new( > NAME => $module_name, > COMPACT => 1, > CPANID => 0, > WEBSITE => 0, > ORGANIZATION => 0, > ); > > $mod->complete_build(); > > > [modulemaker] 541 $ perl rt-15563.pl > [modulemaker] 542 $ grep -A8 AUTHOR Foo-Bar/lib/Foo/Bar.pm > =head1 AUTHOR > > A. U. Thor > a.u.thor@a.galaxy.far.far.away > > =head1 COPYRIGHT > > This program is free software; you can redistribute > it and/or modify it under the same terms as Perl itself. > > ##### > > Result: CPANID, WEBSITE and ORGANIZATION are omitted, as intended, > with no extra whitespace. > > ################### > > Case 2: At least one of CPANID, WEBSITE or ORGANIZATION is omitted. > E.g., omit CPANID: > > [modulemaker] 543 $ grep -A10 -E '^\$mod\s' rt-15563.pl > $mod = ExtUtils::ModuleMaker->new( > NAME => $module_name, > COMPACT => 1, > WEBSITE => 0, > ORGANIZATION => 0, > ); > > $mod->complete_build(); > > > __END__ > [modulemaker] 544 $ perl rt-15563.pl > [modulemaker] 545 $ grep -A8 AUTHOR Foo-Bar/lib/Foo/Bar.pm > =head1 AUTHOR > > A. U. Thor > CPAN ID: MODAUTHOR > a.u.thor@a.galaxy.far.far.away > > =head1 COPYRIGHT > > This program is free software; you can redistribute > it and/or modify it under the same terms as Perl itself. > > The full text of the license can be found in the > > ##### > > Result: CPANID is populated from default values. WEBSITE and > ORGANIZATION are omitted, as intended, with no extra whitespace. > > ###################

What I'm probably going to do is to change the documentation to reflect the actual behavior, then add tests for that behavior. If someone (e.g., a business) really needed to suppress the output of those three lines on a regular basis, they would be better off subclassing ExtUtils::ModuleMaker (which is on my Todo list for my own use of this library).

Thu May 03 14:08:52 2018 jkeenan [...] cpan.org - Correspondence added

On Wed May 02 21:58:12 2018, JKEENAN wrote: Show quoted text

> On Wed May 02 16:15:36 2018, JKEENAN wrote:

> > On Sun Nov 06 08:39:43 2005, JKEENAN wrote:

> > > The documentation for ExtUtils::ModuleMaker.pm (section USAGE; > > > subsection "Use of Public Methods within a Perl > > > Program/new/Arguments > > > Related to the Module's Author") asserts that if the user elects > > > *not* > > > to provide values for attributes CPANID, WEBSITE and ORGANIZATION, > > > "...then the line will not be added to the documentation." Visual > > > inspection of lib/*.pm files created with modulemaker reveals that, > > > in > > > those circumstances, a line *is* added to the documentation, albeit > > > an > > > all-whitespace line. This should be fixed so that the author data > > > contains no visually blank lines.

> > > > > > Case 1: Each of CPANID, WEBSITE and ORGANIZATION is explicitly set to > > a Perl-false value. > > > > [modulemaker] 540 $ grep -A10 -E '^\$mod\s' rt-15563.pl > > $mod = ExtUtils::ModuleMaker->new( > > NAME => $module_name, > > COMPACT => 1, > > CPANID => 0, > > WEBSITE => 0, > > ORGANIZATION => 0, > > ); > > > > $mod->complete_build(); > > > > > > [modulemaker] 541 $ perl rt-15563.pl > > [modulemaker] 542 $ grep -A8 AUTHOR Foo-Bar/lib/Foo/Bar.pm > > =head1 AUTHOR > > > > A. U. Thor > > a.u.thor@a.galaxy.far.far.away > > > > =head1 COPYRIGHT > > > > This program is free software; you can redistribute > > it and/or modify it under the same terms as Perl itself. > > > > ##### > > > > Result: CPANID, WEBSITE and ORGANIZATION are omitted, as intended, > > with no extra whitespace. > > > > ################### > > > > Case 2: At least one of CPANID, WEBSITE or ORGANIZATION is omitted. > > E.g., omit CPANID: > > > > [modulemaker] 543 $ grep -A10 -E '^\$mod\s' rt-15563.pl > > $mod = ExtUtils::ModuleMaker->new( > > NAME => $module_name, > > COMPACT => 1, > > WEBSITE => 0, > > ORGANIZATION => 0, > > ); > > > > $mod->complete_build(); > > > > > > __END__ > > [modulemaker] 544 $ perl rt-15563.pl > > [modulemaker] 545 $ grep -A8 AUTHOR Foo-Bar/lib/Foo/Bar.pm > > =head1 AUTHOR > > > > A. U. Thor > > CPAN ID: MODAUTHOR > > a.u.thor@a.galaxy.far.far.away > > > > =head1 COPYRIGHT > > > > This program is free software; you can redistribute > > it and/or modify it under the same terms as Perl itself. > > > > The full text of the license can be found in the > > > > ##### > > > > Result: CPANID is populated from default values. WEBSITE and > > ORGANIZATION are omitted, as intended, with no extra whitespace. > > > > ###################

> > What I'm probably going to do is to change the documentation to > reflect the actual behavior, then add tests for that behavior. > > If someone (e.g., a business) really needed to suppress the output of > those three lines on a regular basis, they would be better off > subclassing ExtUtils::ModuleMaker (which is on my Todo list for my own > use of this library).

Addressed in: ##### commit e9e593bfd5ca81d2bb3275ddc37fb372fea3b844 Author: James E Keenan <jkeenan@cpan.org> AuthorDate: Thu May 3 09:25:20 2018 Commit: James E Keenan <jkeenan@cpan.org> CommitDate: Thu May 3 09:25:20 2018 Address rt.cpan.org #15563. Change documentation to describe existing behavior. Add block of tests to t/91_miscargs.t to demonstrate that behavior. ##### Will appear in the next CPAN release (not yet scheduled).

Thu May 03 14:09:40 2018 jkeenan [...] cpan.org - Status changed from 'new' to 'patched'

Sat May 05 19:13:28 2018 jkeenan [...] cpan.org - Status changed from 'patched' to 'resolved'

Sat May 05 19:13:28 2018 jkeenan [...] cpan.org - Fixed in 0.58 added