Bug #39007 for podlators: suppress the POD ERRORS section

Fri Sep 05 02:20:42 2008 ntyni [...] iki.fi - Ticket created

Subject:

suppress the POD ERRORS section

Hi Russ, as reported by Enrico Zini in Debian bug #497866, it would be nice if pod2man could (optionally?) suppress the POD ERRORS section. See the Debian report for Enrico's reasoning. It looks like fiddling with Pod::Simple->no_errata_section() should work. Maybe the complain_stderr() method would be a better default? -- Niko

Fri Sep 05 03:08:56 2008 rra [...] stanford.edu - Correspondence added

Subject:	Re: [rt.cpan.org #39007] suppress the POD ERRORS section
Date:	Fri, 05 Sep 2008 00:08:36 -0700
To:	bug-podlators [...] rt.cpan.org
From:	Russ Allbery <rra [...] stanford.edu>

"ntyni@iki.fi via RT" <bug-podlators@rt.cpan.org> writes: Show quoted text

> as reported by Enrico Zini in Debian bug #497866, it would be nice if > pod2man could (optionally?) suppress the POD ERRORS section. See the > Debian report for Enrico's reasoning.

Show quoted text

> It looks like fiddling with Pod::Simple->no_errata_section() should > work. Maybe the complain_stderr() method would be a better default?

I can certainly do this optionally. Doing it intentionally means overriding the default for all other POD formatters and making Pod::Man work differently than all of the rest. I'm not sure that's a great idea... if this is bad behavior, shouldn't the default be changed in Pod::Simple instead? I don't think there's anything unique about Pod::Man that its default should be different than all other POD formatters. -- Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/>

Fri Sep 05 03:09:00 2008 The RT System itself - Status changed from 'new' to 'open'

Fri Sep 05 07:13:55 2008 ntyni [...] iki.fi - Correspondence added

Subject:	Re: [rt.cpan.org #39007] suppress the POD ERRORS section
Date:	Fri, 5 Sep 2008 14:12:05 +0300
To:	"rra [...] stanford.edu via RT" <bug-podlators [...] rt.cpan.org>
From:	Niko Tyni <ntyni [...] iki.fi>

On Fri, Sep 05, 2008 at 03:09:01AM -0400, rra@stanford.edu via RT wrote: Show quoted text

> <URL: http://rt.cpan.org/Ticket/Display.html?id=39007 > > > "ntyni@iki.fi via RT" <bug-podlators@rt.cpan.org> writes: >

> > as reported by Enrico Zini in Debian bug #497866, it would be nice if > > pod2man could (optionally?) suppress the POD ERRORS section. See the > > Debian report for Enrico's reasoning.

>

> > It looks like fiddling with Pod::Simple->no_errata_section() should > > work. Maybe the complain_stderr() method would be a better default?

> > I can certainly do this optionally. > > Doing it intentionally means overriding the default for all other POD > formatters and making Pod::Man work differently than all of the rest. > I'm not sure that's a great idea... if this is bad behavior, shouldn't the > default be changed in Pod::Simple instead? I don't think there's anything > unique about Pod::Man that its default should be different than all other > POD formatters.

I think the usage context is the key difference here: Pod::Simple and (to a lesser extent) Pod::Man are designed as a reusable libraries, so they really can't complain on stderr by default. IMO using the POD ERRORS section is fine for them. However, pod2man is a command line application, and stderr is the perfect way for it to signal problems. I think all pod2* applications should do that. I'd actually be OK with having both stderr and the errata section on by default, but Enrico clearly wouldn't (and I certainly agree that the errata section isn't particularly useful in a manpage inside a Debian binary package). One possible approach is to make the errata section configurable, default to the current behaviour and then try to get ExtUtils::MakeMaker, Module::Build and the like override the default. No idea if that would get accepted, though. -- Niko

Fri Sep 05 16:44:45 2008 rra [...] stanford.edu - Correspondence added

Subject:	Re: [rt.cpan.org #39007] suppress the POD ERRORS section
Date:	Fri, 05 Sep 2008 11:18:47 -0700
To:	bug-podlators [...] rt.cpan.org
From:	Russ Allbery <rra [...] stanford.edu>

"ntyni@iki.fi via RT" <bug-podlators@rt.cpan.org> writes: Show quoted text

> I think the usage context is the key difference here: Pod::Simple and > (to a lesser extent) Pod::Man are designed as a reusable libraries, > so they really can't complain on stderr by default. IMO using the POD > ERRORS section is fine for them. > > However, pod2man is a command line application, and stderr is the perfect > way for it to signal problems. I think all pod2* applications should > do that.

Oh, hey, you're right, that's a very good point. Show quoted text

> I'd actually be OK with having both stderr and the errata section on by > default, but Enrico clearly wouldn't (and I certainly agree that the > errata section isn't particularly useful in a manpage inside a Debian > binary package).

Yeah, I can see his point. It's not useful to the reader of the man page; they can't do anything to fix it. Show quoted text

> One possible approach is to make the errata section configurable, > default to the current behaviour and then try to get ExtUtils::MakeMaker, > Module::Build and the like override the default. No idea if that would > get accepted, though.

I think they would argue that's a weird place to change the default as well. I think the only concern would be that messages to stderr tend to get lost in large builds. I may query perl5-porters about this and see what their opinion is. -- Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/>

Fri Sep 05 17:03:07 2008 rra [...] stanford.edu - Correspondence added

Subject:	Re: [rt.cpan.org #39007] suppress the POD ERRORS section
Date:	Fri, 05 Sep 2008 11:18:47 -0700
To:	bug-podlators [...] rt.cpan.org
From:	Russ Allbery <rra [...] stanford.edu>

"ntyni@iki.fi via RT" <bug-podlators@rt.cpan.org> writes: Show quoted text

> I think the usage context is the key difference here: Pod::Simple and > (to a lesser extent) Pod::Man are designed as a reusable libraries, > so they really can't complain on stderr by default. IMO using the POD > ERRORS section is fine for them. > > However, pod2man is a command line application, and stderr is the perfect > way for it to signal problems. I think all pod2* applications should > do that.

Oh, hey, you're right, that's a very good point. Show quoted text

> I'd actually be OK with having both stderr and the errata section on by > default, but Enrico clearly wouldn't (and I certainly agree that the > errata section isn't particularly useful in a manpage inside a Debian > binary package).

Yeah, I can see his point. It's not useful to the reader of the man page; they can't do anything to fix it. Show quoted text

> One possible approach is to make the errata section configurable, > default to the current behaviour and then try to get ExtUtils::MakeMaker, > Module::Build and the like override the default. No idea if that would > get accepted, though.

I think they would argue that's a weird place to change the default as well. I think the only concern would be that messages to stderr tend to get lost in large builds. I may query perl5-porters about this and see what their opinion is. -- Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/>

Sun Sep 14 14:10:16 2008 rra [...] stanford.edu - Correspondence added

CC:	bug-podlators [...] rt.cpan.org
Subject:	[rt.cpan.org #39007] pod2man and POD ERRORS
Date:	Sun, 14 Sep 2008 11:10:03 -0700
To:	perl5-porters [...] perl.org, pod-people [...] perl.org
From:	Russ Allbery <rra [...] stanford.edu>

I've received a request to make pod2man report POD errors to stderr by default instead of adding a POD ERRORS section. I think it makes sense for the default for the modules be to document errors in the POD output, since libraries complaining to stderr is something that's often very annoying, but pod2man and pod2text as command-line tools don't have that problem. The primary argument for doing this is that POD errors are primarily of interest to the author of the POD, not to thte end-user, but the POD ERRORS section in an installed man page tells the user about things they can't do anything about. However, if pod2man complains to stderr, that's not particularly useful for perldoc. (It *does* match the standard behavior of the man program, but still.) I'm not sure what makes the most sense for perldoc to do. Does anyone have any opinions about this? I'll definitely add an option that controls where warnings go for pod2man, but I'm not sure if I should change the default to stderr instead of POD ERRORS. -- Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/>

Sat Sep 20 14:09:04 2008 RRA [...] cpan.org - Correspondence added

podlators 2.1.3 added a new option to pod2man and pod2text to suppress the POD ERRORS section. I've inquired on p5p whether the default should be changed as well.

Sat Sep 20 14:09:06 2008 RRA [...] cpan.org - Status changed from 'open' to 'resolved'

Mon Sep 22 19:40:29 2008 RRA [...] cpan.org - Fixed in 2.1.3 added

Sat May 21 09:58:05 2011 dom [...] cpan.org - Correspondence added

On Sat Sep 20 14:09:04 2008, RRA wrote: Show quoted text

> podlators 2.1.3 added a new option to pod2man and pod2text to suppress > the POD ERRORS section. I've inquired on p5p whether the default should > be changed as well.

There seemed to two responses in favour of such a change (one also suggesting that they should die in this case. Would it be appropriate to re-open this bug to track such a change? Thanks, Dominic.

Sat May 21 09:58:07 2011 The RT System itself - Status changed from 'resolved' to 'open'

Sat May 21 09:59:12 2011 dom [...] cpan.org - Correspondence added

On Sat May 21 09:58:05 2011, DOM wrote: Show quoted text

> On Sat Sep 20 14:09:04 2008, RRA wrote:

> > podlators 2.1.3 added a new option to pod2man and pod2text to suppress > > the POD ERRORS section. I've inquired on p5p whether the default should > > be changed as well.

> > There seemed to two responses in favour of such a change (one also > suggesting that they should die in this case. Would it be appropriate to > re-open this bug to track such a change?

Sorry, I should have included a reference to the replies: <http://www.nntp.perl.org/group/perl.perl5.porters/2008/09/msg139898.html>

Sat May 21 15:21:59 2011 rra [...] stanford.edu - Correspondence added

Subject:	Re: [rt.cpan.org #39007] suppress the POD ERRORS section
Date:	Sat, 21 May 2011 12:21:50 -0700
To:	bug-podlators [...] rt.cpan.org
From:	Russ Allbery <rra [...] stanford.edu>

"Dominic Hargreaves via RT" <bug-podlators@rt.cpan.org> writes: Show quoted text

> On Sat Sep 20 14:09:04 2008, RRA wrote:

Show quoted text

>> podlators 2.1.3 added a new option to pod2man and pod2text to suppress >> the POD ERRORS section. I've inquired on p5p whether the default should >> be changed as well.

Show quoted text

> There seemed to two responses in favour of such a change (one also > suggesting that they should die in this case. Would it be appropriate to > re-open this bug to track such a change?

Yes, please. I'm a bit behind on working on podlators, and that will ensure that I don't lose track of it. Looks like the default should be changed, and at least an option to just die should be added. -- Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/>

Wed Jan 02 13:25:54 2013 RRA [...] cpan.org - Fixed in 2.1.3 deleted

Sun Mar 10 19:45:44 2013 dom [...] cpan.org - Correspondence added

On Sat May 21 15:21:59 2011, rra@stanford.edu wrote: Show quoted text

> "Dominic Hargreaves via RT" <bug-podlators@rt.cpan.org> writes:

> > On Sat Sep 20 14:09:04 2008, RRA wrote:

>

> >> podlators 2.1.3 added a new option to pod2man and pod2text to

suppress Show quoted text

> >> the POD ERRORS section. I've inquired on p5p whether the default

should Show quoted text

> >> be changed as well.

>

> > There seemed to two responses in favour of such a change (one also > > suggesting that they should die in this case. Would it be

appropriate to Show quoted text

> > re-open this bug to track such a change?

> > Yes, please. I'm a bit behind on working on podlators, and that will > ensure that I don't lose track of it. Looks like the default should

be Show quoted text

> changed, and at least an option to just die should be added.

Regrettably I found I was unable to reopen this ticket in RT (I guess I found the same two years ago and forgot to comment to this effect...). I guess you can do so?

Sun Mar 10 19:46:20 2013 dom [...] cpan.org - Correspondence added

On Sun Mar 10 19:45:44 2013, DOM wrote: Show quoted text

> On Sat May 21 15:21:59 2011, rra@stanford.edu wrote:

> > "Dominic Hargreaves via RT" <bug-podlators@rt.cpan.org> writes:

> > > On Sat Sep 20 14:09:04 2008, RRA wrote:

> >

> > >> podlators 2.1.3 added a new option to pod2man and pod2text to

> suppress

> > >> the POD ERRORS section. I've inquired on p5p whether the default

> should

> > >> be changed as well.

> >

> > > There seemed to two responses in favour of such a change (one also > > > suggesting that they should die in this case. Would it be

> appropriate to

> > > re-open this bug to track such a change?

> > > > Yes, please. I'm a bit behind on working on podlators, and that

will Show quoted text

> > ensure that I don't lose track of it. Looks like the default should

> be

> > changed, and at least an option to just die should be added.

> > Regrettably I found I was unable to reopen this ticket in RT (I guess

I Show quoted text

> found the same two years ago and forgot to comment to this effect...).

I Show quoted text

> guess you can do so?

Er, no. The ticket re-opened itself. Sorry, it's been a long week...

Tue Mar 19 01:57:37 2013 rra [...] stanford.edu - Correspondence added

CC:	dom [...] cpan.org
Subject:	Re: [rt.cpan.org #39007] suppress the POD ERRORS section
Date:	Mon, 18 Mar 2013 22:57:24 -0700
To:	bug-podlators [...] rt.cpan.org
From:	Russ Allbery <rra [...] stanford.edu>

"Dominic Hargreaves via RT" <bug-podlators@rt.cpan.org> writes: Show quoted text

> Queue: podlators > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=39007 >

Show quoted text

> On Sat May 21 15:21:59 2011, rra@stanford.edu wrote:

>> "Dominic Hargreaves via RT" <bug-podlators@rt.cpan.org> writes:

>>> On Sat Sep 20 14:09:04 2008, RRA wrote:

Show quoted text

>>>> podlators 2.1.3 added a new option to pod2man and pod2text to suppress >>>> the POD ERRORS section. I've inquired on p5p whether the default should >>>> be changed as well.

Show quoted text

>>> There seemed to two responses in favour of such a change (one also >>> suggesting that they should die in this case. Would it be appropriate to >>> re-open this bug to track such a change?

Show quoted text

>> Yes, please. I'm a bit behind on working on podlators, and that will >> ensure that I don't lose track of it. Looks like the default should >> be changed, and at least an option to just die should be added.

Show quoted text

> Regrettably I found I was unable to reopen this ticket in RT (I guess I > found the same two years ago and forgot to comment to this effect...). I > guess you can do so?

Actually, in the meantime, I just implemented this. :) podlators 2.5.0 now has a new --errors option with values die, stderr, pod, and none that controls your preferred error handling mechanism. The default is actually die in pod2man (and output in Pod::Man); I'm seeing if I get too many complaints about that, and will downgrade to stderr in pod2man if I have to. -- Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/>

Sun Mar 24 07:53:29 2013 dom [...] earth.li - Correspondence added

CC:	bug-podlators [...] rt.cpan.org, dom [...] cpan.org
Subject:	Re: [rt.cpan.org #39007] suppress the POD ERRORS section
Date:	Sun, 24 Mar 2013 11:53:12 +0000
To:	Russ Allbery <rra [...] stanford.edu>
From:	Dominic Hargreaves <dom [...] earth.li>

On Mon, Mar 18, 2013 at 10:57:24PM -0700, Russ Allbery wrote: Show quoted text

> "Dominic Hargreaves via RT" <bug-podlators@rt.cpan.org> writes: >

> > Queue: podlators > > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=39007 >

>

> > On Sat May 21 15:21:59 2011, rra@stanford.edu wrote:

> >> "Dominic Hargreaves via RT" <bug-podlators@rt.cpan.org> writes:

> >>> On Sat Sep 20 14:09:04 2008, RRA wrote:

>

> >>>> podlators 2.1.3 added a new option to pod2man and pod2text to suppress > >>>> the POD ERRORS section. I've inquired on p5p whether the default should > >>>> be changed as well.

>

> >>> There seemed to two responses in favour of such a change (one also > >>> suggesting that they should die in this case. Would it be appropriate to > >>> re-open this bug to track such a change?

>

> >> Yes, please. I'm a bit behind on working on podlators, and that will > >> ensure that I don't lose track of it. Looks like the default should > >> be changed, and at least an option to just die should be added.

>

> > Regrettably I found I was unable to reopen this ticket in RT (I guess I > > found the same two years ago and forgot to comment to this effect...). I > > guess you can do so?

> > Actually, in the meantime, I just implemented this. :) podlators 2.5.0 > now has a new --errors option with values die, stderr, pod, and none that > controls your preferred error handling mechanism. The default is actually > die in pod2man (and output in Pod::Man); I'm seeing if I get too many > complaints about that, and will downgrade to stderr in pod2man if I have > to.

Thanks - that sounds perfect! Cheers, Dominic. -- Dominic Hargreaves | http://www.larted.org.uk/~dom/ PGP key 5178E2A5 from the.earth.li (keyserver,web,email)

Sun Sep 22 14:28:24 2013 RRA [...] cpan.org - Correspondence added

As of podlators 2.5.0, there is now support for configurable error handling, including die, stderr, pod, and none.

Sun Sep 22 14:28:25 2013 RRA [...] cpan.org - Status changed from 'open' to 'resolved'

Sun Sep 22 14:28:25 2013 RRA [...] cpan.org - Fixed in 2.5.0 added