Perl 的 pod2usage 函数错误地处理格式化代码

Question

首先，我使用的是 Ubuntu 20.04 和 Perl v5.30.0；然而，我在使用 macOS High Sierra 和 Perl v5.32.1 时遇到了同样的问题，因此它不限于一个平台。

我开始使用 Perl 的

Pod::Usage

模块通过调用

pod2usage

来记录我的代码。我很高兴有一些东西可以处理手册页的格式，但当我注意到格式代码（例如

B<text>

和

I<text>

）在输出手册页中无法正确呈现时，我感到很沮丧。下面是我的终端窗口的屏幕截图。

正如我在描述部分所说，我希望有粗体文本，然后是普通文本，然后是斜体文本。前两组以相同的字体显示，而斜体部分出现在星号之间以模拟不同的字体。我的脚本的源代码如下。

#!/usr/bin/env perl

use strict;
use warnings;
# NOTE: un-commenting the following line produces the "Undefined
#       subroutine" error described below in the post. Otherwise this
#       code executes, though it does not produce the desired output.
# BEGIN { $Pod::Usage::Formatter = "Pod::Perldoc::ToMan"; }

use Getopt::Long qw(GetOptions);
use Pod::Usage qw(pod2usage);

my $man  = 0;
my $help = 0;

GetOptions("help|h" => \$help, "man" => \$man) || pod2usage(2);
pod2usage(1) if ($help);
pod2usage(-verbose => 2) if ($man);

__END__

=pod

=head1 NAME

Sample POD.

=head1 SYNOPSIS

This is a simple test to see if Perl is correctly formatting POD.

=head1 DESCRIPTION

B<This text should be bold>, this text should be normal,
I<and this text should be italicized>.

=cut

我尝试使用以下代码行更改 POD 格式化程序，这些代码是我直接从

Pod::Usage

页面获取的，但没有成功。

BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
use Pod::Usage qw(pod2usage);

走了几个兔子洞，我从命令行调用

perldoc

来读取 POD，然后我将格式化程序更改为

Pod::Perldoc::ToMan

，首先使用

-oman

，然后通过

-M

标志；我是通过阅读

perldoc

手册页了解到这些的。这产生了预期的结果 - 尽管斜体文本显示为下划线，但我会接受它。

perldoc -t -oman test.pl
perldoc -t -MPod::Perldoc::ToMan test.pl

认为可以解决脚本中的问题，我将格式化程序从

"Pod::Text::Termcap"

更改为

"Pod::Perldoc::ToMan"

，但这产生了以下意外错误。

Undefined subroutine &main::pod2usage called at test.pl line 16.

我希望

pod2usage

的输出看起来像第二个屏幕截图中所示 - 即使我无法正确渲染斜体。我该如何做到这一点？是否需要更改 POD 格式化程序？

编辑：这是我的文件中出现的代码，直接从输出中复制

xclip

。

#!/usr/bin/env perl

use strict;
use warnings;

BEGIN { $Pod::Usage::Formatter = "Pod::Perldoc::ToMan"; }

use Getopt::Long qw(GetOptions);
use Pod::Usage qw(pod2usage);

my $man  = 0;
my $help = 0;

GetOptions("help|h" => \$help, "man" => \$man) || pod2usage(2);
pod2usage(1) if ($help);
pod2usage(-verbose => 2) if ($man);

__END__

=pod

=head1 NAME

Sample POD.

=head1 SYNOPSIS

This is a simple test to see if Perl is correctly formatting POD.

=head1 DESCRIPTION

B<This text should be bold>, this text should be normal,
I<and this text should be italicized>.

=cut

运行不带标志的脚本会产生零退出状态，没有错误。但是，使用以下标志执行会导致上述

Undefined subroutine

错误。再次，此输出是使用

xclip

直接从终端收集的。

$ perl test.pl -help
Undefined subroutine &main::pod2usage called at test.pl line 15.
$ perl test.pl -man
Undefined subroutine &main::pod2usage called at test.pl line 16.

Answer 1

首先，Pod::Text::Termcap 工作正常。

“用法”是粗体，我添加了下划线的

I<foo>

。

---

其次，您使用的是

perldoc

插件而不是 pod 格式化程序。您应该使用 Pod::Man 而不是 Pod::Perldoc::ToMan。

（Pod::Man 会导致与 Pod::Perldoc::ToMan 相同的错误。我将在下面提供解释和解决方法。）

当然，这会生成一个手册页，除非您使用以下内容之一调用

nroff

，否则该手册页完全不可读：

man <( perl a.pl --help )     # Requires bash

perl a.pl --help | nroff -man

不过，文字完全缺失。

所以这是不行的。坚持使用 Pod::Text::Termcap。

---

但是至于你的问题，Pod::Usage 中有一个错误。

大多数导出符号的模块都使用 Exporter。这就是 Pod::Usage 用于导出的

pod2usage

。

Exporter 有两种使用方式：

1. 继承它。

   use Exporter;
   our @EXPORT = qw( pod2usage );
   our @ISA = qw( Exporter );
   

2. 从中导入

   import

   。

   use Exporter qw( import );
   our @EXPORT = qw( pod2usage );
   

这就是 Pod::Usage 的作用：

use Exporter;
our @EXPORT = qw( pod2usage );
our @ISA = $Pod::Usage::Formatter;

如果格式化程序继承自 Exporter（例如 Pod::Text），则此方法有效，但如果格式化程序不继承，则此方法失败。 Pod::Man 就是这种情况。

但是，有解决方法。

BEGIN { $Pod::Usage::Formatter = 'Pod::Man'; }
package Pod::Usage { use Exporter qw( import ); }
use Pod::Usage qw( pod2usage );

我已提交票。

---

最后，您可能注意到我在上面使用了

--help

。您可能会问

--man

，您已经使用

perldoc

而不是 Pod::Usage 的格式化程序。因此，使用 Pod::Usage 的格式化程序对

--man

绝对没有影响。不过，

-perldocopt

应该可以带你去你想去的地方。

Answer 2

按照 Pod::Usage 手册所述，将 POD 格式化程序更改为“Pod::Text::Termcap”，修复了“--help”输出。现在我得到了粗体和下划线的文本。

BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
use Pod::Usage qw(pod2usage);

我在调用 mod2usage() 时得到了“--man”输出，并将 -perldocopt 设置为“-o man”

pod2usage(-perldocopt => '-o man', -verbose => 2) if ($man);