Bug #57176 for Pod-Parser: Pod::Checker requires a comma or dash to recognize NAME

Mon May 03 13:51:49 2010 khw [...] cpan.org - Ticket created

Subject:

Pod::Checker requires a comma or dash to recognize NAME

The attached file when parsed by Pod::Checker does not extract the name. Checker is expecting something of the form: =head1 NAME FOO - bar And this file, which is an official one, only has FOO for the name, without a hyphen and explanatory text. Running perldoc on the file does extract the name. I care because I'm changing the Perl 5 podcheck.t test, and I need the names of such modules, which are included in the 5.12 distribution. The line that matters is 1232. I'd change it myself, but wonder if there are consequences that I'm unaware of to making the name just the first \S+ characters.

Subject:

Backend.pm

Message body is not shown because it is too large.

Mon May 24 12:09:46 2010 khw [...] cpan.org - Correspondence added

Subject:	Re: [rt.cpan.org #57176] AutoReply: Pod::Checker requires a comma or dash to recognize NAME
Date:	Mon, 24 May 2010 10:09:29 -0600
To:	bug-Pod-Parser [...] rt.cpan.org
From:	Karl WIlliamson <corporate [...] khwilliamson.com>

Show quoted text

>

------------------------------------------------------------------------- Show quoted text

> The attached file when parsed by Pod::Checker does not extract the name. > Checker is expecting something of the form: > =head1 NAME > FOO - bar > > And this file, which is an official one, only has FOO for the name, > without a hyphen and explanatory text. Running perldoc on the file does > extract the name. > > I care because I'm changing the Perl 5 podcheck.t test, and I need the > names of such modules, which are included in the 5.12 distribution. The > line that matters is 1232. I'd change it myself, but wonder if there > are consequences that I'm unaware of to making the name just the first > \S+ characters. >

I've looked at this further, and it seems to me that the correct solution is to make the omission of the comma or dash a new warning, but to set the name of the pod anyway. Similarly if the text in the NAME section is verbatim: a new warning, but extract the likely name.

Mon May 24 12:24:31 2010 public [...] khwilliamson.com - Correspondence added

Subject:	Re: [rt.cpan.org #57176] AutoReply: Pod::Checker requires a comma or dash to recognize NAME
Date:	Mon, 24 May 2010 10:24:18 -0600
To:	bug-Pod-Parser [...] rt.cpan.org
From:	karl williamson <public [...] khwilliamson.com>

Karl WIlliamson wrote: Show quoted text

> >

> -------------------------------------------------------------------------

>> The attached file when parsed by Pod::Checker does not extract the name. >> Checker is expecting something of the form: >> =head1 NAME >> FOO - bar >> >> And this file, which is an official one, only has FOO for the name, >> without a hyphen and explanatory text. Running perldoc on the file does >> extract the name. >> >> I care because I'm changing the Perl 5 podcheck.t test, and I need the >> names of such modules, which are included in the 5.12 distribution. The >> line that matters is 1232. I'd change it myself, but wonder if there >> are consequences that I'm unaware of to making the name just the first >> \S+ characters. >>

> > I've looked at this further, and it seems to me that the correct > solution is to make the omission of the comma or dash a new warning, but > to set the name of the pod anyway. Similarly if the text in the NAME > section is verbatim: a new warning, but extract the likely name. > >

It also seems to me that there should be a warning issued when the pod has no NAME And that any =encoding statement come first.

Mon May 24 12:24:32 2010 The RT System itself - Status changed from 'new' to 'open'

Tue Jan 17 15:45:13 2012 Marek.Rouchal [...] gmx.net - Taken

Tue Jan 17 15:49:55 2012 Marek.Rouchal [...] gmx.net - Correspondence added 5 min

There were similar discussions before... and the bottom line was that podchecker should check the syntax, but not the content. One thread I remember was about checking that certain manpage-style headlines should be there (NAME, DESCRIPTION, ...) - but one might want to document (and podcheck) something else than a manpage, and would be annoyed by errors. That's why I decided to reject this ticket.

Tue Jan 17 15:49:56 2012 Marek.Rouchal [...] gmx.net - Status changed from 'open' to 'rejected'