跳转到内容

标记语言/POD 和 Wikitext/示例/Wikitext

Add links
来自 Wikibooks，开放世界中的开放书籍


名称

[编辑 | 编辑源代码]

perlpod - Plain Old Documentation 格式

描述

[编辑 | 编辑源代码]

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

有可用的转换器，用于将 Pod 转换为各种格式，例如纯文本、HTML、手册页等。

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


普通段落

[编辑 | 编辑源代码]

文档中的大多数段落将是普通的文本块，就像这段一样。您可以简单地输入文本，而无需任何标记，只需要在前后留空行即可。当它被格式化时，它将进行最少的格式化，例如重新换行，可能被放在一个比例字体中，甚至可能被对齐。

您可以在普通段落中使用格式化代码，以实现粗体、斜体、代码样式、超链接等等。这些代码在下面的格式化代码部分进行了解释。

逐字段落

[编辑 | 编辑源代码]

逐字段落通常用于呈现不需要任何特殊解析或格式化的代码块或其他文本，并且不应该换行。

逐字段落以其第一个字符是空格或制表符为特征。（并且通常，它的所有行都以空格和/或制表符开头。）它应该被精确地复制，制表符假定在 8 列边界上。没有特殊的格式化代码，因此您无法使用斜体或类似的格式。\ 代表 \，没有其他含义。


命令段落

[编辑 | 编辑源代码]

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

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

   =pod
   =head1 Heading Text
   =head2 Heading Text
   =head3 Heading Text
   =head4 Heading Text
   =over indentlevel
   =item stuff
   =back
   =begin format
   =end format
   =for format text...
   =encoding type
   =cut

详细解释它们

=head1 标题文本
=head2 标题文本
=head3 标题文本
=head4 标题文本

Head1 到 head4 生成标题，head1 是最高级别。此段落中其余文本是标题的内容。例如

=head2 对象属性

文本“对象属性”构成了标题。 （请注意，head3 和 head4 是最近的添加，在旧的 Pod 转换器中不受支持。）这些标题命令中的文本可以使用格式化代码，如下所示

=head2 C<$/> 的可能值

此类命令在下面的格式化代码部分进行了解释。

=over indentlevel
=item 内容...
=back

Item、over 和 back 需要更多解释：“=over”开始一个专门用于生成使用“=item”命令的列表或缩进（组）普通段落的区域。在列表结束时，使用“=back”来结束它。 "=over" 命令的 I<indentlevel> 选项指示缩进的距离，通常以 em 为单位（其中一个 em 是文档基本字体中“M”的宽度）或大致等效的单位；如果不存在 I<indentlevel> 选项，则默认为 4。 （并且一些格式化程序可能会忽略您提供的任何 <indentlevel>。）在 C<=item I<stuff...>> 中的 I<stuff> 中，您可以使用格式化代码，如下所示

=item 使用 $| 控制缓冲

此类命令在下面的“L<Formatting Codes|/"Formatting Codes">”部分进行了解释。

还要注意，使用 "=over" ... "=back" 区域有一些基本规则

  • 不要在 "=over" ... "=back" 区域之外使用 "=item"。
  • "=over" 命令后的第一个东西应该是一个 "=item"，除非在这个 "=over" ... "=back" 区域中没有项目。
  • 不要将 "=headI<n>" 命令放在 "=over" ... "=back" 区域内。
  • 也许最重要的是，保持项目的一致性：要么对所有项目使用 "=item *"，以生成项目符号；要么使用 "=item 1."，"=item 2." 等等，以生成编号列表；要么使用 "=item foo"，"=item bar" 等等——也就是说，看起来不像项目符号或数字的东西。
如果您以项目符号或数字开头，请继续使用它们，因为格式化程序会使用第一个 "=item" 类型来决定如何格式化列表。
=cut

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

=pod

"=pod" 命令本身并没有做太多事情，但它向 Perl（和 Pod 格式化程序）发出信号，表明 Pod 块从这里开始。Pod 块以 I<any> 命令段落开头，因此“=pod”命令通常只在您想以普通段落或逐字段落开始 Pod 块时使用。例如

 =item stuff()

 This function does stuff.

 =cut

 sub stuff {
   ...
 }

 =pod

 Remember to check its return value, as in:

   stuff() || die "Couldn't do stuff!";

 =cut
  • =begin formatname
  • =end formatname
  • =for formatname text...

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

命令 "=begin I<formatname>"、一些段落和命令 "=end I<formatname>" 意味着它们之间的文本/数据是为理解名为 I<formatname> 的特殊格式的格式化程序准备的。例如，

  =begin html
 
  <hr> <img src="thang.png">
  <p> This is a raw HTML paragraph </p>
 
  =end html

