Re: Pod::Simple output as POD

[David E. Wheeler]

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.

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.

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

D



signature.asc
Description: Message signed with OpenPGP

Re: Pod::Simple output as POD

[David E. Wheeler]

On May 13, 2016, at 7:00 PM, Ron Savage  wrote:

> So make it -J JustPod, or is that parameter list sacrosanct?
> 
> Perhaps leave -M, and add -J, which defaults to a value of JustPod.

You pass the name of the formatting module to -M. I see no reason to change it.

D

smime.p7s
Description: S/MIME cryptographic signature

Re: Pod::Simple output as POD

[David E. Wheeler]

On May 13, 2016, at 11:03 AM, Karl Williamson  wrote:

> If we wanted to be cute, we could call it Pod::Simple::SimplyPod, with you 
> know, only one, natural, ingredient, and no harmful additives.

But is it organic? Or Biodynamic?

D



smime.p7s
Description: S/MIME cryptographic signature

Re: Pod::Simple output as POD

[David E. Wheeler]

On May 11, 2016, at 5:29 PM, Karl Williamson  wrote:

>> My only comment on ‘ExtractPod’ as a name would be that all the other 
>> modules in the Pod::Simple dist that do similar things are simply named 
>> ‘Pod::Simple::$FORMAT’, (e.g., Pod::Simple::HTML, Pod::Simple::RTF, etc.)

Probably should have been Pod::Simple::Format::*. :-(

>> At the end of the day, you’ve done the work to get it out the door and as 
>> far as I’m concerned, you can call it whatever you like. 8^)
> 
> It's more a matter of what is the least worst name to help people at a glance 
> know what it does.  I imagine that if it were named simply 'Pod' that people 
> would think. "I've already got Pod input, why would I want Pod output", and 
> either investigate, or blow it off.  So that's why I came up with ExtractPod, 
> but I'd like to hear other opinions.

Like John, I don’t much care. I agree that Pod::Simple::Pod lacks necessary 
information. ExtractPod seems fine to me. Uh, though there is this:

   perldoc [-h] [-D] [-t] [-u] [-m] [-l] [-F]
[-i] [-V] [-T] [-r]
[-d destination_file]
[-o formatname]
[-M FormatterClassName]
[-w formatteroption:value]
[-n nroff-replacement]
[-X]
[-L language_code]
PageName|ModuleName|ProgramName|URL

So the formatter arg to -M would be:

perldoc -M ExtractPod

Which also seems a little weird. Maybe Pod::Simple::PodFormat?

Anyway, I’ve no strong opinions.

Best,

David



smime.p7s
Description: S/MIME cryptographic signature

Re: Pod::Simple - August PR Challenge Assignment

[David E. Wheeler]

On Aug 19, 2015, at 4:25 PM, Ron Savage r...@savage.net.au wrote:

 - ASCII 'v' Unicode 'v' CP1252. See
 - http://www.mail-archive.com/pod-people@perl.org/msg01710.html

This has been done, thanks to Karl.

David



smime.p7s
Description: S/MIME cryptographic signature

Re: Pod::Simple - August PR Challenge Assignment

[David E. Wheeler]

On Aug 18, 2015, at 7:58 AM, Sean Zellmer s...@lejeunerenard.com wrote:

 I was assigned Pod::Simple as my August module for the PR Challenge and was 
 wondering if anything jumps to mind as a project for my PR. Any ideas are 
 welcome. :)

How about this?

  https://rt.cpan.org/Ticket/Display.html?id=105220

If not, take a look at the other open issues.

  https://rt.cpan.org/Dist/Display.html?Status=ActiveQueue=Pod-Simple

Best,

David



smime.p7s
Description: S/MIME cryptographic signature

Test-Pod GitHub Move

[David E. Wheeler]

Pods,

I’ve just moved the Test-Pod project to the perl-pod organization on GitHub. 
The bug and repo links will be updated in the next release.

Best,

David

smime.p7s
Description: S/MIME cryptographic signature

Re: Assume CP1252

[David E. Wheeler]

On Jan 13, 2015, at 6:07 PM, David E. Wheeler da...@justatheory.com wrote:

 Pod::Simple 3.29 is on its way to CPAN now. I’m going to apply the change 
 proposed in the Pod::Simple can treat binary as pod due to 
 liberal/inconsistent regexp patterns thread now, and once you have the 
 EBCDIC and CP1252 stuff done, we can do a test release to let it smoke with 
 those changes.

And now 3.29_1 is on CPAN with EBCDIC support and CP1252 as the default thanks 
to Karl Williamson. Details here:

  http://theory.pm/2015/02/11/please-test-pod-simple-3-dot-29-3/

Please test!

Best,

David



smime.p7s
Description: S/MIME cryptographic signature

Re: Pod::Simple can treat binary as pod due to liberal/inconsistent regexp patterns

[David E. Wheeler]

On Jan 13, 2015, at 10:11 PM, Karl Williamson pub...@khwilliamson.com wrote:

 Nobody has explained to me why we accept uppercase when all existing pod 
 commands (I believe) are entirely lowercase.  And shouldn't the digits only 
 be in the final position?  I don't know the answers, but am just pointing out 
 potential problems.

I think it is an historical thing. No harm in it, really. I would not be 
surprised if there were uppercase Pod commands in the wild.

David



smime.p7s
Description: S/MIME cryptographic signature

Re: Pod::Simple can treat binary as pod due to liberal/inconsistent regexp patterns

[David E. Wheeler]

On Jan 12, 2015, at 11:42 AM, David E. Wheeler da...@justatheory.com wrote:

 Honest, since the current regex matches stuff that is not in fact Pod, I 
 think it is reasonable to tighten up the regex to
 
/\A=([a-zA-Z]+[0=9]*)\b/

That one, it turns out, was no less liberal than the previous regex. I added a 
test matching the pattern Randy identified, and it failed with this regex, too. 
So I instead copied the regex from later in the file, which *is* sufficiently 
more strict, and brings them into line, to boot. The change is here:

  https://github.com/theory/pod-simple/commit/31942ec

Look good? If so, I will update perlpodspec to match it and send it off to p5p.

Best,

David



smime.p7s
Description: S/MIME cryptographic signature

Re: Assume CP1252

[David E. Wheeler]

On Jan 13, 2015, at 10:31 AM, Karl Williamson pub...@khwilliamson.com wrote:

 What Perl does to handle this is to simple swap the NEL and LF code points.  
 That makes \n mean NEL instead of LF.  Apparently LF is unused in EBCDIC 
 applications, so it works.  There is official support for this swap, as 
 Unicode's definition of how to get UTF-8 to work on EBCDIC platforms says to 
 do the swap.

Huh. Good to know (and have it documented now!).

 It does mean that NL doesn't mean the character that a native EBCDIC speaker 
 would think.
 
 But the bottom line is that because of this character swapping, the NEL 
 characters in EBCDIC appear as \n, so aren't a problem for CP1252.

Nice. So should we then adopt the same pattern as the HTML 5 spec?

And I wonder if that W3 spec issue you pointed to the other day could use a 
comment to this effect.

Best,

David



smime.p7s
Description: S/MIME cryptographic signature

Re: Assume CP1252

[David E. Wheeler]

On Jan 12, 2015, at 11:18 AM, Karl Williamson pub...@khwilliamson.com wrote:

 To be clear, I think that assuming 1252 when there is no =encoding
 line is a good idea.  But I'm leery of overriding an actual =encoding
 line.
 
 Agreed.

I’m okay with this.

 I could possibly be persuaded, if someone want to make it, by the argument 
 that 'latin1' is kind of colloquial, and someone using it may very well not 
 be familiar with the possibility that they really mean cp1252.  But, if so, 
 there needs to be a way for someone to say I really mean it and not be 
 overridden by us.  Perhaps
 that could be =encoding ISO-8859-1.

If we *were* to assume CP1252 for Latin-1, I would want it to be consistent 
with the precedent set by the W3C. Sean supplied this link:

  http://www.w3.org/TR/encoding/#names-and-labels

Here’s the list of labels that they translate to Windows-1252:


ansi_x3.4-1968
ascii
cp1252
cp819
csisolatin1
ibm819
iso-8859-1
iso-ir-100
iso8859-1
iso88591
iso_8859-1
iso_8859-1:1987
l1
latin1
us-ascii
windows-1252
x-cp1252

In their interpretation, no label ever resolves to iso-8859-1. Pretty 
interesting.

 Q: What if there is more than one =encoding line? Does it switch
 encoding part way thru a POD?
 
 
 
 Error while formatting with Pod::Perldoc::ToMan:
 Nested processed encoding. at /usr/share/perl/5.18/Pod/Simple/BlackBox.pm 
 line 380.

I recently changed this error, because that was a pretty useless message. The 
new message is Cannot have multiple =encoding directives. Also, it is no 
longer fatal, but is passed to scream(), which means it would be a failure for 
Test::Pod, but won’t break tools that generate docs.

  http://github.com/theory/pod-simple/commit/cb884b5

Best,

David



smime.p7s
Description: S/MIME cryptographic signature

Re: Assume CP1252

[David E. Wheeler]

On Jan 10, 2015, at 5:48 PM, Sean Burke sbu...@cpan.org wrote:

 Helleu, Pod pals!
 Short version about Re: Assume CP1252-- I advise: yes, assume CP1252 where 
 technically you were expecting Latin-1.

Thanks for chiming in, Sean.

 I agree completely, go for it!
 
 Yes:
 * assume that input is CP1252 in the absence of any encoding being declared
 * assume that input is CP1252 if the declared encoding is Latin-1
 
 As far as I know, that amicable bait-and-switch (i.e., construing Latin-1 to 
 actually mean the superset CP1252) means in practice that everybody wins, and 
 nobody loses, and DWIM prevails yet again.

Right, I vaguely remember you telling me this before. I forgot about #2 (and 
the HTML 5 precedent).

 BTW: I think many people would appreciate having =encoding ansi tolerated 
 as a synonym for =encoding win-1252... because some systems simply call it 
 that-- and I can never remember 1252 vs 1250 vs my own zipcode vs last four 
 digits of my Antarctican passport, etc.

ansi == cp1252??

I think Encode determines aliases.

 Incidentally, you presumably might want to expand the %Latin1Code_to_fallback 
 table in Pod::Escapes.

