html - 在使用 Pod::Simple::HTML 之前使用 Pod::Weaver 预处理 POD

Question

我正在尝试制作一个 Pod::Simple::HTML 的简单子(monad)类用于 Pod::Simple::HTMLBatch .我希望使用 POD::Weaver 对所有 POD 进行预处理.但是，我无法找到我应该使用哪些 API/命令来使用 Pod::Weaver 处理字符串文档。完成我想要的基本大纲是这样的:

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);
}

有没有人做过类似的事情？谁能告诉我如何使用 Pod:Weaver 转换 $in_file，它可以是 .pm 或 .pod 文件？

Answer 1

好吧，事实证明这比预期的要难得多，而且这可能是个坏主意。我们真正需要的是一个将 Pod::Elemental 文档转换为 (X)HTML(5) 的新实用程序，它与 Pod::Simple::(X)HTML 兼容(以便我们可以继续使用旧的 CSS 样式)。如果有人写/找到合适的模块并在此处发布，我将接受另一个答案。

这就是我所做的。我不得不继承 POD::Simple::Search因为它使用不包含与 Pod::Weaver 一起使用的 =method 之类的正则表达式来检查 POD 文件。对于每个文件，我必须创建一个 PPI 文档并剥离 POD，然后连接 POD 并将其制作成 Pod::Elemental 文档。 Pod::Elemental::PerlMunger 就是这样做的，而 Dist::Zilla 就是这样做的。

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' );