Hey Harald,
Somewhere in 2003, I had the same need. I suggested to get Pod to a
higher level, but people refused larger changes. So, I developed my own
Pod extension, which generates both clean HTML via templates and clean POD.
It is named 'OODoc' (because it was created before OpenOffice existed :-(
Additions:
- meaningfull element names: additional =method, =c_method, =function,
=option, =default, =requires, =example
- far more fine-grained references via an M<> tag: even refer to
specific named parameters of (maybe inherited) methods. In HTML,
those fine-grained refs work.
- extraction of the extended POD from the pm files, so manpage elements
can be added automatically: header, footer, inheritance relations,
inherited options and methods/functions.
- combining/merging information from various packages into one set of
HTML or man-pages.
- pluggable (extensible) parsers, page elements, and output generators.
For produced HTML see: http://perl.overmeer.net/mailbox/html/manuals/
(Yes, I should really spend some time on a modern style-sheet)
(I should convert the template to use ajax to replace frames)
For produced manpages, see
https://metacpan.org/pod/distribution/Mail-Box-IMAP4/lib/Mail/Box/IMAP4.pod
which is created by extraction from source
https://github.com/markov2/perl5-Mail-Box-IMAP4/blob/master/lib/Mail/Box/IMAP4.pm
For my MailBox suite of modules (about 1000 methods), OODoc generates
70k lines of Pod which before I have to maintain myself.
However... the fancier things you want to achieve, the more time you have
to spend on configuring it... that's the advantage of the traditional
Pod set-up. One of the reasons that I think I still am the only user of
OODoc ;-)
Maybe this helps you shaping your ideas.
MarkOv
* Harald Jörg ([email protected]) [190505 22:59]:
> 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?
------------------------------------------------------------------------
Mark Overmeer MSc MARKOV Solutions
[email protected] [email protected]
http://Mark.Overmeer.net http://solutions.overmeer.net
