http://qs1969.pair.com?node_id=11140057

Darkwing has asked for the wisdom of the Perl Monks concerning the following question:

Hi Perl monks,

i'm maintaining a perl script that makes use of the Pod::Parser module Pod::Select. I noticed that the documentation for these modules says: "This module is considered legacy; modern Perl releases (5.18 and higher) are going to remove Pod-Parser from core and use Pod-Simple for all things POD". So i looked for a Pod::Simple based replacement for Pod::Select and found Pod::Simple::Select. But I am not sure whether this is a good substitute for Pod::Select or not: its version is very low (0.002), no changes since 2017 and even its POD docu looks broken (in section "Version" something appears that looks like a Log4perl configuration).

Does anyone use this module? Or can anyone recommend another one?

Replies are listed 'Best First'.
Re: Is Pod::Simple::Select a recommended replacement for Pod::Select? Or is there a better choice?
by pryrt (Abbot) on Dec 31, 2021 at 23:18 UTC
    As shown in one of my example CPAN Makefile.PL, I use Pod::Simple::Select to extract sections of my POD to put into the README.md and LICENSE files (so I can use my POD for the single-source for those, rather than separately maintaining them.

    # auto-generate the README from the lib/Win32/Mechanize/NotepadPlusPlu +s.pm README.md :: lib/Win32/Mechanize/NotepadPlusPlus.pm Makefile.PL $(PERL) -MPod::Simple::Select -e 'my $$p = Pod::Simple::Select->ne +w();$$p->output_file(qq(README.pod));$$p->select({head1 => [qq(NAME), +qq(SYNOPSIS),qq(DESCRIPTION),qq(LIMITATIONS),qq(INSTALLATION),qq(TODO +),qq(AUTHOR),qq(COPYRIGHT),qq(LICENSE)]});$$p->parse_file(qq(lib/Win3 +2/Mechanize/NotepadPlusPlus.pm));' pod2markdown README.pod README.md $(RM_F) README.pod # auto-generate the LICENSE file from the lib/Win32/Mechanize/NotepadP +lusPlus.pm LICENSE :: lib/Win32/Mechanize/NotepadPlusPlus.pm Makefile.PL $(PERL) -MPod::Simple::Select -e 'my $$p = Pod::Simple::Select->ne +w();$$p->output_file(qq(LICENSE.pod));$$p->select({head1 => [qw/AUTHO +R COPYRIGHT LICENSE/]});$$p->parse_file(qq(lib/Win32/Mechanize/Notepa +dPlusPlus.pm));' pod2text LICENSE.pod LICENSE $(RM_F) LICENSE.pod

    The VERSION weirdity appears to be that the author didn't put the newline after =for comment, which made the POD paragraphs not be what they thought it was.

    That author doesn't seem to have updated any of their repositories in the last couple of years, but that doesn't necessarily mean that it's abandonware (though it makes it more likely). The only open issue is about the minimum required Tie::File version, which isn't a super-critical issue. And, as of yet, with my example usage above, I haven't had any difficulty in using the distribution as published for v0.002. (The number in a version number is just that -- a number. Being low doesn't indicate that it's not usable; many authors just start at 0.001 or 0.01 instead of 1.00. It's just a personal preference on where to start.)

      I'd replace the repeated qq()s with a qw().
        Originally, one of the headers in my list had a space, which is why they were separate qq, but that section was removed, and I didn't bother converting to qw. But yes, in general, I concur.
Re: Is Pod::Simple::Select a recommended replacement for Pod::Select? Or is there a better choice?
by haukex (Archbishop) on Dec 31, 2021 at 22:09 UTC