作者
Raimo Niskanen <raimo(at)erlang(dot)org>
状态
活跃
类型
流程
创建于
2010年3月31日
替换
2, 3

EEP 33: Markdown EEP 示例模板 #

摘要 #

此 EEP 提供了一个用于创建您自己的 Markdown EEP 的样板或示例模板。结合 EEP 1 中的内容指南,这应该能让您轻松地使您自己的 EEP 符合以下概述的格式。

注意:如果您正在通过 Web 阅读此 EEP,您应该首先获取此 EEP 的纯文本 源代码,以便完成以下步骤。请勿使用 HTML 文件作为您的模板!

本文档基于 PEP 9

理由 #

EEP 提交的形式多种多样,并非所有形式都遵守以下规定的格式指南。使用此模板,并结合 EEP 1 中的内容指南,以确保您的 EEP 提交不会因格式问题而被自动拒绝。

如何使用此模板 #

要使用此模板,您必须首先确定您的 EEP 将是流程型 EEP 还是标准跟踪型 EEP。大多数 EEP 都是标准跟踪型,因为它们为 Erlang 语言或标准库提出了新功能。如有疑问,请阅读 EEP 1 以了解详细信息,或联系 EEP 编辑器 [email protected]

一旦您确定了您的 EEP 将是哪种类型,请按照以下说明进行操作。

  • 复制 此文件(.md 文件,而不是 HTML!),并执行以下编辑。

  • 将“EEP 33: “标题替换为“EEP XXX: “和您的 EEP 的标题,即在您获得分配的 EEP 编号之前使用 ‘XXX’。

  • 更改作者标题以包含您的姓名,以及可选的您的电子邮件地址。请务必仔细遵循格式:您的姓名必须首先出现,并且不能包含在括号中。您的电子邮件地址可以第二个出现(也可以省略),如果出现,则必须出现在尖括号中。建议混淆您的电子邮件地址。作者可以是换行符分隔的(遵循 RFC 2822 行延续约定)列表,其中第一位作者是 EEP 的所有者。

  • 如果有一个用于讨论您的新功能的邮件列表,请在作者标题之后添加“Discussions-To”标题。如果使用的邮件列表是 [email protected],或者讨论应该直接发送给您,则不应添加“Discussions-To”标题。大多数流程 EEP 没有“Discussions-To”标题。

  • 将状态标题更改为“草案”。

  • 对于标准跟踪 EEP,将类型标题更改为“标准跟踪”。

  • 对于流程 EEP,将类型标题更改为“流程”。

  • 对于标准跟踪 EEP,如果您的功能取决于其他正在开发中的 EEP 的接受,请在类型标题之后添加“Requires”标题。该值应该是您的 EEP 所依赖的 EEP 的编号。如果您的依赖功能在最终 EEP 中描述,则不要添加此标题。

  • 将“创建于”标题更改为今天的日期。请务必仔细遵循格式:它必须是 dd-mmm-yyyy 格式,其中 mmm 是 3 个英文字母的月份缩写,例如 Jan、Feb、Mar、Apr、May、Jun、Jul、Aug、Sep、Oct、Nov、Dec 中的一个。

  • 对于标准跟踪 EEP,在“创建于”标题之后,添加一个“Erlang-Version”标题,并将值设置为 Erlang 的下一个计划版本,即您的新功能有望首次出现的版本。因此,如果 Erlang/OTP 的最后一个版本是 R13B-3,并且您希望将您的新功能添加到 28.0,则将版本标题设置为

      Erlang-Version: OTP-28.0
    
  • 暂时不要管“Post-History”;每次将您的 EEP 发布到 [email protected] 时,您都会在此标题中添加日期。例如,如果您在 2009 年 8 月 14 日和 2009 年 9 月 3 日将您的 EEP 发布到列表,则“Post-History”标题将如下所示

      Post-History: 14-Aug-2009, 03-Sept-2009
    

    您必须手动添加新日期并将其签入。如果您没有签入权限,请将您的更改发送给 EEP 编辑器。

  • 如果您的 EEP 取代了较早的 EEP,请添加“Replaces”标题。此标题的值是您的新 EEP 正在替换的 EEP 的编号。仅当较旧的 EEP 处于“最终”形式时才添加此标题,即已被接受、最终或拒绝。如果您提交的是一个竞争的想法,则您不是在替换较旧的开放 EEP。

  • 现在,编写您的摘要、理由以及 EEP 的其他内容,并将所有这些胡言乱语替换为您自己的文本。请务必遵守以下格式指南,特别是关于禁止制表符和缩进要求。

  • 更新您的“参考”和“版权”部分。通常,您会将您的 EEP 置于 CC0-1.0-Universal 许可下,在这种情况下,只需保留“版权”部分即可。或者,您可以使用 开放出版许可证知识共享署名 3.0 许可证,但仍然强烈建议使用 CC0-1.0-Universal。

  • 请保留此文件末尾的 Emacs 小标记,使用它可以获得良好的模式和字符编码,并且可以例如使用 fill-paragraph(默认 [ESC] q)修复段落。

  • 将您的 EEP 提交发送给 EEP 编辑器 [email protected]

Markdown EEP 格式要求 #

有关常规格式语法,请参阅 Markdown 语法。在此基础上,Markdown EEP 有以下要求

EEP 的前几行用于 EEP 索引生成器解析和 Markdown 预处理,因此它必须看起来像 此文件的前 10 行,具有特定的水平规则和标题 2 标题样式。您的 EEP 可能有更多或更少的标题行。

EEP 顶级标题是 H1 类型,即 ==== 下划线。每个单词的首字母必须像书名一样大写。

首字母缩略词应全部大写。

节内的代码示例应缩进 4 个空格。

您必须在所有 H1 标题之前使用三个空行,在所有 H2 标题之前使用两个空行。

您必须遵守 Emacs 的约定,即在每个句子的末尾添加两个空格。您应该将段落填充到 70 列,但在任何情况下,您的行都不应超过 79 列。如果您的代码示例溢出 79 列,则应重写它们。

制表符永远不应出现在文档中。

当在 EEP 的正文中引用外部网页时,您应该在文本中包含该页面的标题,并在脚注中引用 URL。不要在 EEP 的正文中包含 URL。例如

Refer to the [Erlang Language web site][1] for more details.

:

[1]: https://erlang.ac.cn
    "Erlang Programming Language"

脚注参考定义应放置在文档的倒数第二位,紧接在“版权”部分和 Emacs 魔术之前。请注意,这些引用在 Markdown 生成的 HTML 中是不可见的。

当引用另一个 EEP 时,请使用隐式链接名称脚注(例如 [EEP 1][])在正文中包含 EEP 编号。标题可以可选地出现。脚注正文应包含 EEP 的标题和作者,并应引用其 URL。

注意:URL 相对于当前 URL,构建工具会将其修复为指向 .html 文件。

示例

Refer to [EEP 1][] for more information about EEP style

:

[EEP 1]: eep-0001.md
    "EEP 1, EEP Purpose and Guidelines, Gustafsson"

URL 中的 EEP 编号必须从左侧填充零,使其宽度恰好为 4 个字符,但文本中的 EEP 编号永远不会填充。

版权 #

本文档置于公共领域或 CC0-1.0-Universal 许可之下,以较宽松者为准。