Re: POD formatter version comments

[Ricardo Signes]

On Wed, Mar 20, 2024, at 18:34, Karen Etheridge wrote:
>  I believe the paragraph in the docs should stay, but change the MUST to a 
> SHOULD, with a proviso that there should be a way to disable it (for the 
> purposes of repeatable builds etc). If the paragraph is removed entirely, no 
> one will implement it (the fact that it is not well-implemented now is sad, 
> but beside the point). I have no strong feelings as to whether the option 
> should default to on or off, but the option should exist for those that wish 
> this extra content.

I don't have strong feelings about using SHOULD here, although mostly I think 
it's simpler to strike the paragraph.

If the paragraph is removed, nothing will change except some noncompliant 
formatters might become compliant.  Removing the "formatters must" does not 
imply a "formatters must not", so nobody is being robbed of an option to do 
this or to keep doing it.

I think a better paragraph, if we don't just delete, might be:

Formatters may introduce comments to their output that provide information on 
the tooling used to produce that output.  When doing this, implementers should 
consider that reproducible build systems benefit from reduced churn in the 
build products.  This implies that it should be possible to suppress those 
comments.  If the *significant* content of a translation doesn't change between 
versions, mandatory *insignificant* changes might be a hindrance.

-- 
rjbs

Re: podlators 5.00 released

[Ricardo Signes]

On Fri, Nov 25, 2022, at 17:53, Russ Allbery wrote:
> This is the first major release of podlators, which provides Pod::Man and
> Pod::Text, in some time.

Thanks, Russ!  These libraries are really important and probably you don't get 
enough kudos for the many years you've spent keeping them going.  Especially I 
want to call out…

> This will hopefully mean the beginning of the end of mangling people's names 
> and languages with X characters.

Taking old code and making this work reliably can be a real pain, especially 
without type checks to help you along the way.  It's also really important, 
because it allows people to be represented and credited by the name that they 
actually know as their own.

I haven't installed v5 yet, but will do so sometime soon and see what shakes 
out!

-- 
rjbs

Re: podlators 4.07 released

[Ricardo Signes]

* Dave Mitchell  [2016-03-21T04:56:11]
> I vote for this being merged into blead despite the code-freeze. I can
> vouch for the 1st and 3rd fixes, I know nothing about the second.

+1

-- 
rjbs


signature.asc
Description: Digital signature

Re: podlators 4.05 released

[Ricardo Signes]

* Russ Allbery  [2016-01-16T17:36:02]
> I'm pleased to announce release 4.05 of podlators.

Thanks, Russ!  I can only assume that moving back to the *.PL was a bit of a
disappointment.  Thanks for helping to keep things great on all platforms!

-- 
rjbs


signature.asc
Description: Digital signature

Re: Assume CP1252

[Ricardo Signes]

* Grant McLean gr...@mclean.net.nz [2015-01-07T18:47:49]
 I also agree this is a good idea.  None of the Latin-1 control
 characters that CP1252 replaces with printable characters should be
 appearing in POD anyway.

Seems safe, I think.  At first, I thought, They're disjunct!! but then I
realized that this is only true on codepoints that nobody is going to use in
their Latin-1 POD.

-- 
rjbs


signature.asc
Description: Digital signature

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

[Ricardo Signes]

* David E. Wheeler da...@justatheory.com [2015-01-08T00:38:04]
 I agree that’s too liberal. I suggest
 
 /\A=([a-zA-Z]+\d*)\b/

trolling?
Surely you want [0-9] instead of \d, lest we end up with =head୩ !
/trolling?

-- 
rjbs


signature.asc
Description: Digital signature

Re: Allow Whitespace in L URLs?

[Ricardo Signes]

* David E. Wheeler da...@justatheory.com [2015-01-08T13:42:10]
 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 .

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

-- 
rjbs


signature.asc
Description: Digital signature

Re: Is Pod::Simple::POD worth pursuing?

[Ricardo Signes]

* John SJ Anderson geneh...@genehack.org [2013-05-21T19:33:14]
 * Is this a worthwhile idea? (The recent How do I get Pod::Simple to
 extract pod thread suggests the answer is yes.)

It's hard to judge this without the context in which you're considering it.
The GH issue to which you linked is largely context-free.

