Which Pod module should be used / subclassed?

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
0
haj
5/5/2019 10:52:49 PM
perl.pod-people 524 articles. 0 followers. Follow

7 Replies
70 Views

Similar Articles

[PageSpeed] 13

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=C3=B6rg <haj@posteo.de> 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:
>
>      =3Dhead1 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
0
perl
5/9/2019 3:23:42 AM
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=C3=B6rg <haj@posteo.de> 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:
>>
>>      =3Dhead1 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
>

--=20
Cheers,
haj
0
haj
5/9/2019 3:21:10 PM
On 5/5/19 4:52 PM, Harald J=C3=B6rg wrote:
> Hello Pod-People,
>=20
> 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 woul=
d
> accept a bias towards Pod::Simple based solutions :)
>=20
> 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 whic=
h
> I haven't found an existing solution yet.
>=20
> The issues are rather harmless:
>=20
>   - 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.
>=20
>   - Pod::Simple::HTML produces invalid HTML (nested 'a' elements) when =
a
>     heading or item contains a Link like this:
>=20
>       =3Dhead1 Start at L<https://www.perl.org>
>=20
>   - Pod::Simple::XHTML apparently makes no effort to find content for t=
he
>     <title> element (nor does core pod2html, BTW).
>=20
> 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 Pul=
l
> Request:
>=20
>   - A custom link resolver: I want links to documents within the projec=
t
>     to be relative, but link to other CPAN modules to be
>     absolute. Preferably to metacpan.org instead of search.cpan.org.
>=20
>   - A custom table of contents
>=20
>   - Custom (or just different) backlinks to top of page
>=20
>   - Decent heuristics for page titles (Pod::Simple::PullParser does tha=
t
>     marvelously)
>=20
>   - ...and some more, but not enough to roll out my own converter.
>=20
> 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?
>=20
> Do others have similar requirements?
>=20

I seem to be the one mostly maintaining Pod:Simple these days.  I think=20
the design of Pod::Simple is basically sound.  If you came up with=20
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=20
they would be nice to have, but the code basically works and no one has=20
felt the need to spend the effort to implement them.
0
public
5/9/2019 4:55:35 PM
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 (haj@posteo.de) [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
       Mark@Overmeer.net                          solutions@overmeer.net
http://Mark.Overmeer.net                   http://solutions.overmeer.net
0
mark
5/10/2019 7:59:56 AM
Hi Mark,

you write:

> 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 :-(

Oh, I am aware of OODoc.  I really like your standardized method of
documenting inheritance in your modules and *guess* this is another
benefit of your toolchain.

But actually, OODoc serves a different need.  Right now, I don't plan to
*rewrite* the Pod of 100 modules: I just want to get the most out of the
*existing* Pod.

> [...]
> 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 ;-)

Yeah - that's what I call The Curse Of TIMTOWTDI: It is easier for one
single person to write a wonderful, rich replacement for Pod than for
the community to agree on enhancements to Pod.  "Pod" is just one of the
areas where this has happened in Perl.

> Maybe this helps you shaping your ideas.

It sure does - on a less urgent, but maybe more important scale.  The
topic is: How can we get the Perl community to accept change?  But that
is beyond the scope of this thread :)
-- 
Cheers,
haj
0
haj
5/10/2019 12:17:57 PM
Karl Williamson <public@khwilliamson.com> writes:

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

Indeed, the parser in Pod::Simple is pretty easy to use.  I guess that
the formatting part can turn into a can of worms with regard to
different tastes how things should look like or behave.  It seems that
the Pods I'm dealing with are somewhat non-standard, so I don't think
that changing the behaviour of the existing formatters is justified.

For now, I've submitted a pull request for a few of those documentation
TODOs where I had to open the source to see what's available.

Maybe I'll get to that problem of nested 'a' elements later, but since
browsers don't really choke on that, it isn't too high on my list.
-- 
Cheers,
haj
0
haj
5/10/2019 7:52:11 PM
--000000000000bd6d1805888ffbfe
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

