Skip Menu |

Preferred bug tracker

Please visit the preferred bug tracker to report your issue.

This queue is for tickets about the Perl-Critic CPAN distribution.

Report information
The Basics
Id: 56615
Status: open
Priority: 0/
Queue: Perl-Critic
People
Owner: Nobody in particular
Requestors: JARIAALTO [...] cpan.org
Cc:
AdminCc:
Bug Information
Severity: Wishlist
Broken in: (no value)
Fixed in: (no value)

History Show all quoted text
  Thu Apr 15 02:54:20 2010 JARIAALTO [...] cpan.org - Ticket created
Subject: POD manual page: Add POSIX compliant checks
The POSIX standard defines format of the manual pages: http://www.opengroup.org/onlinepubs/009695399/utilities/ xcu_chap01.html#tag_01_11 The current Perl::Critic does not include Posix convention checks. SUGGESTION 1) Examine the POSIX standard and require a minimal set of typical sections to appear in the page. Here is a brief list of suggested ones (r=required, o=optional): NAME r, SYNOPSIS r, DESCRIPTION r, OPTIONS r, INPUT FILES o, ENVIRONMENT VARIABLES r, OUTPUT FILES o, EXIT STATUS o, EXAMPLES r, SEE ALSO r * Require that these sections appear in this order presented. * Complain loudly about any missing required section * Complain less loudly about optional sections. * Mark these lint messages with a [POSIX] tag or something. * Add some option to enable Posix checks: --posix or similar 2) Mark the other POD lint messages with a separate tag, like [PERL], to differentiate them from the POSIX checks. Examples: Missing "USAGE" section in POD at line 1, column 1. See pages 133,138 of PBP. Severity: 2 Missing "REQUIRED ARGUMENTS" section in POD at line 1, column 1. See pages 133,138 of PBP. Severity: 2 Missing "DIAGNOSTICS" section in POD at line 1, column 1. See pages 133,138 of PBP. Severity: 2 Missing "EXIT STATUS" section in POD at line 1, column 1. See pages 133,138 of PBP. Severity: 2 Missing "CONFIGURATION" section in POD at line 1, column 1. See pages 133,138 of PBP. Severity: 2 Missing "DEPENDENCIES" section in POD at line 1, column 1. See pages 133,138 of PBP. Severity: 2 Missing "INCOMPATIBILITIES" section in POD at line 1, column 1. See pages 133,138 of PBP. Severity: 2 Missing "BUGS AND LIMITATIONS" section in POD at line 1, column 1. See pages 133,138 of PBP. Severity: 2 Missing "AUTHOR" section in POD at line 1, column 1. See pages 133,138 of PBP. Severity: 2 Missing "LICENSE AND COPYRIGHT" section in POD at line 1, column 1. See pages 133,138 of PBP. Severity: 2
  Thu Apr 15 09:01:35 2010 perl [...] galumph.com - Correspondence added
