内容

• 名称
• 描述
  • 普通段落
  • 逐字段落
  • 命令段落
  • 格式化代码
  • 目的
  • 在Perl模块中嵌入Pods
  • 写作盒提示
• 另请参阅
• 作者

#名称

perlpod-普通旧文档格式

#描述

Pod是一种简单易用的标记语言，用于编写Perl、Perl程序和Perl模块的文档。

可以使用翻译器将Pod转换为各种格式，如纯文本、HTML、手册页等。

播客标记由三种基本类型的段落组成：普通的,逐字记录、和命令.

#普通段落

文档中的大多数段落都是普通的文本块，比如这个。您只需键入文本而不需要任何标记，前后只需一个空行。当它被格式化时，它将经历最小的格式化，比如被重写，可能被放入一个等距的字体中，甚至可能被调整。

您可以在普通段落中使用格式代码大胆的,斜体,代码样式,超链接，等等。这些代码在“格式化代码”部分，如下所示。

#逐字段落

逐字段落通常用于表示代码块或其他文本，这些文本不需要任何特殊的解析或格式，也不应该进行包装。

逐字段落的区别在于，它的第一个字符是空格或制表符。（通常，它的所有行都以空格和/或制表位开头。）它应该准确地复制，制表位假定位于8列边界上。没有特殊的格式代码，所以你不能用斜体或类似的东西。A表示\，其他什么都没有。

#命令段落

命令段用于对整段文本进行特殊处理，通常作为标题或列表的一部分。

所有命令段落（通常只有一行长）都以“=”开头，后跟标识符，然后是命令可以随意使用的任意文本。当前识别的命令有

=吊舱=head1标题文本=head2标题文本=head3标题文本=head4标题文本=head5标题文本=head6标题文本=超过缩进级别=物品=背面=开始格式=结束格式=用于格式化文本。。。=编码类型=切割

要详细解释它们：

#=头部1标题文本

#=头部2标题文本

#=头部3标题文本

#=头部4标题文本

#=头5标题文本

#=头部6标题文本

标题1到标题6生成标题，标题1为最高级别。本段其余部分的文本是标题的内容。例如：

=head2对象属性

文本“对象属性”包含其中的标题。这些标题命令中的文本可以使用格式代码，如下所示：

=head2 C的可能值<$/>

这些命令在“格式化代码”部分，如下所示。

请注意头部5和头部6于2020年和年推出吊舱：：简单3.41，于2020年10月发布，因此您使用的Pod解析器可能不支持它们。

#=超过缩进级别

#=项目东西。。。

#=背面

Item、over和back需要更多的解释：“=over”启动一个区域，专门用于使用“=Item”命令生成列表，或用于缩进（组）普通段落。在列表的末尾，使用“=back”结束列表缩进级别“=over”选项表示缩进的距离，通常以ems（其中一个em是文档基本字体中“M”的宽度）或大致可比较的单位表示；如果没有缩进级别选项，默认为4。（有些格式化程序可能会忽略任何内容缩进级别您提供。）在东西在里面=项目东西。。。，可以使用格式代码，如下所示：

=项使用C<$|>控制缓冲

这些命令在“格式化代码”部分，如下所示。

还要注意，使用“=over”有一些基本规则。。。“=背面”区域：

• 不要在“=over”之外使用“=item”。。。“=背面”区域。

• “=over”命令之后的第一件事应该是“=item”，除非在这个“=over”中根本没有任何项。。。“=背面”区域。

• 不要放“=头n个“在”=over“…”=back“区域内的命令。

• 也许最重要的是，保持项目的一致性：或者对所有项目使用“=item*”，以生成子弹；或使用“=第1项”、“=第2项”等生成编号列表；或者使用“=item-foo”、“=item bar”等——也就是说，看起来与项目符号或数字完全不同的东西。（如果你有一个列表，其中包含以下两项：1）看起来不像项目符号或数字的东西，再加上2）看起来像的东西，你应该在项目符号或类似数字的项目前面加上Z轴<>。请参阅Z轴<>下面是一个示例。）

  如果您以项目符号或数字开头，请坚持使用它们，因为格式化程序使用第一个“=item”类型来决定如何格式化列表。

#=切割

要结束Pod块，请使用一个空行，然后使用一个以“=cut”开头的行，以及它后面的空行。这让Perl（和Pod格式化程序）知道这是Perl代码恢复的地方。（“=cut”前的空行在技术上是不必要的，但许多较旧的Pod处理器都需要它。）

#=吊舱

“=pod”命令本身并没有做什么，但它向Perl（和pod格式化程序）发出信号，表示pod块从这里开始。Pod块以开始任何命令段，所以“=pod”命令通常只在您想用普通段落或逐字段落开始pod块时使用。例如：

