At 10:19 2002-10-17 -0700, Russ Allbery wrote:
At least so far, Pod::Simple doesn't fit the way that I prefer to work very well.I have a feeling this is something entirely peculiar to you, and your unique combination of inexperience with modern markup language parsing approaches, and wealth of experience with Pod::Parser's very strange approach to, well, everything, including the very concept of parsing itself.
It's not a bad thing that you have managed to think in Pod::Parser's terms and not so much in terms of things like SAX, XMLA::Parser, etc; but you do have to recognize that it's a totally idiosyncratic perspective.
If you can articulate what it is you like about Pod::Parser's interface, I think I can make a thin wrapper around Pod::Simple that will make it work that way in that particular respect. Would you like if I made something like the Pod::Simple::Methody class that uses the return value of methods as the code that is to be sent to the output channel, and/or if it had some notion of "the output text of the paragraph in progress"? I'm more than willing to accomodate all sorts of approaches to things. As you explain what you want, do bear in mind that it's been a while since I've been conversant with Pod::Parser's interface.
I'm not sure that anyone would write a new one from scratch, but I could readily see someone improving Pod::Parser to bring it up to the current specification.I wouldn't mind if someone really did try to bring Pod::Parser up to spec, and also would improve its docs, and its interface, and to make it a real parser for Pod, instead of barely more than a tokenizer for the set of Pod-like languages.
I considered being that somebody, but as I read Pod::Parser's documentation and source, I decided it /really would/ be easier to start over.
It has been about a year since I finished writing perlpodspec, and I've seen no signs that anyone is interested in modernizing Pod::Parser. You and one or two other people have said "it'd be nice if someone did", but there has been a universal expression of disinterest in actually doing it.
Incidentally, it is my opinion that changing Pod::Man to use Pod::Simple is a much more important (and vastly easier) task than bringing Pod::Parser into the 90's, much less the 00's. Are you interested in trying to make Pod::Man use Pod::Simple? If dealing with Pod::Parser's interfaces is too hard for you, I could probably find someone else who knows enough *roff to pull it off. But I'd like it to happen sooner rather than later.
I realize that Sean's been working hard on getting things working rather than cleaning them up, so hopefully this will improve, but at least right now the source for Pod::Simple doesn't make for a very good reference implementation, at least in my opinion.Okay, give me compelling arguments for why I should make it be a good reference implementation, rather than just work well and have a good API.
Bearing in mind that I'm doing all the actual work here, I emphasize the word "compelling".
At the moment, I'm tending toward saying that Pod::Simple doesn't need to be a good reference implementation of a Pod parser any more than perl needs to be a good reference implementation of a Perl interpreter/compiler. That is, if magic wands and copious spare time were available, yes, I'd like for both perl and Pod::Simple to be good as reference implementations; but what are the /compelling/ arguments for doing so, now, instead of doing other things that subjectively seem more important?
I'm torn between saying "funny, that's what I thought when I read Pod::Parser", and "funny, that's what I thought when I read the perl source".It's extremely dense, mostly uncommented, and very difficult to read.
But actually, there are 165 DEBUG statements in Pod/Simple.pm and Pod/Simple/BlackBox.pm, which each explain what that bit of code is doing. As they are extremely explanatory, just like comments are.
BTW, you might find this an instructive way to start your programs:
use Pod::Simple::Debug (10); # to set DEBUG level to 10
use Pod::Simple;
--
Sean M. Burke http://search.cpan.org/author/sburke/