Paging Neil Bowers.

 Now, there's two issues that may or may not be already seen as separate:
 * assuming that input is CP1252 in the absence of any encoding being declared
 * assuming that input is CP1252 if the declared encoding is Latin-1
 I suggest doing both (like HTML5)-- but at least the first definitely!

+1

 If anyone wants extreme SM, maybe a throw a note in WARNINGS about I 
 expected this to be in Latin-1 but it looks like maybe you should probably 
 have a '=encoding win1252' line.
 But that seems a case of pointless and even onerous obtuseness, instead of 
 unproblematic DWIM.  I think.

Meh. I'm thinking, however, of adding a note to the ChangeLog for the next 
release that this change will be in the following release. I’ve already added a 
note that support for Perls  5.5 will be dropped.

 As to possible flaws, I see two that are on the very edge of remote 
 possibility.
 But, for sake of completeness, I'll note:

Pretty obscure!

 I hope this message has helped.
 REESE'S PIECES OUT.

Thanks again!

Best,

David




smime.p7s
Description: S/MIME cryptographic signature

Re: Allow Whitespace in L URLs?

[David E. Wheeler]

On Jan 9, 2015, at 3:25 PM, Kent Fredric kentfred...@gmail.com wrote:

 Presently that format is quite useful when either URL or link text is very 
 large, and avoids tripping some
 line-length metrics that can't otherwise easily be satisfied in a non-global 
 manner.

I’m not proposing to remove current functionality, just not to add new 
functionality.

Best,

David



smime.p7s
Description: S/MIME cryptographic signature

Re: Allow Whitespace in L URLs?

[David E. Wheeler]

On Jan 8, 2015, at 1:07 PM, David E. Wheeler da...@justatheory.com wrote:

 IIUC, the case that came up was
 
Lfoo bar|http://baz.com/foo
bar
 
 I am kind of inclined to just say that such things are verboten.

Done by closing this issue. https://rt.cpan.org/Ticket/Display.html?id=93491

 However, ticket 95710 offers up this example:
 
LDEMO with NL|
/DEMO and trailing text
 
 It’s not just URLs that we need to decide how to deal with, I guess.

I think this one should be rejected, too. Really, there should be no whitespace 
on either side of the |, and no newlines at all inside L. Any objections?

Best,

David




smime.p7s
Description: S/MIME cryptographic signature

Re: Pod::Simple can treat binary as pod due to liberal/inconsistent regexp patterns

[David E. Wheeler]

On Jan 7, 2015, at 10:18 PM, Marek Rouchal ma...@rouchal.net wrote:

 IIRC the first liberal rx is to detect start of POD just like the Perl 
 (language) parser does, i.e. it pauses parsing for instructions until the 
 next =cut

Oh. Can someone dig into the Perl parser and confirm this?

 I think POD parsers should do the same.

My suspicion is that, even if that’s true, the Parser ignores everything in a 
__DATA__ or __END__ block.

Anyway, even if Perl is more lenient, that doesn’t mean a Pod parser needs to 
be. What is and is not valid Pod is quite well-defined in perlpodspec, so I 
suspect taht we can afford to be a bit stricter.

 If the matched pod-start sequence does not match any of the known commands, 
 it's an error condition, and we should discuss what to do then, like 
 - throw exception 
 - print error and/or call error callback
 - warn and treat the content as a plain text paragraph

It might be valid Perl.

my $foo = q{
=sîî
};

So I think it would be better just to be stricter in what we consider to be Pod.

Best,

David



smime.p7s
Description: S/MIME cryptographic signature

Allow Whitespace in L URLs?

[David E. Wheeler]

Poders,

RT #93491 (https://rt.cpan.org/Ticket/Display.html?id=93491) reports that URLs 
are mis-formatted when they contain a newline. Turns out, the regex that 
detects a URL in L explicitly forbids whitespace:

next unless $ell-[$_] =~ m/^(?:([^|]*)\|)?(\w+:[^:\s]\S*)$/s;

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

I think that is probably sane, but maybe there are other opinions? Should we 
allow whitespace in L URLs? If so, I think we would just change \S to .

Thoughts?

David



smime.p7s
Description: S/MIME cryptographic signature

Re: Allow Whitespace in L URLs?

[David E. Wheeler]

On Jan 8, 2015, at 1:00 PM, Ricardo Signes perl@rjbs.manxome.org wrote:

 I didn't scrutinize the regexp (which is present in perlpodspec) closely, but
 URLs may not contain unescape spaces, so I think there's no reason to allow 
 it.
 
  Lfoo bar|http://baz-barshould be okay
  Lfoo bar|http://baz barshould not
  Lfoo bar | http://baz-bar  unclear from quick skim of spec
 
 I assume the second case is what came up.  It's not a valid URI, by my reading
 of https://tools.ietf.org/html/rfc3986#appendix-A

IIUC, the case that came up was

Lfoo bar|http://baz.com/foo
bar

I am kind of inclined to just say that such things are verboten. However, 
ticket 95710 offers up this example:

LDEMO with NL|
/DEMO and trailing text

It’s not just URLs that we need to decide how to deal with, I guess.

David



smime.p7s
Description: S/MIME cryptographic signature

Re: Pod::Simple can treat binary as pod due to liberal/inconsistent regexp patterns

[David E. Wheeler]

On Jan 7, 2015, at 11:30 AM, Karl Williamson pub...@khwilliamson.com wrote:

 I asked David about the inconsistency and he asked that I bring it up here.
 
 Shouldn't the more strict regexp be used in both places?
 
 I think so.  Looking at the regexes though, I didn't know that directives 
 could be capitals, and I thought that digits had to always be the last 
 character (or characters ?) in a directive.  It seems to me that both regexes 
 should be tightened.

perlpodspec says:

 Pod content is contained in Pod blocks. A Pod block starts with a line
 that matches m/\A=[a-zA-Z]/, and continues up to the next line that
 matches m/\A=cut/ or up to the end of the file if there is no
 m/\A=cut/ line.

I agree that’s too liberal. I suggest

/\A=([a-zA-Z]+\d*)\b/

 On the first pass the parser marks the line as pod (presumably matching
 a directive)
 but on the second pass the line doesn't match any patterns and it all
 falls through as a paragraph.
 
 This inconsistency allows binary data to be treated as a pod document.
 Is there a recommended way to parse the pod out of a document that might
 have binary data in it?
 
 I don't know about this.

It seems to me that if the second match does not think it is Pod, then it 
should not be a paragraph (unless it was already in a pod section from a 
previous declaration). I suspect that if we tighten up the first regex as I 
suggest year, and sync the second with it, we should be okay. Thoughts?

Best,

David



smime.p7s
Description: S/MIME cryptographic signature

Assume CP1252

[David E . Wheeler]

Pod Peeps:

perlpodspec says:

   *   Since Perl recognizes a Unicode Byte Order Mark at the start of files
   as signaling that the file is Unicode encoded as in UTF-16 (whether
   big-endian or little-endian) or UTF-8, Pod parsers should do the same.
   Otherwise, the character encoding should be understood as being UTF-8
   if the first highbit byte sequence in the file seems valid as a UTF-8
   sequence, or otherwise as Latin-1.

I suggest we switch from Latin-1 to CP1252. The reasons are:

* CP1252 is effectively a superset of Latin-1.

* Sometimes characters valid in CP1252 but not in Latin-1 appear in Pod, 
typically curly quotes or m-dashes or similar pasted from Word. The usual 
suspects are listed in this table:

 
http://search.cpan.org/dist/Encode-ZapCP1252/lib/Encode/ZapCP1252.pm#Conversion_Table

* By assuming CP1252 instead of Latin-1, such characters would be properly 
decoded when parsing Pod, thus making them come out right in the resulting 
outputs. Latin-1 should be unaffected.

So I think it would get better output for those documents that include special 
Windows characters, without side effects. We would just get a little more stuff 
to be output properly. I’ve discussed this with Sean Burke in the last couple 
years, and IIRC he said he probably should have assumed CP1252 instead of 
Latin-1 when he wrote it. It’s coming up again now because Karl Williamson has 
been improving the EBCDIC support recently, which is the same bit of code (it’s 
all about encodings, you know?), so this would be a natural time/place to do it.

But not if there are flaws with the plan. Thoughts? Should we make this change? 
Seems like a win overall to me, but I miss details all the time. Let me know 
your thoughts.

Best,

David



smime.p7s
Description: S/MIME cryptographic signature

Re: intermittent failure of cpan/Pod-Simple/t/search50.t

[David E. Wheeler]

On Sep 19, 2013, at 4:50 AM, Dave Mitchell da...@iabyn.com wrote:

 I don't really understand whether:
 
 1) search50.t has unreasonable expectations;
 2) Pod::Simple::Search::survey() should be returning 'Pod::perldoc' as the
name rather than 'perldoc';
 3) perldoc.pod should be installed as lib/perldoc.pod rather than
lib/Pod/perldoc.pod;
 4) something in the content of perldoc.pod is wrong, and that is confusing
Pod::Simple::Search.

Neither do I. The search stuff is a bit of a black box to me. That test has 
failed a bunch of times on case-insensitive file systems, too, which drove me 
nuts until I figured it out and fixed it.

  
https://github.com/theory/pod-simple/commit/2e1cee24c9fe013729880de83bb5765a431886e3

It also used to get confused by .pod files, which I fixed here:

  
https://github.com/theory/pod-simple/commit/77391b2f2cf4268608ba9e6a2ccc44f3f9776cdf

Are these the correct fixes? I have no idea. I don’t use the search stuff 
myself, and have no idea how it’s supposed to work.

Maybe we can ask Sean?

 Independently of that, perhaps that test file should check all pod files
 rather than just one at random, to make errors easier to spot?

That sounds like a good idea. How does this work for you?

  
https://github.com/theory/pod-simple/commit/b174dd0927d672ce3a10b1626f4004a8276fa449

Best,

David

Re: Recent pod

[David E. Wheeler]

On Feb 24, 2013, at 12:57 PM, H.Merijn Brand h.m.br...@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 Cs.

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

David

Re: Recent pod

[David E. Wheeler]

On Feb 25, 2013, at 9:20 AM, Russ Allbery r...@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

[David E. Wheeler]

On Feb 25, 2013, at 9:36 AM, Allison Randal alli...@perl.org wrote:

 Those are all pretty weird hacks, and make for ugly Pod.

