source: html/ceps/cep-0002.html @ 2502

Last change on this file since 2502 was 2502, checked in by wehart, 9 years ago

Misc documentation update.

File size: 10.9 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
2                      "http://www.w3.org/TR/REC-html40/loose.dtd">
3<html>
4<!--
5This HTML is auto-generated.  DO NOT EDIT THIS FILE!  If you are writing a new
6CEP, see http://www.python.org/ceps/cep-0001.html for instructions and links
7to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
8-->
9<head>
10  <title>CEP 2 -- Sample Plaintext CEP Template</title>
11  <link rel="STYLESHEET" href="style.css" type="text/css" />
12</head>
13<body bgcolor="white">
14<table class="navigation" cellpadding="0" cellspacing="0"
15       width="100%" border="0">
16<tr><td class="navicon" width="150" height="35">
17<a href="../" title="Python Home Page">
18<img src="../pics/PyBanner002.gif" alt="[Python]"
19 border="0" width="150" height="35" /></a></td>
20<td class="textlinks" align="left">
21[<b><a href="../">Python Home</a></b>]
22[<b><a href=".">CEP Index</a></b>]
23[<b><a href="cep-0002.txt">CEP Source</a></b>]
24</td></tr></table>
25<div class="header">
26<table border="0">
27  <tr><th>CEP:&nbsp;</th><td>2</td></tr>
28  <tr><th>Title:&nbsp;</th><td>Sample Plaintext CEP Template</td></tr>
29  <tr><th>Version:&nbsp;</th><td>$Revision: 65634 $</td></tr>
30  <tr><th>Last-Modified:&nbsp;</th><td><a href="http://svn.python.org/view/ceps/trunk/cep-0002.txt">$Date: 2008-08-10 11:25:11 -0600 (Sun, 10 Aug 2008) $</a> </td></tr>
31  <tr><th>Author:&nbsp;</th><td>William Hart</td></tr>
32  <tr><th>Status:&nbsp;</th><td>Draft</td></tr>
33  <tr><th>Type:&nbsp;</th><td>Process</td></tr>
34  <tr><th>Content-Type:&nbsp;</th><td><a href="cep-0009.html">text/plain</a> </td></tr>
35  <tr><th>Created:&nbsp;</th><td>09-Apr-2010</td></tr>
36  <tr><th>Post-History:&nbsp;</th><td></td></tr>
37</table>
38</div>
39<hr />
40<div class="content">
41<h3>Abstract</h3>
42<pre>
43    This CEP provides a boilerplate or sample template for creating
44    your own plaintext CEPs.  In conjunction with the content
45    guidelines in <a href="cep-0001.html">CEP 1</a> [1], this should make it easy for you to
46    conform your own CEPs to the format outlined below.
47
48    Note: if you are reading this CEP via the web, you should first
49    grab the plaintext source of this CEP in order to complete the
50    steps below.  DO NOT USE THE HTML FILE AS YOUR TEMPLATE!
51
52    To get the source this (or any) CEP, look at the top of the HTML
53    page and click on the date &amp; time on the "Last-Modified" line.  It
54    is a link to the source text in the Coopr repository.
55
56    If you would prefer to use lightweight markup in your CEP, please
57    see <a href="cep-0003.html">CEP 3</a>, "Sample reStructuredText CEP Template" [2].
58
59
60</pre>
61<h3>Rationale</h3>
62<pre>
63    CEP submissions come in a wide variety of forms, not all adhering
64    to the format guidelines set forth below.  Use this template, in
65    conjunction with the content guidelines in <a href="cep-0001.html">CEP 1</a>, to ensure that
66    your CEP submission won't get automatically rejected because of
67    form.
68
69
70</pre>
71<h3>How to Use This Template</h3>
72<pre>
73    To use this template you must first decide whether your CEP is
74    going to be an Informational or Standards Track CEP.  Most CEPs
75    are Standards Track because they propose a new feature for Coopr.
76    When in doubt, read <a href="cep-0001.html">CEP 1</a> for details or contact the CEP editors
77    &lt;coopr-admin@googlecodes.com&gt;.
78
79    Once you've decided which type of CEP yours is going to be, follow
80    the directions below.
81
82    - Make a copy of this file (.txt file, not HTML!) and perform the
83      following edits.
84
85    - Replace the "CEP: 2" header with "CEP: XXX" since you don't yet
86      have a CEP number assignment.
87
88    - Change the Title header to the title of your CEP.
89
90    - Leave the Version and Last-Modified headers alone; we'll take
91      care of those when we check your CEP into Coopr's Subversion
92      repository.  These headers consist of keywords ("Revision" and
93      "Date" enclosed in "$"-signs) which are automatically expanded
94      by the repository.  Please do not edit the expanded date or
95      revision text.
96
97    - Change the Author header to include your name, and optionally
98      your email address.  Be sure to follow the format carefully:
99      your name must appear first, and it must not be contained in
100      parentheses.  Your email address may appear second (or it can be
101      omitted) and if it appears, it must appear in angle brackets.
102      It is okay to obfuscate your email address.
103
104    - If there is a mailing list for discussion of your new feature,
105      add a Discussions-To header right after the Author header.
106      You should not add a Discussions-To header if the mailing
107      list to be used is either coopr-forum@googlecodes.com or
108      coopr-developers@googlecodes.com, or if discussions should be
109      sent to you directly.  Most Informational CEPs don't have a
110      Discussions-To header.
111
112    - Change the Status header to "Draft".
113
114    - For Standards Track CEPs, change the Type header to "Standards
115      Track".
116
117    - For Informational CEPs, change the Type header to
118      "Informational".
119
120    - For Standards Track CEPs, if your feature depends on the
121      acceptance of some other currently in-development CEP, add a
122      Requires header right after the Type header.  The value should
123      be the CEP number of the CEP yours depends on.  Don't add this
124      header if your dependent feature is described in a Final CEP.
125
126    - Change the Created header to today's date.  Be sure to follow
127      the format carefully: it must be in dd-mmm-yyyy format, where
128      the mmm is the 3 English letter month abbreviation, e.g. one of
129      Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.
130
131    - For Standards Track CEPs, after the Created header, add a
132      Coopr-Version header and set the value to the next planned
133      version of Coopr, i.e. the one your new feature will hopefully
134      make its first appearance in.  Do not use an alpha or beta
135      release designation here.  Thus, if the last version of Coopr
136      was 2.2 alpha 1 and you're hoping to get your new feature into
137      Coopr 2.2, set the header to:
138
139      Coopr-Version: 2.2
140
141    - Leave Post-History alone for now; you'll add dates to this
142      header each time you post your CEP to coopr-forum@googlecodes.com or
143      coopr-developers@googlecodes.com.  E.g. if you posted your CEP to the lists
144      on August 14, 2001 and September 3, 2001, the Post-History
145      header would look like:
146
147      Post-History: 14-Aug-2001, 03-Sept-2001
148
149      You must manually add new dates and check them in.  If you don't
150      have check-in privileges, send your changes to the CEP editor.
151
152    - Add a Replaces header if your CEP obsoletes an earlier CEP.  The
153      value of this header is the number of the CEP that your new CEP
154      is replacing.  Only add this header if the older CEP is in
155      "final" form, i.e. is either Accepted, Final, or Rejected.  You
156      aren't replacing an older open PEP if you're submitting a
157      competing idea.
158
159    - Now write your Abstract, Rationale, and other content for your
160      PEP, replacing all this gobbledygook with your own text. Be sure
161      to adhere to the format guidelines below, specifically on the
162      prohibition of tab characters and the indentation requirements.
163
164    - Update your References and Copyright section.  If possible,
165      place your CEP in the public domain or use the Open Publication
166      License [3].  Otherwise, include your copyright information.
167
168    - Leave the little Emacs turd at the end of this file alone,
169      including the formfeed character ("^L", or \f).
170
171    - Send your CEP submission to the CEP editor
172      (coopr-admin@googlecodes.com).
173
174
175</pre>
176<h3>Plaintext CEP Formatting Requirements</h3>
177<pre>
178    CEP headings must begin in column zero and the initial letter of each
179    word must be capitalized as in book titles.  Acronyms should be in
180    all capitals.  The body of each section must be indented 4 spaces.
181    Code samples inside body sections should be indented a further 4
182    spaces, and other indentation can be used as required to make the
183    text readable.  You must use two blank lines between the last line
184    of a section's body and the next section heading.
185
186    You must adhere to the Emacs convention of adding two spaces at the
187    end of every sentence.  You should fill your paragraphs to column 70,
188    but under no circumstances should your lines extend past column 79.
189    If your code samples spill over column 79, you should rewrite them.
190
191    Tab characters must never appear in the document at all.  A CEP
192    should include the standard Emacs stanza included by example at the
193    bottom of this CEP.
194
195    When referencing an external web page in the body of a CEP, you
196    should include the title of the page in the text, with a
197    footnote reference to the URL.  Do not include the URL in the body
198    text of the CEP.  E.g.
199
200        Refer to the Coopr web site [1] for more details.
201        ...
202        [1] <a href="https://software.sandia.gov/coopr">https://software.sandia.gov/coopr</a>
203
204    When referring to another CEP, include the CEP number in the body
205    text, such as "<a href="cep-0001.html">CEP 1</a>".  The title may optionally appear.  Add a
206    footnote reference, a number in square brackets.  The footnote
207    body should include the CEP's title and author.  It may optionally
208    include the explicit URL on a separate line, but only in the
209    References section.  Note that the pep2html.py script will
210    calculate URLs automatically.  For example:
211
212            ...
213            Refer to <a href="cep-0001.html">CEP 1</a> [7] for more information about CEP style
214            ...
215
216        References
217
218            [7] <a href="cep-0001.html">CEP 1</a>, CEP Purpose and Guidelines, Hart
219                <a href="http://www.coin-or.org/Coopr/ceps/cep-0001">http://www.coin-or.org/Coopr/ceps/cep-0001</a>
220
221    If you decide to provide an explicit URL for a CEP, please use
222    this as the URL template:
223
224        <a href="http://www.coin-or.org/Coopr/ceps/cep-xxxx/">http://www.coin-or.org/Coopr/ceps/cep-xxxx/</a>
225
226    CEP numbers in URLs must be padded with zeros from the left, so as
227    to be exactly 4 characters wide, however CEP numbers in the text
228    are never padded.
229
230
231</pre>
232<h3>References</h3>
233<pre>
234    [1] <a href="cep-0001.html">CEP 1</a>, CEP Purpose and Guidelines, Hart
235        <a href="http://www.coin-or.org/Coopr/ceps/cep-0001">http://www.coin-or.org/Coopr/ceps/cep-0001</a>
236
237    [2] <a href="cep-0003.html">CEP 3</a>, Sample reStructuredText CEP Template, Hart
238        <a href="http://www.coin-or.org/Coopr/ceps/cep-0003">http://www.coin-or.org/Coopr/ceps/cep-0003</a>
239
240    [3] <a href="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</a>
241
242
243
244</pre>
245<h3>Copyright</h3>
246<pre>
247    Copyright 2010 by Sandia National Laboratories.  Sandia National
248    Laboratories is a multi-program laboratory operated by Sandia
249    Corporation, a wholly owned subsidiary of Lockheed Martin company, for
250    the U.S. Department of Energy's National Nuclear Security Administration
251    under contract DE-AC04-94AL85000.
252
253
254</pre>
255</div>
256</body>
257</html>
Note: See TracBrowser for help on using the repository browser.