Re: podlators v6.0.0 released
On Wed, Jul 10, 2024, at 23:39, Russ Allbery wrote: > I'm pleased to announce release v6.0.0 of podlators. Thanks for your seeming unending efforts to keep Perl's documentation system going strong. I continue to get benefit from this work, well over 20 years after I first started using it. -- rjbs
Re: POD formatter version comments
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
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: Working on CPAN Testers fails for Pod::Simple::Search
* "David E. Wheeler" [2016-04-29T16:43:03] > Anyone object to making Neil a committer and co-maint on Pod-Simple? (I’m > hoping Neil doesn’t object.) The canonical repository is here: No objection, and I preemptively overrule Neil's potential objection. -- rjbs signature.asc Description: Digital signature
Re: podlators 4.07 released
* 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
* 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: Allow Whitespace in L<> URLs?
* "David E. Wheeler" [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. Lhttp://baz-bar>should be okay Lhttp://baz bar>should not Lhttp://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: Pod::Simple can treat binary as pod due to liberal/inconsistent regexp patterns
* "David E. Wheeler" [2015-01-08T00:38:04] > I agree that’s too liberal. I suggest > > /\A=([a-zA-Z]+\d*)\b/ Surely you want [0-9] instead of \d, lest we end up with =head୩ ! -- rjbs signature.asc Description: Digital signature
Re: Assume CP1252
* Grant McLean [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: Announcing MetaPOD
* Kent Fredric [2013-05-31T09:41:51] > In the last few hours I uploaded something I hope people will find useful. > > MetaPOD Neat, thanks. :) -- rjbs signature.asc Description: Digital signature
Re: Is Pod::Simple::POD worth pursuing?
* John SJ Anderson [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
* Russ Allbery [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
podlators broken by Pod-Simple 3.24
Pod::Simple 3.24's new warning on mismatched item types has broken podlators. This is pretty unfortunate, since it also fixes hash ordering problems in tests which will be needed if some of the last patches to hash ordering land in 5.18.0. I had a quick look at the tests, but I don't really know what they're up to, so I'm hoping that you (Russ) can have a look at this. -- 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
* "David E. Wheeler" [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: Pod::Simple doesn't warn when the text of a definition =item matches /[\*\d]/; and a fix to this bug
* Ricardo Signes [2013-01-18T08:54:05] > 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 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. -- 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
* Marc Green [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: Version comments in POD output
* Russ Allbery [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)
* "David E. Wheeler" [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
Re: Nested Links in XHTML Head Elements
* "David E. Wheeler" [2012-06-07T12:02:55] > > > > http://search.cpan.org/perldoc? > > perldata">perldata > > > > This is caused by the L heading in perldelta.pod. > > So, should Pod::Simple’s HTML output: > > * Strip links from head elements; or > * Exclude head elements with links from the TOC; or > * Something else? If I understand things correctly, then when you say L in something that becomes a section header, the TOC links to it by doing something morally equivalent to L|/foo>, which is obviously nuts. Restated: * =head2 L becomes "bar" * the TOC links with bar The text of the link in the TOC should be the same as the text of the thing to which it's linking. So the TOC should link with: bar ...and if you'd said (you can say this, right?) "L<< The B Bang|boom >>" then the TOC should have something like: The Big Bang This email has received about 120s of thought, so it might be a terrible idea. It feels pretty sound, though. (Oh, but I totally punted on the #-anchors there. They weren't really at issue, right?) -- rjbs signature.asc Description: Digital signature
Re: Possible patch to Test::Pod
* Russ Allbery [2012-06-06T01:10:01] > Grant McLean writes: > > > While my patch adds a warning, in combination with Test::Pod it is > > effectively elevated to a fatal error which blocks a clean installation > > of affected distributions. > > > The "correct" answer is for people who use Test::Pod to only run those > > tests on the author's system - i.e. pre release rather than pre install. > > (And ideally add the missing -=encoding too). Of course it might be a > > bit inconvenient for some maintainers to rush out a new release for that > > reason alone. > > I don't think I agree with this, and I'm not sure why that would be a > recommendation. Surely, the tests should fail if there are bugs in the > documentation? I don't see what's different about this than any other bug > in edge functionality or minor APIs, which may not affect any particular > user but which are routinely diagnosed as bugs by the test suite. If the author is shipping his Pod tests to run for all users, and to prevent installation when the Pod is detected as might-be-broken, and if the tools for detecting might-be-broken Pod get better, this is exactly what should be expected. Almost certainly, as Grant said, the authors should have limited the Pod tests to their release process. The biggest question for me is: if we add this exception now, will we also add exceptions for every future warning? Are only the current warnings as of 2012-05-01 the ones that should be allowed to make Test::Pod fail? Otherwise, what's the transition plan from passing on this warning to not passing on this warning? We can't say "only fail if it's the author running the tests" because we don't know. In fact, the author should be telling us this by making the tests only run for him or her, which gets us back to that problem. So, maybe we'll say "well, this warning is not fatal for a year, by which time you should really have gotten around to this." Except only x% of authors will, and then we're back to a bunch of breakage, and this argument again about whether we extend the grace period or allow the test failures to break those modules that were otherwise so stable that they needed no fixes in the last year. DBI is already fixed. Dancer releases frequently already, so the notion that we're forcing them to "rush out a new release" doesn't seem too troublesome. Do we have a list of affected dists? > Why would an end-user have trouble with failing tests at install time? If > they don't care about the failure, just ignore it and install the module > anyway. > > Is there some tool involved that's refusing to install modules if the test > suite fails? If so, I think that tool is what's buggy here, and that tool > should be fixed so that it's possible to install modules with failing > tests, since that's very common, for many reasons other than this. Basically every tool that does CPAN installs will refuse to install if the test suite fails, and this isn't going to be viewed as buggy or changed. End users don't always know whether the test failure is significant or not. This is another reason for authors to disable insignificant tests in their shipped distribution. -- rjbs signature.asc Description: Digital signature
Re: podlators 2.4.1 released
* Russ Allbery [2012-05-30T15:01:53] > This is long-overdue, and still doesn't address the various character set > and encoding problems, but it at least fixes a bunch of other bugs. I'm > going to try to rethink the UTF-8 problem next. Thanks, Russ! That's a whole mess of improvement! -- rjbs signature.asc Description: Digital signature
Re: Strange perldoc perldoc
* Shawn H Corey [2012-04-30T12:26:58] > With further investigation, I found that pod::perldoc is formatted > for regular paragraphs in is SYNOPSIS. It's the pod2... that decided > that anything under SYNOPSIS _must_ be verbatim. Since when was this > decided and why? I believe you are mistaken -- or that you are using an old version of perldoc. http://api.metacpan.org/source/MALLEN/Pod-Perldoc-3.17/lib/perldoc.pod The SYNOPSIS contents are indented. Someone earlier in the thread noted that this has not always been the case. The pod2_ programs seem blameless, here. -- rjbs signature.asc Description: Digital signature
Re: Strange perldoc perldoc
* Shawn H Corey [2012-04-30T10:18:57] > I just ran `perldoc perldoc` and got this: > > SYNOPSIS >B [B<-h>] [B<-D>] [B<-t>] [B<-u>] [B<-m>] > […] > > Why is there mark-up in these verbatim paragraphs? Funny. My guess is that the author was targeting Pod::Simple::XHTML which, as was recently discussed, strangely chooses to display verbatim blocks not-verbatim by default. This should be fixed in perldoc's Pod. -- rjbs signature.asc Description: Digital signature
please test perl5.git's Pod-Html
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: pod checker that finds missing internal links?
* Patrice Dumas [2012-01-27T18:15:17] > More precisely, podchecker coming with perl 5.10 gets it wrong, it > finds multiple defined labels because it takes only into account the > beginning of an =item, for example podchecker is in the process of being replaced with Pod::Simple-based code. Hopefully that will help. Maybe Marc Green can comment... -- rjbs signature.asc Description: Digital signature
Re: Fwd: [rt.cpan.org #74389] Pod::Simple::Pullparser get_title should ignore X<...>
* Marek Rouchal [2012-01-29T03:05:50] > I agree... the content of X<...> is not visible text, so for > > =head1 NAME > X > > Pod::Simple should return "NAME" for the heading text, not > "NAME some text" 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 X THIS X TUNE X ...should be "NAME THIS TUNE" But in the simpler case, I think that "NAME" and not "NAME " is actually likely to come up. -- rjbs signature.asc Description: Digital signature
Re: an 'anchor' command is missing from Pod
* Shawn H Corey [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. X 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
* Shawn H Corey [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 > Z You're thinking of X<> -- Z<> should always be empty, and is a zero-effect code. X is used to help indexing. It isn't how perldoc -f works, though. -- rjbs signature.asc Description: Digital signature
Re: [rt.cpan.org #74389] Pod::Simple::Pullparser get_title should ignore X<...>
* "David E. Wheeler" [2012-01-25T22:03:26] > On Jan 25, 2012, at 6:00 PM, Ricardo Signes wrote: > > >>> =head1 NAME > >>> X > >>> > >>> 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 NAME Some Entry? That would certainly be an error. > > No, it doesn't. Text: ...then without a failing test to demonstrate what's up, I got nothin'. -- rjbs signature.asc Description: Digital signature
Re: Fwd: [rt.cpan.org #74389] Pod::Simple::Pullparser get_title should ignore X<...>
* "David E. Wheeler" [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 > > X > > > > 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 NAME Some Entry? That would certainly be an error. -- rjbs signature.asc Description: Digital signature
Re: Deprecation of alternate text in hyperlinks
* Karl Williamson [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
* Marc Green [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
* Marc Green [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 L
* Nicholas Clark [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 L
* Michael Stevens [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: no deprecation warning for L
* Karl Williamson [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: `=item 1. Text` Doesn't Produce Ordered List Item
* "David E. Wheeler" [2010-11-12T13:56:01] > 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. 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. 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. -- rjbs
Re: `=item 1. Text` Doesn't Produce Ordered List Item
* "David E. Wheeler" [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
* "David E. Wheeler" [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
* "David E. Wheeler" [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: `=item 1. Text` Doesn't Produce Ordered List Item
* "David E. Wheeler" [2010-07-20T00:55:33] > This Pod: > > =over > > =item 1 Item 1 > > =item 2 Item 2 > The correct way to write this according to the Pod spec is: =item 1 Item 1 =item 2 Item 2 Does that help? -- rjbs
Re: pod2html
* Will Coleda [2010-06-29T20:01:51] > > Is subclassing Pod::Simple::HTML the current best practice for doing > this? (I have some =begin/=end markers that I need to be handled in a > non-standard fashion) I tend to use Pod::Simple::XHTML, but either one can work. > If so, any pointers on how would be greatly appreciated. I tend to abuse Pod::Simple in conjunction with Pod::Elemental, so these are not demonstrative of much beyond my hamfistedness: http://cpansearch.perl.org/src/RJBS/WWW-AdventCalendar-0.100160/lib/WWW/AdventCalendar/Article.pm http://github.com/rjbs/pod-cyoa/blob/master/lib/Pod/CYOA/XHTML.pm http://github.com/rjbs/dzil.org/raw/master/src/tutorial/build-tutorial.pod Sorry. I can probably help with specific questions. Oh, this might be useful: http://cpansearch.perl.org/src/DWHEELER/Pod-Simple-3.14/t/xhtml05.t -- rjbs
Re: Seeking guidance on use of X<...> in pods
* karl williamson [2010-06-02T18:08:24] > I couldn't find any documentation on when to use X<...>. I would > have thought it would be reserved for the single (or few) main > defining text that applies to the indexed term, but it appears that > existing practice uses it for minor mentions of the term. I'm not sure what things usefully index X<...> entries, but I think that your assumption is correct and lousy uses are probably the result of lousy indexers. You know how most technical books have really crappy indexes? Those are written by professionals. Imagine how lousy the ones that amateurs are trying to write with X<...> are going to be... -- rjbs
Re: SPEC UPDATE: [rt.cpan.org #55602] Bug #12239 was a mistake
* "David E. Wheeler" [2010-04-20T13:35:11] > 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? 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. I could be wrong. I will ask him if he's around, today. -- rjbs
Re: SPEC UPDATE: [rt.cpan.org #55602] Bug #12239 was a mistake
* "David E. Wheeler" [2010-04-20T12:27:11] > On Apr 19, 2010, at 7:39 PM, Ricardo Signes wrote: > > > This is done. I've bumped the version number, installed locally, confirmed > > that it DWIW, and Christopher Madsen has also confirmed that it's what he > > expects. > > > > Can we get 3.14 on the CPAN, then I'll work on getting in into blead, if not > > maint. > > Yes, although there are a few bugs I'd also like to get fixed: > > https://rt.cpan.org/Ticket/Display.html?id=56572 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? -- rjbs
Re: SPEC UPDATE: [rt.cpan.org #55602] Bug #12239 was a mistake
* Ricardo Signes [2010-04-19T15:09:56] > * "David E. Wheeler" [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. This is done. I've bumped the version number, installed locally, confirmed that it DWIW, and Christopher Madsen has also confirmed that it's what he expects. Can we get 3.14 on the CPAN, then I'll work on getting in into blead, if not maint. -- rjbs
Re: SPEC UPDATE: [rt.cpan.org #55602] Bug #12239 was a mistake
* "David E. Wheeler" [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: SPEC UPDATE: [rt.cpan.org #55602] Bug #12239 was a mistake
* "David E. Wheeler" [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: Ansi color tag
* nadim khemir [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 )? )? ">" G Here is a link to our internal bug tracker: G ...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
SPEC UPDATE: [rt.cpan.org #55602] Bug #12239 was a mistake
As promised ages ago, here is my attempted, very simple fix for the pod spec. I don't think the spec is wrong, but making its intent clearer shouldn't hurt. The entire suggested change is this commit: http://github.com/rjbs/perl5/commit/59b13951596010d0e104d040e92785de6e21f226 If there is no serious dissent, I will commit this to perl5/blead. I will also lobby for the inclusion of an updated Pod-Simple into 5.12.1. -- rjbs
Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)
* Allison Randal [2010-03-16T08:01:49] > David E. Wheeler wrote: > > > >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 `<>`. > > That's my interpretation too. If you have to escape every angle > bracket inside doubled-up C<<>> tags, there's really no point in > even having the doubled-up tags. No one is saying that you have to escape every angle bracket inside anything. For example, these should all be fine: The ->, or dereference, operator... Call C<< $object->foo >> If x > 10 All items where C<< $x > 10 >> In the event that C<< $x > L->blort >> In the first four, there is no ambiguity. We don't have something in the form X<...> where X is [A-Z]. The only thing in question is the last one. The question is whether all characters until the matching \s>> are considered literally or whether they're still Pod. The bug report from CJM seems correct: formatting codes should work inside C<<>>. There is nothing about that change which would require escpaing -> or other non-formatting-code uses of angle brackets. -- rjbs
Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)
* "David E. Wheeler" [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: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)
* "David E. Wheeler" [2010-03-15T14:56:48]
> >
> >C<<< open(X, ">>thing.dat") || die $! >>>
> >C<< $foo−>bar(); >>
> >
> >which is presumably easier to read than the old way:
> >
> >CEthing.dat") || die $!>
> >C<$foo−Ebar();>
>
> 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 EE because there's no open quote to give the
closing one special significance. If we did this, though:
C<"Hello world." >> cout;>
...then the first > closes the C<>.
What if we wanted:
C<< ls > F >>
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: Fwd: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)
* "David E. Wheeler" [2010-03-15T13:32:28] > Comments? >From perlpodspec (presented as verbatim text): =item C<< $thing->stuff(I) >> Further, I see nothing that implies that C<< C >> should be rendered as "C" 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: All tests fail
* Mike Brown [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
* "David E. Wheeler" [2009-12-17T17:31:16] > I've released it as Pod::Simple 3.13. Enjoy. Great news, thanks! -- rjbs
Re: Pod::Simple fullstop_space_harden Attribute
* "David E. Wheeler" [2009-12-14T17:24:56] > 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. The only part of my serious Pod stuff that uses Pod::Simple is the advent calendar, which still renders as well as usual with the new commit. -- rjbs
Re: XHTML formatter 'xhtml' regions
* Ricardo Signes [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: XHTML formatter 'xhtml' regions
* "David E. Wheeler" [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 [2009-12-11T13:36:32] > * "David E. Wheeler" [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 ... =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
* "David E. Wheeler" [2009-12-11T12:56:28] > > > > =for xhtml ... > > > > ...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
XHTML formatter 'xhtml' regions
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 " or "becomes " 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 ... ...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
Pod::Simple "simplification"
NOTE: I went on too long. You can skip to "ACTUAL QUESTION" if you hate it when I ramble. So, I go and spend several weeks or months of my life writing something so that I never need to use Pod::Simple, and here I am learning about how Pod::Simple works so that I don't need to implement formatting codes. Life is funny. My "Advent calendar" of Perl module articles uses Pod to mark up the documents. I use Pod::Elemental transformers to produce Pod suitable for feeding to Pod::Simple::XHTML, which produces all the HTML of the article bodies save for the code samples. You can see the output here: http://advent.rjbs.manxome.org/2009-12-08.html I've had to do more hacking around than I think is reasonable to get it to work how I'd like, largely (I think) due to weirdness in how regions are handled in Pod::Simple. Regions, in fact, are what led me to write my own Pod handling code in the first place, way back when! Sadly, figuring how how to do stuff is a pain because the documentation is weird and scattered. It's also hilarious at times. Earlier tonight I chuckled at this: CAVEATS: This is just a beta release -- there are a good number of things still left to do. Notably, support for EBCDIC platforms is still half-done, an untested. If I was going to name what was most notably missing from Pod::Simple... yeah, not EBCDIC. Anyway, I'm digressing far more than I meant to. I'd like to (a) document more of what I've learned and (b) fix the fixable problems that I've encountered. Documenting things now is silly, because most of what I've learned is what to fix, not what to document. ACTUAL QUESTION: Is there any strong feeling that Pod::Simple needs to have so many things done either apparently or clearly in the interest of speed? I found a number of methods that I could barely track down because they're generated strangely, explicitly in the name of speed. There's a good bit of code to allow debugging output to be optimized away, which leads to stupid method of using "DEBUG" which leads to stupid bugs. And so on. I would like to refactor the code as I work so that methods are easier to find, use, and replace as needed. Maybe I can fill in some of the "to do" documentation, once I understand what the hell is going on. Is anyone going to be put off by these kinds of changes *in general*? The first one I hope to make is to add $self->debug($level, $msg) to replace the use of "print" which is broken when there's a non-STDOUT handle select-ed. That's also a good taste of the kind of changes I think I'll end up wanting to make. -- rjbs
Re: allowing L
* "David E. Wheeler" [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
Re: deprecating L<"Section">
* Nicholas Clark [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: deprecating L<"Section">
* "David E. Wheeler" [2009-12-01T14:03:21] > Jesus Christ. > > I don't think they should be in Pod::Simple. So I'd like to remove them. > Anyone else have any opinions? Allison? HDP? RJBS? TorgoX? I do not like them in Pod-Simple. I think if they are in Pod-Spec, it's a little easier to move Pod ahead without touching core, because all(?) pod tools are dual-lived anyway. My preference for canonical copies, in order: Pod-Spec, core, Pod-Simple -- rjbs
Re: deprecating L<"Section">
* "David E. Wheeler" [2009-12-01T12:36:54] > On Dec 1, 2009, at 4:55 AM, Ricardo Signes wrote: > > > 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? Gosh, I didn't know Pod-Simple included those. I'd much prefer it be core, to keep the reference separate from an implementation. (I wouldn't object to Pod-Spec, but I don't think we want to give core one more thing to sync up.) -- rjbs
deprecating L<"Section">
This is one of those bits of syntax that, I think, almost nobody really knows about -- and that those who do wish they didn't. We all know L and L. These can both also be written as L and L, which I guess is fine, although sort of pointless. That's not the gross case. The grossest case is L which is totally unambiguous and was (hooray) deprecated in perlpodspec in 2001. The sort of utterly insane (but less ambiguous) case is L<"Section"> which is equivalent to L In other words: L links to Foo::Bar but L<"Foo::Bar"> links to the section Foo::Bar in the current document. The meaning of L<"Foo::Bar"/"Foo::Bar"> is left as an exercise to the reader. I propose to remove mention of L<"Section"> from perlpod and to deprecate it in perlpodspec, and also to reword the mention of L in perlpodspec to make it less optional and more dead. 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. Thoughts? -- rjbs
is L still needed?
I'm still in the habit of writing: This code is built with L. 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: expanding =begin
* Allison Randal [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: > > > > C > > 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
allowing L
The long-lost question of "Why can't we have L?" came up this week
on p5p. David Wheeler and I spoke about the issue briefly, because we couldn't
find anything in perlpod or perlpodspec that really specifically addressed the
reason other than "because it would be difficult."
I did a fair big of archive-diving and found two basic arguments:
(1) Sean Burke was fighting against very painful parsing code and wanted to
keep things as simple as possible, which was "not very simple" to begin
with. Adding this seemed too hard, and it was declared off limits.
(2) It was unclear how non-hypertext formatters would choose to render links
with text.
As to (2), I think it's up to the formatter, many of them already deal with
this problem, and I do not think any formatter author will be terribly
inconvenienced by it.
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:
# Grammar for L<> in Pod5
link-code = "L<"
( link-text "|" ) ?
(link-target)
">"
link-text = [^|]+
link-target = pod-target
| man-target
| internal-target
| url-target
pod-target = perl-module-name
( "/" section-name ) ?
man-target = [-\w]+ ( "(" digit ")" ) ?
( "/" section-name ) ?
internal-target = "/" section-name
| "/" quoted-sec-name
| quoted-sec-name
section-name= [^|/]+
quoted-sec-name = DQUOTE section-name DQUOTE
url-target = \w+ ":" [^:\s] \S+
The only ambiguity that is obvious to me is also obvious to perlpodspec.
L could mean either xyzzy.pm in @INC or the man page for xyzzy. The
L form disambiguates in favor of man. This is already a known issue
and is not complicated by allowing Lhttp://foo.com>
So... what's the problem?
--
rjbs
expanding =begin
>From perlpodspec: "=begin formatname" 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/". Implementors should anticipate future expansion in the semantics and syntax of the first parameter to "=begin"/"=end"/"=for". 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. -- rjbs
=encoding [is making me crazy]
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::Weaver is released
After a whirlwind of activity, I've released v3 of Pod::Weaver, which finally realizes my original vision, only better. You can see an outline of how the program is used, here: http://gist.github.com/217004 >From here on out, I just improve its configuration and write more plugins, I hope! -- rjbs
Pod::Elemental back on track
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
=begin :dialect
Pod5::Ordinary
=image foo
=head1 Header 1.1
=head2 Header 2.1
=head1 METHODS
=head2 foo
Pod5::Ordinary
=over 2
=item * bar
=back
=head2 Header 2.2
Pod5::Ordinary
=head3 Header 3.1
=over 4
=item * foo
=back
=head2 quux
Pod5::Ordinary
Pod5::Nonpod <>
=head2 quince
Pod5::Verbatim < my $method = …quince(1,2,3);>
Pod5::Ordinary
Pod5::Verbatim < my $method = …quince(3,2,1);>
Pod5::Nonpod <sub quince { …ity(@args);}>
Pod5::Ordinary
=head1 Header 1.2
Pod5::Ordinary
=begin comments
Pod5::Data
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<< >>
* Allison Randal [2009-05-25T20:01:29] > Ricardo SIGNES wrote: >> >> I keep telling myself that I am the *only* person who is interested in the >> idea of restructuring perlpodspec to be more... structured. > > Nah, certainly not the first, just the most recent in a series of us. I > mean, perlpodspec itself was written with that very thought in mind, > back when the definition of Pod was "whatever perldoc parses". Right. perlpodspec is a fantastically useful, practical document. I like it. It's good because it really cuts through the crap and answers all the questions you're going to expect. My only beef, for the most part, is that it's sort of a pile of facts. I will not admit any notion that Pod5 is done for, but I will admit that it's not likely to change much -- so the idea of spending any time making the spec easier on future parser implementors is ... not that great. I thought I might be able to use my new Pod::* code to trivially implement much of Pod6, but once I realized that it was not compatible with the perl5 compiler, I was less enthused. >> I remind myself that if I skip it, I can go play Mario Kart... so far, so >> good. > > Most of us end up writing our own special-purpose variant or extension > of Pod. I'm not sure if that's preferable to Mario Kart. Yeah, that's largely what I'm working on enabling in a better way than what I have now. That wins out, but Random Leisure Activity wins out (for now) over an overhaul of perlpodspec. See you in Pittsburgh! -- rjbs
Re: Pod POD pod poD pOd or P.O.D.
* John McNamara [2009-05-25T05:03:28] > I'd be wary of making any changes to perlpodspec beyond fixing typos (if > any) since it affects everyone who will write or has written a Pod parser. > Also, I'd think that this is the forum for discussing perlpodspec patches > rather than p5p. The only patches I have (or would) submit to p5p without discussion here are obvious mistakes. One bit said that inside a =begin/=end, data paragraphs are not created, for example; it meant ordinary paragraphs. Another bit said =use instead of =encoding. -- rjbs
Re: X<> vs. X<< >>
* Allison Randal [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 POD pod poD pOd or P.O.D.
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
X<> vs. X<< >>
perlpodspec gives "two syntaxes" for formatting codes. There's X and X<< content >>. In the "two or more angle brackets" form, the whitespace immediately following << and preceding >> are not renderable. That's fine, but I'm confused as to why that isn't just the universal case. Is it just a backcompat issue that someone might have been relying on B< foo > having spaces at either end? 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. Also, because it seems almost absurd for the opposite to be true, I'm currently assuming that a formatting code may *never* have a blank line in its contents. That is, this is illegal: I love you B< very > much. I realize these are edge cases. I'm only asking because I'm interested in opinions, not because I think it will come up frequently. -- rjbs
Pod::{Weaver,Elemental,Eventual} work begun
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 L, 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 I 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
Re: CPP-style #includes in POD
* David Cantrell [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
* Allison Randal <[EMAIL PROTECTED]> [2008-10-26T15:33:16] > I'd say you already know where the greatest challenges will lie. That's good to hear. I hate thinking that I'm 80% done, only to have someone point out that I totally missed the major problem and that my design is never going to survive the next 15%. > - You're not currently paying any attention to the content of the X<> > tags. Eventually, someone will want to make a smart formatter for L<> > link tags for HTML, PDF, XML, etc, and will need more intelligence in > handling these tags. But, you can punt for a long time just by handing > the formatter a raw blob of text and letting the formatter parse it. Yeah, I'm totally treating all textual paragraphs (text, verbatim, data) like verbatim paragraphs. I -think- this is safe, because I don't think this is ever considered legal: =begin møøse ... =end mEEse After I do a bit more work reading and digesting perlpodspec, I hope I can help make it more explicit in a few cases, especially to make it clear that formatting codes never affect understanding paragraph syntax. > - Sooner or later, people will want to use Pod::Elemental or > Pod::Eventual as a drop-in replacement for Pod::Parser or Pod::Simple. > (A headache, but a worthwhile one.) That's when you'll need perlpodspec. I'm hoping that I can somehow manage to keep any form of formatting code parsing on the n+1 tier, so that the product would go: pod2sgml is built on Pod::Exegete is built on Pod::Elemental is built on Pod::Eventual is built on rock and roll Actually, I'm hoping to never need to deal with formatting codes, but L. -- rjbs
Re: Pod::Elemental, a standards-snubbing pod mungler
* 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
Pod::Elemental, a standards-snubbing pod mungler
I released Pod::Elemental a few days ago, and just write up a blog post about it. I'd be interested in comments from the list, if anybody cares enough to look at it. http://rjbs.manxome.org/rubric/entry/1690 -- rjbs
questions about =cut
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 C 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
new distribution: Pod-Eventual
I posted this earlier today:
I've been wanting to do some mucking around with POD. I started a little down
this route a few weeks ago with Pod::Coverage::TrustPod and what I found was
that it was really a pain in the butt to easily say, "this file contains POD.
Give me the content of hunks between `=begin foo` and `=end foo`. I'm sure
it's possible, and that if you understand Pod::Simple you can do it fairly
quickly, but I just got too confused and side-tracked trying to figure it out.
I really just wanted to get a hunk of data by saying something like:
my @hunks = Pod::Imaginary->parse('file.pm')->for_formatter('foo');
Later, this sort of thing started to bite me again, because Pod::Simple seems
much more geared to... well, to getting things right. I mean, it doesn't want
you to make up directives all over the place, it understands the relationship
between over and item, and it cares about what's inside of text paragraphs
(like C<> and all that).
After talking about it with Dieter for a while and growing more grumpy, I
realized that this was just like the INI parsing situation. POD is just a line
oriented data format. I could just write a little state machine to collect POD
events and do whatever I wanted.
So, Wednesday after ABE.pm, I wrote Pod::Eventual. It reads POD and collects
lines into events, which look something like these:
my @events = (
{ type => 'command', command => 'head1', content => "NAME\n" },
{ type => 'text',content => "Pod::Eventual - read POD as events\n" },
);
Sure, it doesn't realize that most people would consider that text paragraph to
be "part of" the header. That's fine! It means it also doesn't need to be
special cased the other way to handle this:
=for HTML
...and now some text!
In that case, the paragraph is definitely *not* part of the `for` construct.
Pod::Simple works something like this, under the hood, but it's much more
complicated. Pod::Eventual ignores the structure of the document beyond
paragraphs, and it doesn't look at the content of the text paragraphs. It also
might just get some cases wrong. (Failing tests welcome!)
Still, it makes it very easy to write quick (but accurate) POD handling code.
My hunk-finder from above could probably be:
my @hunks = grep {
$_->{content} =~ /^foo$/m
and ($_->{command} =~ 'begin' .. $_->{command} =~ 'end')
} Pod::Eventual->read_file('file.pm');
...or something very like it.
--
rjbs
