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
From:
demerphq
Date:
May 24, 2013 08:57
Subject:
Re: I made t/podcheck.t less sensitive and fixed various pod issues
Message ID:
CANgJU+Xxq9oygrJR5ZhJmSyta838RULPXWACo4cPyg1nG3Qw7w@mail.gmail.com
On 24 May 2013 04:44, Karl Williamson <public@khwilliamson.com> wrote:
> 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 Config.pm
>> 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.
Sometimes we talk things to death and get nothing but talking done.
Sometimes we just do things and then deal with the fallout. I think
its healthy.
But I respect your point here. Generally we do discuss first and
generally that is the right thing to do. But I dont think Dave is
really out of line either. Its not that hard to revert or modify such
things after all.
> 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.
Every change has the potential of impacting someone elses change. I
don't think that is the best argument.
> 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.
But you could make the same argument about choosing 80. You and some
others prefer 80 columns. On the other hand, my screen shows about 210
at my normal font size without wrapping and my preference is too keep
code under 120 columns. So why does your preference win over mine?
> 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.
I know you don't mean it like this, but try think about what you just
said from a different perspective. You are essentially asking that
others do work to satisfy your preferences. (Yes I am aware that there
are lots of people that share your views, you just happen to be their
ambassador here :-).) It sounds like you want to be able read POD
without using a POD rendering tool to view it, but you want others to
do extra work so you can do so. Whereas I don't care about pod line
lengths. If I find one that is annoyingly long I fix it, but generally
it is simply a non problem for me. So why should I have to do a bunch
of make work to satisfy your preference? If you prefer 80 column pod
then feel free to post patches to update the pod accordingly, but
adding tests that I have to pass or bypass essentially externalizes
the cost of your preference on me, and I don't think that is right.
The person that wants something should be the one that pays for it.
The normal thing in open source is to scratch your own itch and to not
externalize costs onto others. If there are people on this list which
prefer 80 column pod then they should take it on themselves to
contribute the patches to fix the pod, not add tests which effectively
say "you can only add documentation if you satisfy my preferences for
how documentation should be formatted". Id much prefer people add
documentation without concerning themselves with trivialities like
line length.
Yves
--
perl -Mre=debug -e "/just|another|perl|hacker/"
Thread Previous
|
Thread Next