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

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