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

Question

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

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

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

Answer 1

正如您已经意识到的那样， Pod （故意）是一种非常简单的标记语言。 它没有任何特别复杂的功能，它缺少的一件事是从另一个来源嵌入文本的方法。

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

Answer 2

虽然 Pod 标记是非常基础的，但我们不必逐字逐句地手动输入。

文档文本可以像 Perl 中的任何其他文本一样处理，使用其广泛的工具集，以创建带有 pod 格式文本的字符串。 然后可以使用 core Pod::Usage通过文件（可以删除或保留）或直接使用 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 = $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 arguments 使其不会退出，然后删除该文件。 或者，更确切地说，保持它可用于其他工具和用途。

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

直接显示 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
}

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

这些方法中的任何一种都为您提供了更大的灵活性。

此外，虽然确实可以通过引用包含该文本的单独部分来解决重复的文本，但这当然不允许我们使用变量或进行任何 Perl 处理——当您编写 Pod 字符串时，所有可用的内容是然后交给perlpod来显示。

注意.pod文件的使用会影响perldoc 。 感谢@briandfoy发表评论。

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

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

---

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