That said, wanting the ability to say gimme just the Pod from this Pod
document seems pretty reasonable.  Your code looks nice and simple.  I'd
rename it from POD to Pod so it's easier to remember.

-- 
rjbs


signature.asc
Description: Digital signature

Re: podlators broken by Pod-Simple 3.24

[Ricardo Signes]

* Russ Allbery r...@stanford.edu [2013-02-20T20:24:58]
 I haven't had a chance to look yet (still recovering from a cold), but
 will try to take a look soon.

I'm glad you're recovering. :)

 I suspect the problem is as simple as the podlators test suite including a
 test for handling of mismatched item types, since that sounds like the kind
 of edge case that I'd test, and not expecting the new warning.

I should've said that, in fact, this is what it seems to be doing.

I just didn't see how to easily futz with its expectations without making a
hash of things.

-- 
rjbs


signature.asc
Description: Digital signature

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

[Ricardo Signes]

* Marc Green pongu...@gmail.com [2012-02-19T16:19:08]
 When given the following input, Pod::Simple does not warn that the [text]
 portion of the 2nd and 3rd =item is invalid.
 
 =over
 =item a definition
 some text
 =item *
 a bullet
 =item 1
 a number
 =back
 
 [perlpodspec cited]
 
 I am not sure why it doesn't warn in this situation, but does warn for
 other =item type mismatches.

This seemed to go nowhere, but was brought up to help get Pod::Checker using
Pod::Simple.

I hope we can agree that if the test results bit gets sorted out, we're in
favor of this warning..?

-- 
rjbs


signature.asc
Description: Digital signature

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

[Ricardo Signes]

* David E. Wheeler da...@justatheory.com [2013-01-18T12:33:52]
 Good idea, though it will require that older versions of Perl install a JSON
 parser just to run the tests…

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

-- 
rjbs


signature.asc
Description: Digital signature

Re: Version comments in POD output

[Ricardo Signes]

* Russ Allbery r...@stanford.edu [2012-12-26T17:47:41]
 Do people feel this comment line provides much real utility in Pod::Man
 output?  I could add a flag to suppress it, but I'm tempted to just drop
 it entirely, since I'm not sure that it's really doing anyone any good.

I have often found such lines *in other programs* useful for sorting out bugs.
I've never tried debugging the podlators, thankfully! :)  My inclination would
be to add the flag for such packagers to use, but I'm not particularly invested
in the problem.

-- 
rjbs


signature.asc
Description: Digital signature

Re: Fwd: Topic/metacpan.org (#36)

[Ricardo Signes]

* David E. Wheeler da...@justatheory.com [2012-08-13T12:41:31]
 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).

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

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.

-- 
rjbs


signature.asc
Description: Digital signature

please test perl5.git's Pod-Html

[Ricardo Signes]

I've already asked for some testing on p5p, but oh ye devoted pod people:

If you have the time, install perl from git, commit ac2b477 or later, and play
around with pod2html and let us know what is broken.

I think it's mostly working now, although there is one chunky bug report to
work through at https://rt.perl.org/rt3/Public/Bug/Display.html?id=110520

I'm especially interested in:

  * workingness with your existing Pod-to-html generation scripts / routines
  * the stuff that the above bug complains about

Thanks.

-- 
rjbs


signature.asc
Description: Digital signature

Re: an 'anchor' command is missing from Pod

[Ricardo Signes]

* Shawn H Corey shawnhco...@gmail.com [2012-01-28T08:41:35]
 On 12-01-27 11:14 PM, Ricardo Signes wrote:
 You're thinking of X  -- Z  should always be empty, and is a zero-effect
 code.  Xopen  is used to help indexing.  It isn't how perldoc -f works,
 though.
 
 No, I've encountered unempty Z in some PODs.

Then you have seen mistakes.

-- 
rjbs


signature.asc
Description: Digital signature

Re: an 'anchor' command is missing from Pod

[Ricardo Signes]

* Shawn H Corey shawnhco...@gmail.com [2012-01-27T19:51:50]
 
 I thought they were using the Z code for it:
 
 
 =item open FILEHANDLE,EXPR
 
 =item open FILEHANDLE,MODE,EXPR
 
 =item open FILEHANDLE,MODE,EXPR,LIST
 Zopen

