Skip Menu |

This queue is for tickets about the ExtUtils-MakeMaker CPAN distribution.

Report information
The Basics
Id: 101007
Status: rejected
Worked: 1.3 hours (80 min)
Priority: 0/
Queue: ExtUtils-MakeMaker

People
Owner: ETJ [...] cpan.org
Requestors: VDB [...] cpan.org
Cc:
AdminCc:

Bug Information
Severity: (no value)
Broken in:
  • 6.94
  • 7.04
Fixed in: (no value)



Subject: pod2man is applied to not filtered .pm file.
Probably it is not a bug but feature. In my .pm file I have to write version many times: 1. In POD. 2. To initialize @VERSION. 3. In use Inline. To avoid such duplication, I have used following trick: __VERSION__ is used in .pm file in place of version number; MakeMaker's PM_FILTER is used to replace the placeholder with actual version. Everything works well, but man page is created from source, not filtered .pm file. So, my questions are: 1. Is any reason to use (for any purpose) non-filtered .pm file? 2. Could MakeMaker be fixed to apply pod2man to .pm file located under blib. e. g. filtered .pm file?
Are you generating the .pm under blib? The idiomatic thing to do is generate in its normal location, and then EUMM will install it under blib and pod2man it as normal. Please give us a bit of code that actually demonstrates the problem.
On Fri Dec 19 11:28:56 2014, ETJ wrote: Show quoted text
> Are you generating the .pm under blib? The idiomatic thing to do is > generate in its normal location, and then EUMM will install it under > blib and pod2man it as normal. > > Please give us a bit of code that actually demonstrates the problem.
Ok, here is a beginning of Systend::Daemon.pm: Show quoted text
> package Systemd::Daemon; > > =head1 NAME > > Systemd::Daemon — ... > > =head1 VERSION > > Version __VERSION__. > > =cut > > our $VERSION = '__VERSION__'; > > use Inline > C => 'DATA', > name => __PACKAGE__, > version => '__VERSION__'; > > Inline->init(); > > ...
Here is a part of Makefile.PL: Show quoted text
> my $version = '0.01'; > WriteMakefile( > NAME => 'Systemd::Daemon', > VERSION => $version, > PM_FILTER => "$^X -p -e \"s{__VERSION__}{$version}g;\"",
Tests 00-load.t (generated by module-starter): Show quoted text
> #!perl -T > use 5.006; > use strict; > use warnings FATAL => 'all'; > use Test::More; > plan tests => 1; > BEGIN { > use_ok( 'Systemd::Daemon' ) || print "Bail out!\n"; > } > diag( "Testing Systemd::Daemon $Systemd::Daemon::VERSION, Perl $], $^X" );
prints version 0.01, as expected: Show quoted text
> $ make test TEST_FILES='t/00-load.t' > PERL_DL_NONLAZY=1 "/usr/bin/perl" "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/00-load.t > t/00-load.t .. 1/? # Testing Systemd::Daemon 0.01, Perl 5.018004, /usr/bin/perl > t/00-load.t .. ok > All tests successful. > Files=1, Tests=1, 0 wallclock secs ( 0.03 usr 0.00 sys + 0.07 cusr 0.01 csys = 0.11 CPU) > Result: PASS
But man page: Show quoted text
> $ man blib/man3/Systemd\:\:Daemon.3pm > > Systemd::Daemon(3) User Contributed Perl Documentation > > NAME > Systemd::Daemon - ... > > VERSION > Version __VERSION__. > ...
I'm not asking for excerpts from your files; don't worry, I believe this is happening. What I'm asking for is a highly cut-down minimal set of files I can put on my hard disk and see this problem happening. Please construct that.
On Fri Dec 19 12:17:53 2014, ETJ wrote: Show quoted text
> What I'm asking for is a highly cut-down minimal set of files I can > put on my hard disk and see this problem happening. Please construct > that.
Ok, attached. It is not minimal but quite small — a module newly created with module-starter with minimal changes to show the problem. To reproduce: Show quoted text
> $ perl Makefile.PL > $ make
Everything is ok but man page.
Subject: Foo-0.01.tar.gz
Download Foo-0.01.tar.gz
application/x-gzip 3.9k

Message body not shown because it is not plain text.

FYI this (see attachment) is what a minimal set of files looks like. More to follow. Makefile.PL: use ExtUtils::MakeMaker; my $version = '0.02'; WriteMakefile( NAME => 'Foo', VERSION => $version, PM_FILTER => "$^X -p -e \"s/__VERSION__/$version/g\"", ); Foo.pm: package Foo; =head1 NAME Foo - The great new Foo! =head1 VERSION Version __VERSION__ =cut 1;
Subject: Foo-0.02.tar.gz
Download Foo-0.02.tar.gz
application/x-gzip 418b

Message body not shown because it is not plain text.

The correct solution for this is to use *.PL files. See attachment and below. As you will have noticed in the output of make, PM_FILTER filters straight into blib/lib/*. Not very surprisingly, pod2man works out of the lib etc files, as does metacpan. You will see your module on metacpan showing the POD without any processing. The way to get your version number showing in your POD is to generate it using a tool, of which there are a number these days. I am marking this as rejected but if you think the docs should reflect this problem and/or solution, please follow up on this ticket with suggested text and I will look at getting it incorporated, since I was only shown this myself recently. Makefile.PL: use ExtUtils::MakeMaker; require 'common.pl'; my $version = get_version(); my @pms = qw(Foo.pm); WriteMakefile( NAME => 'Foo', VERSION => $version, PL_FILES => { map { ("$_.PL" => $_) } @pms }, PM => { map { ("$_" => "\$(INST_LIB)/$_") } @pms }, clean => { FILES => join ' ', @pms }, ); common.pl: sub get_version { '0.03' } sub process { my $v = get_version(); s/__VERSION__/$v/g; } 1; Foo.pm.PL: #!perl -w require 'common.pl'; $_ = join '', <DATA>; process(); my $file = shift; open my $fh, '>', $file or die "$file: $!"; print $fh $_; __DATA__ package Foo; =head1 NAME Foo - The great new Foo! =head1 VERSION Version __VERSION__ =cut 1;
Subject: Foo-0.03.tar.gz
Download Foo-0.03.tar.gz
application/x-gzip 634b

Message body not shown because it is not plain text.

You may also be interested to know that I have submitted this code as a doc PR: https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker/pull/185
On Thu Dec 25 18:03:45 2014, ETJ wrote: Show quoted text
> You may also be interested to know that I have submitted this code as > a doc PR: https://github.com/Perl-Toolchain-Gang/ExtUtils- > MakeMaker/pull/185
Thanks for example. Using PL files has great power, but I think this method is too complicated for such a simple task. In order to preprocess POD a module author have: 1. Introduce common.pl file. 2. Introduce Foo.pm.PL file. 3. Add a bunch of lines to Makefile.PL file. Compare: Using PM_FILTER requires one or two lines of code. We already have notion of "filtering". Preprocessing POD embedded into Foo.pm is perfect example of filtering. All we (I) need is a minor fix: when generating man pages, take pm from blib/ directory. That's all.