Abstract
This CEP provides a boilerplate or sample template for creating
your own plaintext CEPs. In conjunction with the content
guidelines in CEP 1 [1], this should make it easy for you to
conform your own CEPs to the format outlined below.
Note: if you are reading this CEP via the web, you should first
grab the plaintext source of this CEP in order to complete the
steps below. DO NOT USE THE HTML FILE AS YOUR TEMPLATE!
To get the source this (or any) CEP, 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 Coopr repository.
If you would prefer to use lightweight markup in your CEP, please
see CEP 3, "Sample reStructuredText CEP Template" [2].
Rationale
CEP 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 CEP 1, to ensure that
your CEP submission won't get automatically rejected because of
form.
How to Use This Template
To use this template you must first decide whether your CEP is
going to be an Informational or Standards Track CEP. Most CEPs
are Standards Track because they propose a new feature for Coopr.
When in doubt, read CEP 1 for details or contact the CEP editors
<coopr-admin@googlecodes.com>.
Once you've decided which type of CEP yours is going to be, follow
the directions below.
- Make a copy of this file (.txt file, not HTML!) and perform the
following edits.
- Replace the "CEP: 2" header with "CEP: XXX" since you don't yet
have a CEP number assignment.
- Change the Title header to the title of your CEP.
- Leave the Version and Last-Modified headers alone; we'll take
care of those when we check your CEP into Coopr'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.
- 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 coopr-forum@googlecodes.com or
coopr-developers@googlecodes.com, or if discussions should be
sent to you directly. Most Informational CEPs don't have a
Discussions-To header.
- Change the Status header to "Draft".
- For Standards Track CEPs, change the Type header to "Standards
Track".
- For Informational CEPs, change the Type header to
"Informational".
- For Standards Track CEPs, if your feature depends on the
acceptance of some other currently in-development CEP, add a
Requires header right after the Type header. The value should
be the CEP number of the CEP yours depends on. Don't add this
header if your dependent feature is described in a Final CEP.
- 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.
- For Standards Track CEPs, after the Created header, add a
Coopr-Version header and set the value to the next planned
version of Coopr, 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 Coopr
was 2.2 alpha 1 and you're hoping to get your new feature into
Coopr 2.2, set the header to:
Coopr-Version: 2.2
- Leave Post-History alone for now; you'll add dates to this
header each time you post your CEP to coopr-forum@googlecodes.com or
coopr-developers@googlecodes.com. E.g. if you posted your CEP to the lists
on August 14, 2001 and September 3, 2001, the Post-History
header would look like:
Post-History: 14-Aug-2001, 03-Sept-2001
You must manually add new dates and check them in. If you don't
have check-in privileges, send your changes to the CEP editor.
- Add a Replaces header if your CEP obsoletes an earlier CEP. The
value of this header is the number of the CEP that your new CEP
is replacing. Only add this header if the older CEP 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.
- 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. If possible,
place your CEP in the public domain or use the Open Publication
License [3]. Otherwise, include your copyright information.
- Leave the little Emacs turd at the end of this file alone,
including the formfeed character ("^L", or \f).
- Send your CEP submission to the CEP editor
(coopr-admin@googlecodes.com).
Plaintext CEP Formatting Requirements
CEP 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.
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 CEP
should include the standard Emacs stanza included by example at the
bottom of this CEP.
When referencing an external web page in the body of a CEP, 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 CEP. E.g.
Refer to the Coopr web site [1] for more details.
...
[1] https://software.sandia.gov/coopr
When referring to another CEP, include the CEP number in the body
text, such as "CEP 1". The title may optionally appear. Add a
footnote reference, a number in square brackets. The footnote
body should include the CEP'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:
...
Refer to CEP 1 [7] for more information about CEP style
...
References
[7] CEP 1, CEP Purpose and Guidelines, Hart
http://www.coin-or.org/Coopr/ceps/cep-0001.html
If you decide to provide an explicit URL for a CEP, please use
this as the URL template:
http://www.coin-or.org/Coopr/ceps/cep-xxxx/
CEP numbers in URLs must be padded with zeros from the left, so as
to be exactly 4 characters wide, however CEP numbers in the text
are never padded.
References
[1] CEP 1, CEP Purpose and Guidelines, Hart
http://www.coin-or.org/Coopr/ceps/cep-0001.html
[2] CEP 3, Sample reStructuredText CEP Template, Hart
http://www.coin-or.org/Coopr/ceps/cep-0003.html
[3] http://www.opencontent.org/openpub/
Copyright
Copyright 2010 by Sandia National Laboratories. Sandia National
Laboratories is a multi-program laboratory operated by Sandia
Corporation, a wholly owned subsidiary of Lockheed Martin company, for
the U.S. Department of Energy's National Nuclear Security Administration
under contract DE-AC04-94AL85000.