=物品填充（）这个函数可以做一些事情。=切割子材料{...}=吊舱记住检查其返回值，如：stuff（）||die“做不到！”；=切割

#=开始格式名称

#=结束格式名称

#=用于格式名称 文本。。。

For、begin和end将允许您拥有文本/代码/数据区域，这些区域通常不会被解释为普通的Pod文本，而是直接传递给特定的格式化程序，或者是特殊的。可以使用该格式的格式化程序将使用该区域，否则它将被完全忽略。

命令“=开始格式名称“、一些段落和一个命令”=结束格式名称“，意味着中间的文本/数据是为理解特殊格式（称为格式名称例如，

=开始html<hr><img src=“thang.png”><p>这是一个原始的HTML段落</p>=结束html

命令“=for格式名称 文本。。。“指定仅此段落的其余部分（从后面开始格式名称)是那种特殊的格式。

=对于html<hr><img src=“thang.png”><p>这是一个原始的HTML段落</p>

这与上面的“=begin html”的含义相同。。。“=end html”区域。

也就是说，使用“=for”，您只能有一个段落的文本（即“=foo targetname text…”中的文本），但使用“=begin targetname”。。。“=end targetname”，您可以在中间放置任意数量的内容。（请注意，“=begin”命令后仍必须有一个空行，“=end”命令前必须有一行。）

以下是如何使用这些选项的一些示例：

=开始html<br>图1.<br><IMG SRC=“figure1.png”><br>=结束html=开始文本---------------|foo公司||巴|---------------^^^^图1^^^^=结束文本

目前已知格式化程序接受的一些格式名称包括“roff”、“man”、“latex”、“tex”、“text”和“html”。（一些格式化程序将其中一些视为同义词。）

格式名称“comment”通常用于制作不会出现在Pod文档的任何格式化版本中的笔记（可能是对您自己）：

=供评论确保记录所有可用选项！

有些格式名称将需要前导冒号（如“=用于：formatname”，或“=开始：formatname”。。。“=结束：formatname”)，表示文本不是原始数据，而是是播客文本（即，可能包含格式代码），不用于正常格式（例如，可能不是正常使用的段落，但可能用于作为脚注的格式）。

#=编码编码名称

此命令用于声明文档的编码。大多数用户都不需要这个；但如果您的编码不是US-ASCII，则将=编码编码名称命令，以便pod格式化程序知道如何解码文档。对于编码名称，使用由编码：：支持模块。一些pod格式化程序可能会尝试猜测拉丁语-1或CP-1252与UTF-8编码之间的差异，但他们可能猜错了。如果您使用的不是严格的ASCII，最好是显式的。示例：

=编码拉丁语1=编码utf8=编码koi8-r=编码ShiftJIS=编码big5

=编码影响整个文档，并且只能出现一次。

别忘了，所有的命令=编码一直持续到结束段落，而不是它的线条。因此，在下面的示例中，您可以看到每个命令后面都需要空白行，以结束其段落。（一些较老的Pod翻译人员可能需要=编码行的后面还有一个空行，尽管省略应该是合法的。）

列表的一些示例包括：

=超过=项目*第一项=项目*第二项=背面=超过=项目Foo（）Foo功能说明=项目栏（）Bar功能说明=背面

#格式化代码

在普通段落和某些命令段落中，可以使用各种格式代码（也称为“内部序列”）：

#我<文本>--斜体文本

用于强调（“小心点“）和参数（”重做I<标签>")

#B<文本>--粗体文本

用于开关（“perl的B开关“），程序（”一些系统为此提供了B“），强调（”小心点“），依此类推（”这一特征被称为B").

#C<代码>--代码文本

以打字机字体呈现代码，或给出表示程序文本（“C<gmtime（$^T）>“）或其他形式的计算机语言（”C<图纸xr-xr-x>").

#L<名字>--超链接

下面列出了各种语法。在给定的语法中，文本,名称、和部分不能包含字符“/”和“|”；并且任何“<”或“>”都应该匹配。

• L<名字>

  链接到Perl手册页（例如。，L<网络：：Ping>). 请注意名称不应包含空格。此语法有时也用于对Unix手册页的引用，如L<crontab（5）>.

• L<名称/“秒”>或L<名称/秒>

  链接到其他手册页面中的一节。例如。，L<perlsyn/“For Loops”>

• L</“秒”>或L</秒>

  链接到本手册页面中的一节。例如。，L</“对象方法”>

节由命名的标题或项开始。例如，L<perlvar/$.>或L<perlvar/“$”>都链接到由“=项目$。“在perlvar中。并且L<perlsyn/For循环>或L<perlsyn/“For Loops”>都链接到由“=回路头2“在perlsyn中。