You're thinking of X -- Z should always be empty, and is a zero-effect
code.  Xopen is used to help indexing.  It isn't how perldoc -f works,
though.

-- 
rjbs


signature.asc
Description: Digital signature

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

[Ricardo Signes]

* David E. Wheeler da...@justatheory.com [2012-01-25T15:12:03]
  Subject: [rt.cpan.org #74389] Pod::Simple::Pullparser get_title should 
  ignore X... 
  Date: January 25, 2012 12:10:00 PM PST
  Reply-To: bug-pod-sim...@rt.cpan.org
  
  With Pod::Simple 3.14.
  
  If a pod file has index entries after head:
  
  =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.

-- 
rjbs


signature.asc
Description: Digital signature

Re: Deprecation of alternate text in hyperlinks

[Ricardo Signes]

* Karl Williamson pub...@khwilliamson.com [2012-01-23T12:26:27]
 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.

After all the care taken to be sure that the original fears about
L...|http:/// were unfounded, I think we should stick to it and allow it.
Pod::Parser should probably not be warning on these, unless it somehow can't
handle them, in which case the better fix is to handling them, not warning.

-- 
rjbs


signature.asc
Description: Digital signature

Re: Removal of specific Pod::Checker warnings

[Ricardo Signes]

* Marc Green pongu...@gmail.com [2011-08-11T06:40:17]
 
 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?

Pod::Checker's behavior isn't wrong, but its claims are.  It says:

  =item without any parameters is deprecated

No, it isn't.  Maybe somebody wishes that it was, but it isn't.  It sounds like
nobody thinks it needs to be.  I think it's fine for Pod::Checker to have
opinions of style, in some cases, but I don't think this makes any sense.  The
meaning of =item is well-documented.  I think the warning can and should go.

 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.

You've already heard my opinion on this one, but for everyone else:  I think
this warning is bogus.  =over/=back without =item is well-documented.  Some
formatters don't handle it correctly, but better to fix them than to suggest
that this is in any way problematic Pod.

If someone wants to come forward and tell us that, say, the four most-used Pod
formatters will actually *lose* these sections, that's a different matter.  But
that isn't my experience.

-- 
rjbs

Re: Pod::Html's cross referencing of C links

[Ricardo Signes]

* Marc Green pongu...@gmail.com [2011-05-20T16:24:21]
 links. More specifically, I understand how it resolves L links, but I am
 confused as to why you resolve C links. From reading the source, I
 gather that C links are resolved by searching pod documents for =item
 directives, and storing their text in a global hash.

Marc is referring to comments like this:

my %Pages = (); # associative array used to find the location
#   of pages referenced by L links.
my %Items = (); # associative array used to find the location
#   of =item directives referenced by C
#   links

...

# scan_items - scans the pod specified by $pod for =item directives.  we
#  will use this information later on in resolving C links.

c.

-- 
rjbs

Re: no deprecation warning for Lsection

[Ricardo Signes]

* Nicholas Clark n...@ccl4.org [2011-05-01T05:34:08]
 a: move to maintaining Pod-Parser as part of the core
 or
 b: more to eliminating the need for Pod-Parser
 
 and the consensus seems to be that (b) is far less insane. I think that
 what's then gone wrong is that no-one wants to start on it, but given that
 it is the future, everyone thinks that doing anything in the direction of (a)
 is a waste of effort.

(b) gets started on tomorrow.

-- 
rjbs

Re: no deprecation warning for Lsection

[Ricardo Signes]

* Karl Williamson pub...@khwilliamson.com [2011-04-27T13:52:50]
 I notice that perldoc does not warn on this being deprecated.  Is
 this by design?

I can't say with certainty, but I would wager that this is an oversight.  Maybe
we can get that addressed after 5.14 and, better, can get it into Pod::Checker
after it's updated to use Pod::Simpler.  That's part of a GSoC task this
summer.

-- 
rjbs

Re: no deprecation warning for Lsection

[Ricardo Signes]

* Michael Stevens mstev...@etla.org [2011-04-28T17:03:36]
 Has it got a victim^Wvolunteer?

Yup.  Marc Green (the student) and David Wheeler and I will have our first
meeting to kick things off in a few days.  From there on, a state of constant
progress!

-- 
rjbs

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

[Ricardo Signes]

* David E. Wheeler da...@kineticode.com [2010-11-11T23:06:22]
 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.

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.

-- 
rjbs

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

[Ricardo Signes]

* 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?

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.

-- 
rjbs

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

[Ricardo Signes]

* David E. Wheeler da...@kineticode.com [2010-07-20T16:40:18]
  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?

I would like to see pod2html (as a Pod::Html-based thing) be replaced with
Pod::Simple, which should fix this.  Noncompliant documents should be fixed.

-- 
rjbs

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

[Ricardo Signes]

* David E. Wheeler da...@kineticode.com [2010-04-17T16:46:23]
 Looks good to me. Hopefully, this is how Pod::Simple worked before I changed 
 it to escape everything. If so, it should be as simple as applying this patch:
 
  
 http://github.com/madsen/pod-simple/commit/e02b2ab78c87b6b4b81d92c91b4743bc1242265d

Excellent.  I have updated perlpod/perlpodspec in blead and requested that it
be merged back to maint.  Can you release with the above reversion?  I will ask
Madsen to test that it pleases him, and will test myself.  Once that's done, I
will ask that Pod-Simple be updated for 5.12.1 to fix this regression.

Thanks much!

-- 
rjbs

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

[Ricardo Signes]

* David E. Wheeler da...@kineticode.com [2010-04-19T13:17:13]
 I think I'd rather pull in that commit and have you and Madsen verify that
 it's compliance with the new wording of the spec *before* I release it. Seem
 reasonable?

Sounds great, I'll get this done in the next 2-3 days.

-- 
rjbs

Re: Ansi color tag

[Ricardo Signes]

* nadim khemir na...@khemir.net [2010-04-16T20:07:27]
 Hi, I think it would be nice if pod had a new tag for defining colors.

I think the most useful thing to add would be a generic formatting tag,
analagous to =for/=begin, for endless extensibility.  Off the top of my head,
I'd say:

  G type ( | text ( | anything )? )? 

  Gcolor|This is red!|red

  Here is a link to our internal bug tracker: Gbug|some bug|1234

...and so on.  The default behavior would probably be to replace unknown types
with just the text.

Then people can plug in and provide any formatting code they want without
having to provide a bunch of new code and cause conflict, etc.

I'm not motivated enough to go implement this.  I'm just saying that this would
be a nice way for people to get extensible formatting codes without having to
keep extending the spec.

-- 
rjbs

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

[Ricardo Signes]

* David E. Wheeler da...@kineticode.com [2010-03-15T13:32:28]
 Comments?

From perlpodspec (presented as verbatim text):

=item C $thing-stuff(Idodad) 

Further, I see nothing that implies that C Cfoo  should be rendered as
Cfoo rather than foo

I don't know that I realized this was the change, although I remember talking
about it.  I thought the change was to fix C ...  to require the spaces.
I am willing to believe that previously I openly and clearly agreed with this
change, but I'm not sure I do.

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?

-- 
rjbs

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

[Ricardo Signes]

* David E. Wheeler da...@kineticode.com [2010-03-15T14:56:48]
  
 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
 ``.

Right -- but that's because they're potentially-matching right brackets.  For
example, this line is valid Pod with no formatting codes:

  Hello world.  cout;

We don't need to use EgtEgt because there's no open quote to give the
closing one special significance.  If we did this, though:

  CHello world.  cout;

...then the first  closes the C.

What if we wanted:

  C ls  Fls-file.txt 

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.

-- 
rjbs

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

[Ricardo Signes]

* David E. Wheeler da...@kineticode.com [2010-03-15T19:28:15]
 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

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

-- 
rjbs

Re: All tests fail

[Ricardo Signes]

* Mike Brown br...@mrvideo.vidiot.com [2009-12-25T20:12:21]
 Yep, all of the tests fail.  :-(
 
 Summary of my perl5 (revision 5 version 8 subversion 4) configuration:

That's a five and a half year old version of perl5, with quite a few locally
applied patches, which makes me really nervous to begin with.

Also, I can't tell what for version of what distribution you're reporting a
failure.  Please let us know that, and ew'd like to see the result of the tests
run verbosely:  make test TEST_VERBOSE=1

-- 
rjbs

Re: Pod::Simple fullstop_space_harden Attribute

[Ricardo Signes]

* David E. Wheeler da...@kineticode.com [2009-12-17T17:31:16]
 I've released it as Pod::Simple 3.13. Enjoy.

Great news, thanks!

-- 
rjbs

XHTML formatter 'xhtml' regions

[Ricardo Signes]

I recently got my Advent calendar converted entirely to Pod::Simple where it
had previously used Pod::Parser.  I needed two features added.

I sent Allison and David a pull request for the first, this morning.  It allows
you to say =head1 becomes h2 or becomes h3 and so on, which makes it
easier to produce an HTML fragment for inclusion in a larger document.

I am unsure whether the other feature is welcome.  It makes this:

  =for xhtml tag.../tag

...pass the XHTML right through.  This is invaluable for producing my colorized
code samples.  (I assume it also works as a begin/end block.)

If it is welcome, I will add it to Pod::Simple::XHTML and issue another pull
request.  If not, I will release it as a subclass.

-- 
rjbs

Re: XHTML formatter 'xhtml' regions

[Ricardo Signes]

* David E. Wheeler da...@kineticode.com [2009-12-11T12:56:28]
  
   =for xhtml tag.../tag
  
  ...pass the XHTML right through.  This is invaluable for producing my
  colorized code samples.  (I assume it also works as a begin/end block.)
  
  If it is welcome, I will add it to Pod::Simple::XHTML and issue another
  pull request.  If not, I will release it as a subclass.
 
 Sounds useful. What does the patch look like?

Right now, it's a subclass.  I will make a patch in a branch on Github...

That was easy!

  http://github.com/rjbs/pod-simple/tree/xhtml-region

-- 
rjbs

Re: XHTML formatter 'xhtml' regions

[Ricardo Signes]

* Ricardo Signes perl@rjbs.manxome.org [2009-12-11T13:36:32]
 * David E. Wheeler da...@kineticode.com [2009-12-11T12:56:28]
  
  Sounds useful. What does the patch look like?
 
 Right now, it's a subclass.  I will make a patch in a branch on Github...
 
 That was easy!
 
   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. :)

-- 
rjbs

Re: XHTML formatter 'xhtml' regions

[Ricardo Signes]

* David E. Wheeler da...@kineticode.com [2009-12-11T14:02:33]
 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.

I think it's way out of scope to validate here.  I think it's totally
reasonable to make sure there's a hook for doing so.

 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.

David and I spoke on AIM.  This is 99.99% a regression introduced in October!
I will fix it.

-- 
rjbs

Re: XHTML formatter 'xhtml' regions

[Ricardo Signes]

* Ricardo Signes perl@rjbs.manxome.org [2009-12-11T14:40:52]
 David and I spoke on AIM.  This is 99.99% a regression introduced in October!
 I will fix it.

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!

-- 
rjbs

Re: expanding =begin

[Ricardo Signes]

* Allison Randal alli...@perl.org [2009-12-01T05:44:02]
 David E. Wheeler wrote:
 
 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 is to keep the regex the same for the formatname (which is
 strictly defined), and just say everything after the space to the
 end of the line is the parameter.

Agreed.  Then we avoid accidentally limiting the content of the parameter
beyond valid content for a Pod paragraph.

-- 
rjbs

is LFoo::Bar|Foo::Bar still needed?

[Ricardo Signes]

I'm still in the habit of writing:

  This code is built with LKosher::Salt|Kosher::Salt.

To avoid:

  This code is built with the Kosher::Salt manual page.

Has this behavior been eliminated in all the common Pod translators?  I haven't
seen it in some time.

-- 
rjbs

Re: deprecating LSection

[Ricardo Signes]

* Nicholas Clark n...@ccl4.org [2009-12-01T13:57:18]
 
 Although I note (without investigating)
 
 http://perl5.git.perl.org/perl.git/blob/HEAD:/Porting/Maintainers.pl#l1295
 
   # XXX these two files correspond to similar ones in blead under
   # pod/, but the blead ones have newer changes, and also seem to
   # have been in blead a long time. I'm going to assume then that
   # the blead versions of these two files are authoritative - DAPM
   'EXCLUDED'  = [ qw( lib/perlpod.pod lib/perlpodspec.pod ) ],
 

I will happily get any divergence fixed myself when I start making the changes
I talked about in recent messages.

-- 
rjbs

Re: allowing Ltext|href

[Ricardo Signes]

* David E. Wheeler da...@kineticode.com [2009-12-01T14:16:39]
 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).

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.

