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
Karl Williamson
May 24, 2013 02:44
Re: I made t/podcheck.t less sensitive and fixed various pod issues
Message ID:
On 05/23/2013 06:20 PM, David Golden wrote:
> 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:
>    2466537 Try to avoid nesting F<$F<...>> in generated
>    3d6c5fe fix various podcheck nits
>    1dcc3c1 fix various Pod line length warnings
>    f5bfcfd help t/podcheck.t skip duplicate pod in utils
>    b5902b6 stop t/podcheck.t from flagging blockquotes
>    f26da01 Make t/podcheck.t less sensitive
> The pod checker got these major changes:
> * maximum verbatim line length is now 100 instead of 79
> * removed suggestions that C<> should be L<> or F<> instead
> * =over / =back "blockquotes" are now allowed
> FWIW, I tested 90 and 100 character line limits and the latter was the
> point where the vast majority of known issues went away.
> With those changes, some other bug fixes, and some Pod cleanup, the
> list of "known pod issues" has dropped from 155 or so down to about 15
> -- all of which are "verbatim longer than 100".
> None of them are impossible to fix, but they would take more than just
> splitting a line to do so.  Anyone motivated enough is welcome to give
> it a try.
> To be clear, I think the more aggressive pod linting -- particularly
> the C<> suggestions -- could still be done periodically by those
> interested in actually fixing (not just flagging) such issues, because
> I think they are ultimately good suggestions.
> 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 object to this being done without adequate discussion on the list.
It's not in keeping as to how this project has operated while I've been 
involved, and is contrary to how I would want to have a project operate 
that I contribute to.

Some of the things that podcheck looks at are my doing, and some are 
inherited from Pod::Checker; I no longer remember all of which are 
which.  A new version of Pod::Checker with somewhat different checks is 
to go into 5.19.  I can't remember any details as to what those 
differences are.  Making podcheck changes now complicates the merge of 
the branch that's ready for the final bit of work that rjbs has been 
doing on Pod::Checker.

I'll talk now on just the verbatim line length limit.  That was 
definitely my doing.  Changing the limit to 100 makes no sense; it might 
as well be totally removed.  Making this change is really saying we do 
not support the traditional use of perldoc as a man command in an 80 
column terminal window.  If I'm the only one still doing that, then I'm 
a troglodyte, and the rest of the world has moved on, and you shouldn't 
care what I think.   But before making this change, we should have 
discussed this to make an informed decision that not supporting this use 
is what we want to do.  A unilaterally made, arbitrary 100 column limit 
is not such an informed decision.  The reason for the 79 limit is not 
just the "prettiness" of the documentation; several wrapped lines in a 
row easily make that part of the documentation unreadable, without 
effort.  I believe we owe it to our users, who are free to go elsewhere, 
to have good documentation.  This check in podcheck is to at least have 
it easily readable.

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