Subject: Re: [rt.cpan.org #56615] POD manual page: Add POSIX compliant checks
Date: Thu, 15 Apr 2010 08:01:19 -0500
To: bug-Perl-Critic [...] rt.cpan.org
From: Elliot Shank <perl [...] galumph.com>
On 4/15/10 1:54 AM, Jari Aalto via RT wrote: Show quoted text
> The POSIX standard defines format of the manual pages: > > http://www.opengroup.org/onlinepubs/009695399/utilities/ > xcu_chap01.html#tag_01_11 > > The current Perl::Critic does not include Posix convention checks.
You can configure Documentation::PodSpelling to require these if you want. Perl runs in non-POSIX environments, so isn't bound by such things.
  Thu Apr 15 09:01:36 2010 The RT System itself - Status changed from 'new' to 'open'
  Thu Apr 15 09:25:34 2010 JARIAALTO [...] cpan.org - Correspondence added
On Thu Apr 15 09:01:35 2010, clonezone wrote: Show quoted text
> On 4/15/10 1:54 AM, Jari Aalto via RT wrote:
> > The POSIX standard defines format of the manual pages: > > > > http://www.opengroup.org/onlinepubs/009695399/utilities/ > > xcu_chap01.html#tag_01_11 > > > > The current Perl::Critic does not include Posix convention checks.
> > You can configure Documentation::PodSpelling to require these if you > want. Perl runs in non-POSIX environments, so isn't bound by such > things.
The bug has nothing to do with "running on POSIX", but about how the manual page sections is customarily laid out: what section names to use and in with what order they appear. There is a standard how to make manual pages by the POSIX organization. What Perl::Critic is suggesting is not in line with it. Now, to make this clear, I'm not suggesting to complying to all the sections expressed in the standard, but to the minimal set that are the most common (as suggested) in the bug. Having a uniform standard for all programs, Perl included, is a goal that should be encouraged. I hope to see Perl::Critic to improve towards it. I hope Perl::Critic would not call for making a "new standard" and people believing in it.
  Wed Apr 21 21:35:49 2010 perl [...] galumph.com - Correspondence added
Subject: Re: [rt.cpan.org #56615] POD manual page: Add POSIX compliant checks
Date: Wed, 21 Apr 2010 20:35:35 -0500
To: bug-Perl-Critic [...] rt.cpan.org
From: Elliot Shank <perl [...] galumph.com>
On 4/15/10 8:25 AM, Jari Aalto via RT wrote: Show quoted text
> There is a standard how to make manual pages by the POSIX organization. > > What Perl::Critic is suggesting is not in line with it.
This policy was not intended to address POSIX in any way. It is based upon PBP and what it says. Show quoted text
> I hope Perl::Critic would not call for making a "new standard" and > people believing in it.
It follows the standard as specified by PBP.
  Wed Apr 21 21:36:31 2010 ELLIOTJS [...] cpan.org - Status changed from 'open' to 'rejected'
  Wed Apr 28 12:05:13 2010 JARIAALTO [...] cpan.org - Correspondence added
On Wed Apr 21 21:35:49 2010, clonezone wrote: Show quoted text
> On 4/15/10 8:25 AM, Jari Aalto via RT wrote:
> > There is a standard how to make manual pages by the POSIX
> organization.
> > > > What Perl::Critic is suggesting is not in line with it.
> > This policy was not intended to address POSIX in any way. It is based > upon PBP and what it says.
What happened to this? "....Perl::Critic is distributed with a number of Perl::Critic::Policy modules that attempt to enforce *various* *coding* *guidelines* ..." The description goes on saying that "most" are based on PBP. It would be pity if there will never be nothing else than PBP. Show quoted text
> > I hope Perl::Critic would not call for making a "new standard" and > > people believing in it.
> > It follows the standard as specified by PBP.
You mean book? being existed only a short time (pub. 2005), that's hardly a standard. N more than hundreds of other style books and internet pages out there. For manual pages, POSIX has been, is, and continue to be. Jari
  Wed Apr 28 12:05:15 2010 The RT System itself - Status changed from 'rejected' to 'open'
  Wed Apr 28 20:29:54 2010 perl [...] galumph.com - Correspondence added
Subject: Re: [rt.cpan.org #56615] POD manual page: Add POSIX compliant checks
Date: Wed, 28 Apr 2010 19:29:41 -0500
To: bug-Perl-Critic [...] rt.cpan.org
From: Elliot Shank <perl [...] galumph.com>
On 4/28/10 11:05 AM, Jari Aalto via RT wrote: Show quoted text
> What happened to this? > > "....Perl::Critic is distributed with a number of Perl::Critic::Policy > modules that attempt to enforce *various* *coding* *guidelines* ..." > > The description goes on saying that "most" are based on PBP. It would be > pity if there will never be nothing else than PBP.
There's nothing stopping you from configuring this policy to require the sections you want. Show quoted text
> For manual pages, POSIX has been, is, and continue to be.
What about Perl programmers who use MS Windows who don't even have a man page reader. Not to mention that most module documentation on the CPAN does not follow the POSIX standard. Even if I did agree with you, I wouldn't change the policy in such a way that it suddenly started complaining about documentation that it hadn't complained about before.