summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat (limited to 'glep-0002.txt')
-rw-r--r--glep-0002.txt201
1 files changed, 98 insertions, 103 deletions
diff --git a/glep-0002.txt b/glep-0002.txt
index 9679be5..2f2f2b9 100644
--- a/glep-0002.txt
+++ b/glep-0002.txt
@@ -1,10 +1,8 @@
GLEP: 2
-Title: Sample reStructuredText GLEP Template
-Version: $Revision: 1.1 $
-Last-Modified: $Date: 2003/06/01 04:33:49 $
+Title: Sample ReStructuredText GLEP Template
+Version: $Revision: 1.2 $
+Last-Modified: $Date: 2003/06/01 14:05:29 $
Author: Grant Goodyear <g2boojum@gentoo.org>,
- David Goodger <goodger@users.sourceforge.net>,
- Barry A. Warsaw <barry@zope.com>
Status: Draft
Type: Informational
Content-Type: text/x-rst
@@ -12,61 +10,63 @@ Created: 31 May 2003
Post-History:
+Credits
+=======
+
+The text of this GLEP was, to a significant extent, stolen from Python's
+[#PYTHON]_ PEP-0012 [#PEP12]_ by David Goodger and Barry A. Warsaw.
+
+
Abstract
========
-This GLEP provides a boilerplate or sample template for creating your
-own reStructuredText GLEPs. In conjunction with the content guidelines
-in GLEP 1 [1]_, this should make it easy for you to conform your own
-GLEPs to the format outlined below.
+This GLEP provides a boilerplate or sample template for creating your own
+reStructuredText GLEPs. In conjunction with the content guidelines in GLEP 1
+[#GLEP1]_, this should make it easy for you to conform your own GLEPs to the
+format outlined below.
-Note: if you are reading this GLEP via the web, you should first grab
-the text (reStructuredText) source of this GLEP in order to complete
-the steps below. **DO NOT USE THE HTML FILE AS YOUR TEMPLATE!**
+Note: if you are reading this GLEP via the web, you should first grab the text
+(reStructuredText) source of this GLEP in order to complete the steps below.
+**DO NOT USE THE HTML FILE AS YOUR TEMPLATE!**
-To get the source of this (or any) GLEP, look at the top of the HTML
-page and click on the link titled "GLEP Source".
+To get the source of this (or any) GLEP, look at the top of the HTML page and
+click on the link titled "GLEP Source".
Motivation
==========
-Provide adequate motivation here. In this particular case,
-we need to provide people with the information necessary
-to submit GLEPs in the proper form.
+Provide adequate motivation here. In this particular case, we need to provide
+people with the information necessary to submit GLEPs in the proper form.
Rationale
=========
-GLEP submissions come in a wide variety of forms, not all adhering
-to the format guidelines set forth below. Use this template, in
-conjunction with the format guidelines below, to ensure that your
-GLEP submission won't get automatically rejected because of form.
+GLEP submissions come in a wide variety of forms, not all adhering to the
+format guidelines set forth below. Use this template, in conjunction with the
+format guidelines below, to ensure that your GLEP submission won't get
+automatically rejected because of form.
-ReStructuredText is used to
-allow GLEP authors more functionality and expressivity, while
-maintaining easy readability in the source text. The processed HTML
-form makes the functionality accessible to readers: live hyperlinks,
-styled text, tables, images, and automatic tables of contents, among
-other advantages.
+ReStructuredText is used to allow GLEP authors more functionality and
+expressivity, while maintaining easy readability in the source text. The
+processed HTML form makes the functionality accessible to readers: live
+hyperlinks, styled text, tables, images, and automatic tables of contents,
+among other advantages.
Backwards Compatibility
=======================
-Not a problem for this GLEP. This section should be
-included *even* when it is only to state that there are
-no backwards compatibility issues.
+Not a problem for this GLEP. This section should be included *even* when it
+is only to state that there are no backwards compatibility issues.
How to Use This Template
========================
-To use this template you must first decide whether your GLEP is going
-to be an Informational or Standards Track GLEP. Most GLEPs are
-Standards Track because they propose new functionality for
-some aspect of Gentoo Linux.
-When in doubt, read GLEP 1 for details
-or contact the GLEP editors <glep@gentoo.org>.
+To use this template you must first decide whether your GLEP is going to be an
+Informational or Standards Track GLEP. Most GLEPs are Standards Track because
+they propose new functionality for some aspect of Gentoo Linux. When in
+doubt, read GLEP 1 for details or contact the GLEP editors <glep@gentoo.org>.
Once you've decided which type of GLEP yours is going to be, follow the
directions below.
@@ -83,19 +83,17 @@ directions below.
of those when we check your GLEP into CVS.
- Change the Author header to include your name, and optionally your
- email address. Be sure to follow the format carefully: your name
- must appear first, and it must not be contained in parentheses.
- Your email address may appear second (or it can be omitted) and if
- it appears, it must appear in angle brackets. Your e-mail address
+ email address. Be sure to follow the format carefully: your name must
+ appear first, and it must not be contained in parentheses. Your email
+ address may appear second (or it can be omitted) and if it appears, it must
+ appear in angle brackets. Your e-mail address
here will e automatically obfuscated.
- If there is a forum thread or a mailing list for discussion
- of your new feature, add a
- Discussions-To header right after the Author header. You should not
- add a Discussions-To header if the mailing list to be used is
- gentoo-dev@gentoo.org, or if discussions
- should be sent to you directly. Most Informational GLEPs don't have
- a Discussions-To header.
+ of your new feature, add a Discussions-To header right after the Author
+ header. You should not add a Discussions-To header if the mailing list to
+ be used is gentoo-dev@gentoo.org, or if discussions should be sent to you
+ directly. Most Informational GLEPs don't have a Discussions-To header.
- Change the Status header to "Draft".
@@ -105,43 +103,40 @@ directions below.
- For Informational GLEPs, change the Type header to "Informational".
- For Standards Track GLEPs, if your feature depends on the acceptance
- of some other currently in-development GLEP, add a Requires header
- right after the Type header. The value should be the GLEP number of
- the GLEP yours depends on. Don't add this header if your dependent
- feature is described in a Final GLEP.
+ of some other currently in-development GLEP, add a Requires header right
+ after the Type header. The value should be the GLEP number of the GLEP
+ yours depends on. Don't add this header if your dependent feature is
+ described in a Final GLEP.
- Change the Created header to today's date. Be sure to follow the
- format carefully: it must be in ``dd-mmm-yyyy`` format, where the
- ``mmm`` is the 3 English letter month abbreviation, i.e. one of Jan,
- Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.
+ format carefully: it must be in ``dd-mmm-yyyy`` format, where the ``mmm`` is
+ the 3 English letter month abbreviation, i.e. one of Jan, Feb, Mar, Apr,
+ May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.
- Leave Post-History alone for now; you'll add dates to this header
- each time you post your GLEP to gentoo-dev@gentoo.org.
- If you posted your GLEP to the list on
- August 14, 2003 and September 3, 2003, the Post-History header would
- look like::
+ each time you post your GLEP to gentoo-dev@gentoo.org. If you posted your
+ GLEP to the list on August 14, 2003 and September 3, 2003, the Post-History
+ header would look like::
Post-History: 14-Aug-2003, 03-Sept-2003
- You must manually add new dates and check them in. If you don't
- have check-in privileges, send your changes to the GLEP editors.
+ You must manually add new dates and check them in. If you don't have
+ check-in privileges, send your changes to the GLEP editors.
- Add a Replaces header if your GLEP obsoletes an earlier GLEP. The
value of this header is the number of the GLEP that your new GLEP is
- replacing. Only add this header if the older GLEP is in "final"
- form, i.e. is either Accepted, Final, or Rejected. You aren't
- replacing an older open GLEP if you're submitting a competing idea.
+ replacing. Only add this header if the older GLEP is in "final" form, i.e.
+ is either Accepted, Final, or Rejected. You aren't replacing an older open
+ GLEP if you're submitting a competing idea.
- Now write your Abstract, Rationale, and other content for your GLEP,
- replacing all of this gobbledygook with your own text. Be sure to
- adhere to the format guidelines below, specifically on the
- indentation requirements.
+ replacing all of this gobbledygook with your own text. Be sure to adhere to
+ the format guidelines below, specifically on the indentation requirements.
- Update your References and Copyright section. Usually you'll place
- your GLEP into the public domain, in which case just leave the
- Copyright section alone. Alternatively, you can use the `Open
- Publication License`__, but public domain is still strongly
- preferred.
+ your GLEP into the public domain, in which case just leave the Copyright
+ section alone. Alternatively, you can use the `Open Publication License`__,
+ but public domain is still strongly preferred.
__ http://www.opencontent.org/openpub/
@@ -151,34 +146,32 @@ directions below.
ReStructuredText GLEP Formatting Requirements
=============================================
-The following is a GLEP-specific summary of reStructuredText syntax.
-For the sake of simplicity and brevity, much detail is omitted. For
-more detail, see `Resources`_ below. `Literal blocks`_ (in which no
-markup processing is done) are used for examples throughout, to
-illustrate the plaintext markup.
+The following is a GLEP-specific summary of reStructuredText syntax. For the
+sake of simplicity and brevity, much detail is omitted. For more detail, see
+`Resources`_ below. `Literal blocks`_ (in which no markup processing is done)
+are used for examples throughout, to illustrate the plaintext markup.
General
-------
-You must adhere to the convention of adding two spaces at the
-end of every sentence. You should fill your paragraphs to column 70,
-but under no circumstances should your lines extend past column 79.
-If your code samples spill over column 79, you should rewrite them.
+You must adhere to the convention of adding two spaces at the end of every
+sentence. You should fill your paragraphs to column 70, but under no
+circumstances should your lines extend past column 79. If your code samples
+spill over column 79, you should rewrite them.
Section Headings
----------------
-GLEP headings must begin in column zero and the initial letter of each
-word must be capitalized as in book titles. Acronyms should be in all
-capitals. Section titles must be adorned with an underline, a single
-repeated punctuation character, which begins in column zero and must
-extend at least as far as the right edge of the title text (4
-characters minimum). First-level section titles are underlined with
-"=" (equals signs), second-level section titles with "-" (hyphens),
-and third-level section titles with "'" (single quotes or
-apostrophes). For example::
+GLEP headings must begin in column zero and the initial letter of each word
+must be capitalized as in book titles. Acronyms should be in all capitals.
+Section titles must be adorned with an underline, a single repeated
+punctuation character, which begins in column zero and must extend at least as
+far as the right edge of the title text (4 characters minimum). First-level
+section titles are underlined with "=" (equals signs), second-level section
+titles with "-" (hyphens), and third-level section titles with "'" (single
+quotes or apostrophes). For example::
First-Level Title
=================
@@ -189,9 +182,8 @@ apostrophes). For example::
Third-Level Title
'''''''''''''''''
-If there are more than three levels of sections in your GLEP, you may
-insert overline/underline-adorned titles for the first and second
-levels as follows::
+If there are more than three levels of sections in your GLEP, you may insert
+overline/underline-adorned titles for the first and second levels as follows::
============================
First-Level Title (optional)
@@ -210,25 +202,24 @@ levels as follows::
Fifth-Level Title
'''''''''''''''''
-You shouldn't have more than five levels of sections in your GLEP. If
-you do, you should consider rewriting it.
+You shouldn't have more than five levels of sections in your GLEP. If you do,
+you should consider rewriting it.
-You must use two blank lines between the last line of a section's body
-and the next section heading. If a subsection heading immediately
-follows a section heading, a single blank line in-between is
-sufficient.
+You must use two blank lines between the last line of a section's body and the
+next section heading. If a subsection heading immediately follows a section
+heading, a single blank line in-between is sufficient.
-The body of each section is not normally indented, although some
-constructs do use indentation, as described below. Blank lines are
-used to separate constructs.
+The body of each section is not normally indented, although some constructs do
+use indentation, as described below. Blank lines are used to separate
+constructs.
Paragraphs
----------
-Paragraphs are left-aligned text blocks separated by blank lines.
-Paragraphs are not indented unless they are part of an indented
-construct (such as a block quote or a list item).
+Paragraphs are left-aligned text blocks separated by blank lines. Paragraphs
+are not indented unless they are part of an indented construct (such as a
+block quote or a list item).
Inline Markup
@@ -611,7 +602,11 @@ list`_. The `Docutils project web site`_ has more information.
References
==========
-.. [1] GLEP 1, GLEP Purpose and Guidelines, Goodyear, Warsaw, Hylton
+.. [#PYTHON] http://www.python.org
+
+.. [#PEP12] http://www.python.org/peps/pep-0012.html
+
+.. [#GLEP1] GLEP 1, GLEP Purpose and Guidelines, Goodyear,
(http://www.gentoo.org/glep/glep-0001.html)