Skip Menu |

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

Report information
The Basics
Id: 98369
Status: open
Priority: 0/
Queue: ExtUtils-MakeMaker

People
Owner: Nobody in particular
Requestors: intrigeri [...] boum.org
Cc: RRA [...] cpan.org
AdminCc:

Bug Information
Severity: Normal
Broken in: (no value)
Fixed in: (no value)



Subject: Builds empty manpages
Hi, while packaging 0.39 for Debian, one of our QA tools (Lintian) warned me that a few empty manpages are generated, namely: MooseX::Declare::Context::WithOptions.3pm.gz MooseX::Declare::StackItem.3pm.gz MooseX::Declare::Syntax::MethodDeclaration::Parameterized.3pm.gz Maybe the manpages generation process should skip modules without POD? Alternatively, POD could be added to the corresponding modules. Cheers!
On 2014-08-27 14:52:05, intrigeri@boum.org wrote: Show quoted text
> Maybe the manpages generation process should skip modules without POD?
I agree. Since pod2man is responsible for generating the manpages, I have moved this ticket to that queue.
Subject: Re: [rt.cpan.org #98369] Builds empty manpages
Date: Thu, 28 Aug 2014 11:36:56 -0700
To: bug-podlators [...] rt.cpan.org
From: Russ Allbery <rra [...] cpan.org>
"Karen Etheridge via RT" <bug-podlators@rt.cpan.org> writes: Show quoted text
> Queue: podlators > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=98369 >
Show quoted text
> On 2014-08-27 14:52:05, intrigeri@boum.org wrote:
Show quoted text
>> Maybe the manpages generation process should skip modules without POD?
Show quoted text
> I agree. Since pod2man is responsible for generating the manpages, I > have moved this ticket to that queue.
I'm not sure if pod2man can do anything about this. It just generates a man page for the file it was told to generate. If there's no POD in that file, I think something else in the build system should avoid passing it to pod2man in the first place. That said, I'll take a closer look. There is some special handling in Pod::Simple and Pod::Man already for files that contain no POD. -- #!/usr/bin/perl -- Russ Allbery, Just Another Perl Hacker $^=q;@!>~|{>krw>yn{u<$$<[~||<Juukn{=,<S~|}<Jwx}qn{<Yn{u<Qjltn{ > 0gFzD gD, 00Fz, 0,,( 0hF 0g)F/=, 0> "L$/GEIFewe{,$/ 0C$~> "@=,m,|,(e 0.), 01,pnn,y{ rw} >;,$0=q,$,,($_=$^)=~y,$/ C-~><@=\n\r,-~$:-u/ #y,d,s,(\$.),$1,gee,print
On 2014-08-28 11:22:21, ETHER wrote: Show quoted text
> On 2014-08-27 14:52:05, intrigeri@boum.org wrote: >
> > Maybe the manpages generation process should skip modules without > > POD?
> > I agree. Since pod2man is responsible for generating the manpages, I > have moved this ticket to that queue.
13:20 < mohawk> philosophically i say EUMM shouldn't care about whether scripts/modules have POD 11:21 <@ether> yes, I agree. I'll move that ticket to the podlators queue. 11:21 < mohawk> ok 11:21 < mohawk> there's an immediate option, to write a bit of POD for those pages 11:23 <@ether> nope. those are internal modules, so they shouldn't be documented. 11:26 <@haarg> mohawk: what should be responsible for that then? 11:27 <@ether> either EUMM only calls pod2man for modules that have pod, or pod2man should handle podless modules and not generate manpages for them. 11:27 <@ether> the latter sounds a lot simpler 11:28 <@ether> asking EUMM to crack open the module and look for pod is beyond its call of duty I think 11:28 <@ether> although it's not hard to do, given Module::Metadata. 11:28 <@haarg> eumm calls pod2man for each file. having pod2man not generate a man file when asked to seem off. 11:28 < mohawk> haarg, down that road asks for EUMM to also syntax- and spell-check all the perl in there 11:29 <@haarg> no it doesn't 11:29 < mohawk> and maybe commentate on the english style of the docs 11:29 <@haarg> what the fuck? 11:29 <@ether> mohawk: you're over-reaching 11:29 < mohawk> i'm satirising 11:29 <@haarg> pod2man is a command 11:30 < mohawk> yes, we agree on that 11:30 <@haarg> if you call it on a file, i would expect it to produce a man file 11:31 < mohawk> and an empty one is aok? 11:31 < mohawk> no pod -> ...? 11:31 <@haarg> an empty file is valid pod 11:31 <@haarg> so yes 11:31 < mohawk> from a user perspective, that seems untidy 11:32 <@ether> if it's a lot easier for pod2man to see there's no pod, then it could have an option: --no-file-if-no-pod 11:32 <@ether> which EUMM could use. 11:32 < mohawk> if i go "man Module" and it tells me "no man page found", that's correct 11:32 < mohawk> (if there's no docs in it) 11:33 <@haarg> exiting with an error would also be a reasonable behavior 11:33 < mohawk> so the make stops 11:34 <@haarg> i'm telling you what i think is reasonable behavior for a pod2man command
It's also worth clarifying that the pod2man used by EUMM is not the standard pod2man command. It has its own implementation using the Pod::Man API.
RT-Send-CC: RRA [...] cpan.org
On 2014-08-28 11:37:08, RRA wrote: Show quoted text
> I'm not sure if pod2man can do anything about this. It just generates a > man page for the file it was told to generate. If there's no POD in that > file, I think something else in the build system should avoid passing it > to pod2man in the first place.
Right, it might be easier for ExtUtils::MakeMaker to first determine which files have pod, and not call pod2man for them.
Subject: Builds empty manpages for modules without POD
pod2man has support for deleting the output file if the POD document turned out to be contentless, but it's done in pod2man, not Pod::Man. I believe that's the correct place to do this given the Pod::Man API; I don't think Pod::Man should be deleting files out from under the caller, and if the caller wants to generate a man page from an empty file and is using the Pod::Man API directly, that's their choice. I'm therefore reassigning this to ExtUtils::MakeMaker, which needs to either use the pod2man driver script or needs to duplicate whatever functionality of it is desirable if it wants to call Pod::Man directly.
Subject: Re: [rt.cpan.org #98369] Builds empty manpages for modules without POD
Date: Fri, 05 Sep 2014 09:30:21 -0700
To: bug-ExtUtils-MakeMaker [...] rt.cpan.org
From: Michael G Schwern <schwern [...] pobox.com>
In general, there should be no functionality in a program which is not window-dressing over an API call. If pod2man has a "delete empty man page after generation" option, Pod::Man should do it, too. Programs are hard to use by other programs and they are difficult to test. Whether it's on by default is another matter, programs and APIs have different use cases. I would suggest... * The functionality be added to Pod::Man as an option to new(). * pod2man changed to use that option. * MakeMaker (and Module::Build) pass the option to Pod::Man->new. This improves the functionality of Pod::Man for all, avoids duplicating code in MakeMaker (and everywhere else) and removes the last piece of functional code from pod2man making it purely a command line wrapper.
CC: intrigeri [...] boum.org
Subject: Re: [rt.cpan.org #98369] Builds empty manpages for modules without POD
Date: Fri, 05 Sep 2014 15:32:47 -0700
To: bug-ExtUtils-MakeMaker [...] rt.cpan.org
From: Russ Allbery <rra [...] cpan.org>
"Michael G Schwern via RT" <bug-ExtUtils-MakeMaker@rt.cpan.org> writes: Show quoted text
> In general, there should be no functionality in a program which is not > window-dressing over an API call. If pod2man has a "delete empty man > page after generation" option, Pod::Man should do it, too. Programs are > hard to use by other programs and they are difficult to test.
Show quoted text
> Whether it's on by default is another matter, programs and APIs have > different use cases.
Show quoted text
> I would suggest...
Show quoted text
> * The functionality be added to Pod::Man as an option to new(). > * pod2man changed to use that option. > * MakeMaker (and Module::Build) pass the option to Pod::Man->new.
Show quoted text
> This improves the functionality of Pod::Man for all, avoids duplicating > code in MakeMaker (and everywhere else) and removes the last piece of > functional code from pod2man making it purely a command line wrapper.
Yeah, that's a reasonable way to approach the problem. Will do, although it's going to get blocked on the other things that need to go into the next release, so it may be a while before it makes it into a released version. -- #!/usr/bin/perl -- Russ Allbery, Just Another Perl Hacker $^=q;@!>~|{>krw>yn{u<$$<[~||<Juukn{=,<S~|}<Jwx}qn{<Yn{u<Qjltn{ > 0gFzD gD, 00Fz, 0,,( 0hF 0g)F/=, 0> "L$/GEIFewe{,$/ 0C$~> "@=,m,|,(e 0.), 01,pnn,y{ rw} >;,$0=q,$,,($_=$^)=~y,$/ C-~><@=\n\r,-~$:-u/ #y,d,s,(\$.),$1,gee,print
RT-Send-CC: haarg [...] cpan.org, ether [...] cpan.org
Coming from the EUMM side, would this be considered resolved (in the absence of "don't make empty file" functionality) if this were added to the pod2man EU::Command::MM::pod2man (after the real Pod::Man does its thing): if (-e $man and !-s $man) { unlink $man; next; } # do normal thing otherwise