第二十六章，简单旧文档
26.1 pod in a NutShell
26.1.1. 字面段落
26.1.2. pod 指示符
26.1.3 Pod 序列
! /usr/bin/perl -l00n
olpod - outline pod
! /usr/bin/perl -00 catpod - cat out just the pods
! /usr/bin/perl -n00
podlit - print the indented literal blocks from pod input
! /usr/bin/perl
catpod2, class and program
设计 Perl 的一个原则是简单的事情应该简单，而难的事情应该有可能简单。文档应该简单。
Perl 支持一种叫 pod 的简单文本标记格式，它可以独立存在或者自由地与你的源代码混合在一起形成嵌入的文档。Pod 可以转换成许多其他格式，用于查阅或者打印，或者你也可以直接阅读它，因为它很简单。
Pod 不象 XML，LatEx，troff(1) 那样富于表现力，甚至连 HTML 都不如。这么做是故意的：我们为了简单和方便牺牲了表现力。有些文本标记语言让作者写的标记比文本还多，这样就把写作变得比原来还要复杂，而阅读则几乎是不可能的。一个好的格式应该象好的电影乐曲那样，隐藏在后台而不会让观众的注意力分散。
让程序员写文档几乎和让他们打领带一样困难。Pod 的设计让写文档非常容易，甚至一个程序员都可以写——并且愿意写。我们可没有说 pod 胜任写一本书——尽管它足够写我们这本。
26.1 pod in a NutShell?
大多数文档格式要求整个文档都是用该格式写的。Pod 更宽容：你可以在任何文件里嵌入 pod，然后依靠 pod 翻译器抽取 pod。有些文件包含 100% 纯 pod。但是其他文件，尤其是 Perl 程序和模块，可能只包含若干团 pod，散布在作者认为合适的地方。当 Perl 分析该文件准备执行的时候，它只是简单地忽略 pod 文本。
如果某一句话是用一个等于号和一个标识符开的头（象下面这样），而不是普通的一句程序，那么 Perl 的词法分析器就会知道忽略这一句话：
=head1 Here There Be Pods!
从这段文本开始，一直到一个以 =cut 开头的行为止，中间的所有文本（包括两端的行）都会被忽略。这样你就可以自由地把你的程序和文档混合在一起，比如：
=item snazzle
The snazzle() function will behave in the most spectacular
form that you can possibly imagine, not even excepting
cybernetic pyrotechnics.
=cut
sub snazzle {
my $arg = shift;
....
}
=item razzle
The razzle() function enables autodidactic epistemology generation.
=cut
sub razzle {
print "Epistemology generation unimplemented on this platform.\n";
}
如果需要更多的例子，请参阅标准的或者 CPAN Perl 模块。除了极个别的以外，它们很可能都随身带着 pod，
因为 Perl 词法器可以识别 pod 并且会把它抛弃，所以你还可以使用合适的 pod 指示符快速地注释掉大块的程序代码。使用 =for pod 块注释掉一个段落，或者一个 =begin/=end 对注释一个段落。我们稍后将介绍这些 pod 指示符。不过，请记住，在两种情况下，你仍然都是在 pod 模式下的，因此你需要 =cut 回到编译器。
print "got 1\n";
=for commentary
This paragraph alone is ignored by anyone except the
mythical "commentary" translator. When it's over, you're
still in pod mode, not program mode.
print "got 2\n";
=cut
# ok, real program again
print "got 3\n";
=begin comment
print "got 4\n";
all of this stuff
here will be ignored
by everyone
print "got 5\n";
=end comment
=cut
print "got 6\n";
这段代码将单引出得到 1，3，和 6。请注意这些 pod 指示符并不是哪里都能去。你必须把它们放到分析器预计会看到一行新语句的地方，而不是在一个表达式的中间或者其他任意的地方。
从 Perl 的观点来看，所有 pod 标记都被抛弃，但是从 pod 翻译器的观点来看，抛弃的是代码。pod 翻译器把余下的文本当作一系列用空白行分隔的段落。所有现代的 pod 翻译器都用同样的方法分析 pod：使用标准的 Pod::Parser 模块。它们的区别只是输出，因为每种翻译器都专门生成一种输出格式。
目前有三种段落：字面段落，命令段落，和散文段落。
26.1.1. 字面段落
字面段落用于那些你想表现为文本的文字，比如一小段代码。字面段落必须是缩进的，也就是说，它必须用空格或者水平制表符字符开头。翻译器会准确地重现它的格式——通常是用一种固定宽度的字体，并且假定水平制表符为八个空格宽。字面段落里面没有什么特殊的格式化逃逸，所以，你不能使用斜体或者宽体的字体。< 字符的意思就是文本 <，不是别的什么东西。
26.1.2. pod 指示符
所有 pod 指示符都是以 = 开头后面跟着一个标识符。它后面可以跟指示符愿意的任意数量的任意文本。唯一的语法要求就是这些文本必须都在同一个段落里。目前翻译器可以识别的指示符是（有时候我们把它们称做 pod 命令）： |
