您正在从Perl 5.22.3查看此文档的版本。查看最新版本
perlpod-普通旧文档格式
Pod是一种简单易用的标记语言,用于编写Perl、Perl程序和Perl模块的文档。
可以使用翻译器将Pod转换为各种格式,如纯文本、HTML、手册页等。
播客标记由三种基本类型的段落组成:普通的,逐字记录、和命令.
#普通段落
文档中的大多数段落都是普通的文本块,比如这个。您只需键入文本而不需要任何标记,前后只需一个空行。当它被格式化时,它将经历最小的格式化,比如被重写,可能被放入一个等距的字体中,甚至可能被调整。
您可以在普通段落中使用格式代码大胆的,斜体,代码样式
,超链接,等等。这些代码在“格式化代码”部分,如下所示。
#逐字段落
逐字段落通常用于表示代码块或其他文本,这些文本不需要任何特殊的解析或格式,也不应该进行包装。
逐字段落的区别在于,它的第一个字符是空格或制表符。(通常,它的所有行都以空格和/或制表位开头。)它应该准确地复制,制表位假定位于8列边界上。没有特殊的格式代码,所以你不能用斜体或类似的东西。A表示\,其他什么都没有。
#命令段落
命令段用于对整段文本进行特殊处理,通常作为标题或列表的一部分。
所有命令段落(通常只有一行长)都以“=”开头,后跟标识符,然后是命令可以随意使用的任意文本。当前识别的命令有
=吊舱=head1标题文本=head2标题文本=head3标题文本=head4标题文本=超过缩进级别=物品=背面=开始格式=结束格式=用于格式化文本。。。=编码类型=切割
要详细解释它们:
- #
=头部1标题文本
-
- #
=头部2标题文本
-
- #
=头部3标题文本
-
- #
=头部4标题文本
-
标题1到标题4生成标题,标题1为最高级别。本段其余部分的文本是标题的内容。例如:
=head2对象属性
文本“对象属性”包含其中的标题。这些标题命令中的文本可以使用格式代码,如下所示:
=head2 C的可能值<$/>
这些命令在“格式化代码”部分,如下所示。
- #
=超过缩进级别
-
- #
=项目东西。。。
-
- #
=背面
-
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”等——也就是说,看起来与项目符号或数字完全不同的东西。
如果您以项目符号或数字开头,请坚持使用它们,因为格式化程序使用第一个“=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<各种属性|/“成员数据”>
或者您可以链接到网页:
- #
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<…>的一部分“代码)。
大多数情况下,您只需要一组尖括号来分隔格式代码的开头和结尾。然而,有时您会希望在格式代码中放置一个真正的直角括号(一个比符号“>”大的符号)。当使用格式化代码为代码片段提供不同的字体类型时,这种情况尤其常见。与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)