Re: Which Pod module should be used / subclassed?

[Karen Etheridge]

Have you looked at Pod::Weaver? It's usually used as part of
Dist::Zilla, but it absolutely can be used on its own, and it's great
for parsing pod documents into separate pieces. I'm also a big fan of
Pod::Simple.

On Sun, May 5, 2019 at 3:59 PM Harald Jörg  wrote:
>
> Hello Pod-People,
>
> I hope that I don't start a religious war with this question.
> I found this mailing list advertised in the Pod::Simple docs, so I would
> accept a bias towards Pod::Simple based solutions :)
>
> So here's what I want to do: Extract Pod from a bunch of (ca 100) Perl
> modules and Pod files and convert it to HTML.  Or XHTML.  Anything good
> for today's browsers is fine.  Sounds pretty TIMTOWTDI, but every way
> I've tried so far has minor issues, and I've some requirements for which
> I haven't found an existing solution yet.
>
> The issues are rather harmless:
>
>  - Pod::POM is what's used today in the software to create the HTML
>docs.  It fails to process Lhttps://www.perl.org>
>links correctly.
>
>  - Pod::Simple::HTML produces invalid HTML (nested 'a' elements) when a
>heading or item contains a Link like this:
>
>  =head1 Start at L
>
>  - Pod::Simple::XHTML apparently makes no effort to find content for the
> element (nor does core pod2html, BTW).
>
> And there are a few things I miss.  They could be implemented in a
> subclass of either of these, or even provided as an enhancement via Pull
> Request:
>
>  - A custom link resolver: I want links to documents within the project
>to be relative, but link to other CPAN modules to be
>absolute. Preferably to metacpan.org instead of search.cpan.org.
>
>  - A custom table of contents
>
>  - Custom (or just different) backlinks to top of page
>
>  - Decent heuristics for page titles (Pod::Simple::PullParser does that
>marvelously)
>
>  - ...and some more, but not enough to roll out my own converter.
>
> So, which if the modules is considered "state of the art" by the Pod
> People?  Which one of them is least likely to be deprecated?
>
> Do others have similar requirements?
> --
> Cheers,
> haj

Re: Which Pod module should be used / subclassed?

[Karl Williamson]

On 5/5/19 4:52 PM, Harald Jörg wrote:

Hello Pod-People,

I hope that I don't start a religious war with this question.
I found this mailing list advertised in the Pod::Simple docs, so I would
accept a bias towards Pod::Simple based solutions :)

So here's what I want to do: Extract Pod from a bunch of (ca 100) Perl
modules and Pod files and convert it to HTML.  Or XHTML.  Anything good
for today's browsers is fine.  Sounds pretty TIMTOWTDI, but every way
I've tried so far has minor issues, and I've some requirements for which
I haven't found an existing solution yet.

The issues are rather harmless:

  - Pod::POM is what's used today in the software to create the HTML
docs.  It fails to process Lhttps://www.perl.org>
links correctly.

  - Pod::Simple::HTML produces invalid HTML (nested 'a' elements) when a
heading or item contains a Link like this:

  =head1 Start at L

  - Pod::Simple::XHTML apparently makes no effort to find content for the
 element (nor does core pod2html, BTW).

And there are a few things I miss.  They could be implemented in a
subclass of either of these, or even provided as an enhancement via Pull
Request:

  - A custom link resolver: I want links to documents within the project
to be relative, but link to other CPAN modules to be
absolute. Preferably to metacpan.org instead of search.cpan.org.

  - A custom table of contents

  - Custom (or just different) backlinks to top of page

  - Decent heuristics for page titles (Pod::Simple::PullParser does that
marvelously)

  - ...and some more, but not enough to roll out my own converter.

So, which if the modules is considered "state of the art" by the Pod
People?  Which one of them is least likely to be deprecated?

Do others have similar requirements?



I seem to be the one mostly maintaining Pod:Simple these days.  I think 
the design of Pod::Simple is basically sound.  If you came up with 
reasonable pull requests for either of those modules, I would apply them.


All those TODOs in the code are from the original author, I believe, and 
they would be nice to have, but the code basically works and no one has 
felt the need to spend the effort to implement them.

Re: Which Pod module should be used / subclassed?

[Harald Jörg]

Hi Karen,

you wrote:

> Have you looked at Pod::Weaver? It's usually used as part of
> Dist::Zilla, but it absolutely can be used on its own, and it's great
> for parsing pod documents into separate pieces. I'm also a big fan of
> Pod::Simple.

Thanks for the pointers!

You made me look at Pod::Weaver, as I'm using it in some setups, if only
as part of Dist::Zilla and without thinking too much.  It really solves
a lot of problems which I don't have :)

I'm not going to use it for the current project, though.  I've settled
for sort of re-inventing Pod::Simple::SimpleTree (without the scary
part), adding a bit of node-rearranging which Pod::Weaver also could
have done.  But Pod::Weaver comes with more dependencies than my code
has lines, and the Pod converter ships with the project, which does not
yet use Moose.  I love Moose, but I don't want to add it to a project
which isn't mine (I'm just contributing) only to get a better Pod
converter.

My enthusiasm for Pod::Simple has cooled a bit since I found out that
there are lots of TODOs in the documentation, and that these TODOs
linger there for 15 years or so.  I like the method-maker, though :-P
and I haven't found a better alternative.

When I wrote my mail I felt a bit uneasy because of the mess in the
Pod:: modules section while Pod is, in my opinion, an important part of
the Perl ecosystem.  But I've decided to get over it.  For now.

So, thanks again for your time!

> On Sun, May 5, 2019 at 3:59 PM Harald Jörg  wrote:
>>
>> Hello Pod-People,
>>
>> I hope that I don't start a religious war with this question.
>> I found this mailing list advertised in the Pod::Simple docs, so I would
>> accept a bias towards Pod::Simple based solutions :)
>>
>> So here's what I want to do: Extract Pod from a bunch of (ca 100) Perl
>> modules and Pod files and convert it to HTML.  Or XHTML.  Anything good
>> for today's browsers is fine.  Sounds pretty TIMTOWTDI, but every way
>> I've tried so far has minor issues, and I've some requirements for which
>> I haven't found an existing solution yet.
>>
>> The issues are rather harmless:
>>
>>  - Pod::POM is what's used today in the software to create the HTML
>>docs.  It fails to process Lhttps://www.perl.org>
>>links correctly.
>>
>>  - Pod::Simple::HTML produces invalid HTML (nested 'a' elements) when a
>>heading or item contains a Link like this:
>>
>>  =head1 Start at L
>>
>>  - Pod::Simple::XHTML apparently makes no effort to find content for the
>> element (nor does core pod2html, BTW).
>>
>> And there are a few things I miss.  They could be implemented in a
>> subclass of either of these, or even provided as an enhancement via Pull
>> Request:
>>
>>  - A custom link resolver: I want links to documents within the project
>>to be relative, but link to other CPAN modules to be
>>absolute. Preferably to metacpan.org instead of search.cpan.org.
>>
>>  - A custom table of contents
>>
>>  - Custom (or just different) backlinks to top of page
>>
>>  - Decent heuristics for page titles (Pod::Simple::PullParser does that
>>marvelously)
>>
>>  - ...and some more, but not enough to roll out my own converter.
>>
>> So, which if the modules is considered "state of the art" by the Pod
>> People?  Which one of them is least likely to be deprecated?
>>
>> Do others have similar requirements?
>> --
>> Cheers,
>> haj
>

-- 
Cheers,
haj