perlpod-普通旧文档格式
Pod是一种简单易用的标记语言,用于编写Perl、Perl程序和Perl模块的文档。
可以使用翻译器将Pod转换为各种格式,如纯文本、HTML、手册页等。
播客标记由三种基本类型的段落组成:普通的,逐字记录、和命令.
#普通段落
文档中的大多数段落都是普通的文本块,比如这个。您只需键入文本而不需要任何标记,前后只需一个空行。当它被格式化时,它将经历最小的格式化,比如被重写,可能被放入成比例间隔的字体,甚至可能被对齐。
您可以在普通段落中使用格式代码大胆的,斜体,代码样式
,超链接等等。这些代码在“格式化代码”部分,如下所示。
#逐字段落
逐字段落通常用于表示代码块或其他文本,这些文本不需要任何特殊的解析或格式,也不应该进行包装。
逐字段落的区别在于,它的第一个字符是空格或制表符。(通常,它的所有行都以空格和/或制表位开头。)它应该准确地复制,制表位假定位于8列边界上。没有特殊的格式代码,所以你不能用斜体或类似的东西。A表示\,其他什么都没有。
#命令段落
命令段用于对整段文本进行特殊处理,通常作为标题或列表的一部分。
所有命令段落(通常只有一行长)都以“=”开头,后跟标识符,然后是命令可以随意使用的任意文本。当前识别的命令有
=head1标题文本=head2标题文本=head3标题文本=head4标题文本=超过缩进级别=物品=背面=切割=吊舱=开始格式=结束格式=用于格式化文本。。。
要详细解释它们:
- #
=头部1标题文本
-
- #
=头部2标题文本
-
- #
=头部3标题文本
-
- #
=头部4标题文本
-
标题1到标题4生成标题,标题1为最高级别。本段其余部分的文本是标题的内容。例如:
=head2对象属性
文本“对象属性”包含其中的标题。(请注意,head3和head4是最近添加的,旧的Pod翻译器不支持。)这些标题命令中的文本可以使用格式代码,如下所示:
=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”
),表示文本不是原始数据,而是是不适用于普通格式的播客文本(即,可能包含格式代码)(例如,可能不是正常使用的段落,但可能用于作为脚注格式)。
在使用任何命令时,不要忘记该命令将一直持续到其结束段落,而不是它的线条。因此,在下面的示例中,您可以看到每个命令后面都需要空白行,以结束其段落。
列表的一些示例包括:
=超过=项目*第一项=项目*第二项=背面=超过=项目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</“对象方法”>
节由命名的标题或项开始。例如,L<perlvar/$.>
或L<perlvar/“$”>
都链接到由“=项目$。
“在perlvar中。并且L<perlsyn/For循环>
或L<perlsyn/“For Loops”>
都链接到由“=回路头2
“在perlsyn中。
要控制用于显示的文本,可以使用“L<文本|…>
“,如:
L<文本|名称>
将此文本链接到手册页面。例如。,L<Perl错误消息|perldiag>
L<text|name/“秒”>
或L<文本|名称/秒>
将此文本链接到手册页面中的该部分。例如。,L<SWITCH语句|perlsyn/“Basic BLOCKs and SWITCH语句”>
L<text|/“秒”>
或L<文本|/秒>
或L<文本|“秒”>
将此文本链接到本手册页面中的该部分。例如。,L<各种属性|/“成员数据”>
或者您可以链接到网页:
- #
E<逃生>
--字符转义
-
非常类似于HTML/XML&foo公司;
“实体参考”:
E(电子)
--文字<(小于)
E<gt>
--文字>(大于)
E<普通>
--文字|(版本理论上的酒吧)
E<溶胶>
=文字/(溶胶身份证)
除其他格式代码外,上述四个是可选的,特别是L<…>
,前面加一个大写字母。
电子名称
一些非数字HTML实体名称,例如E(每个)
,意思与&相互作用;
在HTML中——即带有锐音符(/形)的小写e。
E<数字>
带有该数字的ASCII/Latin-1/Unicode字符。前导“0x”表示数为十六进制,如E<0x201E>
。前导“0”表示数是八进制,如E<075>
。否则数被解释为十进制,如E<181>
.
请注意,较旧的Pod格式化程序可能无法识别八进制或十六进制数字转义,并且许多格式化程序无法可靠地呈现255以上的字符。(一些格式化程序甚至可能不得不使用拉丁语-1字符的折衷渲染,如渲染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美元
"
一种更易读,也可能更“简单”的方法是使用一组备用分隔符,不需要转义单个“>”。对于从perl5.5.660开始的标准Pod格式化程序,可以使用双尖括号(“<<”和“>>”)当且仅当在开始分隔符之后有空格,在结束分隔符之前有空格!例如,以下方法可以实现这一点:
C<<$a<=>$b>>
事实上,只要在开始分隔符和结束分隔符中使用相同数量的重复角括号,就可以使用任意多的角括号,并确保空白紧跟开始分隔符的最后一个“<”之后,紧跟结束分隔符的第一个“>”之前。(空白被忽略。)因此以下操作也将有效:
C<<<$a<=>$b>>C<<<<$a<=>$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格式不一定足以写一本书。Pod只是用来作为nroff、HTML、TeX和其他标记语言的防白痴通用源,用于在线文档。存在的转换器播客2文本,豆荚2小时,吊舱2man(这是针对nroff(1)和troff(1,荚果2乳胶、和播客2fm。CPAN中提供了各种其他功能。
#在Perl模块中嵌入Pods
您可以在Perl模块和脚本中嵌入Pod文档。以空行开始文档,在开头使用“=head1”命令,并以“=cut”命令和空行结束文档。Perl将忽略Pod文本。有关示例,请参阅提供的任何库模块。如果要将Pod放在文件的末尾,并且使用__end__或__DATA__剪切标记,请确保在第一个Pod命令之前在那里放一个空行。
__结束__=头1名称时间::本地-根据本地时间和GMT时间有效计算时间
如果没有“=head1”前的空行,许多翻译人员就不会将“=heat1”视为启动Pod块。
#写作盒提示
这个播客检查器命令用于检查Pod语法中的错误和警告。例如,它检查Pod块中是否有完全空白的行,以及未知的命令和格式代码。您还应该通过一个或多个翻译人员传递文档并校对结果,或者打印出结果并进行校对。发现的一些问题可能是翻译器中的错误,您可能希望也可能不希望解决。
如果您更熟悉用HTML编写而不是用Pod编写,您可以尝试用简单的HTML编写文档,并通过实验将其转换为Pod吊舱::HTML2Pod模块(在CPAN中可用),并查看生成的代码。实验吊舱::PXMLCPAN中的模块也可能很有用。
许多较老的Pod翻译器要求每个Pod命令之前的行和每个Pod指令之后的行(包括“=cut”!)都是空行。有这样的东西:
# - - - - - - - - - - - -=物品$firecrack->boom()这响亮地引爆了爆竹物体。=切割副动臂{...
……将使此类Pod翻译器完全看不到Pod块。
相反,要这样做:
# - - - - - - - - - - - -=物品$爆竹->轰鸣声()这响亮地引爆了爆竹物体。=切割副动臂{...
一些较旧的Pod翻译器要求段落(包括命令段落,如“=head2 Functions”)之间用完全地空行。如果您有一个明显的空行,上面有一些空格,这可能不会被视为这些翻译人员的分隔符,这可能会导致奇怪的格式。
较老的翻译人员可能会在L链接周围添加措辞,以便L<Foo::酒吧>
例如,可能会成为“Foo::Bar手册页”。所以你不应该写这样的东西L<foo>文档
,如果您希望翻译后的文档能够合理地阅读,那么可以写L文档
或L<the-Foo::Bar文档|Foo::Bar>
,以控制链接的显示方式。
在逐字块中超过第70列可能会被一些格式化程序包装得不好。
#另请参阅
按产品规格,perlsyn中的“POD:嵌入式文档”,珀尔纽莫德,珀尔多克,豆荚2小时,吊舱2man,播客检查器.
拉里·沃尔(Larry Wall)、肖恩·伯克(Sean M.Burke)