Mailing List Archive

Recent pod
This used to be valid and warning-free until recently:

--8<--- test.pod
=head1 TEST

=head2 Return values

=over 4

=item undef

The return value is undefined

=item 0

The return value i numerical 0 (OK).

=item *

Any other value.

=back

=cut
-->8---

Now it gives me TWO errors and dies:

$ pod2text test.pod
TEST
Return values
undef
The return value is undefined

test.pod around line 11: Expected text after =item, not a number
0 The return value i numerical 0 (OK).

test.pod around line 15: Expected text after =item, not a bullet
* Any other value.

POD document had syntax errors at /pro/bin/pod2text line 82.


--
H.Merijn Brand http://tux.nl Perl Monger http://amsterdam.pm.org/
using perl5.00307 .. 5.17 porting perl5 on HP-UX, AIX, and openSUSE
http://mirrors.develooper.com/hpux/ http://www.test-smoke.org/
http://qa.perl.org http://www.goldmark.org/jeff/stupid-disclaimers/
Re: Recent pod [ In reply to ]
* H. Merijn Brand (h.m.brand@xs4all.nl) [130224 20:57]:
> This used to be valid and warning-free until recently:

> =item 0
> The return value i numerical 0 (OK).

Same here, from cpantesters
http://www.cpantesters.org/cpan/report/5883d11a-7944-11e2-98ce-62bbf368c44f

# Failed test 'POD test for blib/lib/XML/LibXML/Simple.pod'
# at /home/graham/perls/perl-5.14.2/lib/site_perl/5.14.2/Test/Pod.pm line 186.
# blib/lib/XML/LibXML/Simple.pod (441): Expected text after =item, not a number
# blib/lib/XML/LibXML/Simple.pod (447): Expected text after =item, not a number

------ 8< ------ 8< ------ BEGIN
=item NormaliseSpace => 0 | 1 | 2 I<# handy>

This option controls how whitespace in text content is handled. Recognised
values for the option are:

=over 4

=item 0

(default) whitespace is passed through unaltered (except of course for the
normalisation of whitespace in attribute values which is mandated by the XML
recommendation)

=item 1

whitespace is normalised in any value used as a hash key (normalising means
removing leading and trailing whitespace and collapsing sequences of whitespace
characters to a single space)

=item 2

whitespace is normalised in all text content
------ 8< ------ 8< ------END

However... in this case, I see only an error for '1' and '2', not '0'
--
Regards,

MarkOv

------------------------------------------------------------------------
Mark Overmeer MSc MARKOV Solutions
Mark@Overmeer.net solutions@overmeer.net
http://Mark.Overmeer.net http://solutions.overmeer.net
Re: Recent pod [ In reply to ]
On Feb 24, 2013, at 12:57 PM, H.Merijn Brand <h.m.brand@xs4all.nl> wrote:

> =head1 TEST
>
> =head2 Return values
>
> =over 4
>
> =item undef
>
> The return value is undefined
>
> =item 0
>
> The return value i numerical 0 (OK).
>
> =item *
>
> Any other value.
>
> =back
>
> =cut
> -->8---
>
> Now it gives me TWO errors and dies:
>
> $ pod2text test.pod
> TEST
> Return values
> undef
> The return value is undefined
>
> test.pod around line 11: Expected text after =item, not a number
> 0 The return value i numerical 0 (OK).
>
> test.pod around line 15: Expected text after =item, not a bullet
> * Any other value.

This was due to this change:

https://github.com/theory/pod-simple/commit/5a01eba83824d9f91ecfae302af33fef65a8385c

Note that this is a warning, rather than a fatal error, though of course Test::Pod considers warnings to be test failures.

In general, I think that this is an improvement, as one should not usually mix =item formats. I can see that your case is completely legitimate, though. You can fix it by wrapping those items in C<>s.

But this does raise the question as to whether this change is too much. Thoughts?

David
Re: Recent pod [ In reply to ]
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.

It's likely that Pod::Simple has always formatted this list as a definition list. Is that what you wanted? If so, then you can fix it by wrapping the numbers on C<> or S<>. If not, then consider re-numbering from 1.

Either way, this warning has alerted you* to an unexpected inconsistency, and so gives you the opportunity to do something about it.

*Where by "you" I man the maintainer of this module and others that might exhibit a similar problem.

Best,

David
Re: Recent pod [ In reply to ]
"David E. Wheeler" <david@justatheory.com> writes:

> This was due to this change:

> https://github.com/theory/pod-simple/commit/5a01eba83824d9f91ecfae302af33fef65a8385c

> Note that this is a warning, rather than a fatal error, though of course
> Test::Pod considers warnings to be test failures.