命令 "=for I<formatname> I<text...>" 指定仅此段落的其余部分（从 I<formatname> 之后开始）采用这种特殊格式。

=for html

<img src="thang.png">

这是一个原始 HTML 段落

这与上面的 "=begin html" ... "=end html" 区域相同。

也就是说，使用 "=for"，您只能拥有一个段落长度的文本（即，"=foo targetname text..." 中的文本），但使用 "=begin targetname" ... "=end targetname"，您可以在它们之间拥有任意数量的内容。 （请注意，在“=begin”命令之后仍然必须有一个空行，并且在“=end”命令之前必须有一个空行。）

以下是一些使用它们的示例

 =begin html

 
Figure 1.
<IMG SRC="figure1.png">


 =end html

 =begin text

   ---------------
   |  foo        |
   |        bar  |
   ---------------

 ^^^^ Figure 1. ^^^^

 =end text

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

"comment" 的格式名称通常用于仅仅制作注释（可能是您自己的注释），这些注释不会出现在 Pod 文档的任何格式化版本中

 =for comment
 Make sure that all the available options are documented!

一些 I<formatnames> 将需要一个冒号开头（如 C<"=for :formatname">，或 C<"=begin :formatname" ... "=end :formatname">），以指示文本不是原始数据，而是 I<is> Pod 文本（即，可能包含格式化代码），只是不适用于普通格式化（例如，可能不是普通用途的段落，但可能是用于作为脚注格式化的）。

  • =encoding encodingname

此命令用于声明文档的编码。大多数用户不需要此命令；但是，如果您的编码不是 US-ASCII 或 Latin-1，则在文档开头放置一个 C<=encoding I<encodingname>> 命令，以便 pod 格式化程序知道如何解码文档。对于 I<encodingname>，请使用 L<Encode::Supported> 模块识别的名称。示例

 =encoding utf8

 =encoding koi8-r

 =encoding ShiftJIS

 =encoding big5

不要忘记，使用任何命令时，该命令一直持续到其 I<paragraph> 结束，而不是其行结束。因此，在下面的示例中，您可以看到每个命令都需要在其之后留空行来结束其段落。一些列表示例包括

 
  =over 
  =item * 
  First item 
  =item * 
  Second item 
  =back 
  =over 
  =item Foo() 
  Description of Foo function 
  =item Bar() 
  Description of Bar function 
  =back

格式化代码

[编辑 | 编辑源代码]

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


I<text>
斜体文本
用于强调（“C<be I<careful!>>”）和参数（“C<redo I<LABELE>>”）
B<text>
粗体文本
用于开关（“C<perl's B<-n> switch>”）、程序（“C<some systems provide a B<chfn> for that>”）、强调（“C<be B<careful!>>”）等等（“C<and that feature is known as B<autovivification>>”）。
C<code>
代码文本
以打字机字体渲染代码，或以其他方式指示代码文本，例如 "C<gmtime($^T)>" 或其他形式的计算机语言 "C<drwxr-xr-x>"。
L<name>
一个超链接
有多种语法，如下所示。在给定的语法中，given、text、name 和 section 不能包含字符 '/' 和 '|'； 并且任何 '<' 或 '>' 应该匹配。
  • L<name>
链接到 Perl 手册页（例如，L<Net::Ping>）。注意，name 不应包含空格。此语法有时也用于引用 UNIX 手册页。
例如 L<crontab(5)>.
  • L<name/"sec"> 或 L<name/sec>
链接到另一个手册页中的一个节。
例如 L<perlsyn/"For Loops">
L</"sec"> 或 L</sec> 或 L<"sec">
链接到本手册页中的一个节。例如，
L</"Object Methods">

一个节以命名的标题或项目开始。例如，C<L<perlvar/$.>> 或 C<L<perlvar/"$.">> 都链接到 perlvar 中以 "C<=item $.>" 开始的节。并且 C<L<perlsyn/For Loops>> 或 C<L<perlsyn/"For Loops">> 都链接到 perlsyn 中以 "C<=head2 For Loops>" 开始的节。

要控制用于显示的文本，可以使用 "C<L<text|...>>"，例如

  • L<text|name>

将此文本链接到该手册页。例如，C<L<Perl Error Messages|perldiag>>

=item *

C<L<text|name/"sec">> 或 C<L<text|name/sec>>

将此文本链接到该手册页中的该节。例如，C<L<postfix "if"|perlsyn/"Statement Modifiers">>

=item *

C<L<text|/"sec">> 或 C<L<text|/sec>> 或 C<L<text|"sec">>

将此文本链接到本手册页中的该节。例如，C<L<the various attributes|/"Member Data">>

=back

或者你可以链接到一个网页

=over

=item *

C<L<scheme:...>>

链接到一个绝对 URL。例如，C<L<https://www.perl5.cn/>>。但请注意，出于多种原因，没有相应的 C<L<text|scheme:...>> 语法。

