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 <[email protected]> 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 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 > -- Cheers, haj