I find most Pod ugly, anyway. But I use C all the time in such situations.

 Can the level
 of strictness on =item checking be made configurable? Like, in
 _ponder_paragraph_buffer, check !$self-{'allow_mixed_items'} before
 whining?

I suppose someone could make that change, but then would Test::Pod have to be 
updated to pass through that configuration, as well?

Best,

David

Re: Should Pod::Simple test for repeated elements in a dl

[David E. Wheeler]

On Feb 13, 2013, at 5:01 PM, Karl Williamson pub...@khwilliamson.com wrote:

 Shall I create a ticket for this?

Sure. I will likely mark it as stalled until a patch comes in, though. But 
yeah, best not to let it fall through the cracks.

Best,

David

Re: Should Pod::Simple test for repeated elements in a dl

[David E. Wheeler]

On Jan 26, 2013, at 12:03 PM, Karl Williamson pub...@khwilliamson.com wrote:

 I do not propose warning for something like the above.  The warning would 
 only be for repeated uses of the exact same item name, like
 
 =item -
 
 =item -
 
 =item -

Oh, okay. Works for me.

David

Re: How do I get Pod::Simple to extract pod from its containing file?

[David E. Wheeler]

On Jan 26, 2013, at 8:49 AM, Karl Williamson pub...@khwilliamson.com wrote:

 With Pod::Parser, you just do
   parse_from_file($in_fh, $out_fh)
 
 and it outputs the pod to $out_fh.  Pod::Simple has a method of the same name 
 which is supposed to emulate the Pod::Parser method, but when I run it, 
 nothing is output.

Code looks okay. I don't see a test case, though. Care to add one?

David

Re: Pod::Simple doesn't warn when the text of a definition =item matches /[\*\d]/; and a fix to this bug

[David E. Wheeler]

On Jan 18, 2013, at 7:31 AM, Ricardo Signes perl@rjbs.manxome.org wrote:

 I hope we can agree that if the test results bit gets sorted out, we're in
 favor of this warning..?
 
 I have submitted https://github.com/theory/pod-simple/pull/44

+1. Will merge it if there are no objections.

 I also had the idea, mentioned in the commits, that we could consider 
 replacing
 the XML output for testing with JSON output.  This would make it easier to 
 test
 subsections and identify structural differences, since we have a JSON parser 
 in
 core but not an XML parser.

Good idea, though it will require that older versions of Perl install a JSON 
parser just to run the tests…

David

Re: Pod::Simple doesn't warn when the text of a definition =item matches /[\*\d]/; and a fix to this bug

[David E. Wheeler]

On Jan 18, 2013, at 10:09 AM, Ricardo Signes perl@rjbs.manxome.org wrote:

 I believe it could be bundled, and would be worth the hassle.  Maybe. :-)

Well, if it's a hassle someone else wants, great! :-)

David

Re: Allow =over 0?

[David E. Wheeler]

On Oct 10, 2012, at 1:42 PM, Grant McLean gr...@mclean.net.nz wrote:

 is a bit bogus because the formal specification for POD is in 'perldoc
 perlpodspec' which says:
 
If there is any text following the =over, it must consist of
only a nonzero positive numeral.
 
 So a change to Pod::Simple would need to be accompanied by a change to
 perlpodspec.

Great point, thanks.

David

Allow =over 0?

[David E. Wheeler]

Pod People,

See the forwarded complaint below. Should we allow `=over 0`? I tend not to 
think of it as the same as `=over`, because that is the same as `=over +=4`, 
IIRC.

Best,

David