=back

=item C<E<escape>> -- 一个字符转义 X<E> X<< EZ<><> >> X<POD, formatting code, escape> X<escape>

非常类似于 HTML/XML 中的 C<&I<foo>;> "实体引用"

=over

=item *

C<<> -- 一个文字 <（小于）

=item *

C<>> -- 一个文字 >（大于）

=item *

C<E<verbar>> -- 一个文字 |（I<ver>tical I<bar>）

=item *

C<E<sol>> = 一个文字 / （I<sol>idus）

以上四个是可选的，除了在其他格式化代码中，特别是 C<L<...>>，以及在以大写字母开头的情况下。

=item *

C<E<htmlname>>

一些非数字 HTML 实体名称，例如 C<E<eacute>>，意思与 HTML 中的 C<é> 相同 - 也就是说，一个小写 e 带有锐音（/- 形）重音。

=item *

C<E<number>>

具有该数字的 ASCII/Latin-1/Unicode 字符。一个前导 "0x" 表示 I<number> 是十六进制，如 C<E<0x201E>>。一个前导 "0" 表示 I<number> 是八进制，如 C<E<075>>。否则，I<number> 被解释为十进制，如 C<E<181>>。

请注意，较旧的 Pod 格式化程序可能无法识别八进制或十六进制数字转义，并且许多格式化程序无法可靠地呈现超过 255 的字符。（一些格式化程序甚至可能不得不使用妥协的 Latin-1 字符渲染，例如将 C<E<eacute>> 渲染为简单的 "e"。）

=back

=item C<F<filename>> -- 用于文件名

X<F> X<< FZ<><> >> X<POD, formatting code, filename> X<filename>

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

=item C<S<text>> -- 文本包含不间断空格

X<S> X<< SZ<><> >> X<POD, formatting code, non-breaking space> 
X<non-breaking space>

这意味着 I<text> 中的单词不应该断开跨行。示例：S<C<S<$x ? $y : $z>>>。

=item C<X<topic name>> -- 一个索引条目 X<X> X<< XZ<><> >> X<POD, formatting code, index entry> X<index entry>

大多数格式化程序会忽略它，但有些可能会用它来构建索引。它始终呈现为空字符串。示例：C<X<absolutizing relative URLs>>

=item C<Z<>> -- 一个空（零效果）格式化代码 X<Z> X<< ZZ<><> >> X<POD, formatting code, null> X<null>

这很少使用。它是在某些情况下绕过使用 E<...> 代码的一种方法。例如，而不是 "C<N<3>"（对于 "N<3"），你可以写 "C<NZ<><3>"（"Z<>" 将 "N" 和 "<" 分开，因此它们不能被视为（虚构的）"N<...>" 代码的一部分。

=for comment

This was formerly explained as a "zero-width character".  But it in
most parser models, it parses to nothing at all, as opposed to parsing
as if it were a E<zwnj> or E<zwj>, which are REAL zero-width characters.
So "width" and "character" are exactly the wrong words.

=back

大多数情况下，你只需要一对尖括号来分隔格式化代码的开头和结尾。但是，有时你可能想要在格式化代码中放入一个真正的右尖括号（大于号，'>'）。这在使用格式化代码为代码片段提供不同的字体类型时尤其常见。与 Perl 中的所有事物一样，有多种方法可以做到这一点。一种方法是简单地使用 C<E> 代码转义结束括号

   C<$a <=> $b>

这将产生："C<$a <=> $b>"

一种更易读，可能更 "简单" 的方法是使用不需转义单个 ">" 的备用分隔符。对于从 perl5.5.660 开始成为标准的 Pod 格式化程序，可以使用双尖括号 ("<<" 和 ">>") I<如果且仅当在打开分隔符后紧跟空格，并且在关闭分隔符之前紧跟空格！>。例如，以下将起作用：X<POD, formatting code, escaping with multiple brackets>

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

事实上，你可以使用任意多个重复的尖括号，只要你在打开和关闭分隔符中使用相同数量的尖括号，并确保在打开分隔符的最后一个 '<' 后紧跟空格，并且在关闭分隔符的第一个 '>' 之前紧跟空格。（空格会被忽略。）因此，以下也会起作用：X<POD, formatting code, escaping with multiple brackets>

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

它们都与以下完全相同

   C<$a <=> $b>

作为另一个示例，这意味着如果你想要将这些代码片段放入 C<C>（代码）样式中

   open(X, ">>thing.dat") || die $!
   $foo->bar();

你可以像这样进行

   C<<< open(X, ">>thing.dat") || die $! >>>
   C<< $foo->bar(); >>

这可能比旧方法更易读

   C<open(X, ">>thing.dat") || die $!>
   C<$foo->bar();>

