Re: Looking for another pod tip

[Shawn H Corey]

On Wed, 9 May 2018 20:54:57 -0600
Karl Williamson  wrote:

> I have an item text list.  Not all the items have content besides the 
> text, and so the pod would collapse them together into adjacent
> lines, whereas I want them separated.  I did this by adding a NBSP,
> but then I get an extra line that I'd rather not have.

Try using the Z<> specification.

=over

=item one

=item two

The 2 above items are together

=item three

Z<>

=item four

This item is separate from item three

=back


-- 
Don't stop where the ink does.

Shawn H Corey

Re: Pod::Simple output as POD

[Karl Williamson]

On 05/08/2018 07:05 PM, David E. Wheeler wrote:

On May 8, 2018, at 18:48, John SJ Anderson  wrote:


I suspect the plea for counsel was more intended for David, but I’ll pipe up 
from the peanut gallery and say, “why not both?” It seems like the ideal thing 
to put under a feature flag.


Actually, I wasn't thinking specifically of him.


I’m sorry, I’ve lost all context on this thread after two years. What’s it for 
again? Flag sounds okay, but better is to use =encoding.


This is a new module started by John, to extract the pod portions from 
say a .pm.  I think he said he thought he got about 80% of it done.  Now 
I'm completing it.  It requires hooks in BlackBox and other .pm's to 
enable it to really work.



Of course, that just changes this decision into “which one should be the 
default and which one should need to be enabled?”, but perhaps thinking about 
it in those terms will make it more clear which has the higher utility value?


Yeah, whichever is going to be more valuable for your intended audience.


The intended audience is me initially.  So I've decided to write it for 
my use, which wants the results in ASCII or UTF-8.


I think this is as much as I'm prepared to chew on for now, and if 
someone else wishes to extend it in the future to have the option John 
suggested, I agree it would be nice, and don't think it would be very hard.

Looking for another pod tip

[Karl Williamson]

I have an item text list.  Not all the items have content besides the 
text, and so the pod would collapse them together into adjacent lines, 
whereas I want them separated.  I did this by adding a NBSP, but then I 
get an extra line that I'd rather not have.


Here's an example

 Category "LC_NUMERIC": Numeric formatting
 This indicates how numbers should be formatted for human 
readability,

 for example the character used as the decimal point.

 Category "LC_MONETARY": Formatting of monetary amounts


 Category "LC_TIME": Date/Time formatting


 Category "LC_MESSAGES": Error and other messages
 This is used by Perl itself only for accessing operating 
system error

 messages via $! and $^E.


I don't know if your email client will collapse the lines, but there are 
two empty ones after the two items that don't have accompanying text. 
Any ideas as how to get rid of one?

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?