如何在 Perl POD 中记录参数

Question

我有这个 POD：

=head1 My code

=head2 check

Checks something. 

Parameters:

=over 8

=item what to check.

=back

=cut

podchecker 没有抱怨。 perldoc 显示：

My code
  check
    Checks something.

    Parameters:

    what to check.

我希望“要检查的内容”行进一步缩进。

我需要如何更改我的 POD 以缩进显示参数？有没有比使用 =items 更好的方法来做到这一点？

Answer 1

perldoc 和 pod2html 都忽略了 indentlevel。使用项目符号作为解决方法。请参阅下面的示例。

=head1 My code

=head2 check with no bullets or numbers

Checks something. 

Parameters:

=over

=item what to check A

=item what to check B

=back

=head2 check with bullets

Checks something. 

=over

=item * what to check A

=item * what to check B

=back

=head2 check with numbers

Checks something. 

=over

=item 1. what to check A

=item 2. what to check B

=back

=cut

运行 perldoc /path/to/script.pl 结果：

My code
   check with no bullets or numbers
       Checks something.

       Parameters:

       what to check A
       what to check B

   check with bullets
       Checks something.

       o   what to check A

       o   what to check B

   check with numbers
       Checks something.

       1. what to check A
       2. what to check B

参考资料：

The indentlevel option to "=over" indicates how far over to indent, generally in ems (where one em is the width of an "M" in the document's base font) or roughly comparable units; if there is no indentlevel option, it defaults to four. (And some formatters may just ignore whatever indentlevel you provide.)

（来自 perldoc perlpod，黑体字）

Answer 2

请学习我的模板代码，您需要安装 Getopt::Long 和 Pod::Usage。

您将能够运行使用选项 --man 和 --help 此脚本来生成简短和完整的文档。

#!/usr/bin/perl
#
# Description:
#           Describe purpose of the program
#
# Parameters:
#           Describe parameters purpose
#
# Date:     Tue Nov 29 1:18:00 UTC 2019
#
# Author:   Polar Bear 
#           https://whosebug.com/users/12313309/polar-bear
#

use strict;
use warnings;

use Getopt::Long qw(GetOptions);
use Pod::Usage;
use Data::Dumper;

my %opt;
my @args = (
            'input|i=s',
            'output|o=s',
            'debug|d',
            'help|?',
            'man|m'
        );

GetOptions( \%opt, @args ) or pod2usage(2);

print Dumper(\%opt) if $opt{debug};

pod2usage(1) if $opt{help};
pod2usage(-exitval => 0, -verbose => 2) if $opt{man};

pod2usage("[=10=]: No files given.")  if ((@ARGV == 0) && (-t STDIN));

__END__

=head1 NAME

program - brief on program's purpose 

=head1 SYNOPSIS

 program.pl [options] file(s)

 Options:
    -i,--input  input filename
    -o,--output output filename
    -d,--debug  output debug information
    -?,--help   brief help message
    -m,--man    full documentation
    
=head1 OPTIONS

=over 4

=item B<-i,--input>

Input filename

=item B<-o,--output>

Output filename

=item B<-d,--debug>

Print debug information.

=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> accepts B<input> and processes to B<output> with purpose of achiving some goal.

=head1 EXIT STATUS

The section describes B<EXIT STATUS> codes of the program

=head1 ENVIRONMENT

The section describes B<ENVIRONMENT VARIABLES> utilized in the program

=head1 FILES

The section describes B<FILES> which used for program's configuration

=head1 EXAMPLES

The section demonstrates some B<EXAMPLES> of the code

=head1 REPORTING BUGS

The section provides information how to report bugs

=head1 AUTHOR

The section describing author and his contanct information

=head1 ACKNOWLEDGMENT

The section to give credits people in some way related to the code

=head1 SEE ALSO

The section describing related information - reference to other programs, blogs, website, ...

=head1 HISTORY

The section gives historical information related to the code of the program

=head1 COPYRIGHT

Copyright information related to the code

=cut

手册页 script.pl --man

NAME
    program - brief on program's purpose

SYNOPSIS
     program.pl [options] file(s)

     Options:
            -i,--input      input filename
            -o,--output     output filename
            -d,--debug      output debug information
            -?,--help       brief help message
            -m,--man        full documentation

OPTIONS
    -i,--input
        Input filename

    -o,--output
        Output filename

    -d,--debug
        Print debug information.

    -?,--help
        Print a brief help message and exits.

    --man
        Prints the manual page and exits.

DESCRIPTION
    This program accepts input and processes to output with purpose of
    achiving some goal.

EXIT STATUS
    The section describes EXIT STATUS codes of the program

ENVIRONMENT
    The section describes ENVIRONMENT VARIABLES utilized in the program

FILES
    The section describes FILES which used for program's configuration

EXAMPLES
    The section demonstrates some EXAMPLES of the code

REPORTING BUGS
    The section provides information how to report bugs

AUTHOR
    The section describing author and his contanct information

ACKNOWLEDGMENT
    The section to give credits people in some way related to the code

SEE ALSO
    The section describing related information - reference to other
    programs, blogs, website, ...

HISTORY
    The section gives historical information related to the code of the
    program

COPYRIGHT
    Copyright information related to the code

帮助页面script.pl --help

     program.pl [options] file(s)

     Options:
            -i,--input      input filename
            -o,--output     output filename
            -d,--debug      output debug information
            -?,--help       brief help message
            -m,--man        full documentation

Options:
    -i,--input
        Input filename

    -o,--output
        Output filename

    -d,--debug
        Print debug information.

    -?,--help
        Print a brief help message and exits.

    --man
        Prints the manual page and exits.

如何在 Perl POD 中记录参数

How to document parameters in Perl POD

perl

format

indentation

perldoc

perl-pod