develooper Front page | perl.perl5.porters | Postings from May 2013

Re: I made t/podcheck.t less sensitive and fixed various pod issues

Thread Previous | Thread Next
Ricardo Signes
May 24, 2013 01:50
Re: I made t/podcheck.t less sensitive and fixed various pod issues
Message ID:
* David Golden <> [2013-05-23T20:20:43]
> I have just pushed a series of commits to blead that reduce the number
> of "false positives" thrown by t/podcheck.t and fix most of the known
> pod issues:

Thanks.  Looks like this was a bunch of unexciting work.

In 3d6c5fe, op.c changes twice like this:

  -must have been allocated using L</PerlMemShared_malloc>; the memory will
  +must have been allocated using C<PerlMemShared_malloc>; the memory will

This makes me wonder whether PerlMemShared_malloc (and PL_compiling) should
have their own entries in perlapi docs.  (What you did was obviously sane and
right!  But maybe someone would like to add entries...)

>   b5902b6 stop t/podcheck.t from flagging blockquotes

I think this should be fixed in Pod-Checker.  I'll look into it.  (I'm already
engaged in getting changes into Pod-Checker.)

>   f26da01 Make t/podcheck.t less sensitive

This commit is two pieces:

>   The warnings about using F<> and L<> instead of C<> have been removed
>   on the rationale that they are too opinionated.  They flag stylistic
>   issues rather than syntactic or structural issues and have minimal
>   impact on the effectiveness of the resulting documentation.

I agree.  Or, maybe what I really think is that I don't mind the opinion, I
just mind the gross inability for them to be right often enough, because the
code can't get the meaning of the formatting sequence's content right.

>   The max line length is increased to 100.  This eliminates dozens of
>   known issues.

I'm not a fan.  I'd rather fix the issues, and am willing to do so.  Strangely,
a quick scan suggests that at least some of them aren't even a problem anymore.

I read Pod documentation all the time, almost always in perldoc, in an 80
column terminal.  I would like to keep things looking good in that format.

It seems reasonable if we want to say that a 92-character line won't break the
build, but this change makes the line length test, in my opinion, worthless.
I'd rather we do something like add an environment variable to make that part
of the podcheck matter.

> That said, I feel very strongly that style linting along those lines
> should *not* cause test failures that interrupt ongoing development,
> which is why I made the changes described above.

I agree with this sentiment.  I want to be clear, too, that the *other* stuff
should prevent stuff from landing in blead.  For example, "funny characters"
without =encoding, duplicate names, etc.


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