要控制用于显示的文本，可以使用“L<文本|…>“，如：

• L<文本|名称>

  将此文本链接到该手册页面。例如。，L<Perl错误消息|perldiag>

• L<text|name/“秒”>或L<文本|名称/秒>

  将此文本链接到手册页面中的该部分。例如。，L<postfix“if”|perlsyn/“语句修饰符”>

• L<text|/“秒”>或L<文本|/秒>或L<文本|“秒”>

  将此文本链接到本手册页面中的该部分。例如。，L<各种属性|/“成员数据”>

或者您可以链接到网页：

• L<方案：…>

  L<text|方案：…>

  指向绝对URL的链接。例如，L（左）<http://www.perl.org/>或L<Perl主页|http://www.perl.org/>.

#E<逃逸>--字符转义

非常类似于HTML/XML&foo公司;“实体参考”：

• E（电子）--文字<（小于）

• E<gt>--文字>（大于）

• E<普通>--文字|(版本tical（理论）酒吧)

• E<溶胶>--文字/(溶胶身份证）

  除其他格式代码外，上述四个是可选的，特别是L<…>，前面加一个大写字母。

• 电子名称

  一些非数字HTML实体名称，例如E（每个），意思与&相互作用；在HTML中——即带有锐音符（/形）的小写e。

• E<数字>

  带有该数字的ASCII/Latin-1/Unicode字符。前导“0x”表示数为十六进制，如E<0x201E>。前导“0”表示数是八进制的，如E<075>。否则数被解释为十进制，如E<181>.

  请注意，较旧的Pod格式化程序可能无法识别八进制或十六进制数字转义，并且许多格式化程序无法可靠地呈现255以上的字符。（一些格式化程序甚至可能不得不使用拉丁语-1/CP-1252字符的折衷渲染，如渲染E（每个）只是一个普通的“e”。）

#F<文件名>--用于文件名

通常以斜体显示。示例：“F<.cshrc>"

#S<文本>--文本包含不间断空格

这意味着文本不应跨越线条。例子：S<x美元$y:$z>.

#X＜主题名称＞--索引条目

大多数格式化程序都忽略了这一点，但有些格式化程序可能会使用它来构建索引。它始终呈现为空字符串。例如：X<绝对化相对URL>

#Z轴<>--空（零效应）格式代码

这是很少使用的。这是使用E的一种方法有时编写代码。例如，代替“东北<lt>3“（对于“N<3”）你可以写”新西兰<><3“（“Z<>”分解了“N”和“<”，因此它们不能被视为（虚构的）“N<…>的一部分“代码）。

另一个用法是表示东西在里面=项目Z东西。。。不应被视为项目符号或数字。例如，没有Z轴<>，线

=项目Z<>500服务器错误

可能会被解析为编号列表中的一项，但这并不意味着它是。

另一个用途是在=项目线。如果您指定

=项目foo=项目栏

它通常会呈现为

foo公司酒吧

这可能是你想要的，但如果你真正想要的是

foo公司酒吧

你可以使用Z轴<>实现这一目标

=项目fooZ轴<>=项目栏

大多数情况下，您只需要一组尖括号来分隔格式代码的开头和结尾。然而，有时您会希望在格式代码中放置一个真正的直角括号（一个比符号“>”大的符号）。当使用格式化代码为代码片段提供不同的字体类型时，这种情况尤其常见。与Perl中的所有内容一样，有多种方法可以做到这一点E类代码：

C<$a E<lt>=E<gt>$b>

这将产生：“a美元<=>b美元"

一种更易读，也可能更“简单”的方法是使用一组备用分隔符，不需要转义单个“>”。可以使用双尖括号（“<<”和“>>”）当且仅当在开始分隔符之后有空格，在结束分隔符之前有空格！例如，以下方法可以实现这一点：

C<<$a<=>$b>>

事实上，只要在开始分隔符和结束分隔符中使用相同数量的重复角括号，就可以使用任意多的角括号，并确保空白紧跟开始分隔符的最后一个“<”之后，紧跟结束分隔符的第一个“>”之前。（空白被忽略。）因此以下操作也将有效：

C<<<$a<=>$b>>C<<<<$a<=>$b>>>

它们的意思完全一样：

C<$a E<lt>=E<gt>$b>

多重格式不影响对格式代码内容的解释，只影响它必须如何结束。这意味着上述示例也完全相同：

C<<$a E<lt>=E<gt>$b>>

作为进一步的示例，这意味着如果您想将这些代码放入C类（代码）样式：

打开（X，“>>thing.dat”）||die$！$foo->bar（）；

你可以这样做：

C<<<open（X，“>>thing.dat”）||die$！>>>C<<$foo->bar（）；>>

这大概比旧方法更容易阅读：

C<open（X，“E<gt>E<gt>thing.dat”）||die$！>C<$foo-E<gt>bar（）；>

目前，pod2text（Pod:：Text）、pod2man（Pod:：Man）以及任何其他使用Pod：：Parser 1.093或更高版本，或Pod：:Tree 1.02或更高级别的pod2xxx或Pod:∶Xxxx翻译器都支持此功能。

#目的

其目的是使用简单，而不是表达能力。段落看起来像段落（块格式），所以它们在视觉上很突出，所以我可以把它们通读一遍柔性制造技术很容易重新格式化（在我的版本中是F7不及物动词，或我的版本中的Esc Q电子邮箱). 我希望翻译总是离开'和`和"在逐字模式下，只有引号，所以我可以在一个工作程序中发出咕噜声，把它移到四个空格上，然后逐字打印出来。大概是用单格字体。

