Re: Pod::Simple output as POD

On 08/12/2014 02:25 PM, John SJ Anderson wrote:
> Jim -
>
> The current state of that code is that I think it mostly works, but it
> needs tests (or it needs the tests to be finished). It's been a while
> since I touched it, I'm not sure when I'm going to be able to get back
> to it, but I would be perfectly happy if somebody wanted to grab it
> and wrap it up.
>
> chrs,
> john.

I have taken on the task of completing this, and am nearly done.  I'm 
writing because I wonder what other use-cases there are for this module 
besides extracting pod from a file that also contains other things.  I 
can't think of any.  And if there are no significant ones, I wonder if 
the name should instead be Pod::Simple::ExtractPod, instead of 
Pod::Simple::Pod?

>
>
> On Tue, Aug 12, 2014 at 9:06 AM, James E Keenan <[email protected]> wrote:
>> I am writing concerning https://rt.perl.org/Ticket/Display.html?id=116467.
>> The objective of this ticket is to revise t/porting/podcheck.t so that it no
>> longer depends on CPAN module Pod::Parser.  The latter has been designated
>> "legacy code" but we cannot remove it from the core distribution until
>> podcheck.t no longer depends on it, either directly (calls to
>> parse_from_filehandle) or indirectly (via an older version of Pod::Checker
>> which depends on Pod::Parser rather than Pod::Simple).
>>
>> While studying podcheck.t recently I noticed that we could get substantially
>> closer to our goal if we took the following subroutine from podcheck.t:
>>
>> #####
>> sub extract_pod {   # Extracts just the pod from a file; returns undef if
>> file
>>                      # doesn't exist
>>      my $filename = shift;
>>
>>      my @pod;
>>
>>      # Arrange for the output of Pod::Parser to be collected in an array we
>> can
>>      # look at instead of being printed
>>      tie *ALREADY_FH, 'Tie_Array_to_FH', \@pod;
>>      if (open my $in_fh, '<:bytes', $filename) {
>>          my $parser = Pod::Parser->new();
>>          $parser->parse_from_filehandle($in_fh, *ALREADY_FH);
>>          close $in_fh;
>>
>>          return join "", @pod
>>      }
>> ...
>> #####
>>
>> ... and could rewrite the 'if' block using a Pod::Simple-based call.
>> However, AFAICT there is nothing in the latest CPAN release of Pod::Simple
>> by which one could simple extract the POD from a file and return it as a
>> single string, POD-formatting intact and otherwise unmodified.
>>
>> Karl Williamson noted
>> (https://rt.perl.org/Ticket/Display.html?id=116467#txn-1304150) that there
>> have been some efforts in this direction, citing:
>> https://github.com/genehack/pod-simple/tree/add-pod-simple-pod. Could you
>> advise as to the current state of development of this fork and whether it is
>> likely to be of benefit to P5P in this instance?
>>
>> Thank you very much.
>> Jim Keenan
>>
>