Re: Which Pod module should be used / subclassed?

[LNATION .]

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örg,  wrote:

> Karl Williamson  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
>

Re: Which Pod module should be used / subclassed?

[Harald Jörg]

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

Re: Which Pod module should be used / subclassed?

[Mark Overmeer]

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 (h...@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 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?

   Mark Overmeer MScMARKOV Solutions
   m...@overmeer.net  soluti...@overmeer.net
http://Mark.Overmeer.net   http://solutions.overmeer.net