develooper Front page | perl.pod-people | Postings from May 2019

Which Pod module should be used / subclassed?

Thread Next
From:
haj
Date:
May 5, 2019 22:59
Subject:
Which Pod module should be used / subclassed?
Message ID:
87o94gecou.fsf@posteo.de
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 L<The Perl Homepage|https://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<https://www.perl.org>

 - Pod::Simple::XHTML apparently makes no effort to find content for the
   <title> 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

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About