diff --git a/pep-0009.txt b/pep-0009.txt index 6af11280007..a94b4f5917f 100644 --- a/pep-0009.txt +++ b/pep-0009.txt @@ -5,225 +5,224 @@ Last-Modified: $Date$ Author: Barry Warsaw Status: Withdrawn Type: Process -Content-Type: text/plain +Content-Type: text/x-rst Created: 14-Aug-2001 Post-History: Resolution: https://mail.python.org/mailman/private/peps/2016-January/001165.html +:: + Update -Update + As of 05-Jan-2016, this PEP is officially deprecated and replaced + by PEP 12. All PEPs should now use the reStructuredText format + described by PEP 12, and plaintext PEPs will no longer be + accepted. - As of 05-Jan-2016, this PEP is officially deprecated and replaced - by PEP 12. All PEPs should now use the reStructuredText format - described by PEP 12, and plaintext PEPs will no longer be - accepted, however you may still see legacy PEPs written using the - plaintext style. + Abstract -Abstract + This PEP provides a boilerplate or sample template for creating + your own plaintext PEPs. In conjunction with the content + guidelines in PEP 1 [1], this should make it easy for you to + conform your own PEPs to the format outlined below. - This PEP provides a boilerplate or sample template for creating - your own plaintext PEPs. In conjunction with the content - guidelines in PEP 1 [1], this should make it easy for you to - conform your own PEPs to the format outlined below. + Note: if you are reading this PEP via the web, you should first + grab the plaintext source of this PEP in order to complete the + steps below. DO NOT USE THE HTML FILE AS YOUR TEMPLATE! - Note: if you are reading this PEP via the web, you should first - grab the plaintext source of this PEP in order to complete the - steps below. DO NOT USE THE HTML FILE AS YOUR TEMPLATE! + To get the source this (or any) PEP, look at the top of the HTML + page and click on the date & time on the "Last-Modified" line. It + is a link to the source text in the Python repository. - To get the source this (or any) PEP, look at the top of the HTML - page and click on the date & time on the "Last-Modified" line. It - is a link to the source text in the Python repository. + If you would prefer to use lightweight markup in your PEP, please + see PEP 12, "Sample reStructuredText PEP Template" [2]. - If you would prefer to use lightweight markup in your PEP, please - see PEP 12, "Sample reStructuredText PEP Template" [2]. + Rationale -Rationale + PEP 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 content guidelines in PEP 1, to ensure that + your PEP submission won't get automatically rejected because of + form. - PEP 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 content guidelines in PEP 1, to ensure that - your PEP submission won't get automatically rejected because of - form. + How to Use This Template -How to Use This Template + To use this template you must first decide whether your PEP is + going to be an Informational or Standards Track PEP. Most PEPs + are Standards Track because they propose a new feature for the + Python language or standard library. When in doubt, read PEP 1 + for details or contact the PEP editors . - To use this template you must first decide whether your PEP is - going to be an Informational or Standards Track PEP. Most PEPs - are Standards Track because they propose a new feature for the - Python language or standard library. When in doubt, read PEP 1 - for details or contact the PEP editors . + Once you've decided which type of PEP yours is going to be, follow + the directions below. - Once you've decided which type of PEP yours is going to be, follow - the directions below. + - Make a copy of this file (.txt file, not HTML!) and perform the + following edits. - - Make a copy of this file (.txt file, not HTML!) and perform the - following edits. + - Replace the "PEP: 9" header with "PEP: XXX" since you don't yet + have a PEP number assignment. - - Replace the "PEP: 9" header with "PEP: XXX" since you don't yet - have a PEP number assignment. + - Change the Title header to the title of your PEP. - - Change the Title header to the title of your PEP. + - Leave the Version and Last-Modified headers alone; we'll take + care of those when we check your PEP into Python's Subversion + repository. These headers consist of keywords ("Revision" and + "Date" enclosed in "$"-signs) which are automatically expanded + by the repository. Please do not edit the expanded date or + revision text. - - Leave the Version and Last-Modified headers alone; we'll take - care of those when we check your PEP into Python's Subversion - repository. These headers consist of keywords ("Revision" and - "Date" enclosed in "$"-signs) which are automatically expanded - by the repository. Please do not edit the expanded date or - revision text. + - 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. + It is okay to obfuscate your email address. - - 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. - It is okay to obfuscate your email address. + - If there is 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 either python-list@python.org or python-dev@python.org, + or if discussions should be sent to you directly. Most + Informational PEPs don't have a Discussions-To header. + + - Change the Status header to "Draft". + + - For Standards Track PEPs, change the Type header to "Standards + Track". + + - For Informational PEPs, change the Type header to + "Informational". + + - For Standards Track PEPs, if your feature depends on the + acceptance of some other currently in-development PEP, add a + Requires header right after the Type header. The value should + be the PEP number of the PEP yours depends on. Don't add this + header if your dependent feature is described in a Final PEP. - - If there is 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 either python-list@python.org or python-dev@python.org, - or if discussions should be sent to you directly. Most - Informational PEPs don't have a Discussions-To header. + - 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, e.g. one of + Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec. - - Change the Status header to "Draft". - - - For Standards Track PEPs, change the Type header to "Standards - Track". + - For Standards Track PEPs, after the Created header, add a + Python-Version header and set the value to the next planned + version of Python, i.e. the one your new feature will hopefully + make its first appearance in. Do not use an alpha or beta + release designation here. Thus, if the last version of Python + was 2.2 alpha 1 and you're hoping to get your new feature into + Python 2.2, set the header to: - - For Informational PEPs, change the Type header to - "Informational". + Python-Version: 2.2 - - For Standards Track PEPs, if your feature depends on the - acceptance of some other currently in-development PEP, add a - Requires header right after the Type header. The value should - be the PEP number of the PEP yours depends on. Don't add this - header if your dependent feature is described in a Final PEP. + - Leave Post-History alone for now; you'll add dates to this + header each time you post your PEP to python-list@python.org or + python-dev@python.org. E.g. if you posted your PEP to the lists + on August 14, 2001 and September 3, 2001, the Post-History + header would look like: - - 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, e.g. one of - Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec. + Post-History: 14-Aug-2001, 03-Sept-2001 - - For Standards Track PEPs, after the Created header, add a - Python-Version header and set the value to the next planned - version of Python, i.e. the one your new feature will hopefully - make its first appearance in. Do not use an alpha or beta - release designation here. Thus, if the last version of Python - was 2.2 alpha 1 and you're hoping to get your new feature into - Python 2.2, set the header to: + You must manually add new dates and check them in. If you don't + have check-in privileges, send your changes to the PEP editor. - Python-Version: 2.2 + - Add a Replaces header if your PEP obsoletes an earlier PEP. The + value of this header is the number of the PEP that your new PEP + is replacing. Only add this header if the older PEP is in + "final" form, i.e. is either Accepted, Final, or Rejected. You + aren't replacing an older open PEP if you're submitting a + competing idea. - - Leave Post-History alone for now; you'll add dates to this - header each time you post your PEP to python-list@python.org or - python-dev@python.org. E.g. if you posted your PEP to the lists - on August 14, 2001 and September 3, 2001, the Post-History - header would look like: + - Now write your Abstract, Rationale, and other content for your + PEP, replacing all this gobbledygook with your own text. Be sure + to adhere to the format guidelines below, specifically on the + prohibition of tab characters and the indentation requirements. - Post-History: 14-Aug-2001, 03-Sept-2001 + - Update your References and Copyright section. Usually you'll + place your PEP into the public domain, in which case just leave + the "Copyright" section alone. Alternatively, you can use the + Open Publication License[3], but public domain is still strongly + preferred. - You must manually add new dates and check them in. If you don't - have check-in privileges, send your changes to the PEP editor. + - Leave the little Emacs turd at the end of this file alone, + including the formfeed character ("^L", or \f). - - Add a Replaces header if your PEP obsoletes an earlier PEP. The - value of this header is the number of the PEP that your new PEP - is replacing. Only add this header if the older PEP is in - "final" form, i.e. is either Accepted, Final, or Rejected. You - aren't replacing an older open PEP if you're submitting a - competing idea. + - Send your PEP submission to the PEP editors (peps@python.org), + along with $100k in unmarked pennies. (Just kidding, I wanted + to see if you were still awake. :) - - Now write your Abstract, Rationale, and other content for your - PEP, replacing all this gobbledygook with your own text. Be sure - to adhere to the format guidelines below, specifically on the - prohibition of tab characters and the indentation requirements. - - Update your References and Copyright section. Usually you'll - place your PEP into the public domain, in which case just leave - the "Copyright" section alone. Alternatively, you can use the - Open Publication License[3], but public domain is still strongly - preferred. + Plaintext PEP Formatting Requirements - - Leave the little Emacs turd at the end of this file alone, - including the formfeed character ("^L", or \f). + PEP 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. The body of each section must be indented 4 + spaces. Code samples inside body sections should be indented a + further 4 spaces, and other indentation can be used as required to + make the text readable. You must use two blank lines between the + last line of a section's body and the next section heading. - - Send your PEP submission to the PEP editors (peps@python.org), - along with $100k in unmarked pennies. (Just kidding, I wanted - to see if you were still awake. :) + You must adhere to the Emacs 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. + Tab characters must never appear in the document at all. A PEP + should include the standard Emacs stanza included by example at + the bottom of this PEP. -Plaintext PEP Formatting Requirements + When referencing an external web page in the body of a PEP, you + should include the title of the page in the text, with a + footnote reference to the URL. Do not include the URL in the body + text of the PEP. E.g. - PEP 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. The body of each section must be indented 4 - spaces. Code samples inside body sections should be indented a - further 4 spaces, and other indentation can be used as required to - make the text readable. You must use two blank lines between the - last line of a section's body and the next section heading. + Refer to the Python Language web site [1] for more details. + ... + [1] http://www.python.org - You must adhere to the Emacs 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. + When referring to another PEP, include the PEP number in the body + text, such as "PEP 1". The title may optionally appear. Add a + footnote reference, a number in square brackets. The footnote + body should include the PEP's title and author. It may optionally + include the explicit URL on a separate line, but only in the + References section. Note that the pep2html.py script will + calculate URLs automatically. For example: - Tab characters must never appear in the document at all. A PEP - should include the standard Emacs stanza included by example at - the bottom of this PEP. + ... + Refer to PEP 1 [7] for more information about PEP style + ... - When referencing an external web page in the body of a PEP, you - should include the title of the page in the text, with a - footnote reference to the URL. Do not include the URL in the body - text of the PEP. E.g. + References - Refer to the Python Language web site [1] for more details. - ... - [1] http://www.python.org + [7] PEP 1, PEP Purpose and Guidelines, Warsaw, Hylton + http://www.python.org/dev/peps/pep-0001/ - When referring to another PEP, include the PEP number in the body - text, such as "PEP 1". The title may optionally appear. Add a - footnote reference, a number in square brackets. The footnote - body should include the PEP's title and author. It may optionally - include the explicit URL on a separate line, but only in the - References section. Note that the pep2html.py script will - calculate URLs automatically. For example: + If you decide to provide an explicit URL for a PEP, please use + this as the URL template: - ... - Refer to PEP 1 [7] for more information about PEP style - ... + http://www.python.org/dev/peps/pep-xxxx/ - References + PEP numbers in URLs must be padded with zeros from the left, so as + to be exactly 4 characters wide, however PEP numbers in the text + are never padded. - [7] PEP 1, PEP Purpose and Guidelines, Warsaw, Hylton - http://www.python.org/dev/peps/pep-0001/ - If you decide to provide an explicit URL for a PEP, please use - this as the URL template: + References - http://www.python.org/dev/peps/pep-xxxx/ + [1] PEP 1, PEP Purpose and Guidelines, Warsaw, Hylton + http://www.python.org/dev/peps/pep-0001/ - PEP numbers in URLs must be padded with zeros from the left, so as - to be exactly 4 characters wide, however PEP numbers in the text - are never padded. + [2] PEP 12, Sample reStructuredText PEP Template, Goodger, Warsaw + http://www.python.org/dev/peps/pep-0012/ + [3] http://www.opencontent.org/openpub/ -References - [1] PEP 1, PEP Purpose and Guidelines, Warsaw, Hylton - http://www.python.org/dev/peps/pep-0001/ - [2] PEP 12, Sample reStructuredText PEP Template, Goodger, Warsaw - http://www.python.org/dev/peps/pep-0012/ + Copyright - [3] http://www.opencontent.org/openpub/ - - - -Copyright - - This document has been placed in the public domain. + This document has been placed in the public domain.