Pod::使用帮助格式化答案

【问题标题】：Pod::Usage help formattingPod::使用帮助格式化
【发布时间】：2014-07-03 07:11:46
【问题描述】：

我想为我的 Perl 脚本正确格式化我的帮助消息，如果可能的话，使用标准模块，例如 Pod::Usage。不幸的是，我不太喜欢 pod2usage 的输出格式。例如，使用grep，我得到以下帮助结构：

$ grep --help
Usage: grep [OPTION]... PATTERN [FILE]...
Search for PATTERN in each FILE or standard input.
PATTERN is, by default, a basic regular expression (BRE).
Example: grep -i 'hello world' menu.h main.c

Regexp selection and interpretation:
  -E, --extended-regexp     PATTERN is an extended regular expression (ERE)
  -F, --fixed-strings       PATTERN is a set of newline-separated fixed strings
  -G, --basic-regexp        PATTERN is a basic regular expression (BRE)
  -P, --perl-regexp         PATTERN is a Perl regular expression

但这与Pod::Usage 非常不同，我不需要\n 和\t：

$ ./sample.pl --help
Usage:
    sample [options] [file ...]

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

Options:
    --help
        Print a brief help message and exits.

    --man
        Prints the manual page and exits.

我想以传统方式修改我的帮助格式，即不带 \n 且不带前导 \t。事实上，我正在寻找允许我这样写的解决方案：

__END__

=head1 SYNOPSIS

sample [options] [file ...]

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

=head1 OPTIONS

=item B<-h,--help>
    Print a brief help message and exits.

=item B<-v,--version>
    Prints the version and exits.

=cut

得到这个：

Usage: sample [options] [file ...]        
 This program will read the given input file(s) and do something useful
 with the contents thereof.

Options:
 -h,    --help     Print a brief help message and exits.
 -v,    --version  Prints the version and exits.

不是这个：

Usage:
    sample [options] [file ...]

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

Options:
    -h,--help Print a brief help message and exits.
    -v,--version Prints the version and exits.

有什么线索吗？

【问题讨论】：

标签： perl options command-line-interface

【解决方案1】：

当您使用=item 时，您应该在其前面加上=over x，其中x 是您想要移动的距离。完成项目后，您需要使用=back。如果=over x 足够远，该项目的段落将打印在与=item 相同的行上。我玩了一圈，发现=over 20看起来不错：

use strict;
use warnings;

use Pod::Usage;

pod2usage( -verbose => 1);

=pod

=head1 SYNOPSIS

    sample [options] [file ...]

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

=head1 OPTIONS

=over 20

=item B<-h>, B<--help>

Print a brief help message and exits.

=item B<-v>, B<--version>

Prints the version and exits.

=back 

=cut

打印出来：

Usage:
        sample [options] [file ...]

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

Options:
    -h, --help          Print a brief help message and exits.

    -v, --version       Prints the version and exits.

对于 POD 中的 v, --version 内容，您无能为力，无法让它以漂亮的三列格式打印。您可以做的是在-h 和--help 之间留出更多空间，就像我在上面所做的那样，以提高可读性。

请记住，重要的是 POD 中的数据，而不是绝对格式。使用格式使其易于阅读，但不要过多关注细节。

我强烈建议您使用旧的标准手册页布局（Pod2Usage 假定）。

【讨论】：

【解决方案2】：

你可以尝试两件事：

-noperldoc option 使其切换到 Pod::Text，这是一个更简单的格式化程序。

或

Set a different formatter

Pod::Text 也有几个格式选项，例如左边距、缩进级别、页面宽度，可能会更符合您的喜好。

【讨论】：