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

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

Thread Previous | Thread Next
Karl Williamson
June 14, 2013 16:15
Re: I made t/podcheck.t less sensitive and fixed various pod issues
Message ID:
On 06/13/2013 12:50 AM, demerphq wrote:
> On 13 June 2013 02:01, Leon Timmermans <> wrote:
>> On Thu, Jun 13, 2013 at 1:47 AM, Tony Cook <> wrote:
>>> Just adding to the exception list is similar to making a change that
>>> breaks perl and then changing the tests that broke into TODO tests.
>> That's the part that doesn't make sense to me. Is it really more work
>> to fix a newly introduced verbatim line than it is to add it to the
>> list of exceptions?
> When the verbatim line is output from perl, then yes, it is.
> I have had these tests go off when I am documenting what Perl outputs.
> It outputs a string longer than 80 characters, but I cant just paste
> it into a doc because of these tests. And I dont think the docs should
> contain munge perl output. If the output is going to be munged it
> should be munged by the pod processor.
> That is my big objection here. We are forcing people to change the
> *input* to a *program* so that other people can view that input in a
> text editor at their preferred screen dimensions.
> I think that is wrong. The input should be such that if I have a wide
> enough screen I see the *unmunged* data, and the program should handle
> munging it for their screen size.
> In otherwords we are doing it backwards and we are doing it
> unperlishly. Computers and Perl especially is supposed to make mundane
> tasks go away, not force new ones on us. We are hackers, we should
> fixing the *display* program, and not the *input* it receives.

The pod language doesn't have tables where we specify columns.  In lieu 
of that functionality, the verbatim line is used, which puts the onus on 
the human.  And, in the decades since pod was developed, no one has had 
a big enough itch to implement tables.  I've thought about it, but other 
things have had higher precedence for my tuits.

Your example of the output of a program being placed in a pod is one 
case where it is unavoidable to have verbatim lines longer than 79 
columns.  Instances like this are why podcheck allows exceptions to the 
normal rules.  You aren't being "forced" to change the pod; you just add 
it to the exception list by regen'ing the exception file.

I'm wondering if it would be better in such instances for the user to add an

=for podcheck
These verbatim lines are output from a program

  First verbatim line

instead of just doing a regen.  That is, add comments to the pod for 
podcheck to use, like people do for diag.t, for the cases that are 
permanent exceptions to the rules, and not just TODOs.

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