-- 
rjbs

=encoding [is making me crazy]

[Ricardo Signes]

Right now, all my Pod-handling code basically ignores =encoding.  It doesn't
know anything about what it does or what it's for.  I do not plan to add
support for much of it, because for the most part I don't think it's worth the
time.  My plan is to, more or less, do this:

  * assume documents are in ASCII unless =encoding appears
  * raise an exception on 8-bit characters unless =encoding appears
  * accept the instruction =encoding utf-8 as meaning the document is UTF-8
  * raise an exception on any other =encoding instruction
  * possibly raise an exception if =encoding is not the first directive

I know this is not entirely compliant, but I think it's good enough for my
intents.  I should have almost no problem decoding only the Pod.  Nonpod
paragraphs can be left as octets.

My only question is:  how shall I handle data paragraphs?  For example:

  =encoding utf-8

  =begin data

  This is a data paragraph with a UTF-8 sequence right here: €

  ...and this is part of the same data paragraph (because they're all
  combined.)

  =end data

  Look, an ordinary paragraph.

If that Pod is converted to an element tree and the data paragraph is
extracted, should its contents be a character string or byte string?

-- 
rjbs

Pod::Elemental back on track

[Ricardo Signes]

I'm still working on my pod mangling tools, as funded by TPF, after an
unfortunately protracted distraction.

