develooper Front page | perl.perl5.porters | Postings from March 2022

Indenting pod verbatim lines

Thread Next
Karl Williamson
March 30, 2022 16:53
Indenting pod verbatim lines
Message ID:
Traditionally, pod verbatim lines are indented 4 spaces, but I know of 
nothing written that encourages that, and only a single space indent is 
what is actually required to make the line to be considered verbatim.

A problem arises when the window displaying the pod is narrower than a 
verbatim line.  It wraps, making the result less legible.

podcheck.t in pedantic mode will warn when a verbatim line would wrap in 
a traditional 80 column window.

If the excess is 1-3 columns, and the indent was 4, the wrapping would 
be eliminated by not indenting so much.  I claim that a shorter indent 
results in more legible output than allowing wrapping.

As a result, I have for some time just indented all verbatim lines by a 
single space.  That way, I don't have to think about what reducing the 
indent if the line is getting close to too wide.

But others want a consistent indent throughout the pod.  I don't get 
that; there are plenty of places that is violated, and I haven't heard 
any complaints.  But I'll assume that is a valid constraint.

What to do then when a line exceeds the limit and wouldn't if the indent 
were less?  Again, I claim it is much better for it to not wrap.

One option would be to lessen the indent of all verbatim lines in the 
pod at the same time.

Another would be to lessen the indent of just the ones that would wrap, 
resulting in inconsistency.

But if completely new pods standardized on a single space indent from 
the beginning, this whole question goes away for them.

For existing ones, how important is the consistency of indentation? 
Should new verbatim lines use the prevailing indent unless they are too 

I would very strongly oppose allowing wrapping when shortening the 
indent would solve the problem

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