有没有办法重用 perlpod 文档中的文本？

Question

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

我认为这不可能，但我想我会要求确保我没有遗漏任何东西。

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

Answer 1

如您所知，Pod 是（故意）一种非常简单的标记语言。它没有任何特别复杂的功能，它缺少的一件事是嵌入来自其他来源的文本的方法。

我建议将重复的文本移动到它自己的部分，并在您想要引用该文本时链接到该部分（使用 L<...>）。

Answer 2

虽然 Pod 标记是非常基本的，但我们不必完全手动输入。

可以像 Perl 中的任何其他文本一样处理文档文本，使用其广泛的工具集来创建带有 pod 格式文本的字符串。然后可以使用 core Pod::Usage, via a file (that can be removed or kept), or directly by using core Pod::Simple.

显示该字符串

写文件显示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 = [=10=] =~ 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

[=10=] - demo perldoc

=head1 SYNOP...

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

=cut
EOD

    return $doc_text;
}

可以删除 .pod 文件：将 -exitval => 'NOEXIT' 添加到 pod2usage 参数，这样它就不会退出，然后删除文件。或者，更确切地说，让它可用于其他工具和用途。

作为提示，我已将作业分成两个子部分，因为仅能编写一个 .pod 文件可能很有用，该文件也可以以其他方式和格式使用和查看.^†不需要只显示文档，所有Pod业务都可以在一个子中完成。

直接显示Pod字符串

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

sub show_pod {                  # The rest of the program same as above
    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 个文件会影响 perldoc。感谢 @briandfoy 的评论。

对于较小的文档，使用单独的 .pod 文件没有特别的好处，我推荐第二种方法，如答案中所暗示的那样。它仅在文档文本在文件中的组织方式上有所不同，同时仍然允许人们对其进行处理，因为任何文本通常都是用 Perl 处理的。

对于 .pod 文件具有良好价值的用例，我仍然认为这是一个可以接受的权衡，但这是我的决定。请注意 perldoc 会受到影响，并评估它在您的项目中的重要性。

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

有没有办法重用 perlpod 文档中的文本？

Is there a way to re-use text in perlpod documentation?

perl

perl-pod