Is writing "=item * Foo" in a line in POD allowed?

Darkwing has asked for the wisdom of the Perl Monks concerning the following question:

Hi,

i noticed that this renders as expected:

=over

=item * Foo

=item * Bar

=back
[download]

Same result as rendering this:

=over

=item *

Foo

=item *

Bar

=back
[download]

I tried this with my local Perl and with the online POD renderer https://metacpan.org/pod2html.

But I wonder if this is legal in POD or just works by accident. I looked here: https://perldoc.perl.org/perlpodspec and here: https://perldoc.perl.org/perlpod, but there is no example where =item * is followed by something else in the same line. I would like to use the shorter variant in my POD docu, but first I would like to clarify if this is really legal.

Comment on Is writing "=item * Foo" in a line in POD allowed? Select or Download Code

Replies are listed 'Best First'.
Re: Is writing "=item * Foo" in a line in POD allowed? by hippo (Archbishop) on Jun 29, 2023 at 10:40 UTC
A quick read of perlpodspec suggests to me that both versions are legal but are semantically different. The former is a list of named items equivalent to HTML `<dt>` tags where the term being defined includes the leading asterisk, whereas the latter is a bullet list of items equivalent to HTML `<li>` tags inside a `<ul>`. However, I'll be the first to admit to not being the best at reading formal specs so could be completely wrong on this. That said, pod2html renders them identically (as `<ul><li>...`) so probably I am totally wrong in my reading of it. Either way it could be clearer and/or less ambiguous. 🦛	[reply] [d/l] [select]
Re: Is writing "=item * Foo" in a line in POD allowed? by haj (Vicar) on Jun 29, 2023 at 10:43 UTC
perlpodspec also has the following example: `=item He is at this time transporting large armies of foreign mercenaries to complete the works of death, desolation and tyranny, already begun with circumstances of cruelty and perfidy scarcely paralleled in the most barbarous ages, and totally unworthy the head of a civilized nation.` [download] So, longer texts are allowed. I guess that it is up to the specific renderer whether it picks an initial `"* "` as an indication to produce a bullet list (like pod2html apparently does)	[reply] [d/l]