I recently blogged a very simple overview of what the tools can do hre:

  http://rjbs.manxome.org/rubric/entry/1805

You can see the code producing the demo (which is now better than what the blog
post used)  here:

  http://github.com/rjbs/pod-elemental/blob/master/eg/demo-pod

Here's an example of the second-to-final block printed by that program now:

  Document
Pod5::Ordinary Ordinary Paragraph 1.1
=begin :dialect
  Pod5::Ordinary This is a paragraph.
  =image foo
=head1 Header 1.1
  =head2 Header 2.1
=head1 METHODS
  =head2 foo
Pod5::Ordinary Ordinary Paragraph 2.1
=over 2
=item * bar
=back 
=head2 Header 2.2
Pod5::Ordinary Ordinary Paragraph 2.2
=head3 Header 3.1
=over 4
=item * foo
=back 
  =head2 quux
Pod5::Ordinary Ordinary Paragraph 2.4
Pod5::Nonpod 
  =head2 quince
Pod5::Verbatim   my $method = …quince(1,2,3);
Pod5::Ordinary The above will …wing will not:
Pod5::Verbatim   my $method = …quince(3,2,1);
Pod5::Nonpod ␤sub quince {␤ …ity(@args);␤}␤
Pod5::Ordinary Is that clear?
=head1 Header 1.2
  Pod5::Ordinary Ordinary Paragraph 2.3
