GLEP 2：示例 ReStructuredText GLEP 模板

作者	Grant Goodyear <g2boojum@gentoo.org>，Chris Reffett <creffett@gentoo.org>，Ulrich Müller <ulm@gentoo.org>
类型	信息性
状态	活跃
版本	4.1
创建日期	2003-05-31
最后修改日期	2023-02-22
发布历史	2003-06-02, 2013-12-17, 2017-09-17, 2019-11-24
GLEP 源代码	glep-0002.rst

内容

致谢

此 GLEP 的文本在很大程度上借鉴了 Python 的 [1] PEP-0012 [2]，由 David Goodger 和 Barry A. Warsaw 编写。

摘要

此 GLEP 提供了一个用于创建您自己的 ReStructuredText GLEP 的样板或模板。结合 GLEP 1 [3] 中的内容指南，这将使您能够轻松地将您自己的 GLEP 符合下面概述的格式。

注意：如果您通过网页阅读此 GLEP，您应该首先获取此 GLEP 的文本（ReStructuredText）源代码，以便完成以下步骤。不要使用 HTML 文件作为您的模板！

要获取此（或任何）GLEP 的源代码，请查看 HTML 页面顶部，并点击标题为“GLEP 源代码”的链接。

动机

在这里提供充分的动机。在本例中，我们需要向人们提供必要的信息，以使他们能够以正确的方式提交 GLEP。

原理

GLEP 提交的格式多种多样，并非所有都符合下面列出的格式指南。使用此模板，结合下面的格式指南，确保您的 GLEP 提交不会因为格式问题而被自动拒绝。

使用 ReStructuredText 允许 GLEP 作者获得更多功能和表现力，同时保持源代码的可读性。处理后的 HTML 格式使读者能够访问这些功能：实时超链接、格式化文本、表格、图像和自动目录，以及其他优势。

向后兼容性

对于此 GLEP 来说不是问题。即使只是为了说明没有向后兼容性问题，也应该包含此部分。

如何使用此模板

要使用此模板，您必须首先确定您的 GLEP 是信息性 GLEP 还是标准化 GLEP。大多数 GLEP 都是标准化 GLEP，因为它们为 Gentoo Linux 的某些方面提出了新功能。如有疑问，请阅读 GLEP 1 以获取详细信息，或联系 GLEP 编辑 <glep@gentoo.org>。

确定您的 GLEP 的类型后，请按照以下说明操作。

复制此文件（.rst文件，不是 HTML！）并执行以下编辑。
将“GLEP：2”标题替换为“GLEP：9999”，因为您还没有 GLEP 编号分配。
将标题标题更改为您的 GLEP 的标题。
将作者标题更改为包含您的姓名，以及可选的电子邮件地址。请务必仔细遵循格式：您的姓名必须放在首位，并且不能包含在括号中。您的电子邮件地址可以放在第二位（也可以省略），如果出现，则必须放在尖括号中。
对于标准化 GLEP，将类型标题更改为“标准化”。
对于信息性 GLEP，将类型标题更改为“信息性”。
将状态标题更改为“草稿”。
将版本重置为“1”。
将创建日期和最后修改日期标题更改为今天的日期。请务必仔细遵循格式：它必须符合 ISO 8601yyyy-mm-dd格式，日期以 UTC（协调世界时）表示。
暂时将发布历史重置为空；每次将 GLEP 发布到 gentoo-dev@lists.gentoo.org 时，您都会在此标题中添加日期。如果您在 2003 年 8 月 14 日和 2003 年 9 月 3 日将 GLEP 发布到列表中，发布历史标题将如下所示
```
Post-History: 2003-08-14, 2003-09-03
```
您必须手动添加新日期（同样，以 UTC 表示）并签入。如果您没有签入权限，请将您的更改发送给 GLEP 编辑。
对于标准化 GLEP，如果您的功能依赖于其他正在开发的 GLEP 的接受，请在类型标题后添加一个“依赖项”标题。该值应该是您的 GLEP 依赖的 GLEP 的编号。如果您的依赖功能在最终 GLEP 中描述，请勿添加此标题。
如果您的 GLEP 弃用了一个或多个之前的 GLEP，请添加一个“替换”标题。此标题的值是您的新 GLEP 替换的 GLEP 的编号，用逗号分隔。仅当旧 GLEP 处于“最终”形式（即已接受、最终或拒绝）时，才添加此标题。如果您提交的是竞争性想法，则不算是替换了旧的开放 GLEP。
现在编写您的摘要、原理以及 GLEP 的其他内容，用您自己的文本替换所有这些内容。请务必遵守下面的格式指南，特别是关于缩进要求的说明。
更新您的参考文献部分。您应该保留版权部分，因为所有新的 GLEP 都要根据 Creative Commons Attribution-ShareAlike 4.0 International License (CC-BY-SA-4.0) 许可。
将您的 GLEP 提交发送给 GLEP 编辑，地址是 glep@gentoo.org。

