关于文档

本文档集代表了正在努力记录 Raku 编程语言的目标是：全面; 使用方便; 易于导航; 对新手和经验丰富的 Raku 程序员都很有用。

该文档的 HTML 版本位于线上的 https://docs.raku.org。

该文档的官方来源位于 GitHub上的raku/doc。

本特定文档快速概述了在GitHub上的贡献中更详细描述的过程。本文档还简要介绍了编写 Raku Pod 文件，这些文件可以渲染为 HTML 和其他格式。

结构

所有文档都是用 Raku Pod 编写的，并保存在 doc/ 目录 doc/Language/ 和 doc/Type/ 子目录中。这些文件作为定义集合或“文档”处理，然后进行后处理并链接在一起。

从 Pod 生成 HTML

要从 Pod 文件生成 HTML，你需要：

  • 最新版本的 Rakudo Raku 编译器

  • Raku 模块Pod::To::HTML，Pod::To::BigPage 和 URI::Escape（可以通过zef安装）。

  • 可选：GraphViz，用于创建 Raku 类型之间关系的图形

  • 可选：Atom Highlights 和 language-raku，用于语法高亮显示

要在文件`html/`文件夹中生成文档，请运行：

  1. raku htmlify.p6

要从 Web 服务器托管文档，请安装 Perl 5 和 Mojolicious::Lite，然后运行：

  1. perl app.pl daemon

贡献

文档是用 Raku Pod 编写的。

有关 Raku Pod 的快速介绍，请参阅Raku Pod。

有关 Raku Pod 规范的完整详细信息，请参见概要26,文档。

添加定义

Documentables 可以使用 =headN Pod 指令来定义，其中 N 大于零（例如，=head1，=head2，…​）。

该指令之后的所有段落和块，直到同一级别的下一个指令，将被视为可记录的一部分。所以，在：

  1. =head2 My Definition
  3. Some paragraphs, followed by some code:
  5.     my Code $examples = "amazing";
  7. Mind === blown.
  9. =head3 Minor details about My Definition
  11. It's fantastic.
  13. =head2 And now, for something completely different
  15. …

可记录的 ` My Definition` 延伸到了 =head2 And now…。

可记录文件可能包含其他文件。例如，类可记录文件通常包含类实现的方法。

定义必须采用下列形式之一才能被识别为名为 document 文件的起点。首先是文档源代码：

  1. =item X<C<How to use the þ infix> | infix,þ> (This a special case, which
  2. is always considered a definition)
  4. =item C<The þ Infix>
  6. =item B<The C<þ> Infix>
  8. =item C<Infix þ>
  10. =item B<Infix C<þ>>
  12. =item C<trait is cached> (A special case for the L<trait|/language/functions#Traits> documentables)

然后是渲染页面上的结果：

  • How to use the þ infix （这是一种特殊情况，始终被视为定义）

  • The þ Infix

  • The þ Infix

  • Infix þ

  • Infix þ

  • trait is cached（trait文档的特例）

现在可以使用 HTML 文档中的搜索字段搜索这些项。

您可以使用粗体（B<>）或斜体（I<>）添加强调，可以使用或不使用代码格式（C<>）。由于当前的解析器限制，必须采取特殊步骤将X<>与其他格式代码一起使用; 例如：

  1. =item X<B<foo>|foo> a fancy subroutine

像这样渲染

  • foo a fancy subroutine

请注意，管道（“|”）之后的文本没有格式。另请注意，C<>保留空格并将文本视为逐字处理。