> In general, I think that this is an improvement, as one should not
> usually mix =item formats. I can see that your case is completely
> legitimate, though. You can fix it by wrapping those items in C<>s.

Better (since it doesn't change the formatting):

=item 0Z<>

=item *Z<>

--
Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/>
Re: Recent pod [ In reply to ]
* "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
Re: Recent pod [ In reply to ]
On Feb 25, 2013, at 9:20 AM, Russ Allbery <rra@stanford.edu> wrote:

> Better (since it doesn't change the formatting):
>
> =item 0Z<>
>
> =item *Z<>

I think S<> would work, too.

David
Re: Recent pod [ In reply to ]
On Feb 25, 2013, at 9:26 AM, Ricardo Signes <perl.p5p@rjbs.manxome.org> wrote:

> 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.

FWIW, IIUC, this change was introduced for compatibility with one of the Pod modules we're trying to remove from core.

David
Re: Recent pod [ In reply to ]
"David E. Wheeler" <david@justatheory.com> wrote on Mon, 25 Feb 2013 08:53:29 PST:

>On Feb 24, 2013, at 12:57 PM, H.Merijn Brand <h.m.brand@xs4all.nl> wrote:

>> =head1 TEST
>>
>> =head2 Return values
>>
>> =over 4
>>
>> =item undef
>>
>> The return value is undefined
>>
>> =item 0
>>
>> The return value i numerical 0 (OK).
>>
>> =item *
>>
>> Any other value.
>>
>> =back
>>
>> =cut
>> -->8---
>>
>> Now it gives me TWO errors and dies:
>>
>> $ pod2text test.pod
>> TEST
>> Return values
>> undef
>> The return value is undefined
>>
>> test.pod around line 11: Expected text after =item, not a number
>> 0 The return value i numerical 0 (OK).
>>
>> test.pod around line 15: Expected text after =item, not a bullet
>> * Any other value.

> This was due to this change:

> https://github.com/theory/pod-simple/commit/5a01eba83824d9f91ecfae302a<SNIP>

> Note that this is a warning, rather than a fatal error, though of course<SNIP>

> In general, I think that this is an improvement, as one should not usual<SNIP>

> But this does raise the question as to whether this change is too much. <SNIP>


Would a prefix Z<> work to trick it?

--tom
Re: Recent pod [ In reply to ]
Russ Allbery <rra@stanford.edu> wrote
on Mon, 25 Feb 2013 09:20:11 PST:

>"David E. Wheeler" <david@justatheory.com> writes:

>> This was due to this change:

>> https://github.com/theory/pod-simple/commit/5a01eba83824d9f91ecfae30<SNIP>

>> Note that this is a warning, rather than a fatal error, though of course
>> Test::Pod considers warnings to be test failures.

>> In general, I think that this is an improvement, as one should not
>> usually mix =item formats. I can see that your case is completely
>> legitimate, though. You can fix it by wrapping those items in C<>s.

>Better (since it doesn't change the formatting):

> =item 0Z<>

> =item *Z<>

I hate not waiting till I've digested the whole thread before
giving the same anwwer as was already provided. :)

--tom
Re: Recent pod [ In reply to ]
> Thinking about this on the bus, today, I was really unhappy with the
> whole thing.

Don't get me started on pod-unhappiness. With so many people now reading
manpages in html, we really should make pod2html at least as smart as
pod2man (when set with troff, not just nroff) has always been.

--tom
Re: Recent pod [ In reply to ]
"David E. Wheeler" <david@justatheory.com> writes:

> On Feb 25, 2013, at 9:20 AM, Russ Allbery <rra@stanford.edu> wrote:
>
>> Better (since it doesn't change the formatting):
>>
>> =item 0Z<>
>>
>> =item *Z<>
>
> I think S<> would work, too.

Just what we need... more obscure trickery.

Why not replace "=item *" by something friendly like "=bullet" ?

Also quite stupid:

=over 4

=item 1.

First item.

=item 1.

Another item.

=back

Computers are very good at numbering list items.

-- Johan
Re: Recent pod [ In reply to ]
On Feb 25, 2013, at 1:38 PM, Johan Vromans <jvromans@squirrel.nl> wrote:

> Just what we need... more obscure trickery.
>
> Why not replace "=item *" by something friendly like "=bullet" ?
>
> Also quite stupid:
>
> =over 4
>
> =item 1.
>
> First item.
>
> =item 1.
>
> Another item.
>
> =back
>
> Computers are very good at numbering list items.

Yeah, that’s why I use Markdown for almost all my other documentation.

David
Re: Recent pod [ In reply to ]
* David E. Wheeler (david@justatheory.com) [130225 16:57]:
> 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.
>
> It's likely that Pod::Simple has always formatted this list as a
> definition list. Is that what you wanted? If so, then you can fix it by
> wrapping the numbers on C<> or S<>. If not, then consider re-numbering
> from 1.

On purpose I included a bit larger example: (now a bit stripped down)
This got derived form the original XML::LibXML manpage.

=item NormaliseSpace => 0 | 1 | 2
This option controls how whitespace in text content is handled.
Recognised values for the option are:

=over 4
=item 0
(default) whitespace is passed through unaltered (except of ...

=item 1
whitespace is normalised in any value used as a hash key ...

=item 2
...

The perlpod manual speaks about a special meaning for '1.', not '1'
without dot.

> Either way, this warning has alerted you* to an unexpected
> inconsistency, and so gives you the opportunity to do something about it.
>
> *Where by "you" I man the maintainer of this module and others that
> might exhibit a similar problem.

Of course, there are many work-arounds. That's not the point. It's
the missing point, I think.
--
Regards,

MarkOv

------------------------------------------------------------------------
Mark Overmeer MSc MARKOV Solutions
Mark@Overmeer.net solutions@overmeer.net
http://Mark.Overmeer.net http://solutions.overmeer.net
Re: Recent pod [ In reply to ]
On Feb 25, 2013, at 2:32 PM, Mark Overmeer <mark@overmeer.net> wrote:

> The perlpod manual speaks about a special meaning for '1.', not '1'
> without dot.
>
>> Either way, this warning has alerted you* to an unexpected
>> inconsistency, and so gives you the opportunity to do something about it.
>>
>> *Where by "you" I man the maintainer of this module and others that
>> might exhibit a similar problem.
>
> Of course, there are many work-arounds. That's not the point. It's
> the missing point, I think.

perlpodspec:

> · An "=over" ... "=back" region containing only
> "m/\A=item\s+\d+\.?\s*\z/" paragraphs, each one (or each group
> of them) followed by some number of ordinary/verbatim
> paragraphs, other nested "=over" ... "=back" regions, "=for..."
> paragraphs, and/or "=begin"..."=end" codes. Note that the
> numbers must start at 1 in each section, and must proceed in
> order and without skipping numbers.
>
> (Pod processors must tolerate lines like "=item 1" as if they
> were "=item 1.", with the period.)

As a result, the type of the list is determined by this method:

https://github.com/theory/pod-simple/blob/master/lib/Pod/Simple.pm#L556

Best,

David
Re: Recent pod [ In reply to ]
* David E. Wheeler (david@justatheory.com) [130225 22:38]:
> On Feb 25, 2013, at 2:32 PM, Mark Overmeer <mark@overmeer.net> wrote:
> > Of course, there are many work-arounds. That's not the point. It's
> > the missing point, I think.
>
> perlpodspec:
> > · An "=over" ... "=back" region containing only
> > "m/\A=item\s+\d+\.?\s*\z/" paragraphs, each one (or each group
> > of them) followed by some number of ordinary/verbatim
> > paragraphs, other nested "=over" ... "=back" regions, "=for..."
> > paragraphs, and/or "=begin"..."=end" codes. Note that the
> > numbers must start at 1 in each section, and must proceed in
> > order and without skipping numbers.
> >
> > (Pod processors must tolerate lines like "=item 1" as if they
> > were "=item 1.", with the period.)
>
> As a result, the type of the list is determined by this method:
> https://github.com/theory/pod-simple/blob/master/lib/Pod/Simple.pm#L556

In perlpod:
· And perhaps most importantly, keep the items consistent:
either use "=item *" for all of them, to produce bullets; or
use "=item 1.", "=item 2.", etc., to produce numbered lists;
or use "=item foo", "=item bar", etc.--namely, things that
look nothing like bullets or numbers.

No idea whether perlpodspec changed or perlpod doesn't tell the whole
picture with respect to numbered lists. The manual page always looked
correct.

Most releases of Perl introduce new warnings. Maybe a good thing. As
long as it is an on-purpose change.
--
Regards,

MarkOv

------------------------------------------------------------------------
Mark Overmeer MSc MARKOV Solutions
Mark@Overmeer.net solutions@overmeer.net
http://Mark.Overmeer.net http://solutions.overmeer.net
Re: Recent pod [ In reply to ]
On Feb 25, 2013, at 2:58 PM, Mark Overmeer <mark@overmeer.net> wrote:

> In perlpod:
> · And perhaps most importantly, keep the items consistent:
> either use "=item *" for all of them, to produce bullets; or
> use "=item 1.", "=item 2.", etc., to produce numbered lists;
> or use "=item foo", "=item bar", etc.--namely, things that
> look nothing like bullets or numbers.
>
> No idea whether perlpodspec changed or perlpod doesn't tell the whole
> picture with respect to numbered lists. The manual page always looked
> correct.

perlpodspec describes the spec in great detail. It's for Pod parser writers. perlpod is for Pod users. It's less precise.

> Most releases of Perl introduce new warnings. Maybe a good thing. As
> long as it is an on-purpose change.

This was.

David
Re: Recent pod [ In reply to ]
On Mon, 25 Feb 2013 23:32:30 +0100, Mark Overmeer <mark@overmeer.net>
wrote:

> * David E. Wheeler (david@justatheory.com) [130225 16:57]:
> > 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.
> >
> > It's likely that Pod::Simple has always formatted this list as a
> > definition list. Is that what you wanted? If so, then you can fix it by
> > wrapping the numbers on C<> or S<>. If not, then consider re-numbering
> > from 1.
>
> On purpose I included a bit larger example: (now a bit stripped down)
> This got derived form the original XML::LibXML manpage.
>
> =item NormaliseSpace => 0 | 1 | 2
> This option controls how whitespace in text content is handled.
> Recognised values for the option are:
>
> =over 4
> =item 0
> (default) whitespace is passed through unaltered (except of ...
>
> =item 1
> whitespace is normalised in any value used as a hash key ...
>
> =item 2
> ...
>
> The perlpod manual speaks about a special meaning for '1.', not '1'
> without dot.
>
> > Either way, this warning has alerted you* to an unexpected
> > inconsistency, and so gives you the opportunity to do something about it.
> >
> > *Where by "you" I man the maintainer of this module and others that
> > might exhibit a similar problem.
>
> Of course, there are many work-arounds. That's not the point. It's
> the missing point, I think.

FWIW I never meant to "complain", but to "signal", and seeing the
nature of the change, notice the list.

I knew about the trailing ., but didn't realize it when I saw the
errors/warnings. I can live with the S<>, C<>, or Z<> change. I
actually already changed that in the pod at hand, and the problems
disappeared.

--
H.Merijn Brand http://tux.nl Perl Monger http://amsterdam.pm.org/
using perl5.00307 .. 5.17 porting perl5 on HP-UX, AIX, and openSUSE
http://mirrors.develooper.com/hpux/ http://www.test-smoke.org/
http://qa.perl.org http://www.goldmark.org/jeff/stupid-disclaimers/
Re: Recent pod [ In reply to ]
Mark Overmeer writes:

> * David E. Wheeler (david@justatheory.com) [130225 22:38]:
>
> > perlpodspec:
> > > · An "=over" ... "=back" region containing only
> > > "m/\A=item\s+\d+\.?\s*\z/" paragraphs, each one (or each
> > > group of them) followed by some number of ordinary/verbatim
> > > paragraphs, other nested "=over" ... "=back" regions,
> > > "=for..." paragraphs, and/or "=begin"..."=end" codes. Note
> > > that the numbers must start at 1 in each section, and must
> > > proceed in order and without skipping numbers.
> > >
> > > (Pod processors must tolerate lines like "=item 1" as
> > > if they were "=item 1.", with the period.)
>
> In perlpod:
> · And perhaps most importantly, keep the items consistent:
> either use "=item *" for all of them, to produce bullets; or
> use "=item 1.", "=item 2.", etc., to produce numbered lists;
> or use "=item foo", "=item bar", etc.--namely, things that
> look nothing like bullets or numbers.
>
> No idea whether perlpodspec changed or perlpod doesn't tell the whole
> picture with respect to numbered lists.

The above two don't actually contradict each other:

* perlpod tells Pod authors to use "1.", "2." or to use "things that
look nothing like bullets or numbers".

Clearly "1" doesn't fall in the category of something that doesn't
look like a number, so by perlpod authors shouldn't be using it.

* perlpodspec tells Pod tools developers that if an author does use "1"
they should treat it like "1.".

Cheers

Smylers
--
http://twitter.com/Smylers2
Re: Recent pod [ In reply to ]
Johan Vromans <jvromans@squirrel.nl> writes:

> Just what we need... more obscure trickery.

> Why not replace "=item *" by something friendly like "=bullet" ?

It's an interesting thought, since one can add new POD commands with
backward compatibility. I think in retrospect it's clear that the
automatic list type detection from the contents of =item wasn't a great
idea, and we would have been better off with =bullet, =number, and =desc.

> Also quite stupid:

> =over 4

> =item 1.

> First item.

> =item 1.

> Another item.

> =back

I think this used to work and now doesn't work in a kind of weird and
annoying way. I seem to recall that this was discussed before, but the
current state doesn't make sense to me: either auto-number and warn, or
take what the user entered verbatim, but taking what the user entered
verbatim and then warning is strange. But I probably haven't thought
through it.

--
Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/>