播客格式不一定足以写一本书。Pod只是用来作为nroff、HTML、TeX和其他标记语言的防白痴通用源，用于在线文档。存在的转换器播客2文本,豆荚2小时,吊舱2man（这是针对nroff（1）和troff（1，荚果2乳胶、和播客2fm。CPAN中提供了各种其他功能。

#在Perl模块中嵌入Pods

您可以在Perl模块和脚本中嵌入Pod文档。文档以空行开始，开头是“=head1”命令，结尾是“=cut”命令和空行。这个珍珠可执行文件将忽略播客文本。您可以在以下位置放置Pod语句珍珠期望新语句的开头，但不希望出现在语句中，因为这会导致错误。有关示例，请参阅提供的任何库模块。

如果您要将Pod放在文件末尾，并且使用__结束__或__数据__切割标记，确保在第一个Pod命令之前放一行空行。

__结束__=头1名称时间：：本地-根据本地时间和GMT时间有效计算时间

如果没有“=head1”前的空行，许多翻译人员就不会将“=heat1”视为启动Pod块。

#写作盒提示

• 这个播客检查器命令用于检查Pod语法中的错误和警告。例如，它检查Pod块中是否有完全空白的行，以及未知的命令和格式代码。您还应该通过一个或多个翻译人员传递文档并校对结果，或者打印出结果并进行校对。发现的一些问题可能是翻译器中的错误，您可能希望也可能不希望解决。

• 如果您更熟悉用HTML编写而不是用Pod编写，您可以尝试用简单的HTML编写文档，并通过实验将其转换为Pod吊舱：：HTML2Pod模块（在CPAN中可用），并查看生成的代码。实验吊舱：：PXMLCPAN中的模块也可能很有用。

• 许多较老的Pod翻译器要求每个Pod命令之前的行和每个Pod指令之后的行（包括“=cut”！）都是空行。有这样的东西：

  # - - - - - - - - - - - -=物品$爆竹->轰鸣声（）这响亮地引爆了爆竹物体。=切割副动臂{...

  ……将使此类Pod翻译器完全看不到Pod块。

  相反，要这样做：

  # - - - - - - - - - - - -=物品$爆竹->轰鸣声（）这响亮地引爆了爆竹物体。=切割副动臂{...

• 一些较旧的Pod翻译器要求段落（包括命令段落，如“=head2 Functions”）之间用完全地空行。如果您有一个明显的空行，上面有一些空格，这可能不会被视为这些翻译人员的分隔符，这可能会导致奇怪的格式。

• 较老的翻译人员可能会在L链接周围添加措辞，以便L<Foo:：Bar>例如，可能会成为“Foo:：Bar手册页”。所以你不应该写这样的东西L<foo>文档，如果你想让翻译后的文档读起来有意义。相反，写L文档或L<the-Foo:：Bar文档|Foo:：Bar>，以控制链接的显示方式。

• 在逐字块中超过第70列可能会被一些格式化程序包装得不好。

#另请参阅

按产品规格,perlsyn中的“POD:嵌入式文档”,珀尔纽莫德,珀尔多克,豆荚2小时,吊舱2man,播客检查器.

#作者

拉里·沃尔（Larry Wall）、肖恩·伯克（Sean M.Burke）

Perldoc浏览器由Dan Book维护(数据库). 请通过联系GitHub问题跟踪器或电子邮件关于网站本身、搜索或文档呈现的任何问题。

Perl文档由Perl5 Porters在开发Perl时维护。请通过联系他们Perl问题跟踪器，的邮件列表，或IRC公司报告文档内容或格式方面的任何问题。