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

Question

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

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

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

Answer 1

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

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

Answer 2

While Pod markup is meant to be very basic, we don't have to literally type it all by hand.

Text for documentation can be processed like any other text in Perl, using its extensive set of tools, to create a string with pod-formatted text. That string can then be displayed using core Pod::Usage, via a file (that can be removed or kept), or directly by using core Pod::Simple.

Display the Pod string by writing a file

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

The .pod file can be removed: add -exitval => 'NOEXIT' to pod2usage arguments so that it doesn't exit and then remove the file. Or, rather, keep it available for other tools and uses.

I've split the job into two subs as a hint, since it can be useful to be able to only write a .pod file, which can then also be used and viewed in other ways and formats.^† This isn't needed to just show docs, and all Pod business can be done in one sub.</sup>

Dispaly the Pod string directly

If there is no desire to keep a .pod file around then we don't have to make it

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
}

The ->filter call is a shortcut for creating an object, setting a filehandle, and processing the contents. See docs for a whole lot more.

Either of these approaches provides you with far more flexibility.

Also, while one can indeed solve the repeated text by referencing a separate section with that text, that of course doesn't allow us to use variables or do any Perl processing -- what is all available when you write a Pod string, which is then passed over to perlpod to dispaly.

Note   Use of .pod files affects perldoc. Thanks to @briandfoy for a comment.

For smaller documentation, that has no particular benefit of using separate .pod files, I recommend the second approach, as hinted in the answer. It only differs in how the docs text is organized in the file while still allowing one to process it as any text is normally processed with Perl.

For use cases where .pod files are of good value I still find it an acceptable trade-off but that is my call. Be aware that perldoc is affected and assess how much that matters in your project.

---

^† I use a system like this in a large project, with .pod files in their directory. There is also a simple separate script for overall documentation management, that invokes individual programs with options to write/update their .pods, in HTML with CPAN's style-file, for the main web page. Any program can also simply display its docs in a desired format.</sup>