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

Re: Recent pod

Thread Previous | Thread Next
From:
Ricardo Signes
Date:
February 25, 2013 17:26
Subject:
Re: Recent pod
Message ID:
20130225172608.GA14491@cancer.codesimply.com
* "David E. Wheeler" <david@justatheory.com> [2013-02-25T11:57:02]
> On Feb 24, 2013, at 1:29 PM, Mark Overmeer <mark@overmeer.net> wrote:
> 
> > However... in this case, I see only an error for '1' and '2', not '0'
> 
> Lists must start with 1. When it saw the 0, it assumed it was a definition
> list, so the numbers after that don't look right.

Thinking about this on the bus, today, I was really unhappy with the whole
thing.  I don't know that I have much to suggest as a remedy, but:

We do want to alert the user if the list is confusing.

It seems that we want to say what kind of list it is as soon as possible.

...but we can't always know until the end.

There is nothing wrong with a text list with the terms: 1, 2, 3, undef

...but we can't know it's text until the end.

There is nothing wrong with a text list with the terms: undef, 1, 2, 3

...but we (I think) now complain that "1" means the author thinks it's a number
list after the first element, even though the author's intent is unknown.

There is no mechanism by which an author can say, very early, "this list is
going to be a list of type T" to make his or her intent clear.

The workaround is simple, but unsatisfying.  When using numbers in a text list,
instead of "1" use "Z<>1"

This workaround is in line with the perlpodspec warning against having text
items that match \d+.? which has been there since 5.6.0 at least.

Should we issue this warning at all?  I think we should, because it allows us
to catch problems where items (1, 2, 3, "undef") could confuse a to-spec
formatter.

-- 
rjbs

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About