Perl 内嵌文档

Perl - 内嵌文档 (POD)

Perl 允许您使用一种简单的标记语言（称为 POD，即 Plain Old Documentation）直接在代码中内嵌文档。这是文档化 Perl 模块和脚本的标准方式。

在 Perl 代码中内嵌 POD 的主要规则：

在新行上，使用 =head1 等 POD 命令开始您的文档。
在新行上，使用 =cut 命令结束您的文档块。
Perl 解释器将忽略这些 POD 标记之间的任何文本。

下面是一个简单的示例：

#!/usr/bin/perl
use strict;
use warnings;

print "Hello, World\n";

=head1 Hello, World Example

# 此示例演示了 Perl 和 POD 的非常基础的语法。

=cut

print "Hello, Universe\n";

执行上述代码后，将产生以下结果（POD 内容被解释器忽略）：

Hello, World
Hello, Universe

如果将 POD 放在文件的末尾，特别是在 __END__ 或 __DATA__ 标记之后，请确保在第一个 POD 命令（例如 =head1）之前有一行空行。这有助于许多 POD 转换工具正确识别 POD 块的开始位置。

包含 __DATA__ 的示例：

#!/usr/bin/perl
use strict;
use warnings;

print "Hello, World from script\n";

while (my $line = <DATA>) {
    print "Data: $line";
}

__DATA__
This is some data.

=head1 POD at the End

# 此 POD 块在 __DATA__ 之后。
# 如果前面没有 =cut，或者没有仔细解析，上面的循环会将其作为数据读取。
# 通常，__DATA__ 后的 POD 用于文档目的，除非特别意图如此，否则不应被脚本的数据读取逻辑读取。

=cut
This line is after =cut and __DATA__, so it's also data.

执行上述代码后，将产生（请注意 POD 命令在此处被视为数据）：

Hello, World from script
Data: This is some data.
Data:
Data: =head1 POD at the End
Data:
Data: This POD block is after __DATA__.
Data: It will be read as data by the above loop if not for a =cut before it, or careful parsing.
Data: Typically, POD after __DATA__ is for documentation purposes and not meant to be read by the script's data reading logic unless specifically intended.
Data:
Data: =cut
Data: This line is after =cut and __DATA__, so it's also data.

如果 POD 纯粹用于文档目的，并且不打算与从 __DATA__ 读取的数据混合，则通常将其放在 __DATA__ 之前，或者确保数据读取逻辑在 POD 部分之前停止（如果它们混杂在一起）。

什么是 POD？

POD 是一种轻量级标记语言，用于文档化 Perl 代码。它被设计成易于以原始形式阅读，并且可以使用 perldoc 等工具或 CPAN 中的模块（例如 Pod::Simple）转换为各种其他格式，如 HTML、man 手册页和纯文本。

POD 标记包含三种基本类型的段落：

普通段落： 常规文本。您可以使用格式化代码来实现粗体 (B<>)、斜体 (I<>)、代码风格 (C<>)、链接 (L<>) 等。
逐字段落 (Verbatim Paragraph)： 前面至少有一个空格或制表符。用于代码块或不应被重新格式化或换行的文本。在逐字段落中，格式化代码不会被解释。
命令段落 (Command Paragraph)： 以 = 开头，后跟一个标识符（例如 =head1、=item）。这些命令用于构建文档结构、创建标题、列表等。

常用 POD 命令：

=pod
=head1 Major Heading Text
=head2 Secondary Heading Text
=head3 Tertiary Heading Text
=head4 Quaternary Heading Text
=over indentlevel (e.g., =over 4)
=item text or * for bullet
=back
=begin format_name (e.g., =begin html)
=end format_name
=for format_name text...
=encoding encoding_name (e.g., =encoding UTF-8)
=cut

POD 示例

考虑以下简单的 POD：

=head1 NAME

My::Module - A sample module for demonstration

=head1 SYNOPSIS

  use My::Module;
  my $obj = My::Module->new();
  $obj->do_something();

=head1 DESCRIPTION

This module provides a C<do_something()> method just for fun.
It's B<boldly> going nowhere.

=cut

您可以使用 perldoc your_script.pl 查看此文档。要将其转换为 HTML，您可以使用 perldoc -o html your_script.pl 或通过编程方式使用 CPAN 模块，如 Pod::Simple::HTML。

列表和内嵌 HTML 的示例（尽管现在直接内嵌 HTML 较不常见，通常由 POD 到 HTML 转换器处理）：

=head2 An Example List

=over 4

=item *

This is a bulleted list item.

=item *

Here's another item.

=back

=begin html

<p>This is an <em>HTML</em> block. POD parsers targeting non-HTML formats will typically ignore this.</p>

=end html

=cut

当转换为 HTML 时，这将生成一个标题、一个项目符号列表和原始 HTML 段落。现代 POD 处理器提供了强大的 HTML 生成功能，无需为大多数常见格式显式使用 =begin html。

有关 POD 的更全面信息，请在您的终端中输入 perldoc perlpod 或 perldoc perlpodspec 查阅官方 Perl 文档。