Question

我的Perlpod文档中有一堆重复的文字。我当然可以创建一个单独的节并引用它，但是我想知道是否有一种方法可以在某处输入一次文本并将其插入多个位置？

我认为这是不可能的，但是我想确保我没有错过任何事情。

或者-也许有更好的perl文档技术？

Answer 1

您已经意识到，Pod是（故意）一种非常简单的标记语言。它没有任何特别复杂的功能，它缺少的一件事就是可以嵌入来自其他来源的文本。

我建议每当您要引用该文本时，将重复的文本移至其各自的部分并链接至该部分（使用L<...>）。

Answer 2

虽然Pod标记本来是非常基本的，但我们不必手动键入所有内容。

可以使用您喜欢的任何Perl工具正常处理文档文本，以创建具有pod格式文本的字符串。然后可以使用核心Pod::Usage，通过文件（可以删除或保留文件）或直接使用核心Pod::Simple来显示带有Pod的字符串。

通过写入文件显示Pod字符串

use warnings;
use strict;
use feature 'say';
use Path::Tiny;    # convenience, to "spew" a file    

my $man = shift;        
show_pod() if $man;
say "done $$";

sub show_pod {
    require Pod::Usage; Pod::Usage->import('pod2usage');

    my $pod_text = make_pod();
    my $pod_file = $0 =~ s/\.pl$/.pod/r;
    path($pod_file)->spew($pod_text);

    pod2usage( -verbose => 2, -input => $pod_file );  # exits by default
}

sub make_pod {
    my $repeated = q(lotsa text that gets repeated);
    my $doc_text = <<EOD;
=head1 NAME

$0 - demo perldoc

=head1 SYNOP...

Text that is also used elsewhere: $repeated...

=cut
EOD

    return $doc_text;
}

可以删除.pod文件：在-exitval => 'NOEXIT'参数中添加pod2usage，以使其不退出然后删除该文件。或者，而是使其可用于其他工具和用途。

作为提示，我将作业分为两个子项，因为仅写一个.pod文件会很有用，然后也可以用其他方式和格式来使用和查看它。 sup>†仅显示文档并不需要这样做，所有Pod业务都可以在一个子窗口中完成。

直接分配Pod字符串

如果不想保留.pod文件，那么我们就不必保留它

sub show_pod {
    my $pod_text = make_pod();

    require Pod::Simple::Text;
    Pod::Simple::Text->filter( \$pod_text );  # doesn't exit so add that
}

（上面程序的其余部分是相同的）。->filter调用是创建对象，设置文件句柄和处理内容的快捷方式。有关更多信息，请参阅文档。

这两种方法均可为您提供更大的灵活性。

虽然确实可以通过引用文本的单独部分来解决重复的文本，但是这当然不允许我们使用变量或进行任何Perl处理-编写Pod字符串时可以使用全部内容，然后将其传递到perlpod进行显示。

^†我在一个大型项目中使用了这样的系统，其目录中有.pod个文件。还有一个用于整体文档管理的简单的单独脚本，该脚本调用带有选择选项的单个程序，以使用CPAN的样式文件的HTML编写/更新其.pod，用于主网页。任何程序还可以简单地以所需格式显示其文档。

有没有一种方法可以重用Perlpod文档中的文本？

2 个答案: