diff options
Diffstat (limited to 'glep-0002.txt')
| -rw-r--r-- | glep-0002.txt | 201 |
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) |