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

[David E. Wheeler]

On May 7, 2011, at 3:54 PM, Sean M. Burke wrote:

>> Do you have any code for this lying around somewhere? Might help Marc Green, 
>> our Google Summer of Code student, to get started on porting the Perl core 
>> Pod tools from Pod::Parser to Pod::Simple…
> 
> OK, found it,... I'm trying to make sure there isn't any MORE of it lying 
> around elsewhere, but I think I got it all.
> 
> Anticipate!

Awesome. So is it more than just Pod::Simple::HTMLLegacy?

Anticipating!

David

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

[Sean M. Burke]

On 05/04/2011 09:03 AM, David E. Wheeler wrote:

On Jul 21, 2010, at 5:34 AM, Sean M. Burke wrote:


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.


Hey Sean,

Do you have any code for this lying around somewhere? Might help Marc Green, 
our Google Summer of Code student, to get started on porting the Perl core Pod 
tools from Pod::Parser to Pod::Simple…


OK, found it,... I'm trying to make sure there isn't any MORE of it 
lying around elsewhere, but I think I got it all.


Anticipate!

Re: pod2html and Pod::Simple

[David E. Wheeler]

On May 4, 2011, at 2:06 PM, Russ Allbery wrote:

> I know this is in the subject, but just to be clear, just in case, Sean
> Burke did indeed do the initial port of pod2man and pod2text to
> Pod::Simple, and that has been subsequently incorporated into podlators
> (which I maintain) and into Perl core, so pod2man and pod2text (and
> Pod::Man and Pod::Text) are good.  I assume this is only about pod2html.

Yes.

> There are tons of different POD to HTML conversion modules.  Rather than
> porting the one that happens to be in Perl core, it may be better to
> incorporate one of the other ones that already uses Pod::Simple and remove
> the old one.

I think we'd just use Pod::Simple::XHTML.

Best,

David

Re: pod2html and Pod::Simple

[Russ Allbery]

"David E. Wheeler"  writes:
> On Jul 21, 2010, at 5:34 AM, Sean M. Burke wrote:

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

> Do you have any code for this lying around somewhere? Might help Marc
> Green, our Google Summer of Code student, to get started on porting the
> Perl core Pod tools from Pod::Parser to Pod::Simple…

I know this is in the subject, but just to be clear, just in case, Sean
Burke did indeed do the initial port of pod2man and pod2text to
Pod::Simple, and that has been subsequently incorporated into podlators
(which I maintain) and into Perl core, so pod2man and pod2text (and
Pod::Man and Pod::Text) are good.  I assume this is only about pod2html.

There are tons of different POD to HTML conversion modules.  Rather than
porting the one that happens to be in Perl core, it may be better to
incorporate one of the other ones that already uses Pod::Simple and remove
the old one.

-- 
Russ Allbery (r...@stanford.edu) 

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

[David E. Wheeler]

On Jul 21, 2010, at 5:34 AM, Sean M. Burke wrote:

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

Hey Sean,

Do you have any code for this lying around somewhere? Might help Marc Green, 
our Google Summer of Code student, to get started on porting the Perl core Pod 
tools from Pod::Parser to Pod::Simple…

Thanks,

David

Re: pod2html and Pod::Simple

[David E. Wheeler]

On Jul 21, 2010, at 11:56 PM, Sean M. Burke wrote:

> Oy, pod2html, Pod::Simple::HTMLLegacy, Pod::Simple::HTML, what a jumble... 
> and as I tinker with "perldoc -o html" now, I see it makes every heading a 
> hyperlink back to the top of the document?  Jeez, what was I /thinking/, 
> that's just dumb interface.

This is why I prefer Pod::Simple::XHTML now.

Anyway, would Pod::Simple::Legacy be the thing to put into a new pod2html?

Best,

David

Re: pod2html and Pod::Simple

[Sean M. Burke]

On 07/21/2010 09:29 AM, Russ Allbery wrote:

6) But I similarly-and-worse forgot to produce a /drop-in/ pod2man
replacement.


That's okay, I did that.  :)


Wow, cool, thanks!

See what I mean about my mind being stoner Swiss cheese!


Oy, pod2html, Pod::Simple::HTMLLegacy, Pod::Simple::HTML, what a 
jumble... and as I tinker with "perldoc -o html" now, I see it makes 
every heading a hyperlink back to the top of the document?  Jeez, what 
was I /thinking/, that's just dumb interface.

Re: pod2html and Pod::Simple

[Russ Allbery]

"Sean M. Burke"  writes:

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

pod2man (and pod2text) has indeed converted over, thanks in large part to
your work and the new version you sent me.  pod2html is unrelated, though;
unlike pod2text and pod2man, I don't maintain it and haven't looked at it.

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

That was extremely helpful in getting pod2man switched over.

> 6) But I similarly-and-worse forgot to produce a /drop-in/ pod2man
> replacement.

That's okay, I did that.  :)

-- 
Russ Allbery (r...@stanford.edu) 

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

[Sean M. Burke]

Preamble:
Making pod2html use Pod::Simple::HTMLLegacy /might/ actually be 
simpler than patching Pod::HTML or Pod::Parser or whatever.


About my bungling:

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!  (But, I now see, didn't!)

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



Now we hear an epic of... ME!  And pod.

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.  (That was about a decade ago, when I had a car, and tires, and 
an Albuquerque.)


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 said 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.  Call it a passing thought that wouldn't have survived a 
minute's longer of coding.


4) ...and 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.  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.  Dunno, 
I encourage everyone to do what they can, making sense of it all.


7) ...and then I did some other stuff I've forgotten...

8) Then I got sick.  Hard 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 gave 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.  (If you have ever wondered about my 
well-known bitterness toward Switzerland and marijuana, all is now 
laid bare.)


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 that 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 underappreciated book titularly calls it.)


11) and somewhere I passed off my Pod::* modules to some very kind and 
understanding people who I can't thank enough.


12) Twelve.  I think these numbers are in order.

13) Over the years, I've vaguely had the occasional message thwack 
(L) into 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 
output of either can occasionally be the sort of thing to make ya want 
to reconvene the Nuremberg Tribunal), but:


Firstly, my brain ju

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

[Sean M. Burke]

(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