Pod6 是一种易于使用的标记语言。它可用于编写语言文档,记录程序和模块,以及用于其他类型的文档编写。
每个 Pod6 文档都必须以 =begin pod
开头,以 =end pod
结尾。这两个分隔符之间的所有内容都将被处理并用于生成文档。
=begin podA very simple Pod6 document=end pod
块结构§
Pod6 文档可能包含多个 Pod6 块。有四种方法来定义块:分隔、段落、缩写和声明符;前三个产生相同的结果,但第四个有所不同。你可以使用最适合你的特定文档任务的任何形式。
分隔块§
分隔块由 =begin
和 =end
标记分隔,这两个标记后面都跟着一个有效的 Raku 标识符,即块的 typename
。完全小写(例如:=begin head1
)或完全大写(例如:=begin SYNOPSIS
)的 typename 是保留的。=begin/=end 行的缩进必须相同才能创建有效的块;否则,将出现错误或意外结果。
=begin head1Top Level Heading=end head1
配置信息§
在 typename 之后,=begin
标记行的其余部分被视为块的配置信息。此信息以不同的方式用于不同类型的块,但始终使用 Raku 式选项对进行指定。也就是说,任何
值是... | 用...指定 | 或用...指定 | 或用...指定 |
---|---|---|---|
列表 | :key[$e1, $e2, ...] | :key($e1, $e2, ...) | :key<$e1 $e2 ...> |
哈希 | :key{$k1=>$v1, $k2=>$v2} | ||
布尔值(真) | :key | :key(True) | :key[True] |
布尔值(假) | :!key | :key(False) | :key[False] |
字符串 | :key<str> | :key('str') | :key("str") |
整数 | :key(42) | :key[42] | :42key |
数字 | :key(2.3) | :key[2.3] |
其中 '$e1, $e2, ...' 是类型为 String、Int、Number 或 Boolean 的列表元素。列表可以有混合的元素类型。请注意,单元素列表将转换为其元素的类型(String、Int、Number 或 Boolean)。另请注意,如果需要,可以使用大整数。
对于哈希,'$k1, $k2, ...' 是类型为 Str 的键,'$v1, $v2, ...' 是类型为 String、Int、Number 或 Boolean 的值。
字符串由单引号或双引号分隔。字符串之外的空白不重要。除非哈希键包含重要的空白,否则不需要用引号分隔。如果在尖括号内使用了任何空白,则在尖括号内输入的字符串将变为列表。
由于 Pod6 是一种规范语言,而不是一种编程语言,因此所有选项键和值都必须是常量。具体来说,选项值不能是闭包。有关各种 Raku 对符号的详细信息,请参阅 Synopsis 2。
配置部分可以在后续行中扩展。每行后续行都必须从第一个虚拟列中的 =
开始,这意味着它必须与 Pod6 块声明的 =
垂直对齐,并且它后面必须至少跟一个水平空白字符。
例如
=for head1 :a-first-line-key<firstvalue> :another-first-line-key<xyz>= :a-second-line-key(42)= :a-third-line-key<third>Content for the header block
其中一些选项具有预定值;具体来说,:numbered
用于指定块项或行将被编号。
=for defn :numberedWeNeedNumberssay [0].config<numbered>; # OUTPUT: «True»
此配置选项可以用井号缩写
=para #WeNeedNumberssay [0].config<numbered>; # OUTPUT: «1»
段落块§
段落块以 =for
标记开始,以下一个 Pod6 指令或第一个空白行结束。=for
标记后面是块的 typename
,还可以选择任何配置数据,如上面描述的分隔块中的配置数据。
=for head1Top Level Heading
缩写块§
缩写块以 '='
符号开始,紧跟块的 typename
。所有后续数据都是块内容的一部分,因此不能为缩写块指定配置数据。该块在下一个 Pod6 指令或第一个空白行处结束。
=head1 Top level heading
声明块§
声明块与其他块不同,因为它没有特定的类型,而是附加到某些源代码上。
声明块由特殊注释引入:#|
或 #=
,其后必须紧跟空格或左花括号。如果后面跟着空格,则块由行尾终止;如果后面跟着一个或多个左花括号,则块由匹配的右花括号序列终止。
以 #|
开头的块附加到它们后面的代码,以 #=
开头的块附加到它们前面的代码。
由于声明块附加到源代码上,因此它们可用于记录类、角色、子例程,以及一般任何语句或块。
WHY
方法可用于这些类、角色、子例程等,以返回附加的 Pod6 值。
sub duel(Magician , Magician )say Magician.WHY; # OUTPUT: «Base class for magicians»say .WHY.leading; # OUTPUT: «Fight mechanics»say .WHY.trailing; # OUTPUT: «Magicians only, no mortals.»
这些声明可以扩展多个块
* Numbers turn into strings* Regexes operate on said strings* C<with> topicalizes and places result into)sub search-in-seq( Int , Int )* topic* decont operator»
通过使用成对的括号结构,如 ()
或 «»
,注释可以扩展多行。此格式通常不会通过 raku --doc
转换为多行显示。但是,自 Rakudo 2020.01 版本以来,有一种方法可以实现这一点,仅适用于前导声明块,即定义一个特殊环境变量:RAKUDO_POD_DECL_BLOCK_USER_FORMAT
。设置该值后,使用 --doc
选项运行 raku
应以其原始格式显示前导声明块中的文本。请参阅文件 S26-documentation/block-leading-user-format.t 中的功能测试。
区块类型§
Pod6 提供了各种标准区块类型。
标题§
使用 =headN
定义标题,其中 N 大于零(例如,=head1
、=head2
、…)。
=head1 A top level heading=head2 A second level heading=head3 A third level heading
普通段落§
普通段落由文本组成,该文本将格式化为当前嵌套级别的文档,其中空格被压缩,行被填充,并且应用任何特殊内联标记。
普通段落由一行或多行连续文本组成,每行都以非空格字符开头。段落由第一个空行或块指令终止。
例如
=head1 This is a heading blockThis is an ordinary paragraph.Its text will be squeezed andshort lines filled. It is terminated bythe first blank line.This is another ordinary paragraph.Its text will also be squeezed andshort lines filled. It is terminated bythe trailing directive on the next line.=head2 This is another heading blockThis is yet another ordinary paragraph,at the first virtual column set by theprevious directive
普通段落不需要显式标记或分隔符。
或者,还有一个显式的 =para
标记,可用于显式标记段落。
=paraThis is an ordinary paragraph.Its text will be squeezed andshort lines filled.
此外,可以使用较长的 =begin para
和 =end para
形式。
例如
=begin paraThis is an ordinary paragraph.Its text will be squeezed andshort lines filled.This is still part of the same paragraph,which continues until an...=end para
如上一个示例所示,在分隔的 =begin para
和 =end para
块中,任何空行都会被保留。
代码块§
代码块用于指定源代码,该源代码应在不重新对齐、不压缩空格且不识别任何内联格式化代码的情况下呈现。通常,这些块用于显示代码、标记或其他文本规范的示例,并使用固定宽度的字体呈现。
代码块可以隐式指定为一行或多行文本,每行都以空格字符开头。隐式代码块随后由空行终止。
例如
This ordinary paragraph introduces a code block:my = 'John Doe';say ;
还可以通过将代码块括在 =begin code
和 =end code
中来显式定义代码块
=begin codemy $name = 'John Doe';say $name;=end code
I/O 块§
Pod6 提供了用于指定程序输入和输出的块。
=input
块用于指定预格式化的键盘输入,该输入应在不重新对齐或压缩空格的情况下呈现。
=output
块用于指定预格式化的终端或文件输出,该输出也应在不重新对齐或压缩空格的情况下呈现。
列表§
无序列表§
Pod6 中的列表指定为一系列 =item
块。
例如
The three suspects are:=item Happy=item Sleepy=item Grumpy
三个嫌疑人分别是
开心
困倦
暴躁
定义列表§
定义术语或命令的列表使用 =defn
,相当于 HTML 中的 DL
列表
=defn HappyWhen you're not blue.=defn BlueWhen you're not happy.
将呈现为
- 开心
- 当你心情不好时。
- 不好
- 当你心情不开心时。
多级列表§
列表可以是多级的,使用 =item1
、=item2
、=item3
等块指定每个级别的项目。
请注意,=item
只是 =item1
的缩写。
例如
=item1 Animal=item2 Vertebrate=item2 Invertebrate=item1 Phase=item2 Solid=item2 Liquid=item2 Gas
动物
脊椎动物
无脊椎动物
相态
固态
液态
气态
多段列表§
使用 =item
块的分隔形式(=begin item
和 =end item
),我们可以指定包含多个段落的项目。
例如
Let's consider two common proverbs:=begin itemThis is a common myth and an unconscionable slur on the Spanishpeople, the majority of whom are extremely attractive.=end item=begin itemIn deciding whether to become an early riser, it is worthconsidering whether you would actually enjoy annelidsfor breakfast.=end itemAs you can see, folk wisdom is often of dubious value.
呈现为
让我们考虑两句常见的谚语
西班牙的雨主要下在平原上。
这是一个常见的误传,是对西班牙人民的无耻诽谤,而大多数西班牙人民都极具吸引力。
早起的鸟儿有虫吃。
在决定是否成为早起的人时,值得考虑你是否真的喜欢在早餐时吃环节动物。
正如你所看到的,民间智慧往往价值可疑。
表格§
查看此页面以获取与 表格 相关的文档
Pod6 注释§
Pod6 注释是 Pod6 渲染器忽略的注释。
注释对于元文档(记录文档)很有用。单行注释使用 =comment
标记
=comment Add more here about the algorithm
对于多行注释,请使用分隔的 comment
块
=begin commentThis comment ismulti-line.=end comment
您还可以使用隐式块
=commentThis comment ismulti-line.B<this> is visible
语义块§
所有大写块类型名称都保留用于指定标准文档、发布、源组件或元信息。
=NAME=AUTHOR=VERSION=TITLE=SUBTITLE
格式化代码§
格式化代码提供了一种向一段文本添加内联标记的方法。
所有 Pod6 格式化代码都由一个大写字母组成,后跟一组单角括号或双角括号;可以使用 Unicode 双角括号。
格式化代码可以嵌套其他格式化代码。
以下代码可用:B、C、E、I、K、L、N、P、R、T、U、V、X 和 Z。
粗体§
要以粗体格式化文本,请将其括在 B< >
中
Raku is B<awesome>
Raku 很棒
斜体§
要以斜体格式化文本,请将其括在 I< >
中
Raku is I<awesome>
Raku 很棒
下划线§
要给文本加下划线,请将其括在 U< >
中
Raku is U<awesome>
代码§
要将文本标记为代码并按字面意思对待,请将其括在 C< >
中
C<my $var = 1; say $var;>
my $var = 1; say $var;
链接§
要创建链接,请将其括在 L< >
中
Raku homepage L<https://raku.perl5.cn>
Raku 主页 https://raku.perl5.cn
可以使用一个可选的竖线来分隔标签和目标。
L<Raku homepage|https://raku.perl5.cn>
相对 URL 相对于项目的根目录,因此,例如,在此存储库中,我们可以链接到 language
文件夹中的另一个页面。此处我们使用一个可选片段来链接到一个标题
L<Structure|/language/about#Structure>
还可以指定一个链接到当前文档中的片段
L<Comments|#Comments>
最后,除了 URL 样式的链接(例如 L<Some reference|path/to/filename>
),模块样式的符号(L<Some reference|path::to::filename>
)也可以使用。
放置链接§
此代码未在 Pod::To::HTML
中实现,但在 Pod::To::BigPage
中部分实现了。
第二种链接——P<>
或放置链接——以相反的方向工作。它不会将焦点引导至另一个文档,而是允许你将另一个文档的内容同化到你的文档中。
换句话说,P<>
格式化代码获取一个 URI,并在可能的情况下将相应文档的内容内联插入到代码本身的位置。
P<>
代码非常适合将文档集的标准元素分解为可重用组件,然后直接合并到多个文档中。例如
=COPYRIGHTP<file:/shared/docs/std_copyright.pod>=DISCLAIMERP<http://www.MegaGigaTeraPetaCorp.com/std/disclaimer.txt>
可能会产生
版权
本文件受版权保护 (c) MegaGigaTeraPetaCorp,2006。保留所有权利。
免责声明
绝对不暗示任何保证。甚至没有任何保证。我们向你出售此软件,但没有暗示它有用或可用。至于正确性的保证……别逗了!在未来的某个时候,我们可能会屈尊向你出售升级,声称可以解决应用程序的许多缺陷,但也不做任何承诺。我们的律师比你的员工总数还多,所以不要想告我们。祝你愉快。
如果渲染器找不到或无法访问放置链接的外部数据源,它必须发出警告,并以某种形式直接渲染 URI,可能是作为外链。例如
版权
参见:file:/shared/docs/std_copyright.pod
免责声明
你可以在放置链接中使用以下任何 URI 形式(参见 链接)。
注释§
注释是永远不会渲染的文本。
要创建注释,请将其括在 Z< >
中
Raku is awesome Z<Of course it is!>
Raku 很棒
注释§
注释以脚注的形式呈现。
要创建注释,请将其括在 N< >
中
Raku is multi-paradigmatic N<Supporting Procedural, Object Oriented, and Functional programming>
键盘输入§
要将文本标记为键盘输入,请将其括在 K< >
中
Enter your name K<John Doe>
可替换§
R<>
格式化代码指定包含的文本是可替换项、占位符或元语法变量。它用于指示语法或规范的组件,该组件最终应被实际值替换。例如
The basic C<ln> command is: C<ln> R<source_file> R<target_file>
或
Then enter your details at the prompt:=for inputName:ID:Pass:
终端输出§
要将文本标记为终端输出,请将其括在 T< >
中
Hello T<John Doe>
Unicode§
要在 Pod6 文档中包含 Unicode 代码点或 HTML5 字符引用,请将其括在 E< >
中
E< >
可以括住一个数字,该数字被视为所需代码点的十进制 Unicode 值。它还可以使用 Raku 的显式基于数字的表示法括住显式的二进制、八进制、十进制或十六进制数字。
它还可以括住一个 Unicode 代码点名称。
Raku makes considerable use of the E<laquo> and E<raquo> characters.Raku makes considerable use of the E<171> and E<187> characters.Raku makes considerable use of the E<0b10101011> and E<0b10111011> characters.Raku makes considerable use of the E<0o253> and E<0o273> characters.Raku makes considerable use of the E<0d171> and E<0d187> characters.Raku makes considerable use of the E<0xAB> and E<0xBB> characters.Raku makes considerable use of the E<LEFT-POINTING DOUBLE ANGLE QUOTATION MARK> and E<RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK> characters.
Raku 大量使用了 « 和 » 字符。
您还可以在 ;
分隔的列表中提供多个代码点,例如
Raku makes considerable use of E<171;nbsp;raquo>.
Raku 大量使用了 « »。
逐字文本§
此代码未由 Pod::To::HTML
实现,但由 Pod::To::BigPage
实现。
V<>
格式化代码将其整个内容视为 verbatim,忽略其中的每个明显的格式化代码。例如
The B<V<V<>>> formatting code disarms other codessuch as V<I<>, C<>, B<>, and M<>.>
但是,请注意,V<>
代码只会更改其内容的解析方式,而不是其呈现方式。也就是说,内容仍然像纯文本一样换行和格式化,并且围绕 V<>
代码的任何格式化代码的效果仍会应用于其内容。例如,上一个示例呈现为
V<> 格式化代码解除其他代码的武装,例如 I<>、C<>、B<> 和 M<>。
索引术语§
括在 X<>
代码中的任何内容都是 索引条目。代码的内容既格式化为文档,又用作(不区分大小写的)索引条目
An X<array> is an ordered list of scalars indexed by number,starting with 0. A X<hash> is an unordered collection of scalarvalues indexed by their associated string key.
您可以通过用竖线分隔两个部分来指定索引条目,其中索引文本和索引条目不同
An X<array|arrays> is an ordered list of scalars indexed by number,starting with 0. A X<hash|hashes> is an unordered collection ofscalar values indexed by their associated string key.
在两部分形式中,索引条目位于竖线之后,并且区分大小写。
您可以通过用逗号分隔索引级别来指定分层的索引条目
An X<array|arrays, definition of> is an ordered list of scalarsindexed by number, starting with 0. A X<hash|hashes, definition of>is an unordered collection of scalar values indexed by theirassociated string key.
您可以通过用分号分隔条目来为单个索引文本指定两个或更多条目
A X<hash|hashes, definition of; associative arrays>is an unordered collection of scalar values indexed by theirassociated string key.
索引文本可以为空,从而创建一个“零宽度”索引条目
X<|puns, deliberate>This is called the "Orcish Maneuver"because you "OR" the "cache".
呈现 Pod§
HTML§
要从 Pod 生成 HTML,您需要 Pod::To::HTML 模块。
如果尚未安装,请通过运行以下命令进行安装:zef install Pod::To::HTML
安装后,在终端中运行以下命令
raku --doc=HTML input.rakudoc > output.html
Markdown§
要从 Pod 生成 Markdown,您需要 Pod::To::Markdown 模块。
如果尚未安装,请通过运行以下命令进行安装:zef install Pod::To::Markdown
安装后,在终端中运行以下命令
raku --doc=Markdown input.rakudoc > output.md
文本§
要从 Pod 生成文本,您可以使用默认的 Pod::To::Text
模块。
使用终端,运行以下命令
raku --doc=Text input.rakudoc > output.txt
您可以省略 =Text
部分
raku --doc input.rakudoc > output.txt
您甚至可以在程序中直接嵌入 Pod6,并使用多 MAIN 子例程向程序添加传统的 Unix 命令行 "--man" 选项,如下所示
multi MAIN(Bool :)
现在 myprogram --man
将输出以手册页形式呈现的 Pod6。
访问 Pod§
为了从 Raku 程序中访问 Pod6 文档,必须使用特殊 =
twigil,如 变量部分 中所述。
=
twigil 提供对 Pod6 结构的内省,提供一个 Pod::Block
树根,从中可以访问 Pod6 文档的整个结构。
例如,以下代码片段内省其自己的 Pod6 文档
=begin pod=head1 This is a head1 titleThis is a paragraph.=head2 SubsectionHere some text for the subsection.=end podfor ->
生成以下输出
Pod::Heading.new(level => 1, config => , contents => [Pod::Block::Para.new(config => , contents => ["This is a head1 title"])]);Pod::Block::Para.new(config => , contents => ["This is a paragraph."]);Pod::Heading.new(level => 2, config => , contents => [Pod::Block::Para.new(config => , contents => ["Subsection"])]);Pod::Block::Para.new(config => , contents => ["Here some text for the subsection."]);