* Paul "LeoNerd" Evans (leon...@leonerd.org.uk) [230921 17:29]:
> There's ultimately a choice to be made - is POD still alive, as a
> specification, a technology? Can we continue to add new features to it?
Just as Dmitry Karasik experienced, I encountered blockades by core
maintainers to even think about improvements... I got fed-up by this
back in 2003 already, and have seen many other suggestions fail.
My biggest complaints:
- Pod uses visual markup, like =item, where it should use
semantic markup, like =sub
- Pod does not support anything related to Object Oriented features,
like documenting inheritance relationships
- Pod limits the quality of the manpage: support for more fine-grained
links, for instance, could produce better HTML accessibility.
So, back in 2003, I developed OODoc (OpenOffice did not exist yet).
During the distribution generation process (make dist), it
simply does:
extract extended ---> produce real POD <--- template
pod from .pm files in .pod files,
and smaller .pm files
For my Mail::Box related modules (245 pm files). It immediately saved
maintaining about 80k lines of repetative information.
Short introduction:
- list of extensions:
https://metacpan.org/pod/OODoc::Parser::Markov#Structural-tags
- example of use of the extended POD:
https://github.com/markov2/perl5-Mail-Message/blob/master/lib/Mail/Message.pm#L87
- result in the real POD output:
https://metacpan.org/pod/Mail::Message#Mail::Message-%3Enew(%options)
- automatically added components, like INHERITANCE block ...
https://metacpan.org/pod/Mail::Message#INHERITANCE
- ... and inclusion of inherited methods
https://metacpan.org/pod/Mail::Message#Constructing-a-message
- it also produces a better quality HTML than POD can achieve
http://perl.overmeer.net/mailbox/html/manuals/
Eh, but it's my 2003 view of the World. It needs some (mainly visual)
cleanup.
> [...], than have to throw it all out and replace it with
> something else entirely.
The distance between what POD is, and what a convenient documentation
syntax should be, is really big. Perl-Core developers have shown to
refuse even small useful changes in the past.
I wrote a first version of pod6 for Perl6, which Damian transformed into
the existing pod for Raku. We may finally get an acceptable quality pod
syntax in Perl5, if we integrate that Raku spec into Perl5. That might
finally convince some Core developers to accept dire needed improvements.
--
Regards,
MarkOv
------------------------------------------------------------------------
Mark Overmeer MSc MARKOV Solutions
m...@overmeer.net mark@markov.solutions
http://Mark.Overmeer.net https://markov.solutions
