Preprocess POD with Pod::Weaver before using Pod::Simple::HTML

Question

I'm trying to make a simple subclass of Pod::Simple::HTML for use with Pod::Simple::HTMLBatch. I want all of the POD to be preprocessed with POD::Weaver. However, I am unable to find what API/commands I should use to process a string document with Pod::Weaver. The basic outline to accomplish what I want is this:

use strict;
use warnings;
use Pod::Simple::HTMLBatch;

my $batchconv = Pod::Simple::HTMLBatch->new;
$batchconv->html_render_class('My::Pod');
$batchconv->batch_convert( ['path/to/code'], 'path/to/output' );

package My::Pod;
use Pod::Weaver;
use parent qw(Pod::Simple::HTML);

sub parse_file {
    my ($self, $in_file) = @_;

    my $new_doc = 'Pod::Weaver transformed pod here'

    return $self->SUPER::parse_string_document($new_doc);
}

Has anyone ever done something similar? Can anyone tell me how to transform $in_file, which could be a .pm or a .pod file, with Pod:Weaver?

Answer 1

Well, this turned out to be way harder than expected, and it's probably a bad idea. What we really need is a new utility for converting Pod::Elemental documents into (X)HTML(5), compatibly with Pod::Simple::(X)HTML (so that we can continue to use the old CSS styles). I will accept another answer if anyone writes/finds a suitable module and posts that here.

So here's what I did. I had to subclass POD::Simple::Search because it checks files for POD using a regex that doesn't include things like =method used with Pod::Weaver. For every file, I had to create a PPI document and strip out the POD, then concatenate the POD and make that into a Pod::Elemental document. That's how it's done in Pod::Elemental::PerlMunger, which is what Dist::Zilla uses.

package My::Pod;
use strict;
use warnings;

use Pod::Weaver;
use Pod::Elemental;
use Software::License::Perl_5;
use PPI;
use List::MoreUtils qw(any);
use parent qw(Pod::Simple::HTML);

my $weaver = Pod::Weaver->new_with_default_config;
my $license = Software::License::Perl_5->new({
  holder => 'DFKI',
});

sub parse_file {
    my ($self, $in_file) = @_;

    my $doc = get_doc($in_file);

    my $document = $weaver->weave_document({
        pod_document => $doc->{pod},
        ppi_document => $doc->{ppi},
        authors => ['Nathan Glenn <garfieldnate@gmail.com>'],
        license => $license,
    });

    return $self->SUPER::parse_string_document($document->as_pod_string);
}

#return {ppi, pod}
#Most of this taken from Pod::Elemental::PerlMunger
sub get_doc {
    my ($file_name) = @_;

    my $ppi_document = PPI::Document->new($file_name);
    confess(PPI::Document->errstr) unless $ppi_document;

    my @pod_tokens = map {"$_"} @{ $ppi_document->find('PPI::Token::Pod') || [] };
    $ppi_document->prune('PPI::Token::Pod');

    my $finder = sub {
        my $node = $_[1];
        return 0 unless any { $node->isa($_) }
           qw( PPI::Token::Quote PPI::Token::QuoteLike PPI::Token::HereDoc );
        return 1 if $node->content =~ /^=[a-z]/m;
        return 0;
    };

    if ($ppi_document->find_first($finder)) {
       warn "can't get POD from $file_name: there is POD inside string literals";
    }

    my $pod_str = join "\n", @pod_tokens;
    my $pod_document = Pod::Elemental->read_string($pod_str);

    return {ppi => $ppi_document, pod => $pod_document};
}

# search package to tell Pod::Simple::HTMLBatch that everything has POD
package My::Pod::Search;
use parent qw(Pod::Simple::Search);

#override this method to allow whatever kinds of POD commands (=method, etc.)
#mostly copied from Pod::Simple::Search
sub contains_pod {
    my($self, $file) = @_;
    my $verbose = $self->{'verbose'};

    # check for one line of POD
    $verbose > 1 and print " Scanning $file for pod...\n";
    unless( open(MAYBEPOD,"<$file") ) {
        print "Error: $file is unreadable: $!\n";
        return undef;
    }


    local $_;
    while( <MAYBEPOD> ) {
        # a more forgiving pod regex for things like =method
        if(m/^=(.+)\b/s) {
          close(MAYBEPOD) || die "Bizarre error closing $file: $!\nAborting";
          chomp;
          $verbose > 1 and print "  Found some pod ($_) in $file\n";
          return 1;
        }
    }
    close(MAYBEPOD) || die "Bizarre error closing $file: $!\nAborting";
    $verbose > 1 and print "  No POD in $file, skipping.\n";
    return 0;
}

package main;

my $batchconv = Pod::Simple::HTMLBatch->new;
$batchconv->html_render_class('My::Pod');
$batchconv->search_class('My::Pod::Search');
$batchconv->batch_convert( ['path/to/code'], 'path/to/output' );