这目前受 pod2text (Pod::Text)、pod2man (Pod::Man) 以及任何其他使用 Pod::Parser 1.093 或更高版本，或 Pod::Tree 1.02 或更高版本的 pod2xxx 或 Pod::Xxxx 翻译器支持。

意图

[edit | edit source]

X<POD, intent of>

意图是使用简单，而不是表达能力强。段落看起来像段落（块格式），以便它们在视觉上突出，这样我就可以轻松地将它们通过 C<fmt> 运行来重新格式化（在我的 B<vi> 版本中是 F7，或者在我的 B<emacs> 版本中是 Esc Q）。我希望翻译器始终将 C<'> 和 C<`> 以及 C<"> 引号保留在原样，以逐字模式，这样我就可以将一个正在工作的程序吸入，向右移四个空格，并让它打印出来，呃，逐字。并且可能以等宽字体。

Pod 格式不一定足以编写一本书。Pod 只是为了成为 nroff、HTML、TeX 和其他标记语言（用于在线文档）的傻瓜式通用源代码。存在 B<pod2text>、B<pod2html>、B<pod2man>（这是针对 nroff(1) 和 troff(1) 的）、B<pod2latex> 和 B<pod2fm> 的翻译器。CPAN 中还有其他各种翻译器可用。


在 Perl 模块中嵌入 Pods

[edit | edit source]

你可以在你的 Perl 模块和脚本中嵌入 Pod 文档。从一个空行开始你的文档，在开头使用 "=head1" 命令，并在结尾使用 "=cut" 命令和一个空行。Perl 会忽略 Pod 文本。查看任何提供的库模块以获取示例。如果你要将你的 Pod 放在文件末尾，并且你正在使用 __END__ 或 __DATA__ 剪切标记，请确保在第一个 Pod 命令之前放置一个空行。

 __END__

 =head1 NAME

 Time::Local - efficiently compute time from local and GMT time

如果没有在 "=head1" 之前的那一行空行，许多翻译器将无法识别 "=head1" 是 Pod 块的开始。

编写 Pod 的提示

[edit | edit source]

=over

=item *

提供 B<podchecker> 命令来检查 Pod 语法是否有错误和警告。例如，它会检查 Pod 块中完全为空的行以及未知的命令和格式化代码。你仍然应该将你的文档通过一个或多个翻译器，并校对结果，或者打印结果并校对它。发现的一些问题可能是翻译器中的错误，你可能愿意或不愿意解决这些错误。

=item *

如果你更熟悉使用 HTML 而不是 Pod 编写，你可以尝试使用简单的 HTML 编写文档，并使用实验性的 L<Pod::HTML2Pod|Pod::HTML2Pod> 模块（在 CPAN 中可用）将其转换为 Pod，并查看生成的代码。CPAN 中的实验性 L<Pod::PXML|Pod::PXML> 模块也可能有用。

=item *

许多较旧的 Pod 翻译器要求每个 Pod 命令之前和之后的行（包括 "=cut"！）都是一个空行。如果像这样

# - - - - - - - - - - - -
=item $firecracker->boom()

This noisily detonates the firecracker object.
=cut
sub boom {
...

... 将使这些 Pod 翻译器完全无法识别 Pod 块。

相反，应该像这样

# - - - - - - - - - - - -
  • $firecracker->boom()
    • 这会发出噪音，引爆 firecracker 对象。
 
 sub boom {
 ...
  • 一些较旧的 Pod 翻译器要求段落（包括像 "=head2 Functions" 这样的命令段落）用 I<完全> 空行隔开。如果你有一个明显为空的行，但上面有一些空格，对于这些翻译器来说，这可能不算作分隔符，这会导致奇特的格式。
  • 较旧的翻译器可能会在 L<> 链接周围添加文字，因此 C<L<Foo::Bar>> 可能变成 "the Foo::Bar manpage"，例如。所以你不应该写类似 C<the L<foo> documentation> 的东西，如果你想要翻译后的文档读起来通顺 - 相反，写 C<the L<Foo::Bar|Foo::Bar> documentation> 或 C<L<the Foo::Bar documentation|Foo::Bar>>，来控制链接的显示方式。
  • 在逐字块中超过第 70 列可能会被一些格式化程序粗暴地换行。

另请参阅

[edit | edit source]

L<perlpodspec>、L<perlsyn/"PODs: Embedded Documentation">、L<perlnewmod>、L<perldoc>、L<pod2html>、L<pod2man>、L<podchecker>。

作者

[edit | edit source]

Larry Wall、Sean M. Burke

=cut

检索自 "https://wikibooks.cn/w/index.php?title=Markup_Languages/POD_and_Wikitext/Exmaple/Wikitext&oldid=4412982"
华夏公益教科书