ReStructuredText GLEP 格式要求

以下是 ReStructuredText 语法的 GLEP 特定摘要。为了简单和简洁，省略了很多细节。有关更多详细信息，请参阅下面的资源。整个示例中都使用了文字块（其中不进行任何标记处理）来说明纯文本标记。

通用

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

章节标题

GLEP 标题必须从第零列开始，每个单词的首字母必须大写，就像书名一样。首字母缩略词必须全部大写。章节标题必须用下划线装饰，用一个重复的标点符号，从第零列开始，并且必须至少延伸到标题文本的右边缘（至少 4 个字符）。一级章节标题用“=”（等号）下划线，二级章节标题用“-”（连字符）下划线，三级章节标题用“'”（单引号或撇号）下划线。例如

First-Level Title
=================

Second-Level Title
------------------

Third-Level Title
'''''''''''''''''

如果您的 GLEP 中有超过三级的章节，您可以为第一级和第二级插入带下划线/上划线装饰的标题，如下所示

============================
First-Level Title (optional)
============================

-----------------------------
Second-Level Title (optional)
-----------------------------

Third-Level Title
=================

Fourth-Level Title
------------------

Fifth-Level Title
'''''''''''''''''

您的 GLEP 中不应该超过五级章节。如果有，您应该考虑重新编写它。

您必须在章节主体最后一行的最后一行与下一个章节标题之间使用两个空行。如果小节标题紧随章节标题，则它们之间使用一个空行就足够了。

每个章节的主体通常不缩进，尽管某些结构确实使用缩进，如下所述。空行用于分隔结构。

段落

段落是左对齐的文本块，用空行分隔。段落不缩进，除非它们是缩进结构的一部分（例如块引用或列表项）。

内联标记

段落和其他文本块中的部分文本可以进行格式化。例如

Text may be marked as *emphasized* (single asterisk markup,
typically shown in italics) or **strongly emphasized** (double
asterisks, typically boldface).  ``Inline literals`` (using double
backquotes) are typically rendered in a monospaced typeface.  No
further markup recognition is done within the double backquotes,
so they're safe for any kind of code snippets.

块引用

块引用由缩进的主体元素组成。例如

This is a paragraph.

    This is a block quote.

    A block quote may contain many paragraphs.

块引用用于引用其他来源中的扩展段落。块引用可以嵌套在其他主体元素中。每个缩进级别使用 4 个空格的制表符。

文字块

文字块用于代码示例或预格式化的 ASCII 艺术。要指示文字块，请在缩进的文本块之前加上“::”（两个冒号）。文字块一直持续到缩进结束。用制表符缩进文本块。例如

This is a typical paragraph.  A literal block follows.

::

    for a in [5,4,3,2,1]:   # this is program code, shown as-is
        print a
    print "it's..."
    # a literal block continues until the indentation ends

只包含“::”的段落将从输出中完全删除；不会保留任何空段落。“::”在任何段落的末尾也会被识别。如果紧接在前面的是空格，则两个冒号都将从输出中删除。当文本紧接在“::”之前时，一个冒号将从输出中删除，只留下一个冒号可见（即，“::”将被替换为“:”。例如，这里将保留一个可见的冒号

Paragraph::

    Literal block