=begin comments
  Pod5::Data This is a big c…oes on and on.

Thoughts, feedback, etc, are welcomed.  Actually, I'd love any of them,
although I don't expect much.  I know the world of pod is pretty sedate. ;)

-- 
rjbs

Re: X vs. X

[Ricardo SIGNES]

* Allison Randal alli...@perl.org [2009-05-24T19:13:22]
 I've been pondering how to simplify how some things are explained, and that's
 one place where I think the spec itself could be simplified without any real
 problems.

 To simplify the explanation without changing the implementation, just  
 tell people not to include any spaces right inside the formatting codes  
 (most people don't put spaces there anyway).

Actually, the space is *required* right inside double-or-more angle brackets.

 perlpodspec.pod
 Formatting codes absolutely cannot span paragraphs. If a code is opened  

Thanks!  Somehow I missed that.

I keep telling myself that I am the *only* person who is interested in the idea
of restructuring perlpodspec to be more... structured.  I remind myself that if
I skip it, I can go play Mario Kart... so far, so good.

-- 
rjbs

Pod::{Weaver,Elemental,Eventual} work begun

[Ricardo SIGNES]

I have begun work on my Pod-mangling grant, described here:

  http://rjbs.github.com/pod-weaver/

...so you can expect me to talk about stuff here while I go along.

The first thing I'm doing is re-reading Lperlpodspec, this time with a closer
eye for detail.  I'm finding a number of little nits, but the biggest finding I
have is that most of document is a big pile of declarations or suggestions.
While it's all Iuseful stuff, it's sort of random and disorganized.

I'm wondering whether a restructuring would be useful.  I mean, it's not like
people need to refer to it all that much.  Anybody?

I've been producing a list of questions or quirks as I go, and I'll probably
send a number of messages to the list today or tomorrow, one about each
question.

-- 
rjbs

Pod POD pod poD pOd or P.O.D.

[Ricardo SIGNES]

I am not clear on whether this paragraph says or means much:

  Throughout this document, Pod has been the preferred spelling for the name
  of the documentation format. One may also use POD or pod. For the
  documentation that is (typically) in the Pod format, you may use pod, or
  Pod, or POD. Understanding these distinctions is useful; but obsessing
  over how to spell them, usually is not.

So: the format is POD, Pod or pod, but a document is the pod, Pod, or POD?

Is it trying to say that all three are always acceptable and not to worry about
it?  If there is an intended distinction, I'd like to clarify it.

I'd think Pod for the format and pod for the pod of that module over
there.

(FWIW, I'm submitting a few patches to this doc to p5p to correct obvious
errors.)

-- 
rjbs

Re: CPP-style #includes in POD

[Ricardo SIGNES]

* David Cantrell da...@cantrell.org.uk [2009-05-21T10:26:48]
 The obvious solution is to have both module and script #include the
 appropriate chunk of POD.
 
 So I'm thinking:
 
 =begin cpp
 ...
 =end cpp
 
 has anyone already done this?  And if not, am I correct in thinking that
 I need to write Pod::cpp, have that as a pre-req, and basically follow
 the recipe in the Pod::Simple::Subclassing doco?

This is the sort of thing that I do on the author-side before distributing, and
I do it with Pod::Weaver.  It'd be easy to do with Pod::Eventual, though, too,
and much simpler to learn how.  Basically, you'd use Pod::Eventual::Simple,
turn the document into an event stream, replace the =include event stream with
one from another file, and rewrite it out.

I've generally found Pod::Simple to be too complex for quick hacks because it's
meant to deal with *all* of pod, whereas what I need is usually a much simpler
subset.

-- 
rjbs

Re: Pod::Elemental, a standards-snubbing pod mungler

[Ricardo SIGNES]

* nadim khemir [EMAIL PROTECTED] [2008-10-26T04:57:45]
 So Ricardo, what is it you want? I know this sounds strange but it's what I 
 find myself thinking at this point. It is difficult to comment on anything 
 you have written because you have it all right.

Well, mostly I'm just wondering if someone is going to say, You will encounter
great problems if you don't support X because it's the secret problem we have
been most often dealing with in recent POD or it would be great to use this
for Y if only you had a simple method for Z.

-- 
rjbs

questions about =cut

[Ricardo SIGNES]

I'm pretty sure that Pod::Eventual has a bug or two related to =cut, but I
haven't written the tests yet because I'm not sure how I want to procede.

This POD:

  This is text.

  =head1 HEADER
  ...and some text.

  =cut
  Text again.

results in something roughly like this:

  { type: text, content: This is text.\n }
  { type: command, command: head1, content: HEADER\n...and some text.\n }
  { type: command, command: cut,   content: \n }
  { type: text, content: Text again.\n }

In other words, content that is notionally part of the =cut command (because
there has not yet been a para break) is not made part of the =cut event.
That's because I emulated perl's behavior of going back to Perl on the line
after =cut.

Following perl isn't necessarily the right thing, since when Pod occurs inside
a here-doc it is both part of the Perl document (perl thinks it's in code) and
part of the Pod document (the existing Pod translators pick it up as Pod).

So I think the right thing is to say that content after =cut and before a
paragraph break is part of the =cut commant's content.  (Sure, this is fairly
academic, but it would be nice to reduce the scope of =cut's special casing.)

Also: I know =cut doesn't take content or arguments.  That's for a semantic
parser to deal with.  Eventual just finds events.

The other case is this one:


  say 1;

  =cut

  say 2;

  =cut

  say 3;

perl will say 1 and 3.  Does that mean that Csay 2; is really inside Pod,
or is that a quirk of perl?

If so, is =cut just a misnamed =toggle?

I wonder if perlpod.pod could use some updating.

-- 
rjbs