(Short version: making pod2html use Pod::Simple::HTMLLegacy /might/
actually be simpler than patching Pod::HTML or Pod::Parser or whatever.)
On 07/20/2010 01:00 PM, Ricardo Signes wrote:
I would like to see pod2html (as a Pod::Html-based thing) be replaced with
Pod::Simple, which should fix this. [...]
Oh crap! I thought I fixed this years ago!
Namely, I thought I had replaced the innards of pod2man and pod2html
with something that used Pod::Simple, since Pod::Simple is The Way,
and that all other parsing would be a difficult and confusing
duplication of already difficult and confusing effort, etc.
That was The Plan, at least.
(And if you think I got "The Plan" from Battlestar Galactica then you
are very wrong. Because this was all before the Cylons! Sort of. No
sPoILeRz!!!)
Then I get sick, years pass as I get kinda better, I come back, and
find that I forgot some stuff, see above. Namely, I had pod2man and
pod2html on hand, to wrangulate as would be best, but 1: I didn't
follow through, and 2: I failed to flag this and tell folks "hey, this
is the part where someone should follow through, and sooner rather
than later, so I can probably still remember the details"... which I
no longer remember a whit of.
Anyway, the epic:
0) As I was waiting for my tires to get replaced in a... car...
place... in Albuquerque, I started the guts of Pod::Simple, to work in
the spirit of my years-before rebuild of HTML::TreeBuilder, namely to
be as tolerant and understanding of errors as possible.
And over the following weeks, I wrote perlpodspec as I was cranking
out the innards of Pod::Simple, so I could get my head together and
also run my choices in the module's logic past people, in English
instead of as just a block of nasty jumbly-code with "# ??" here and
there.
1) A while into that, I started writing Pod/Simple/HTMLLegacy.pm with
the plan that it would be a drop-in for something that a tiny
"pod2html" file would invoke (just as the current "perldoc" file is a
little file simply invoking a sub in Pod::Perldoc).
3) ...and that I very stupidly wrote in HTMLLegacy.pm that an
invocation as "pod2html" would be deprecated-- but: no, NO, it should
just do as it's told, with no deprecation for any reason that I can
now imagine.
4) ...but I didn't write proper (any) pod documentation for
HTMLLegacy.pm, in fact I left the code+docs like 80% done, or something...
5) ...while I staggered digressedly away to do something else...
probably that was when I went and spent a month making
Pod::Simple::Man's output nearly byte-for-byte identical to the output
of Pod::Man. Ah, what a crisp and delightful time that was.
6) But I similarly-and-worse forgot to produce a /drop-in/ pod2man
replacement. It sure looks like perldoc -o nroff should do the same
job, just not with the same switches and thus not a drop-in.
7) ...and did some other stuff I've forgotten...
8) Then I got sick. Neuro stuff, and it took ages to work out proper
drug combination fixes. Luckily, my boyfriend's work insurance
covered sort-of-most of the cost of this, because it had domestic
partnership benefits (which they have since yanked, with Phelpsian glee).
A side effect of it all is that I permanently have a memory like Swiss
cheese in a stoner's fridge. (I blame Swiss, and stoners.)
9) ...what were we talking about just now?... Fondue?
10) Then there was a long blur of years where I managed to do a good
amount of in-house programming but not managing anything CPANnish
because it felt Just All Too Much... (But I did re-re-rediscover that
Perl really is indeed wonderful at the task of one-off "Data Munging",
as Dave Cross's ~greatly underappreciated~ book titularly calls it.)
11) and somewhere I passed off my Pod::* modules to some very kind and
understanding people.
12) What were we talking about just now? I think these numbers are in
order.
13) Over the years, I've vaguely seen the occasional message hit my
"pod-people" mail folder, and I really do apologize that I don't
reliably (at /all/ reliably) read and respond, ideally with a quick
insightful reply possibly involving code that illustrates and/or fixes
something. (Or: hummus.)
So... let's survey the quel dommage...
I failed to provide pod2html and pod2man drop-ins.
I WOULD crank one of each out right now (especially since the current
pod2html's output HTML is the sort of thing to make one want to
reconvene the Nuremberg Tribunal), but:
Firstly, my brain just doesn't work with the task of writing CPAN
modules anymore. I can't explain it.
And secondly, when I look at the code for Pod::* stuff now (maybe a
decade later) it looks at best only vaguely familiar, so that if you
told me that any large chunk if it were written actually by somebody
else, I'd believe it without an argument. That afternoon waiting for
my tires, in Albuquerque, was... a decade ago?
So, questions about Pod::Simple::* won't /quite/ get me saying "hey,
your guess is as good as mine!", because I do often have a memory
jogged. But it's unreliable at best.
Oh hey, and look, now there's now a TOP-LEVEL namespace in CPAN called
"Perldoc", for which we apparently have Ingy to thank! And it
contains a program called "perl-doc"!
Do remind me to shower him with kisses if ever he and I run into
eachother at a conference or per-haps in jail.