列表

项目符号列表项以“-”、“*”或“+”（连字符、星号或加号）开头，后面跟着空格和列表项主体。列表项主体必须左对齐，并且相对于项目符号缩进；项目符号后面的文本决定了缩进。例如

This paragraph is followed by a list.

* This is the first bullet list item.  The blank line above the
  first list item is required; blank lines between list items
  (such as below this paragraph) are optional.

* This is the first paragraph in the second item in the list.

  This is the second paragraph in the second item in the list.
  The blank line above this paragraph is required.  The left edge
  of this paragraph lines up with the paragraph above, both
  indented relative to the bullet.

  - This is a sublist.  The bullet lines up with the left edge of
    the text blocks above.  A sublist is a new list so requires a
    blank line above and below.

* This is the third item of the main list.

This paragraph is not part of the list.

枚举（编号）列表项类似，但使用枚举器而不是项目符号。枚举器是数字（1、2、3、…）、字母（A、B、C、…；大写或小写）或罗马数字（i、ii、iii、iv、…；大写或小写），格式化为带句点后缀（“1.”、“2.”）、括号（“(1)”、“(2)”）或右括号后缀（“1)”、“2)”）。例如

1. As with bullet list items, the left edge of paragraphs must
   align.

2. Each list item may contain multiple paragraphs, sublists, etc.

   This is the second paragraph of the second list item.

   a) Enumerated lists may be nested.
   b) Blank lines may be omitted between list items.

定义列表是这样写的

what
    Definition lists associate a term with a definition.

how
    The term is a one-line phrase, and the definition is one
    or more paragraphs or body elements, indented relative to
    the term.

表格

简单表格简单且紧凑

=====  =====  =======
  A      B    A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

表格中至少要有两列（以区别于节标题）。跨列使用连字符下划线（“Inputs”跨越前两列）

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

第一列单元格中的文本开始新行。第一列中没有文本表示续行；其余单元格可能包含多行。例如

=====  =========================
col 1  col 2
=====  =========================
1      Second column of row 1.
2      Second column of row 2.
       Second line of paragraph.
3      - Second column of row 3.

       - Second item in bullet
         list (row 3, column 2).
=====  =========================

超链接

在 GLEP 的正文中引用外部网页时，应在文本中包含页面的标题，以及内联超链接引用到 URL 或脚注引用（参见下面的脚注）。不要在 GLEP 的正文文本中包含 URL。

超链接引用使用反引号和尾部下划线来标记引用文本；如果引用文本是单个词，则反引号是可选的。例如

In this paragraph, we refer to the `Python web site`_.

显式目标提供 URL。将目标放在 GLEP 末尾的“References”部分，或紧接在引用之后。超链接目标以两个句点和一个空格（“显式标记开始”）开头，后跟一个前导下划线、引用文本、冒号和 URL（绝对或相对）

.. _Python web site: https://pythonlang.cn/

引用文本和目标文本必须匹配（尽管匹配不区分大小写并忽略空白符的差异）。请注意，下划线位于引用文本的后面，但位于目标文本的前面。如果你将下划线视为指向右边的箭头，它指向远离引用并指向目标。

相同的机制可用于内部引用。每个唯一的节标题都隐式地定义了一个内部超链接目标。我们可以这样链接到“Abstract”部分

Here is a hyperlink reference to the `Abstract`_ section.  The
backquotes are optional since the reference text is a single word;
we can also just write: Abstract_.

包含来自外部目标的 URL 的脚注将在 GLEP 的“References”部分的末尾自动生成，以及将引用文本链接到脚注的脚注引用。

脚注

脚注引用由左方括号、数字、右方括号和尾部下划线组成

This sentence ends with a footnote reference [1]_.

脚注引用之前必须有空格。在脚注引用和前面的词之间留一个空格。

引用另一个 GLEP 时，在正文文本中包含 GLEP 编号，例如“GLEP 1”。标题可以可选地出现。在标题之后添加脚注引用。例如

Refer to GLEP 1 [2]_ for more information.