Begin forwarded message:

 From: K. Wittrock via RT bug-pod-sim...@rt.cpan.org
 Subject: Re: [rt.cpan.org #79932] Invalid POD Error message
 Date: October 10, 2012 6:06:04 AM PDT
 To: undisclosed-recipients:;
 Reply-To: bug-pod-sim...@rt.cpan.org
 
   Queue: Pod-Simple
 Ticket URL: https://rt.cpan.org/Ticket/Display.html?id=79932 
 
 
 
 Am 02.10.2012 18:02, schrieb David Wheeler via RT:
 URL: https://rt.cpan.org/Ticket/Display.html?id=79932 
 
 On Sep 30, 2012, at 9:06 AM, K. Wittrock via RT bug-pod-sim...@rt.cpan.org 
 wrote:
 
 In addition to modules that are distributed with perl, this program
 needs the following modules (available from CPAN):
 
 =over 0
 
 Just use `=over` instead.
 
 POD is a widely used tool for writing documentation for Perl modules. So I 
 think that any module that processes Pod should accept _any_ POD text that 
 conforms to the POD syntax as documented in perldoc POD. In addition, new 
 modules that are subclassed from Pod::Simple::HTML don't like to inherit this 
 misbehavior. But it's really hard to remedy this from the outside.
 
 On the other hand, you as the author can easily remove this invalid error 
 message. Simply delete lines 1180 to 1186 of Pod::Simple::BlackBox, which read
 if($1 == 0) {
   $self-whine(
 $para-[1]{'start_line'},
 Can't have a 0 in =over $content
   );
   $para-[1]{'indent'} = 4;
 }
 
 And then the text of the error message in line 1190
   =over should be: '=over' or '=over positive_number'
 might be adapted a bit.
 
 I do hope that you may get to like my arguments.
 
 A friend of mine wrote to me some additional arguments which I try to 
 translate to English (although I don't know what he is talking about):
 
 It would be sufficient when the parser wouldn't complain about =over 0 and 
 would set the indentation to 0. When in addition this would be used by the 
 HTML converter for setting a fitting class=OverNumber0 class=OverBullet0 
 at ol and ul, then I could format this appropriately with CSS. This can 
 be easily done with sprintf: 'over-number' = 'ol class=OverNumber%d' - 
 sprintf($tagmap-{'over-number'},$token-{'indent'}). As far as I can see the 
 expenditure wouldn't be very heigh.
 
 Kind regards
 
 Klaus
 
 

Re: The Encoding Warning (Again) - some data

[David E. Wheeler]

On Aug 27, 2012, at 9:03 PM, Grant McLean wrote:

 My opinion is that the warning is useful.  However to be pragmatic, now
 that the encoding detection heuristic has been implemented, adding
 =encoding declarations to any of those 1215 distributions will have no
 practical effect other than silencing the warning.  That's the best
 argument I can come up with in favour of changing the status quo.

Well, that and you ensure that the proper encoding is selected (assuming the 
developer knows how to encode things properly).

 On a tangentially related note, I was pondering whether the heuristic
 should actually fall back to CP1252 rather than ISO8859-1 - after all
 that's what the W3C recommend:
 
  http://www.w3.org/TR/html5/parsing.html#character-encodings-0
 
 However my statistics show that only 44 files in current releases were
 detected as Latin-1 but actually contained CP1252 (typically smart
 quote symbols in the \x80-\x9F range).  So it doesn't seem worth
 pursuing that change.

You could assume CP1252 if characters are found in that range and Latin-1 
otherwise.

 Finally I searched for files which were detected as UTF-8 but actually
 contained characters from the CP1252 range.  There was only one and it
 wasn't an error in the detection, the source file contains a
 double-encoded character. It was a mangled attempt to name a contributor
 - Slaven Resić   :-)

Coincidence I’m sure!

Best,

David

The Encoding Warning (Again)

[David E. Wheeler]

Pod People,

In https://rt.cpan.org/Ticket/Display.html?id=79232, Saven Rezic writes:

 Pod::Simple currently (e.g. with version 3.23) complains if a Pod
 document has latin-1 characters in it but no =encoding command
 specified. I think this is incorrect, both perlpod.pod and
 perlpodspec.pod specify that a document without =encoding command is in
 latin-1:
 
 perlpod.pod (as of commit 684c7e375f581ccd114b4c6b4e8ea730402b50f3 in
 perl):
 
 =encoding encoding
 
 ... Most users won't need this; but if your encoding isn't US-ASCII
 or Latin-1 ...
 
 perlpodspec.pod (as of commit c85e9b4c9684bc896847f5a80e9e91b478c2fc59
 in perl):
 
 ... Otherwise, the character encoding should be understood as being
 UTF-8 if the first highbit byte sequence in the file seems valid as
 a UTF-8 sequence, or otherwise as Latin-1.
 
 (Unfortunately perlpodspec.pod isn't quite clear about this when
 explaining encoding; the quoted paragraph is from the Notes on
 Implementing Pod Processors section.

None of this says anything about warnings, and it does seem that, as of 3.23, 
this is exactly how Pod::Simple behaves (or will once 
https://github.com/theory/pod-simple/pull/40 is merged).

Thoughts?

David

Fwd: Topic/metacpan.org (#36)

[David E. Wheeler]

Pod People,

I got a pull request to switch to metacpan.org for L http links. AFAIK 
search.cpan.org is not deprecated, and is still the official community CPAN 
search site. If there is some discussion about changing it, or if Graham thinks 
it's time to switch then great. Otherwise, I am not inclined to accept this 
patch (though if it is hard to change the default URL with a subclass I would 
be happy to take that, or a command-line option).

But I thought it ought to be subject to discussion here before I make any 
unilateral (and potentially uninformed) decisions. Comments?

Thanks,

David

Begin forwarded message:

 All L markup now uses metacpan.org instead of search.cpan.org, as per this 
 misfiled ticket: https://rt.perl.org/rt3/Public/Bug/Display.html?id=114420
 
 I haven't talked to the metacpan folks about this yet though, so strictly 
 speaking the acknowledgements section regarding use of the site is still a 
 lie. That's to come. :)
 
 You can merge this Pull Request by running:
 
   git pull https://github.com/karenetheridge/pod-simple topic/metacpan.org
 Or view, comment on, or merge it at:
 
   https://github.com/theory/pod-simple/pull/36
 
 

Re: Topic/metacpan.org (#36)

[David E. Wheeler]

On Aug 13, 2012, at 11:10 AM, Ricardo Signes wrote:

 I don't think there's an official community, so I don't think we can have an
 official community site.

Don’t Ask and Robert manage the machines that search.perl.org is on? Or is that 
just DNS?

 I switched all my Pod-to-HTML stuff, like dzil.org's engine, the Perl Advent
 calendar, and perl release announcements, to using metacpan some time ago.
 metacpan is open source and can be contributed to with patches, which means, 
 to
 me, that it's more likely to be a community effort than search.cpan.org.
 
 So, I am in favor of the change.  Rejecting it isn't a big deal, I think, but 
 I
 predict that it will just end up being accepted in the future.

Could be. But I think the ability for users to easily supply whatever URL they 
want would be better. Then it would matter less (and I suspect that Graham 
would have to change the search.cpan.org code so that its URLs are still local).

Best,

David

Re: Possible patch to Test::Pod

[David E. Wheeler]

On Jun 8, 2012, at 11:05 AM, Russ Allbery wrote:

 I think you're too pessimistic about the level of skill of people
 installing CPAN modules.  We all hear primarily from the users who are
 confused, but I think a lot of people just quietly use CPAN and don't tend
 to talk to us a lot, and if the only test failure is something like
 docs/pod.t, I suspect they can draw the obvious conclusions.

Yeah, and they already know about `force install`, too.

I have no objection to adding a message, though I would get tired of seeing it 
in a very short period of time.

David

Re: Add handle_code() method to Pod::Simple::XHTML

[David E. Wheeler]

On May 4, 2012, at 1:01 AM, Gisle Aas wrote:

 Text::Wrap was already in the prereqs.  I did not realize this before :-)
 
  https://github.com/theory/pod-simple/pull/28

Cool, thanks.

David

Re: Add handle_code() method to Pod::Simple::XHTML

[David E. Wheeler]

On Apr 30, 2012, at 1:54 PM, Gisle Aas wrote:

 It's a result of the not-totally-brilliant wrapping algorithm in 
 Pod::Simple::DumpAsXML.  When it can't gobble at least 55 chars it produce 
 strange results on the next line.  I reworked by patch series after replacing 
 it with Text::Wrap in:
 
  
 https://github.com/gisle/pod-simple/commit/8a084ce49d6c513bdc0bf4e3a7c59ab99485f216#diff-0
 
 Now the test suite change in the join-patch is more sane:
 
  
 https://github.com/gisle/pod-simple/commit/bb255b816757f601e9cc2a01c2b7d53026fa173c
 
 The full new series is found at:
 
  https://github.com/gisle/pod-simple/commits/master
 
 Should I send you a github pull request for this?

Add Text::Wrap to the prereqs in Makefile.PL and I say +1.

David

Re: Non-ASCII data in POD

[David E. Wheeler]

On Apr 27, 2012, at 12:10 AM, Grant McLean wrote:

 OK, so I went ahead and implemented both the warning and the heuristic
 to guess Latin-1 vs UTF-8 (only when no encoding was specified).  The
 resulting patch is here:
 
  https://github.com/theory/pod-simple/pull/26

I like this, but wonder if maybe it shouldn't be consistent? That is, if you 
see more than one of these in a single document, and one can be output as UTF-8 
and the other can’t, would the resulting output have mixed encodings? IOW, 
should it not perhaps use the encoding it determined for the first one of these 
it finds in a document?

Best,

David

Re: Non-ASCII data in POD

[David E. Wheeler]

On Apr 27, 2012, at 12:54 PM, Grant McLean wrote:

 I'm not sure I quite understand what you're saying.  The first time a
 non-ASCII byte is encountered, the code will 'fire' and apply the
 heuristic to set an encoding.  Once the encoding is set, the code won't
 be called again.

Oh, perfect. I missed that.

 The perlpodspec seems pretty clear that a POD document containing
 different encodings should be considered an error.

As it should be.

David

Re: pod2html in perl-5.15.9 recognizes POD markup in verbatim sections

[David E. Wheeler]

On Apr 24, 2012, at 2:46 PM, chromatic wrote:

 Any objections?
 
 Yes; I use this feature.

Better to make it an option in pod2html to turn it off. Or perhaps it turns it 
off by default, and you need an option to turn it on.

Best,

David

Re: [rt.cpan.org #74389] Pod::Simple::Pullparser get_title should ignore X...

[David E. Wheeler]

On Mar 2, 2012, at 6:49 AM, Karl Williamson wrote:

 • Pod::Simple::HTML needs to be fixed so that it does not include the 
 contents of X
 • The parser overall should be adjusted to remove superfluous whitespace
 
 FWIW, I could use confirmation on this.
 
 What sort of confirmation do you need?  I agree with the two bulleted items, 
 if you're looking for that kind of confirmation.

Just wanted to make sure I correctly understood the consensus. I’ve added those 
two items to the ticket.

  https://rt.cpan.org/Ticket/Display.html?id=74389

Best,

David

Re: [rt.cpan.org #74389] Pod::Simple::Pullparser get_title should ignore X...

[David E. Wheeler]

On Jan 29, 2012, at 3:15 PM, David E. Wheeler wrote:

 And NAME and not NAME 
 
 It should probably not just become an empty string, but it should be collapse
 whitespace around it, so pathological cases like:
 
 =head1 NAME Xfoo THIS Xbar TUNE
 Xbaz
 
 ...should be NAME THIS TUNE
 
 But in the simpler case, I think that NAME and not NAME  is actually 
 likely
 to come up.
 
 Okay, so if I follow this thread correctly, the upshot is that:
 
 • Pod::Simple::HTML needs to be fixed so that it does not include the 
 contents of X
 • The parser overall should be adjusted to remove superfluous whitespace

FWIW, I could use confirmation on this.

Meanwhile, here's a test case showing the original bug with PullParser:

diff --git a/t/pulltitl.t b/t/pulltitl.t
index 22934f5..a846048 100644
--- a/t/pulltitl.t
+++ b/t/pulltitl.t
@@ -7,7 +7,7 @@ BEGIN {
 
 use strict;
 use Test;
-BEGIN { plan tests = 116 };
+BEGIN { plan tests = 117 };
 
 #use Pod::Simple::Debug (5);
 
@@ -408,6 +408,13 @@ ok( $t  $t-type eq 'start'  $t-tagname, 'Document' );
 }
 
 ###
+print # Testing a title with an X, at line , __LINE__, \n;
+my $p = Pod::Simple::PullParser-new;
+$p-set_source( \qq{\n=head1 NAME\nXSome entry\n} );
+
+ok $p-get_title(), 'NAME';
+
+###
 ###
 
 

That fails with:

not ok 116
# Test 116 got: NAME Some entry (t/pulltitl.t at line 415)
# Expected: NAME
#  t/pulltitl.t line 415 is: ok $p-get_title(), 'NAME';

So it seems as though X issues my be all over the place, eh?

Best,

David

Re: Scrunched up string literals in Pod::Simple tests

[David E. Wheeler]

On Feb 20, 2012, at 4:30 PM, Sean M. Burke wrote:

 (As with vast vast areas of my life, I have to mark this unbar and no_nls 
 things as another (now decade-old) pesky occurrence of: Now, you'd THINK 
 that I would have thought of that!)
 
 
 But whether the subject is myself, or anything else in the world, I have 
 noticed that the phrase Now, you'd THINK... have had a pretty sad track 
 record lately AMIRITE??

You are far from alone there, sir.

Best,

David

Re: Deprecation of alternate text in hyperlinks

[David E. Wheeler]

On Feb 20, 2012, at 7:33 PM, Sean M. Burke wrote:

 I kinda passed off perlpodspec to... whoever...
 I'm pretty sure I did, to somebody….

I believe it is now part of the core Perl distribution; I don't believe it 
ships with Pod::Simple anymore. Which I think is the right thing to do.

 But I'll chip in about Lguh|http://... in perlpodspec.

It has been in for a couple of years now, and I've heard no complaints. :-)

David

Re: [rt.cpan.org #74389] Pod::Simple::Pullparser get_title should ignore X...

[David E. Wheeler]

On Jan 25, 2012, at 6:00 PM, Ricardo Signes wrote:

 =head1 NAME
 XSome entry
 
 Pod::Simple::Pullparser get_title expands 'Some entry' in the title.  It
 seems to me that it should not, and instead should replace it with an 
 empty string.  This  behaviour is also hinted in the pod documentation.
 
 It becomes h1NAME Some Entry/h1?  That would certainly be an error.

No, it doesn't. Text:

 air ~ perl -MPod::Simple::Text -E 
 'Pod::Simple::Text-filter(\=pod\n\n=head1 NAME\nXSome entry)'   
 NAME 

XHTML:

 air ~ perl -MPod::Simple::XHTML -E 
 'Pod::Simple::XHTML-filter(\=pod\n\n=head1 NAME\nXSome entry)'
 
 html
 head
 title/title
 meta http-equiv=Content-Type content=text/html; charset=ISO-8859-1 /
 /head
 body
 
 
 h1 id=NAMENAME /h1
 
 /body
 /html

HTML:

 air ~ perl -MPod::Simple::HTML -E 
 'Pod::Simple::HTML-filter(\=pod\n\n=head1 NAME\nXSome entry)' 
 htmlheadtitleNAME Some entry/title
 meta http-equiv=Content-Type content=text/html; charset=ISO-8859-1 
 /head
 body class='pod'
 !--
   generated by Pod::Simple::HTML v3.19,
   using Pod::Simple::PullParser v3.19,
   under Perl v5.014002 at Thu Jan 26 03:01:45 2012 GMT.
 
  If you want to change this HTML document, you probably shouldn't do that
by changing it directly.  Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
 
 --
 
 !-- start doc --
 a name='___top' class='dummyTopAnchor' /a
 
 h1a class='u' href='#___top' title='click to go to top of document'
 name=NAME
 NAME !--
   INDEX: Some entry
 --/a/h1
 
 !-- end doc --
 
 /body/html

Best,

David

Re: Deprecation of alternate text in hyperlinks

[David E. Wheeler]

On Jan 23, 2012, at 8:06 AM, Karl Williamson wrote:

 The new Pod:Parser has just been installed in blead, and about 10 pods run 
 afoul of this new check, including things like
 
 Lperl...@perl.org|mailto:perl...@perl.org
 
 My question is should there really be a message for this kind of use, and if 
 so, should it extend to mailto: links?

No. Suport for Lname|scheme:... was added to perlpodspec in 2009. Pod::Simple 
has supported it for years; Test::Pod started officially allowing it in v1.41, 
IIRC.

Relevant changes:

  
https://github.com/theory/pod-simple/commit/1e61e819debf9c7c23907d7bb9e37855665fd595
  
http://perl5.git.perl.org/perl.git/commit/f6e963e4dd62b8e3c01b31f4a4dd57e47e104997
  
https://github.com/theory/test-pod/commit/ae6a44894eda4fd09fb412d837efe543628cd7d6

Discussion:

  http://code.activestate.com/lists/perl-pod-people/1393/

Best,

David

Re: Deprecation of alternate text in hyperlinks

[David E. Wheeler]

On Jan 23, 2012, at 9:26 AM, Karl Williamson wrote:

 So, you're saying I believe the text in perlpodspec that was the motivation 
 for these changes should be removed, and that Pod::Parser should revert to 
 its old behavior of not checking for this.
 
 Is that so?

I can’t parse that sentence, but if you’re asking if this bit should be removed:

 Authors wanting to link to a particular (absolute) URL, must do so
 only with LEltscheme:... codes (like
 LElthttp://www.perl.org), and must not attempt LEltSome Site
 Name|scheme:... codes.  This restriction avoids many problems
 in parsing and rendering LElt... codes.

Then the answer is “yes.” And Pod::Parser should be modified to allow or 
support Ltext|scheme:.

Best,

David

Re: [Fwd: question about Pod::Simple::HTMLBatch .css generation]

[David E. Wheeler]

On Jun 18, 2011, at 6:08 PM, Sean M. Burke wrote:

 When I look at the stylesheet _blkblux.css (which is the default .css,
 and the best-looking option of the batch IMO) All it has in it is this:
 
 
 
 /* This file is autogenerated.  Do not edit.  blkbluw */
 
 
 
 @import url(./_blkbluw.css);
 
 .indexgroup { display: none; }
 
 
 
 Which doesn't do much by way of making my HTML look nice
 
 
 
 Can you enlighten me as to what's going on here.  Is this an error, or a
 feature that I don't understand?

Just reviewing the Pod::Simple bug queues and saw this:

  https://rt.cpan.org/Ticket/Display.html?id=70848

Is that a related issue?

Thanks,

David

Re: Removal of specific Pod::Checker warnings

[David E. Wheeler]

On Aug 12, 2011, at 9:17 AM, Karl Williamson wrote:

 I agree with this that there shouldn't be a warning if there are things 
 within the =over/=back that aren't =item's.  I'm not sure about if there is 
 only white space.  I could be persuaded it is a useful warning, which Marc 
 was originally going to implement; or I could be persuaded it is not worth 
 warning about.  The Perl core has several cases where machine-generated pods 
 have empty =over/=back sections.  These mean only that there was a potential 
 section that the generating code wasn't smart enough to realize was empty 
 here, and omit the surrounding pod directives.

I think warning on a completely empty =over/=back block is reasonable.

 Just FYI, I implemented several additional checks in the core's pod test 
 program, podcheck.t, that I think may warrant being used everywhere. These 
 are:
 Should have =encoding statement because have non-ASCII
 =encoding must be first command (if present)
 There is no NAME

Can one not change the encoding throughout a document by using multiple 
=encoding tags? This tag just means everything after this tag is in the named 
encoding.

Er, reading perlpodspec:

A document having more than one =encoding line should be
considered an error.  Pod processors may silently tolerate this if
the not‐first =encoding lines are just duplicates of the first
one (e.g., if there’s a =encoding utf8 line, and later on another
=encoding utf8 line).  But Pod processors should complain if
there are contradictory =encoding lines in the same document
(e.g., if there is a =encoding utf8 early in the document and
=encoding big5 later).  Pod processors that recognize BOMs may
also complain if they see an =encoding line that contradicts the
BOM (e.g., if a document with a UTF−16LE BOM has an =encoding
shiftjis line).

That seems like an unnecessary limitation to me, though it is perhaps sanest.

Anyway, I think it might be worth integrating such changes into Pod::Checker 
later. Maybe once Marc's done with the conversion to Pod::Simple you'd like to 
adapt podcheck.t to use it?

Best,

David

Re: Removal of specific Pod::Checker warnings

[David E. Wheeler]

On Aug 11, 2011, at 7:37 AM, Russ Allbery wrote:

 =item without any parameters is deprecated. It should either be followed by
 * to indicate an unordered list, by a number (optionally followed by a dot)
 to indicate an ordered (numbered) list or simple text for a definition
 list.
 
 perlpodspec states Pod processors must tolerate a bare =item as if it
 were =item *. Is Pod::Checker's behavior still in line with
 perlpodspec?  Is the use of '=item' without any parameters deprecated?
 Or should that warning be removed from Pod::Checker?
 
 I'd remove it.  It seems like a style thing to me, and while I personally
 prefer =item *, I don't see a good reason to require that.

+1

 Given that there is clearly a use for =itemless =over/=back blocks,
 should it still be a warning? I think no, and instead, Pod::Checker
 should warn about an empty =over/=back block, one that contains nothing
 but whitespace.
 
 I agree -- this one should definitely go.

+1

I had no idea one could do block quotes like this. Seems a bit too overloaded, 
frankly (what if I want my block quote to contain a list, just nest them?), but 
if the spec says that's what it is, then I wouldn't warn about it.

Best,

David

Fwd: [pod-simple] Calling _handle_text (#7)

[David E. Wheeler]

Begin forwarded message:

 From: ambs 
 reply+i-1041872-43ac1bf5621187c7c03e55951be2df1629b34...@reply.github.com
 Date: June 11, 2011 7:41:28 AM PDT
 To: da...@justatheory.com
 Subject: [pod-simple] Calling _handle_text (#7)
 

 Hello.
 
 I am hacking `Pod::PseudoPod::LaTeX` and found out a strange behavior that 
 seems to be related with `Pod::Simple::BlackBox`, but it's been difficult to 
 track the correct place where to fix it. So, some help (guidance or 
 correction) is appreciated.
 
 The problem: consider this pod block...
 
=over
 
=item * Some text
 
Some paragraph.
 
=back
 
 It seems that ``_handle_text`` is not being called to ``Some text`` nor 
 ``Some paragraph`` text. Therefore, ``Pod::PseudoPod::LaTeX`` method that 
 should encode special characters to LaTeX is not being called.
 
 Thank you for any hint or direction.
 
 All the best,
 ambs
 
 -- 
 Reply to this email directly or view it on GitHub:
 https://github.com/theory/pod-simple/issues/7

Re: [pod-simple] Calling _handle_text (#7)

[David E. Wheeler]

On Jun 11, 2011, at 9:20 AM, Marc Green wrote:

 It seems he realized it was a bug in his code just as soon as he opened the 
 issue, as per the comment onhttps://github.com/theory/pod-simple/issues/7

Hrm. Wonder why I didn't get an email for that.

Anyone know how to get GitHub to send issue emails to a different address? 
Might be useful to have Pod::Simple issues go to this list…

Thanks,

David

Re: Proposal for Pod::Simple::PDF

[David E. Wheeler]

On May 8, 2011, at 11:27 AM, Shawn H Corey wrote:

 Second, I'm not sure what to use for a base class.  The choices I'm looking 
 at are Pod::Simple, Pod::Simple::Methody, Pod::Simple::PullParser, and even 
 Pod::Simple::SimpleTree.  Is there anything special about these that I should 
 know?

I think that Pod::Simple::XHTML is the model you want to follow for writing 
formatting classes. At least, its approach is the easiest to get started with.

Best,

David

Fwd: Using UTF-8

[David E. Wheeler]

Begin forwarded message:

 From: Nadim Khemir na...@khemir.net
 Date: May 6, 2011 10:54:44 PM PDT
 To: David E. Wheeler da...@kineticode.com
 Subject: Re: Using UTF-8
 
 Add this to your pod:
=encoding utf8
 
 Hi, guys
 
 Shouldn't this be the default? and shouldn't it be made the default?
 
 Cheers, Nadim.

Re: pod2html and Pod::Simple [Was: Re: `=item 1. Text` Doesn't Produce Ordered List Item]

[David E. Wheeler]

On May 7, 2011, at 3:54 PM, Sean M. Burke wrote:

 Do you have any code for this lying around somewhere? Might help Marc Green, 
 our Google Summer of Code student, to get started on porting the Perl core 
 Pod tools from Pod::Parser to Pod::Simple…
 
 OK, found it,... I'm trying to make sure there isn't any MORE of it lying 
 around elsewhere, but I think I got it all.
 
 Anticipate!

Awesome. So is it more than just Pod::Simple::HTMLLegacy?

Anticipating!

David

Re: How to report a documentation error

[David E. Wheeler]

On May 6, 2011, at 7:55 AM, Shawn H Corey wrote:

 I noticed some errors in the documentation of Pod::Simple::HTMLBatch. Here's 
 one:
 
 % mkdir out_html
 % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go @INC out_html
  (to convert the pod from Perl's @INC
   files under the directory ../htmlversion)
 
 Shouldn't ../htmlversion be ./out_html ?
 
 What's the best way to report this?

Send it to bug-pod-sim...@rt.cpan.org. Or file it here:

  https://github.com/theory/pod-simple/issues

Thanks,

David

Re: Using UTF-8

[David E. Wheeler]

On May 6, 2011, at 4:40 PM, Shawn H Corey wrote:

 Does Pod::Simple understand UTF-8?  I have a POD with '½' in it but when I 
 run it through Pod::Simple::SimpleTree, I get '½'.  The UTF-8 code is C2 BD 
 which corresponds to  and ½ in ISO-8859-1. How do I turn on UTF-8?

Add this to your pod:

=encoding utf8

Best,

David

Re: Using UTF-8

[David E. Wheeler]

On May 6, 2011, at 5:10 PM, Shawn H Corey wrote:

 Some things are too obvious.  :)

Hey, I only learned about it by asking Sean years ago. I've used it a lot since 
then, though.

Best,

David

Re: pod2html and Pod::Simple [Was: Re: `=item 1. Text` Doesn't Produce Ordered List Item]

[David E. Wheeler]

On Jul 21, 2010, at 5:34 AM, Sean M. Burke wrote:

 Oh crap! I thought I fixed this years ago!
 Namely, I thought I had replaced the innards of pod2man and pod2html with 
 something that used Pod::Simple, since Pod::Simple is The Way, and that all 
 other parsing would be a difficult and confusing duplication of already 
 difficult and confusing effort, etc.

Hey Sean,

Do you have any code for this lying around somewhere? Might help Marc Green, 
our Google Summer of Code student, to get started on porting the Perl core Pod 
tools from Pod::Parser to Pod::Simple…

Thanks,

David

Re: pod2html and Pod::Simple

[David E. Wheeler]

On May 4, 2011, at 2:06 PM, Russ Allbery wrote:

 I know this is in the subject, but just to be clear, just in case, Sean
 Burke did indeed do the initial port of pod2man and pod2text to
 Pod::Simple, and that has been subsequently incorporated into podlators
 (which I maintain) and into Perl core, so pod2man and pod2text (and
 Pod::Man and Pod::Text) are good.  I assume this is only about pod2html.

Yes.

 There are tons of different POD to HTML conversion modules.  Rather than
 porting the one that happens to be in Perl core, it may be better to
 incorporate one of the other ones that already uses Pod::Simple and remove
 the old one.

I think we'd just use Pod::Simple::XHTML.

Best,

David

Re: no deprecation warning for Lsection

[David E. Wheeler]

On May 1, 2011, at 10:01 AM, Michael Stevens wrote:

 Is there going to be anywhere we can see progress / heckle?

I was just thinking that we ought to ask Marc to sign up for this list and have 
discussions here. Ric?

David

Re: no deprecation warning for Lsection

[David E. Wheeler]

On May 1, 2011, at 11:38 AM, Marc wrote:

 I was just thinking that we ought to ask Marc to sign up for this list and 
 have discussions here. Ric?
 
 Present and standing by ;)

Mac++

This is going to be great!

Best,

David

Re: Lack of html anchor for =item * foo

[David E. Wheeler]

On Apr 27, 2011, at 10:59 AM, Karl Williamson wrote:

 FWIW, Pod::Simple::XHTML doesn't output an ID fordts, either.
 
 The Perl core docs have roughly 700 links to dts.  For example, perlfunc 
 uses =item's for all its functions.

It'd be straight-forward to add it to the XHML output if someone wanted to hack 
it in. Maybe turn it on or off via an attribute. Probably should at least be 
submitted as a ticket to bug-pod-sim...@rt.cpan.org.

Best,

David

Re: Lack of html anchor for =item * foo

[David E. Wheeler]

On Apr 26, 2011, at 10:36 AM, Karl Williamson wrote:

 When I do a perldoc -ohtml, what module is getting called that does generate 
 an ID for dts ?

Pod::Simple::HTML, IIRC. Use

perldoc -MPod::Simple::XHTML

To get the shiny new HTML output.

Best,

David

Re: Blanks and underscores in html links

[David E. Wheeler]

On Apr 26, 2011, at 3:41 PM, Russ Allbery wrote:

 Everything up to the paragraph separator is part of the headline.
 
 Yeah, but they're still basically trailing whitespace.  I think this is a
 (minor) bug in whatever module generated that HTML.  It should strip
 trailing whitespace from the heading.

Hrm. I thought I fixed this.

  https://rt.cpan.org/Ticket/Display.html?id=56572
  
https://github.com/theory/pod-simple/commit/51a052ed53c52dc717e38e7685124a7e2023eb0

What version of Pod::Simple are you using?

Best,

David

Re: How can one put a table into a pod

[David E. Wheeler]

On Apr 25, 2011, at 8:09 PM, Karl Williamson wrote:

 However, in thinking about this some more, I think we need to be able to at 
 least specify centered column headings, and spans.  This is easily done with 
 html and tbl.

But they'er not Pod, are they?

Best,

David

Re: How can one put a table into a pod

[David E. Wheeler]

On Apr 25, 2011, at 8:39 PM, Russ Allbery wrote:

 Yes, but my assumption is that the discussion here is about inventing POD
 syntax to represent tables natively, and to do that we have to figure out
 what the requirements are and confirm that it's viable to convert such POD
 tables into our most common output formats.  Which is what I was assuming
 that Karl was doing.

Oh, okay. I'll STFU then.

Best,

David

Re: How can one put a table into a pod

[David E. Wheeler]

On Apr 23, 2011, at 6:38 PM, Karl Williamson wrote:

 That explains how to do it.  Thanks.  I would like something like this for 
 the core Perl 5 documentation.  Are there reasons besides inertia for this to 
 not be shipped with the Perl core?

Tuits. If you or someone else would like to propose an addition to perlpodspec 
for tables, I'm sure discussion would be welcome here, and we could come to 
some consensus on how it should work. Then it's a SMoP.

Best,

David

Re: How can one put a table into a pod

[David E. Wheeler]

On Apr 23, 2011, at 10:09 PM, Karl Williamson wrote:

 I was thinking that PseudoPod implemented most of what might be needed, and 
 so why not ship that.
 
 Its table spec looks quite simple, and perhaps sufficient.

+1

 tbl's is also pretty simple; it allows, without my looking at the 
 documentation, at least columns that have justification of left, center, and 
 the default 'alpha' which is essentially left, but I can't remember the 
 difference, and numeric, so the decimal points line up.  You can also create 
 spans, and bold, etc.

I expect one can use B and friends within PseudoPod tables, yes?

I do think we should keep Pod as Pod; troff is something else entirely.

 The other specification I'm familiar with is html, and it offers far more 
 power than needed.

Yeah, and one can always =begin html to do that.

Best,

David

Re: attempt to add whitespace warning

[David E. Wheeler]

On Feb 12, 2011, at 1:25 PM, Michael Stevens wrote:

 Hi.
 
 The attached patch tries to add the whitespace on empty line warning
 from Pod::Parser to Pod::Simple.
 
 I suspect this may need discussion, and may even be completely wrong! So
 submitting here rather than github or a job.
 
 Michael
 0001-Add-whitespace-on-empty-line-warning.patch

Anyone got an opinion on this? Michael also opened an RT for this and attached 
the patch there.

  https://rt.cpan.org/Ticket/Display.html?id=65921

I honestly have no idea if this is necessary. I mean, I know Pod::Parser was 
picky about whitespace appearing on blank lines, but I don't think that 
perlpodspec has an opinion on this. What say the rest of you?

Best,

David

Re: podchecker from Pod::Simple

[David E. Wheeler]

On Feb 2, 2011, at 6:46 AM, Michael Stevens wrote:

 Hi.
 
 Okay, this is the worst kind of hack, but:
 
 https://github.com/mstevens/pod-simple
 
 contains a podchecker command that does something, if not very well,
 and uses Pod::Simple as a backend.

Thanks. I'm happen to pull in the Pod fixes. And I could see adding a test that 
runs Test::Pod if it's installed (which would then just SKIP ALL in core). But 
this script seems…odd. I don't understand the config stuff, or the !NO!SUBS! 
at the end.

But isn't there already a pod-checking script somewhere that uses Pod::Simple? 
Somebody help me out here.

Wishing all the POD stuff wan't scattered to the four winds,

David

Re: podchecker from Pod::Simple

[David E. Wheeler]

On Feb 2, 2011, at 9:18 AM, Michael Stevens wrote:

 This is a quick hack to try to make the core podchecker use Pod::Simple
 to do the checking. It was inspired by discussion on p5p about the
 desirability of making podchecker use Pod::Simple.
 
 It looks like Pod::Parser's validation is different from Pod::Simple, at
 the moment I wouldn't like to comment on what's right.
 
 I just copied the original and did the minimal to make it use
 Pod::Simple instead of Pod::Parser as a backend.
 
 At the moment it's very much a toy, and I wouldn't ask you to pull it.

I see. It was in your pull request, though. Where is its permanent home? I'd be 
happy to look at updating it directly in core.

Best,

David

Re: podchecker from Pod::Simple

[David E. Wheeler]

On Feb 2, 2011, at 9:55 AM, Michael Stevens wrote:

 Aah, I'd intended the pull request to apply only to the pod whitespace
 changes. Possibly my github-fu is weak.
 
 I'm playing with it in my github fork you've already seen, but not
 asking anyone to take it yet.
 
 I've fixed the .PL thing, as I couldn't work out what that was doing
 either, it's just a regular script now.

Thanks. I cherry-picked just the POD fixes.

 The goal is to try to get behaviour vaguely like the core podchecker,
 with the daydream of eventually replacing it.

Oh, I see, It's in the Pod-Parser distribution. It should probably be moved 
elsewhere if you're going to rewrite it. Or else the Pod::Simple implementation 
should have a different name.

Best,

David

Re: `=item 1. Text` Doesn't Produce Ordered List Item

[David E. Wheeler]

On Nov 12, 2010, at 4:18 AM, Ricardo Signes wrote:

 I'd like to make them consistent.
 
 RJBS would not.
 
 That is a mischaracterization.  You would like to make them consistent by
 changing the spec to allow new forms.  I would like to make them consistent by
 fixing the long standing bug that renders them contrary to the specification.

Right, but:

a. It's not a bug, it's based on how Pod::Parser worked long before Pod::Simple.
b. We'd break a lot of existing Pod if we changed it.

Best,

David

Re: `=item 1. Text` Doesn't Produce Ordered List Item

[David E. Wheeler]

On Nov 12, 2010, at 11:22 AM, Ricardo Signes wrote:

 It is a bug, insofar as it is behavior not in line with the requirements of 
 the
 specification.  If you're saying that the specification was always mistaken in
 its attempt to document preexisting behavior, I will totally buy that.

Yes.

 In that case, I would be all for seeing the spec fixed and then the
 implementation to match it -- but the spec has to be fixed!  If I work on
 Pod-parsing tools, I need to be able to match them against the spec, not
 against a reference implementation that violates it.  That's my main concern,
 here.

Yes, I would like to see the spec changed. The best argument not to, IMHO, is 
Sean's reading of the current spec:

  http://www.nntp.perl.org/group/perl.pod-people/2010/07/msg1536.html

Best,

David

Re: `=item 1. Text` Doesn't Produce Ordered List Item

[David E. Wheeler]

On Jul 25, 2010, at 11:58 AM, David E. Wheeler wrote:

 * David E. Wheeler da...@kineticode.com [2010-07-25T13:40:24]
 For the purposes of this thread, my question is: Should we support `=item 1.
 foo` as creating an ordered list item the way we support `=item * foo` as
 creating an unordered list item? I vote yes, as it seems more consistent, 
 and
 we're not going to remove the latter. What about the rest of yous?
 
 On Jul 25, 2010, at 10:45 AM, Ricardo Signes wrote:
 
 I would rather not.  I'd rather leave them as simple as can be.  The fact 
 that
 there is a long-standing bug in Pod::Simple isn't a good reason, to me, to 
 make
 the specified behavior any more complicated.
 
 Vote noted. To me it's not a bug; I've actually used this syntax, and always 
 considered it a feature.

Coming back to this, now that we're trying to get Pod::Simple ready for Perl 
5.14. Anyone else want to vote? The only other thing I'd add is that pod2html 
(which IIRC uses Pod::Parser) treats `=item 1. foo` and `=item 1 foo` as 
ordered list items, and both pod2html and Pod::Simple treat `=item * foo` as 
ordred lists.

I'd like to make them consistent.

RJBS would not.

Anyone else want to chime in?

Thanks,

David

Re: `=item 1. Text` Doesn't Produce Ordered List Item

[David E. Wheeler]

On Jul 24, 2010, at 7:02 AM, Sean M. Burke wrote:

 On 07/22/2010 02:12 PM, David E. Wheeler wrote:
 On Jul 22, 2010, at 2:38 PM, Russ Allbery wrote:
 That's not because =item * Stuff is being specially recognized.  That's
 because =item anything where anything isn't a bullet or a number
 produces an unordered list.  perlpodspec does say that, although I admit I
 had to read it a couple of times.
 
 Hooboy, join the club.  I wrote that stuff /so I could forget it/.  I think.  
 I forgot.
 
 No, by my reading, “=item anything where anything isn't a bullet or a 
 number” should be a definition list item.
 
 To cut short an agonizingly long story, please have it be something like:
   dt style=margin-left: 1em
 
 Basically: the default rendering of dt snaps the text /completely/ back to 
 the margin that our =over means for us to be getting away from.
 
 That style=... value stops it from doing that.
 Ideally it'd be in a brilliant-pod.css whose artisanal value for dt would be 
 merely one facet of a gem of typographical perfection, but, uh
 I say jump into Pod/Simple/HTML.pm, strike
item-text=dt
 and go up and add
  'item-text' = 'dt style=margin-left: .5em',
  '/item-text' = '/dt',
 and run!  Run like there's zombies chasing you, zombies made out of SGML!

Frankly I wasn't worried about the =over. I never took it to mean a literal 
indentation so much as a list marker. Given the amount of code that depends on 
Pod::Simple::HTML, I'd be disinclined to make this sort of change. But that's 
also why I prefer Pod::Simple::XHTML, which outputs no style information at 
all. CSS really should be done elsewhere, IMHO.

For the purposes of this thread, my question is: Should we support `=item 1. 
foo` as creating an ordered list item the way we support `=item * foo` as 
creating an unordered list item? I vote yes, as it seems more consistent, and 
we're not going to remove the latter. What about the rest of yous?

Best,

David

Re: `=item 1. Text` Doesn't Produce Ordered List Item

[David E. Wheeler]

On Jul 25, 2010, at 10:45 AM, Ricardo Signes wrote:

 I would rather not.  I'd rather leave them as simple as can be.  The fact that
 there is a long-standing bug in Pod::Simple isn't a good reason, to me, to 
 make
 the specified behavior any more complicated.

Vote noted. To me it's not a bug; I've actually used this syntax, and always 
considered it a feature.

Best,

David

Re: pod2html and Pod::Simple

[David E. Wheeler]

On Jul 21, 2010, at 11:56 PM, Sean M. Burke wrote:

 Oy, pod2html, Pod::Simple::HTMLLegacy, Pod::Simple::HTML, what a jumble... 
 and as I tinker with perldoc -o html now, I see it makes every heading a 
 hyperlink back to the top of the document?  Jeez, what was I /thinking/, 
 that's just dumb interface.

This is why I prefer Pod::Simple::XHTML now.

Anyway, would Pod::Simple::Legacy be the thing to put into a new pod2html?

Best,

David

Re: `=item 1. Text` Doesn't Produce Ordered List Item

[David E. Wheeler]

On Jul 20, 2010, at 1:20 PM, Russ Allbery wrote:

 David E. Wheeler da...@kineticode.com writes:
 
 No. I told the person who reported this issue to use that, and it is the
 proper way to do it. But note that this works:
 
 =item * Foo
 
 =item * Bar
 
 That creates an unordered list. Given that, I would expect the
 corresponding syntax to work for ordered lists:
 
 =item 1 Foo
 
 =item 2 Bar
 
 And it does, when run through pod2html, but not when run through
 Pod::Simple. So the question is, given this Pod, who's right? pod2html
 or Pod::Simple?
 
 perlpodspec says that the former is an unordered list and the latter is a
 description list.  I think pod2html is wrong here.

If so, my next question would be: how dependent are people on this? Is it 
something we want to consider adding to the spec? Or should pod2html be changed 
to remove this interpretation?

Best,

David

Re: SPEC UPDATE: [rt.cpan.org #55602] Bug #12239 was a mistake

[David E. Wheeler]

On Apr 20, 2010, at 10:10 AM, Ricardo Signes wrote:

 I'd really like to get the perldoc command broken into 5.12.1, and I think
 we'll have the best chance of that if the delta to the new version is as small
 as possible.  Can we do 3.14 just for that (and the already-fixed warnings) 
 and
 then 3.15 ASAP with further improvements?

Does it really matter? 5.12.1 won't pull in the full 3.14 release anyway, just 
the regression. Does it matter whether or not it's released with any fixes 
before it goes to maint?

If so, sure, we can do 3.14 with just this change (okay with you Allison?). But 
then we should do 3.15 soon and get it sent upstream to blead.

Best,

David

Re: SPEC UPDATE: [rt.cpan.org #55602] Bug #12239 was a mistake

[David E. Wheeler]

On Apr 20, 2010, at 10:45 AM, Ricardo Signes wrote:

 That is not what I'd expect.  I would not guess that Jesse wants a subset of
 changes, getting us a dual-lived module with no corresponding CPAN release and
 a version number that was never available elsewhere.

It's what I'd expect given that the version numbers of CPAN modules will be 
incremented only to dev release version numbers in maint, IIUC.

 I could be wrong.  I will ask him if he's around, today.

That would help, thanks.

David

Re: Yada Yada Operator Link Broken

[David E. Wheeler]

On Apr 13, 2010, at 11:18 AM, Jan Dubois wrote:

 No, it doesn't.  The X escapes are still part of the head2 element. It could
 have been written like this:
 
  =head2 Yada Yada Operator X... X... operator Xyada yada operator
 
 Except that makes it harder to read if you just read the
 unprocessed pod file directly.
 
 search.cpan.org is just using an old POD formatter.  I fixed the anchor
 generation for multi-line headX directives for Pod::Html here:
 
  http://perl5.git.perl.org/perl.git/commitdiff/d0ff30b50
 
 Seems to work fine for the current docs:
 
  
 http://docs.activestate.com/activeperl/5.12/lib/pods/perlop.html#yada_yada_operator

Should that not use the entire header for the location name? Something like 
#Yada_Yada_Operator_operator_yada_yada_operator?

Ah. Then this change needs to be made to Pod::Simple, too.

pod-people, does it make sense to allow headers to be on more than one line, 
e.g.,

=head2 Yada Yada Operator
X... X... operator Xyada yada operator

Thanks,

David

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[David E. Wheeler]

On Mar 15, 2010, at 10:57 AM, Ricardo Signes wrote:

 Is there anyone who can provide a reading of the spec to support the change?
 Do you (David) remember what part of the spec convinced you?

When I made the change, I wasn't aware of the spec, but based the change on 
`perlpod`, particularly this bit:

C $a = $b 
C  $a = $b 
 
And they all mean exactly the same as this:
 
C$a Elt=Egt $b
 
As a further example, this means that if you wanted to put these bits
of code in C (code) style:
 
open(X, thing.dat) || die $!
$foo−bar();
 
you could do it like so:
 
C open(X, thing.dat) || die $! 
C $foo−bar(); 
 
which is presumably easier to read than the old way:
 
Copen(X, EgtEgtthing.dat) || die $!
C$foo−Egtbar();

My interpretation of that was that any angle brackets inside should be 
considered literal, and thus escaped. The whole point of `   ` AFAICS was 
to allow one to use literal brackets without escaping them, as one must do in 
``.

Best,

David

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[David E. Wheeler]

On Mar 15, 2010, at 12:19 PM, Ricardo Signes wrote:

 In other words, the only change /C{2,}\s+/ has over /C{1}/ is that it 
 changes
 the number of 's that are needed to close that code.  Fewer 's than that are
 just text.
 
 Frustrating.

Well, should it change to that? If we can all agree on a proper solution and 
update the spec to be specific, I'm happy to modify Pod::Simple (if I can find 
the tuits) to match that.

FWIW, I blogged about this when 3.09 came out: 
http://www.justatheory.com/computers/programming/perl/modules/new-pod-simple.html

Everyone I heard from as a result of that post thought it made sense. :-(

Best,

David

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[David E. Wheeler]

On Mar 15, 2010, at 6:08 PM, Ricardo Signes wrote:

 ...and clearly I agreed!  I'm not sure whether I misunderstood or was just
 wrong.  Either way, I think the change was incorrect.
 
 I will try to write an update for the spec soon.

Okay. Once that's done and we have consensus, I'll try to find the tuits to 
make it match the spec.

Best,

David

Re: AW: AW: allowing Ltext|href

[David E. Wheeler]

On Dec 30, 2009, at 9:54 AM, Marek Rouchal wrote:

 sorry, I did not imply that. All I meant was to relax the spec
 (perlpodspec) to tolerate Ltext|URL, and do the same thing
 in Test::Pod, i.e. not flag Ltext|URL as an error.

Yes. The former is already done, and my patch to Test::Pod does the other.

 However, I think it would be a sensible restriction to only
 Allow absolute (not relative) URLs, i.e.
   http://perl.org = ok
   /images/diagram.jpg = NOT ok

That's already the case. They have to start with /\w+:/.

Best,

David

Re: Pod::Simple fullstop_space_harden Attribute

[David E. Wheeler]

On Dec 14, 2009, at 2:24 PM, David E. Wheeler wrote:

 I've now [done 
 so](http://github.com/theory/pod-simple/commit/833369387cafae19d0affe02f8ea31aac86f6d07).
  I'd appreciate it if folks would `git clone` and  test it with their Pod 
 infrastructures to make sure that there are no unexpected consequences before 
 I release it.

I've released it as Pod::Simple 3.13. Enjoy.

Best,

David

Re: XHTML formatter 'xhtml' regions

[David E. Wheeler]

On Dec 11, 2009, at 10:58 AM, Ricardo Signes wrote:

  http://github.com/rjbs/pod-simple/tree/xhtml-region
 
 David and I spoke about this on AIM a little...
 
 Right now, given this input in Pod::Simple::HTML:
 
  =begin html
 
  div.../div
 
  =end html
 
 The HTML is passed through untouched.  If you do the same thing in
 Pod::Simple::XHTML, the HTML is entity escaped before being passed along.
 
 I had assumed this was intentional, and my changes add an 'xhtml' region which
 is untouched.  David suggested that this is an error.
 
 Anybody know?  I would like to get this sorted out so I can rely on it. :)

I asked Graham earlier this week if he'd consider switching to 
Pod::Simple::XHTML, and his comment was that, if we did that, and someone had 
invalid html in a `=for html` section, it would make the whole document 
invalid. Of course, we were both working on the assumption that `=for html` 
stuff would be passed through unmolested.

I'm not sure it should be. I mean, it'd be easiest to do so, but another choice 
might be to parse it and fix validation issues.

But at any rate, the current implementation of escaping the content seems wrong 
to me. If I wanted that, I'd use a verbatim block.

Best,

David

Re: XHTML formatter 'xhtml' regions

[David E. Wheeler]

On Dec 11, 2009, at 12:08 PM, Ricardo Signes wrote:

 I've fixed this problem, added tests, and created a new method,
 accept_targets_as_html.  This acts like _as_text, but the collected texts are
 emitted literally, without entity escaping.  The 'html' target now uses that
 mechanism.  I removed any mention of my ill-fated experiment.
 
 This is still in the same branch, though:
 
  http://github.com/rjbs/pod-simple/tree/xhtml-region
 
 I would love to see this merged and deployed before Christmas 2009!

[Pulled](http://github.com/theory/pod-simple/commit/134725656070b94c7df980bebab847f2738c21ed).
 Thanks. I'll likely do a release next week, since this is a regression.

Best,

David

Re: allowing Ltext|href

[David E. Wheeler]

On Dec 7, 2009, at 5:02 PM, David E. Wheeler wrote:

 On Dec 7, 2009, at 4:44 PM, Russ Allbery wrote:
 
 Hm, just to check, did you already talk to the folks at he.net and confirm
 that they're okay with tons of Perl documents being pointed at their web
 site?  They may have resource constraints.
 
 No. Probably ought to ping them.

They gave their blessing.

While I was at it, and now that the change is in blead and released in 
Pod::Simple 3.11 (which includes perlpod.pod and perlpodspec.pod, FBOFW), I've 
taken the time to send a pull request for Test::Pod to allow this new syntax.


http://github.com/theory/test-pod/commit/ae6a44894eda4fd09fb412d837efe543628cd7d6

I've sent a pull request to Andy and sent the patch to 
[RT](http://rt.cpan.org/Ticket/Display.html?id=52688). 

My motivation here is to match the current spec, at least as implemented by 
Pod::Simple, which Test::Pod uses to do the actual parsing and validation. I 
also want to start using this syntax, since search.cpan.org uses Pod::Simple 
and will therefore get the sane links ASAP. The only stopping point from my POV 
is that my Pod tests will fail, and since this is now legal, I'd rather they 
didn't.

It turns out that the Test::Pod's ability to detect Ltext|scheme:... links 
was added only this past July. Before that, it had completely relied on 
Pod::Simple, which has supported such links for a long time. So it's not that 
long that Test::Pod has forbidden them. Furthermore, this isn't taking any 
syntax away from users, so those who don't want to use Ltext|scheme:... links 
don't have to. It's possible to add some sort of flag to let Test::Pod so that 
such users can enforce the rule, but doing so seems like a slippery slope that 
would eventually end up requiring that Test::Pod track different versions of 
the pod spec (and it's not versioned!).

Anyway, my $0.02.

Best,

David

Re: deprecating LSection

[David E. Wheeler]

On Dec 1, 2009, at 4:55 AM, Ricardo Signes wrote:

 I propose to remove mention of LSection from perlpod and to deprecate it 
 in
 perlpodspec, and also to reword the mention of LSection in perlpodspec to
 make it less optional and more dead.

+1

 I'll probably do this in the next few days, and will look to get this and last
 night's discussed changes merged after 5.12.

Which is the canonical copy of perlpod and perlpodspec? Core or Pod::Simple?

Best,

David

Re: allowing Ltext|href

[David E. Wheeler]

On Dec 1, 2009, at 2:03 AM, Allison Randal wrote:

 The relevant tests are in t/fcodes_l.t, with a few more in t/xhtml01.t.

Yeah, and it looks like it pretty well matches what RJBS and I sketched out. 
Ricardo, are you looking to update perlpod and perlpodspec for 5.12, then? As 
soon as that's in, I'll send a patch for Test::Pod (turns out the change is 
quite simple).

Best,

David

Re: allowing Ltext|href

[David E. Wheeler]

On Dec 1, 2009, at 12:18 PM, Ricardo Signes wrote:

 Yeah, and it looks like it pretty well matches what RJBS and I sketched out.
 Ricardo, are you looking to update perlpod and perlpodspec for 5.12, then? As
 soon as that's in, I'll send a patch for Test::Pod (turns out the change is
 quite simple).
 
 I will update the documents, although I'm not sure if Jesse will want to get 
 those changes in 5.12.  I'll talk to him.  If he's game, I'll do it.

Cool.

I just wrote tests for the text output from Pod::Simple::Text. It's like this:

POD | Text Output
+--
Lthings|crontab(5)| things
Lthings|crontab(5)/foo| things
LPerl Error Messages|perldiag | Perl Error Message
Lperl.org|http://perl.org | perl.org

I think it most unfortunate that the URL is lost in text output. I see two ways 
around this:

1. Change it to output with the URL using something like Markdown format:

POD | Text Output
+
Lthings|crontab(5)| [things](crontab(5))
Lthings|crontab(5)/foo| [things](crontab(5)/foo)
LPerl Error Messages|perldiag | [Perl Error Message](perldiag)
Lperl.org|http://perl.org | [perl.org](http://perl.org)

2. Or, if people hate that, perhaps implement Pod::Simple::Markdown to emit 
Markdown and leave Pod::Simple::Text as-is.

Thoughts?

Not sure what Pod::Man does…

Best,

David

Re: allowing Ltext|href

[David E. Wheeler]

On Dec 1, 2009, at 1:20 PM, John McNamara wrote:

 I think the something like the second second but without the brackets.
 
 
POD | Text Output
+
Lthings|crontab(5)| things (crontab(5))
Lthings|crontab(5)/foo| things (crontab(5)/foo)
LPerl Error Messages|perldiag | Perl Error Message (perldiag)
Lperl.org|http://perl.org | perl.org (http://perl.org) 

Thanks. That does seem a bit better.

 As for Markdown, I had been planning to add support for it to 
 Pod::Simple::Wiki. BTW, the latter is why I am very much in favour of a 
 Ltext|href syntax. Outputting Wiki text without proper link support is a 
 major deficiency.

Yah. Pod::Simple already supports this, though.

Best,

David

Re: allowing Ltext|href

[David E. Wheeler]

On Nov 30, 2009, at 4:41 PM, Russ Allbery wrote:

 As for (1), I think that it is actually not difficult, and merely
 appeared so due to the software involved at the time.  David and I
 whipped up what I believe is a fairly complete and mostly unambiguous
 grammar:

We forgot to account for L . So we need to exclude  and  from any text in 
L, but allow them in L . Otherwise they're the same.

 I was in favor of this originally and am still in favor of it now.  I
 think we should support it and am happy to find a way of representing the
 results textually in Pod::Text and Pod::Man.  It will produce much nicer
 HTML output.

And I'd be happy to test Pod::Simple's existing implementation of this feature, 
and make sure it works properly for man pages and plain text. I can probably 
squeeze some time to do that this week.

Best,

David

Re: expanding =begin

[David E. Wheeler]

On Nov 30, 2009, at 4:14 PM, Ricardo Signes wrote:

 I'd like to extend this definition a bit.  I would replace the second 
 paragraph
 with:
 
   =begin formatname
   =begin formatname parameter
   This marks the following paragraphs (until the matching =end
   formatname) as being for some special kind of processing.  Unless
   formatname begins with a colon, the contained non‐command
   paragraphs are data paragraphs.  But if formatname does begin
   with a colon, then non‐command paragraphs are ordinary paragraphs
   or data paragraphs.  This is discussed in detail in the section
   About Data Paragraphs and =begin/=end Regions.
 
   It is advised that formatnames match the regexp
   m/\A:?[−a−zA−Z0−9_]+\z/.  Everything following whitespace after the
   formatname is a parameter that may be used by the formatter when dealing
   with this region.  Implementors should anticipate future
   expansion in the semantics and syntax of the first parameter to
   =begin/=end/=for.
 
 This allows for constructions like:
 
  =begin syntax javascript
 
  =end syntax
 
 ...or...
 
  =begin table width(10) height(9)
 
  =end table
 
 ...or...
 
  =begin dialect Pod6
 
  =end dialect
 
 I believe several parsers already allow this implicitly.

Makes sense to me, but I think that you need to update the regex to include the 
(optional) parameter. Something like:

  Cm/\A:?[−a−zA−Z0−9_]+(?:\s+[−a−zA−Z0−9_]+)?\z/

Best,

David

Re: allowing Ltext|href

[David E . Wheeler]

On Nov 30, 2009, at 7:28 PM, David E. Wheeler wrote:

 And I'd be happy to test Pod::Simple's existing implementation of this 
 feature, and make sure it works properly for man pages and plain text. I can 
 probably squeeze some time to do that this week.

FWIW, Pod::Simple already parses things as you expect. Here's the relevant 
comment:

  # Lname
  # Lname/sec or Lname/sec
  # L/sec or L/sec or Lsec
  # Ltext|name
  # Ltext|name/sec or Ltext|name/sec
  # Ltext|/sec or Ltext|/sec or Ltext|sec
  # Lscheme:...
  # Ltext|scheme:...

So I'll just need to add some more tests I think, to make sure that nothing 
unexpected happens (like a a misplaced | or /).

For my own personal use, Test::Pod is what most needs to be updated to allow 
this syntax. Hrm. Looks like it uses Pod::Simple; so I'll have to look to see 
what needs to be changed to get it to allow Ltext|schem:

Best,

David