May or may not help:

https://metacpan.org/pod/Pod::Simpler::Aoh

https://github.com/ThisUsedToBeAnEmail/podsearch

Its simple

On Sat, 11 May 2019, 03:52 Harald J=C3=B6rg, <haj@posteo.de> wrote:

> Karl Williamson <public@khwilliamson.com> writes:
>
> > [...]
> > 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.
>
> Indeed, the parser in Pod::Simple is pretty easy to use.  I guess that
> the formatting part can turn into a can of worms with regard to
> different tastes how things should look like or behave.  It seems that
> the Pods I'm dealing with are somewhat non-standard, so I don't think
> that changing the behaviour of the existing formatters is justified.
>
> For now, I've submitted a pull request for a few of those documentation
> TODOs where I had to open the source to see what's available.
>
> Maybe I'll get to that problem of nested 'a' elements later, but since
> browsers don't really choke on that, it isn't too high on my list.
> --
> Cheers,
> haj
>

--000000000000bd6d1805888ffbfe
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"auto">May or may not help:<div dir=3D"auto"><br></div><div dir=
=3D"auto"><a href=3D"https://metacpan.org/pod/Pod::Simpler::Aoh" target=3D"=
_blank" rel=3D"noreferrer">https://metacpan.org/pod/Pod::Simpler::Aoh</a><b=
r></div><div dir=3D"auto"><br></div><div dir=3D"auto"><a href=3D"https://gi=
thub.com/ThisUsedToBeAnEmail/podsearch">https://github.com/ThisUsedToBeAnEm=
ail/podsearch</a><br></div><div dir=3D"auto"><br></div><div dir=3D"auto">It=
s simple</div></div><br><div class=3D"gmail_quote"><div dir=3D"ltr" class=
=3D"gmail_attr">On Sat, 11 May 2019, 03:52 Harald J=C3=B6rg, &lt;<a href=3D=
"mailto:haj@posteo.de" target=3D"_blank" rel=3D"noreferrer">haj@posteo.de</=
a>&gt; wrote:<br></div><blockquote class=3D"gmail_quote" style=3D"margin:0 =
0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Karl Williamson &lt;<=
a href=3D"mailto:public@khwilliamson.com" rel=3D"noreferrer noreferrer" tar=
get=3D"_blank">public@khwilliamson.com</a>&gt; writes:<br>
<br>
&gt; [...]<br>
&gt; I seem to be the one mostly maintaining Pod:Simple these days.=C2=A0 I=
<br>
&gt; think the design of Pod::Simple is basically sound.=C2=A0 If you came =
up<br>
&gt; with reasonable pull requests for either of those modules, I would<br>
&gt; apply them.<br>
&gt;<br>
&gt; All those TODOs in the code are from the original author, I believe,<b=
r>
&gt; and they would be nice to have, but the code basically works and no<br=
>
&gt; one has felt the need to spend the effort to implement them.<br>
<br>
Indeed, the parser in Pod::Simple is pretty easy to use.=C2=A0 I guess that=
<br>
the formatting part can turn into a can of worms with regard to<br>
different tastes how things should look like or behave.=C2=A0 It seems that=
<br>
the Pods I&#39;m dealing with are somewhat non-standard, so I don&#39;t thi=
nk<br>
that changing the behaviour of the existing formatters is justified.<br>
<br>
For now, I&#39;ve submitted a pull request for a few of those documentation=
<br>
TODOs where I had to open the source to see what&#39;s available.<br>
<br>
Maybe I&#39;ll get to that problem of nested &#39;a&#39; elements later, bu=
t since<br>
browsers don&#39;t really choke on that, it isn&#39;t too high on my list.<=
br>
-- <br>
Cheers,<br>
haj<br>
</blockquote></div>

--000000000000bd6d1805888ffbfe--
0
thisusedtobeanemail
5/10/2019 10:20:52 PM
Reply: