Front page | perl.perl5.porters |
Postings from May 2013
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. 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