Re: =item * foo bar

[Shawn H Corey]

On Wed, 9 May 2018 09:44:32 -0600
Karl Williamson  wrote:

> which of course is legal, but the * would be output as a star and not 
> translated into a bullet, and that is what happens here.
> 

A way to get a bullet and text is:

=item E text

Of course, that only does one level.

> If I had known about this earlier, I would have used it in pods to
> make it look better.  So maybe the spec could be changed to
> specifically allow this.  Or are there commonly used implementations
> that don't support it?

The POD for Perl 5.6 and early would allow both. Sometime during 5.8 it
was changed so bullets needed a single * and nothing else. `perldoc
perlpod` still isn't clear on this. `perldoc perlpodspec` makes this
clear. `perldoc perlpod` should be consider deprecated.


-- 
Don't stop where the ink does.

Shawn H Corey

Re: =item * foo bar

[Karl Williamson]

On 05/08/2018 09:57 PM, Dan Book wrote:
On Tue, May 8, 2018 at 11:32 PM, Karl Williamson 
> wrote:


There is code in Pod::Simple that "tolerates" (meaning accepts as a
bullet item) this pod line that would normally be illegal by
perlpodspec.

I wonder if anyone is around who remembers why this was added.  I
didn't see details in an internet search


I don't think it's illegal by perlpodspec. perlpodspec allows "=item 
[text]" where text is not a * followed by spaces, but it doesn't say 
anything about * followed by spaces and then other words.


My reading of that is that this should be treated as

=item text

which of course is legal, but the * would be output as a star and not 
translated into a bullet, and that is what happens here.


If I had known about this earlier, I would have used it in pods to make 
it look better.  So maybe the spec could be changed to specifically 
allow this.  Or are there commonly used implementations that don't 
support it?

Re: =item * foo bar

[Russ Allbery]

Karl Williamson  writes:

> There is code in Pod::Simple that "tolerates" (meaning accepts as a
> bullet item) this pod line that would normally be illegal by
> perlpodspec.

> I wonder if anyone is around who remembers why this was added.  I didn't
> see details in an internet search

Pod::Man tolerated this prior to Pod::Simple (by removing the leading
bullet and, if this was the first =item in an =over block, treating it as
a declaration that the type would be bullet).

Looks like that behavior was there from the very first version of my
Pod::Man in 1999, so I suspect it was in Tom Christiansen's original
pod2man script.

So, the short answer is "very, very, very long-standing backward
compatibility."

-- 
#!/usr/bin/perl -- Russ Allbery, Just Another Perl Hacker
$^=q;@!>~|{>krw>yn{u<$$<[~|| 0gFzD gD,
 00Fz, 0,,( 0hF 0g)F/=, 0> "L$/GEIFewe{,$/ 0C$~> "@=,m,|,(e 0.), 01,pnn,y{
rw} >;,$0=q,$,,($_=$^)=~y,$/ C-~><@=\n\r,-~$:-u/ #y,d,s,(\$.),$1,gee,print

Re: the construct =item * Foo bar

[Russ Allbery]

Sean M Burke [EMAIL PROTECTED] writes:

 You've got an excellent to-do list there, to which the only additions
 that come to mind just now are making sure that E... handling is done
 according to perlpodspec (probably mostly simple done by using
 Pod::Escapes), and making sure that Pod::Man and Pod::Text happily
 format at least most of the Pod generated in the tests in the
 Pod::Simple test/*.t suite.

 When do you think you can have all these things done?

I have no idea.  It's not my highest priority right now, and I don't
promise time frames for volunteer projects generally anyway.  Other than
the i18n issues, everything else is fairly minor, so it will likely wait
until I have the free time to sit down and really study the groff
documentation and figure out how it does Unicode and how to integrate that
with the rest of what Pod::Man is doing.

At a guess, I may (or may not) find time to do that over Christmas break.

Help is, of course, always greatly appreciated from anyone who understands
*roff well.

-- 
Russ Allbery ([EMAIL PROTECTED]) http://www.eyrie.org/~eagle/

Re: the construct =item * Foo bar

[Sean M. Burke]

At 20:54 2002-10-16 +, Smylers wrote:
[...]for other people who try to parse it using pod readers that just 
implement the spec and not your slew of variances.

(Similar to how people view their webpages in 'Internet Explorer', it 
forgives some errors, and so they are unaware of them as they publish 
non-standard code which doesn't work in other browsers.)

This is basically a good analogy, and I generally do like to keep mentally 
distinct the spec I wrote, and the parser I wrote.  That makes things quite 
tidy.

However, I do at times wonder why anyone in their right mind would write 
/another/ perlpodspec-compliant Pod-parser.  Doing the first one, 
Pod::Simple, was plenty hard enough.  I can't think of a motivation that'd 
be worth the bother of doing it all over again.

--
Sean M. Burkehttp://search.cpan.org/author/sburke/

Re: the construct =item * Foo bar

[Iain 'Spoon' Truskett]

* Sean 'TorgoX' Burke ([EMAIL PROTECTED]) [17 Oct 2002 14:18]:

[...]
 However, I do at times wonder why anyone in their right mind would
 write /another/ perlpodspec-compliant Pod-parser. [...] I can't think
 of a motivation that'd be worth the bother of doing it all over again.

Curiosity.

Or they're bored and want it to go EVEN FASTER! Mmm. C pod parser with
XS bindings.


cheers,
-- 
Iain.

Re: the construct =item * Foo bar

[Russ Allbery]

Sean M Burke [EMAIL PROTECTED] writes:

 Andy Lester spotted what I think is the first substantial problem with
 Pod::Simple and perlpodspec (!!) the other day!  It's this:

 Some people, including Andy, use this construct:

 =item * Foo bar baz

 to mean what I always thought one absolutely had to express with:

 =item *

 Foo bar baz

Er, all the translators that I've written require the latter too.

Do we really have to change the spec to support this?  Can't we just say
that it's wrong?

-- 
Russ Allbery ([EMAIL PROTECTED]) http://www.eyrie.org/~eagle/