Pod::Usage 不能正常工作

Question

我有：

my $man = 0;
my $help = 0;
## Parse options and print usage if there is a syntax error,
## or if usage was explicitly requested.
GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
pod2usage(1) if $help;
pod2usage(-verbose => 2) if $man;

#-----------------------------------------------------------------
#----------------  Documentation / Usage / Help ------------------
=head1 NAME
  sample - Using GetOpt::Long and Pod::Usage

=head1 SYNOPSIS
  sample [options] [file ...]
   Options:
     -help            brief help message
     -man             full documentation

=head1 OPTIONS
  =over 8
  =item B<-help>  
    Print a brief help message and exits.
  =item B<-man>
    Prints the manual page and exits.
  =back

=head1 DESCRIPTION
  B<This program> will read the given input file(s) and do something
  useful with the contents thereof.
=cut

从在线示例中复制/粘贴了很多内容。但是，当我执行 script.pl --help 时，什么也没有打印出来，并且脚本退出了。

Answer 1

如前所述，pod 文档的间距很重要。此外，无需在概要中复制您的选项，只需将它们留在选项部分即可。

以下是您试用Pod::Usage的清理版

use strict;
use warnings;

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

## Parse options and print usage if there is a syntax error,
## or if usage was explicitly requested.

GetOptions(
    'help|?'    => \my $help,
    'man'       => \my $man,
) or pod2usage(-verbose => 0);
pod2usage(-verbose => 1) if $help;
pod2usage(-verbose => 2) if $man;

## Check for File
pod2usage("$0: No filename specified.\n") unless @ARGV;

#-----------------------------------------------------------------
#----------------  Documentation / Usage / Help ------------------
=head1 NAME

sample - Using GetOpt::Long and Pod::Usage

=head1 SYNOPSIS

sample [file]

=head1 OPTIONS

=over 8

=item B<--help>  

Print a brief help message and exits.

=item B<--man>

Prints the manual page and exits.

=back

=head1 DESCRIPTION

B<This program> will read the given input file(s) and do something
useful with the contents thereof.

=cut

Answer 2

Miller 有答案。

当您创建 POD 文档时，您需要在每个段落之间添加一个空行，包括 命令段落。 POD 文档没有说明这一点。此外，所有 POD 命令段落必须从第一列开始。例如，这是错误的：

=head1 NAME
foo.cmd
=head1 DESCRIPTION
This is my description of my command.
....

我需要把这个隔开：

=head1 NAME

foo.cmd

=head1 DESCRIPTION

This is my description.

否则，POD 会这样解释：

=head1 NAME foo.cmd =head1 DESCRIPTION This is my description of my command.

现在，您没有名为 NAME 或 DESCRIPTION 的标头，因此您的 pod2usage 不会打印。

我还需要在第 1 列开始我的命令。这不起作用：

=over 4

    =item *
        blah, blah, blah...

我需要这样做：

=over 4

=item *

blah, blah, blah

=back

您可以运行 podchecker 程序来检查您的 pod 并确保一切正确。这应该与perl 命令位于同一目录中。我将您的 pod 文档放入 test.pod 并运行以下命令：

$ podchecker test.pod
*** WARNING: empty section in previous paragraph at line 4 in file test.pod
*** WARNING: empty section in previous paragraph at line 10 in file test.pod
*** ERROR: Apparent command =cut not preceded by blank line at line 21 in file test.pod
*** WARNING: empty section in previous paragraph at line 18 in file test.pod
test.pod has 1 pod syntax error.

empty section in previous paragraph 警告来自=head1 之后没有跳过一行。