添加一个脚注，其中包含 GLEP 的标题和作者。它可以选择在单独的行上包含显式 URL，但仅在“References”部分中包含。脚注以“..”开头（显式标记开始），后跟脚注标记（无下划线），再后跟脚注主体。例如

References
==========

.. [2] GLEP 1, "GLEP Purpose and Guidelines", Goodyear, Warsaw, Hylton
   (https://gentoolinux.cn/glep/glep-0001.html)

如果你决定为 GLEP 提供显式 URL，请使用此 URL 模板

https://gentoolinux.cn/glep/glep-xxxx.html

URL 中的 GLEP 编号必须从左侧用零填充，以确保正好为 4 个字符宽，但是文本中的 GLEP 编号从不填充。

在开发 GLEP 的过程中，你可能需要添加、删除和重新排列脚注引用，这可能会导致引用不匹配、脚注过时以及混淆。自动编号的脚注提供了更大的自由度。使用 "#word" 格式的标签而不是数字，其中“word”是助记符，包含字母数字以及内部连字符、下划线和句点（不允许使用空格或其他字符）。例如

Refer to GLEP 1 [#GLEP-1]_ for more information.

References
==========

.. [#GLEP-1] GLEP 1, "GLEP Purpose and Guidelines", Goodyear
   https://gentoolinux.cn/glep/glep-0001.html

脚注和脚注引用将自动编号，并且数字始终匹配。GLEP 最终确定后，应将自动编号的标签替换为数字，以简化操作。

图像

如果你的 GLEP 包含图表，你可以使用“image”指令将它包含在处理后的输出中

.. image:: diagram.png

任何浏览器友好的图形格式都是可以的：.png、.jpeg、.gif、.tiff 等。

由于此图像在源文本形式的 GLEP 阅读器中不可见，因此你应该考虑包含描述或 ASCII 艺术替代方案，使用注释（如下）。

注释

注释块是紧随显式标记开始后的任意文本的缩进块：两个句点和空格。将“..”单独放在一行以确保注释不被误解为另一个显式标记结构。注释在处理后的文档中不可见。为了方便那些在源文本形式下阅读你的 GLEP 的人，请考虑包含对包含的任何图像的描述或 ASCII 艺术替代方案。例如

.. image:: dataflow.png

..
   Data flows from the input module, through the "black box"
   module, and finally into (and through) the output module.

转义机制

reStructuredText 使用反斜杠（“\”）来覆盖赋予标记字符的特殊含义，并获得文字字符本身。要获得文字反斜杠，请使用转义的反斜杠（“\\”）。在两种上下文中，反斜杠没有特殊含义：文字块和内联文字（见上面的内联标记）。在这些上下文中，不会进行任何标记识别，单个反斜杠表示文字反斜杠，无需重复。

如果你发现需要在文本中使用反斜杠，请考虑改用内联文字或文字块。

避免的习惯

许多熟悉 TeX 的程序员经常这样写引号

`single-quoted' or ``double-quoted''

反引号在 reStructuredText 中很重要，因此应避免这种做法。对于普通文本，请使用普通的 '单引号' 或 "双引号"。对于内联文字文本（见上面的内联标记），请使用双反引号

``literal text: in here, anything goes!``

资源

许多其他结构和变体都是可能的。有关 reStructuredText 标记的更多详细信息，请按详细程度递增的顺序查看

reStructuredText Primer，一个温和的介绍。
Quick reStructuredText，用户快速参考。
reStructuredText Markup Specification，最终权威。

reStructuredText GLEP 的处理使用Docutils完成。如果你对 reStructuredText 或 Docutils 有任何疑问或需要帮助，请在 Docutils-Users 邮件列表中发布消息。Docutils 项目网站包含更多信息。

参考文献

[1]	https://pythonlang.cn/

[2]	https://pythonlang.cn/dev/peps/pep-0012/

[3]	GLEP 1，GLEP 目的和指南，Goodyear，（https://gentoolinux.cn/glep/glep-0001.html）

版权

此作品根据知识共享署名-相同方式共享 4.0 国际许可协议授权。要查看此许可协议的副本，请访问https://creativecommons.org/licenses/by-sa/4.0/。