develooper Front page | perl.perl5.porters | Postings from March 2001

Re: pods patched

Michael Stevens
March 17, 2001 02:06
Re: pods patched
Message ID:
On Fri, Mar 16, 2001 at 06:30:59PM +0000, Michael G Schwern wrote:
> On Fri, Mar 16, 2001 at 01:11:25PM -0500, Ilya Zakharevich wrote:
> > Should it be applied?  What is the sense of
> > --- perl-current.orig/configpm  Thu Mar 15 20:33:42 2001
> > +++ perl-current/configpm       Thu Mar 15 21:10:59 2001
> > @@ -418,7 +418,7 @@
> >      print CONFIG <<EOF;
> >  =head2 $c
> > 
> > -=over
> > +=over 4
> Pod::Checker and most pod2* things will warn about an =over without a
> number.  Its not required (thus leaving POD Plain), but it is
> considered a Good Thing.
> The patch should go in (it removed POD warnings) since the work has
> been done and removing warnings from the core is Good.  If you don't
> like the warning, take it up with the Pod::* authors.  The issue is
> orthogonal to this patch.

Reading perlpod on =over it reads very ambiguously to me, but sounds
like the number on =over could perhaps default to something, but as
yet it doesn't do so.

Anyway, my attitude is that IF we warn about it, AND the documentation
doesn't make it clear the warning is inappropriate (eg if we warned
about the =turnip tag being inappropriate, and the documentation explained
the =turnip tag and said it could and SHOULD be used in all documents),
I will probably do patches. I'm personally not too fussed if we change
the checkers (and, presumably the standard, which is probably unclearly
written if someone experienced enough to write Pod::Checker was able to
misunderstand it), or the docs. I'm just personally more inclined to produce
doc patches. I've been working on the assumption that podchecker 
encapsulates a long established standard, and who am I to change it?

Michael Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About