source: html/ceps/cep-0003.html @ 2526

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

Documentation updates.

File size: 41.2 KB
Line 
1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4<!--
5This HTML is auto-generated.  DO NOT EDIT THIS FILE!  If you are writing a new
6PEP, see http://www.python.org/dev/peps/pep-0001 for instructions and links
7to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
8-->
9<head>
10  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11  <meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" />
12  <title>PEP 3 -- Sample reStructuredText CEP Template</title>
13  <style type="text/css">
14
15/*
16:Author: David Goodger
17:Contact: goodger@python.org
18:date: $Date: 2006-05-21 14:44:42 -0600 (Sun, 21 May 2006) $
19:version: $Revision: 4564 $
20:copyright: This stylesheet has been placed in the public domain.
21
22Default cascading style sheet for the PEP HTML output of Docutils.
23*/
24
25/* "! important" is used here to override other ``margin-top`` and
26   ``margin-bottom`` styles that are later in the stylesheet or
27   more specific.  See http://www.w3.org/TR/CSS1#the-cascade */
28.first {
29  margin-top: 0 ! important }
30
31.last, .with-subtitle {
32  margin-bottom: 0 ! important }
33
34.hidden {
35  display: none }
36
37.navigation {
38  width: 100% ;
39  background: #99ccff ;
40  margin-top: 0px ;
41  margin-bottom: 0px }
42
43.navigation .navicon {
44  width: 150px ;
45  height: 35px }
46
47.navigation .textlinks {
48  padding-left: 1em ;
49  text-align: left }
50
51.navigation td, .navigation th {
52  padding-left: 0em ;
53  padding-right: 0em ;
54  vertical-align: middle }
55
56.rfc2822 {
57  margin-top: 0.5em ;
58  margin-left: 0.5em ;
59  margin-right: 0.5em ;
60  margin-bottom: 0em }
61
62.rfc2822 td {
63  text-align: left }
64
65.rfc2822 th.field-name {
66  text-align: right ;
67  font-family: sans-serif ;
68  padding-right: 0.5em ;
69  font-weight: bold ;
70  margin-bottom: 0em }
71
72a.toc-backref {
73  text-decoration: none ;
74  color: black }
75
76blockquote.epigraph {
77  margin: 2em 5em ; }
78
79body {
80  margin: 0px ;
81  margin-bottom: 1em ;
82  padding: 0px }
83
84dl.docutils dd {
85  margin-bottom: 0.5em }
86
87div.section {
88  margin-left: 1em ;
89  margin-right: 1em ;
90  margin-bottom: 1.5em }
91
92div.section div.section {
93  margin-left: 0em ;
94  margin-right: 0em ;
95  margin-top: 1.5em }
96
97div.abstract {
98  margin: 2em 5em }
99
100div.abstract p.topic-title {
101  font-weight: bold ;
102  text-align: center }
103
104div.admonition, div.attention, div.caution, div.danger, div.error,
105div.hint, div.important, div.note, div.tip, div.warning {
106  margin: 2em ;
107  border: medium outset ;
108  padding: 1em }
109
110div.admonition p.admonition-title, div.hint p.admonition-title,
111div.important p.admonition-title, div.note p.admonition-title,
112div.tip p.admonition-title {
113  font-weight: bold ;
114  font-family: sans-serif }
115
116div.attention p.admonition-title, div.caution p.admonition-title,
117div.danger p.admonition-title, div.error p.admonition-title,
118div.warning p.admonition-title {
119  color: red ;
120  font-weight: bold ;
121  font-family: sans-serif }
122
123/* Uncomment (and remove this text!) to get reduced vertical space in
124   compound paragraphs.
125div.compound .compound-first, div.compound .compound-middle {
126  margin-bottom: 0.5em }
127
128div.compound .compound-last, div.compound .compound-middle {
129  margin-top: 0.5em }
130*/
131
132div.dedication {
133  margin: 2em 5em ;
134  text-align: center ;
135  font-style: italic }
136
137div.dedication p.topic-title {
138  font-weight: bold ;
139  font-style: normal }
140
141div.figure {
142  margin-left: 2em ;
143  margin-right: 2em }
144
145div.footer, div.header {
146  clear: both;
147  font-size: smaller }
148
149div.footer {
150  margin-left: 1em ;
151  margin-right: 1em }
152
153div.line-block {
154  display: block ;
155  margin-top: 1em ;
156  margin-bottom: 1em }
157
158div.line-block div.line-block {
159  margin-top: 0 ;
160  margin-bottom: 0 ;
161  margin-left: 1.5em }
162
163div.sidebar {
164  margin-left: 1em ;
165  border: medium outset ;
166  padding: 1em ;
167  background-color: #ffffee ;
168  width: 40% ;
169  float: right ;
170  clear: right }
171
172div.sidebar p.rubric {
173  font-family: sans-serif ;
174  font-size: medium }
175
176div.system-messages {
177  margin: 5em }
178
179div.system-messages h1 {
180  color: red }
181
182div.system-message {
183  border: medium outset ;
184  padding: 1em }
185
186div.system-message p.system-message-title {
187  color: red ;
188  font-weight: bold }
189
190div.topic {
191  margin: 2em }
192
193h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
194h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
195  margin-top: 0.4em }
196
197h1 {
198  font-family: sans-serif ;
199  font-size: large }
200
201h2 {
202  font-family: sans-serif ;
203  font-size: medium }
204
205h3 {
206  font-family: sans-serif ;
207  font-size: small }
208
209h4 {
210  font-family: sans-serif ;
211  font-style: italic ;
212  font-size: small }
213
214h5 {
215  font-family: sans-serif;
216  font-size: x-small }
217
218h6 {
219  font-family: sans-serif;
220  font-style: italic ;
221  font-size: x-small }
222
223hr.docutils {
224  width: 75% }
225
226img.align-left {
227  clear: left }
228
229img.align-right {
230  clear: right }
231
232img.borderless {
233  border: 0 }
234
235ol.simple, ul.simple {
236  margin-bottom: 1em }
237
238ol.arabic {
239  list-style: decimal }
240
241ol.loweralpha {
242  list-style: lower-alpha }
243
244ol.upperalpha {
245  list-style: upper-alpha }
246
247ol.lowerroman {
248  list-style: lower-roman }
249
250ol.upperroman {
251  list-style: upper-roman }
252
253p.attribution {
254  text-align: right ;
255  margin-left: 50% }
256
257p.caption {
258  font-style: italic }
259
260p.credits {
261  font-style: italic ;
262  font-size: smaller }
263
264p.label {
265  white-space: nowrap }
266
267p.rubric {
268  font-weight: bold ;
269  font-size: larger ;
270  color: maroon ;
271  text-align: center }
272
273p.sidebar-title {
274  font-family: sans-serif ;
275  font-weight: bold ;
276  font-size: larger }
277
278p.sidebar-subtitle {
279  font-family: sans-serif ;
280  font-weight: bold }
281
282p.topic-title {
283  font-family: sans-serif ;
284  font-weight: bold }
285
286pre.address {
287  margin-bottom: 0 ;
288  margin-top: 0 ;
289  font-family: serif ;
290  font-size: 100% }
291
292pre.literal-block, pre.doctest-block {
293  margin-left: 2em ;
294  margin-right: 2em }
295
296span.classifier {
297  font-family: sans-serif ;
298  font-style: oblique }
299
300span.classifier-delimiter {
301  font-family: sans-serif ;
302  font-weight: bold }
303
304span.interpreted {
305  font-family: sans-serif }
306
307span.option {
308  white-space: nowrap }
309
310span.option-argument {
311  font-style: italic }
312
313span.pre {
314  white-space: pre }
315
316span.problematic {
317  color: red }
318
319span.section-subtitle {
320  /* font-size relative to parent (h1..h6 element) */
321  font-size: 80% }
322
323table.citation {
324  border-left: solid 1px gray;
325  margin-left: 1px }
326
327table.docinfo {
328  margin: 2em 4em }
329
330table.docutils {
331  margin-top: 0.5em ;
332  margin-bottom: 0.5em }
333
334table.footnote {
335  border-left: solid 1px black;
336  margin-left: 1px }
337
338table.docutils td, table.docutils th,
339table.docinfo td, table.docinfo th {
340  padding-left: 0.5em ;
341  padding-right: 0.5em ;
342  vertical-align: top }
343
344td.num {
345  text-align: right }
346
347th.field-name {
348  font-weight: bold ;
349  text-align: left ;
350  white-space: nowrap ;
351  padding-left: 0 }
352
353h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
354h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
355  font-size: 100% }
356
357ul.auto-toc {
358  list-style-type: none }
359
360</style>
361</head>
362<body bgcolor="white">
363<table class="navigation" cellpadding="0" cellspacing="0"
364       width="100%" border="0">
365<tr><td class="navicon" width="150" height="35">
366<a href="http://www.python.org/" title="Python Home Page">
367<img src="http://www.python.org/pics/PyBanner012.gif" alt="[Python]"
368 border="0" width="150" height="35" /></a></td>
369<td class="textlinks" align="left">
370[<b><a href="http://www.python.org/">Python Home</a></b>]
371[<b><a href="http://www.python.org/dev/peps/">PEP Index</a></b>]
372[<b><a href="./pep-0003.txt">PEP Source</a></b>]
373</td></tr></table>
374<div class="document">
375<table class="rfc2822 docutils field-list" frame="void" rules="none">
376<col class="field-name" />
377<col class="field-body" />
378<tbody valign="top">
379<tr class="field"><th class="field-name">CEP:</th><td class="field-body">3</td>
380</tr>
381<tr class="field"><th class="field-name">Title:</th><td class="field-body">Sample reStructuredText CEP Template</td>
382</tr>
383<tr class="field"><th class="field-name">Version:</th><td class="field-body">65628</td>
384</tr>
385<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="http://svn.python.org/view/*checkout*/peps/trunk/pep-0003.txt">2008-08-10 07:59:20 -0600 (Sun, 10 Aug 2008)</a></td>
386</tr>
387<tr class="field"><th class="field-name">Author:</th><td class="field-body">William Hart</td>
388</tr>
389<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
390</tr>
391<tr class="field"><th class="field-name">Type:</th><td class="field-body">Process</td>
392</tr>
393<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference external" href="http://www.python.org/dev/peps/pep-0012">text/x-rst</a></td>
394</tr>
395<tr class="field"><th class="field-name">Created:</th><td class="field-body">09-Apr-2010</td>
396</tr>
397<tr class="field"><th class="field-name">Post-History:</th><td class="field-body"></td>
398</tr>
399</tbody>
400</table>
401<hr />
402<div class="contents topic" id="contents">
403<p class="topic-title first">Contents</p>
404<ul class="simple">
405<li><a class="reference internal" href="#abstract" id="id24">Abstract</a></li>
406<li><a class="reference internal" href="#rationale" id="id25">Rationale</a></li>
407<li><a class="reference internal" href="#how-to-use-this-template" id="id26">How to Use This Template</a></li>
408<li><a class="reference internal" href="#restructuredtext-cep-formatting-requirements" id="id27">ReStructuredText CEP Formatting Requirements</a><ul>
409<li><a class="reference internal" href="#general" id="id28">General</a></li>
410<li><a class="reference internal" href="#section-headings" id="id29">Section Headings</a></li>
411<li><a class="reference internal" href="#paragraphs" id="id30">Paragraphs</a></li>
412<li><a class="reference internal" href="#inline-markup" id="id31">Inline Markup</a></li>
413<li><a class="reference internal" href="#block-quotes" id="id32">Block Quotes</a></li>
414<li><a class="reference internal" href="#literal-blocks" id="id33">Literal Blocks</a></li>
415<li><a class="reference internal" href="#lists" id="id34">Lists</a></li>
416<li><a class="reference internal" href="#tables" id="id35">Tables</a></li>
417<li><a class="reference internal" href="#hyperlinks" id="id36">Hyperlinks</a></li>
418<li><a class="reference internal" href="#footnotes" id="id37">Footnotes</a></li>
419<li><a class="reference internal" href="#images" id="id38">Images</a></li>
420<li><a class="reference internal" href="#comments" id="id39">Comments</a></li>
421<li><a class="reference internal" href="#escaping-mechanism" id="id40">Escaping Mechanism</a></li>
422</ul>
423</li>
424<li><a class="reference internal" href="#habits-to-avoid" id="id41">Habits to Avoid</a></li>
425<li><a class="reference internal" href="#resources" id="id42">Resources</a></li>
426<li><a class="reference internal" href="#references" id="id43">References</a></li>
427<li><a class="reference internal" href="#copyright" id="id44">Copyright</a></li>
428</ul>
429</div>
430<div class="section" id="abstract">
431<h1><a class="toc-backref" href="#id24">Abstract</a></h1>
432<p>This CEP provides a boilerplate or sample template for creating your
433own reStructuredText CEPs.  In conjunction with the content guidelines
434in CEP 1 <a class="footnote-reference" href="#id7" id="id1">[1]</a>, this should make it easy for you to conform your own
435CEPs to the format outlined below.</p>
436<p>Note: if you are reading this CEP via the web, you should first grab
437the text (reStructuredText) source of this CEP in order to complete
438the steps below.  <strong>DO NOT USE THE HTML FILE AS YOUR TEMPLATE!</strong></p>
439<p>To get the source this (or any) CEP, look at the top of the HTML page
440and click on the date &amp; time on the &quot;Last-Modified&quot; line.  It is a
441link to the source text in the Coopr repository.</p>
442<p>If you would prefer not to use markup in your CEP, please see CEP 2,
443&quot;Sample Plaintext CEP Template&quot; <a class="footnote-reference" href="#id8" id="id2">[2]</a>.</p>
444</div>
445<div class="section" id="rationale">
446<h1><a class="toc-backref" href="#id25">Rationale</a></h1>
447<p>CEP submissions come in a wide variety of forms, not all adhering
448to the format guidelines set forth below.  Use this template, in
449conjunction with the format guidelines below, to ensure that your
450CEP submission won't get automatically rejected because of form.</p>
451<p>ReStructuredText is offered as an alternative to plaintext CEPs, to
452allow CEP authors more functionality and expressivity, while
453maintaining easy readability in the source text.  The processed HTML
454form makes the functionality accessible to readers: live hyperlinks,
455styled text, tables, images, and automatic tables of contents, among
456other advantages.</p>
457</div>
458<div class="section" id="how-to-use-this-template">
459<h1><a class="toc-backref" href="#id26">How to Use This Template</a></h1>
460<p>To use this template you must first decide whether your CEP is going to be
461an Informational or Standards Track CEP.  Most CEPs are Standards Track
462because they propose a new feature for Coopr.  When in doubt, read CEP
4631 for details or contact the CEP editors &lt;<a class="reference external" href="mailto:coopr-admin&#64;googlegroups.com">coopr-admin&#64;googlegroups.com</a>&gt;.</p>
464<p>Once you've decided which type of CEP yours is going to be, follow the
465directions below.</p>
466<ul>
467<li><p class="first">Make a copy of this file (<tt class="docutils literal">.txt</tt> file, <strong>not</strong> HTML!) and perform
468the following edits.</p>
469</li>
470<li><p class="first">Replace the &quot;CEP: 3&quot; header with &quot;CEP: XXX&quot; since you don't yet have
471a CEP number assignment.</p>
472</li>
473<li><p class="first">Change the Title header to the title of your CEP.</p>
474</li>
475<li><p class="first">Leave the Version and Last-Modified headers alone; we'll take care
476of those when we check your CEP into Coopr's Subversion repository.
477These headers consist of keywords (&quot;Revision&quot; and &quot;Date&quot; enclosed in
478&quot;$&quot;-signs) which are automatically expanded by the repository.
479Please do not edit the expanded date or revision text.</p>
480</li>
481<li><p class="first">Change the Author header to include your name, and optionally your
482email address.  Be sure to follow the format carefully: your name
483must appear first, and it must not be contained in parentheses.
484Your email address may appear second (or it can be omitted) and if
485it appears, it must appear in angle brackets.  It is okay to
486obfuscate your email address.</p>
487</li>
488<li><p class="first">If there is a mailing list for discussion of your new feature, add a
489Discussions-To header right after the Author header.  You should not
490add a Discussions-To header if the mailing list to be used is either
491<a class="reference external" href="mailto:coopr-forum&#64;googlegroups.com">coopr-forum&#64;googlegroups.com</a> or <a class="reference external" href="mailto:coopr-developers&#64;googlegroups.com">coopr-developers&#64;googlegroups.com</a>,
492or if discussions should be sent to you directly.  Most Informational
493CEPs don't have a Discussions-To header.</p>
494</li>
495<li><p class="first">Change the Status header to &quot;Draft&quot;.</p>
496</li>
497<li><p class="first">For Standards Track CEPs, change the Type header to &quot;Standards
498Track&quot;.</p>
499</li>
500<li><p class="first">For Informational CEPs, change the Type header to &quot;Informational&quot;.</p>
501</li>
502<li><p class="first">For Standards Track CEPs, if your feature depends on the acceptance
503of some other currently in-development CEP, add a Requires header
504right after the Type header.  The value should be the CEP number of
505the CEP yours depends on.  Don't add this header if your dependent
506feature is described in a Final CEP.</p>
507</li>
508<li><p class="first">Change the Created header to today's date.  Be sure to follow the
509format carefully: it must be in <tt class="docutils literal"><span class="pre">dd-mmm-yyyy</span></tt> format, where the
510<tt class="docutils literal">mmm</tt> is the 3 English letter month abbreviation, i.e. one of Jan,
511Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.</p>
512</li>
513<li><p class="first">For Standards Track CEPs, after the Created header, add a
514Coopr-Version header and set the value to the next planned version
515of Coopr, i.e. the one your new feature will hopefully make its
516first appearance in.  Do not use an alpha or beta release
517designation here.  Thus, if the last version of Coopr was 2.2 alpha
5181 and you're hoping to get your new feature into Coopr 2.2, set the
519header to:</p>
520<pre class="literal-block">
521Coopr-Version: 2.2
522</pre>
523</li>
524<li><p class="first">Leave Post-History alone for now; you'll add dates to this header
525each time you post your CEP to <a class="reference external" href="mailto:coopr-forum&#64;googlegroups.com">coopr-forum&#64;googlegroups.com</a> or
526<a class="reference external" href="mailto:coopr-developers&#64;googlegroups.com">coopr-developers&#64;googlegroups.com</a>.  If you posted your CEP to the lists on
527August 14, 2001 and September 3, 2001, the Post-History header would
528look like:</p>
529<pre class="literal-block">
530Post-History: 14-Aug-2001, 03-Sept-2001
531</pre>
532<p>You must manually add new dates and check them in.  If you don't
533have check-in privileges, send your changes to the CEP editors.</p>
534</li>
535<li><p class="first">Add a Replaces header if your CEP obsoletes an earlier CEP.  The
536value of this header is the number of the CEP that your new CEP is
537replacing.  Only add this header if the older CEP is in &quot;final&quot;
538form, i.e. is either Accepted, Final, or Rejected.  You aren't
539replacing an older open CEP if you're submitting a competing idea.</p>
540</li>
541<li><p class="first">Now write your Abstract, Rationale, and other content for your CEP,
542replacing all this gobbledygook with your own text. Be sure to
543adhere to the format guidelines below, specifically on the
544prohibition of tab characters and the indentation requirements.</p>
545</li>
546<li><p class="first">Update your References and Copyright section.  Usually you'll place
547your CEP into the public domain, in which case just leave the
548Copyright section alone.  Alternatively, you can use the <a class="reference external" href="http://www.opencontent.org/openpub/">Open
549Publication License</a> <a class="footnote-reference" href="#id16" id="id17">[6]</a>, but public domain is still strongly
550preferred.</p>
551</li>
552<li><p class="first">Leave the Emacs stanza at the end of this file alone, including the
553formfeed character (&quot;^L&quot;, or <tt class="docutils literal">\f</tt>).</p>
554</li>
555<li><p class="first">Send your CEP submission to the CEP editors at <a class="reference external" href="mailto:coopr-admin&#64;googlegroups.com">coopr-admin&#64;googlegroups.com</a>.</p>
556</li>
557</ul>
558</div>
559<div class="section" id="restructuredtext-cep-formatting-requirements">
560<h1><a class="toc-backref" href="#id27">ReStructuredText CEP Formatting Requirements</a></h1>
561<p>The following is a CEP-specific summary of reStructuredText syntax.
562For the sake of simplicity and brevity, much detail is omitted.  For
563more detail, see <a class="reference internal" href="#resources">Resources</a> below.  <a class="reference internal" href="#literal-blocks">Literal blocks</a> (in which no
564markup processing is done) are used for examples throughout, to
565illustrate the plaintext markup.</p>
566<div class="section" id="general">
567<h2><a class="toc-backref" href="#id28">General</a></h2>
568<p>You must adhere to the Emacs convention of adding two spaces at the
569end of every sentence.  You should fill your paragraphs to column 70,
570but under no circumstances should your lines extend past column 79.
571If your code samples spill over column 79, you should rewrite them.</p>
572<p>Tab characters must never appear in the document at all.  A CEP should
573include the standard Emacs stanza included by example at the bottom of
574this CEP.</p>
575</div>
576<div class="section" id="section-headings">
577<h2><a class="toc-backref" href="#id29">Section Headings</a></h2>
578<p>CEP headings must begin in column zero and the initial letter of each
579word must be capitalized as in book titles.  Acronyms should be in all
580capitals.  Section titles must be adorned with an underline, a single
581repeated punctuation character, which begins in column zero and must
582extend at least as far as the right edge of the title text (4
583characters minimum).  First-level section titles are underlined with
584&quot;=&quot; (equals signs), second-level section titles with &quot;-&quot; (hyphens),
585and third-level section titles with &quot;'&quot; (single quotes or
586apostrophes).  For example:</p>
587<pre class="literal-block">
588First-Level Title
589=================
590
591Second-Level Title
592------------------
593
594Third-Level Title
595'''''''''''''''''
596</pre>
597<p>If there are more than three levels of sections in your CEP, you may
598insert overline/underline-adorned titles for the first and second
599levels as follows:</p>
600<pre class="literal-block">
601============================
602First-Level Title (optional)
603============================
604
605-----------------------------
606Second-Level Title (optional)
607-----------------------------
608
609Third-Level Title
610=================
611
612Fourth-Level Title
613------------------
614
615Fifth-Level Title
616'''''''''''''''''
617</pre>
618<p>You shouldn't have more than five levels of sections in your CEP.  If
619you do, you should consider rewriting it.</p>
620<p>You must use two blank lines between the last line of a section's body
621and the next section heading.  If a subsection heading immediately
622follows a section heading, a single blank line in-between is
623sufficient.</p>
624<p>The body of each section is not normally indented, although some
625constructs do use indentation, as described below.  Blank lines are
626used to separate constructs.</p>
627</div>
628<div class="section" id="paragraphs">
629<h2><a class="toc-backref" href="#id30">Paragraphs</a></h2>
630<p>Paragraphs are left-aligned text blocks separated by blank lines.
631Paragraphs are not indented unless they are part of an indented
632construct (such as a block quote or a list item).</p>
633</div>
634<div class="section" id="inline-markup">
635<h2><a class="toc-backref" href="#id31">Inline Markup</a></h2>
636<p>Portions of text within paragraphs and other text blocks may be
637styled.  For example:</p>
638<pre class="literal-block">
639Text may be marked as *emphasized* (single asterisk markup,
640typically shown in italics) or **strongly emphasized** (double
641asterisks, typically boldface).  ``Inline literals`` (using double
642backquotes) are typically rendered in a monospaced typeface.  No
643further markup recognition is done within the double backquotes,
644so they're safe for any kind of code snippets.
645</pre>
646</div>
647<div class="section" id="block-quotes">
648<h2><a class="toc-backref" href="#id32">Block Quotes</a></h2>
649<p>Block quotes consist of indented body elements.  For example:</p>
650<pre class="literal-block">
651This is a paragraph.
652
653    This is a block quote.
654
655    A block quote may contain many paragraphs.
656</pre>
657<p>Block quotes are used to quote extended passages from other sources.
658Block quotes may be nested inside other body elements.  Use 4 spaces
659per indent level.</p>
660</div>
661<div class="section" id="literal-blocks">
662<h2><a class="toc-backref" href="#id33">Literal Blocks</a></h2>
663<!-- In the text below, double backquotes are used to denote inline
664literals.  "``::``" is written so that the colons will appear in a
665monospaced font; the backquotes (``) are markup, not part of the
666text.  See "Inline Markup" above.
667
668By the way, this is a comment, described in "Comments" below. -->
669<p>Literal blocks are used for code samples or preformatted ASCII art. To
670indicate a literal block, preface the indented text block with
671&quot;<tt class="docutils literal">::</tt>&quot; (two colons).  The literal block continues until the end of
672the indentation.  Indent the text block by 4 spaces.  For example:</p>
673<pre class="literal-block">
674This is a typical paragraph.  A literal block follows.
675
676::
677
678    for a in [5,4,3,2,1]:   # this is program code, shown as-is
679        print a
680    print &quot;it's...&quot;
681    # a literal block continues until the indentation ends
682</pre>
683<p>The paragraph containing only &quot;<tt class="docutils literal">::</tt>&quot; will be completely removed from
684the output; no empty paragraph will remain.  &quot;<tt class="docutils literal">::</tt>&quot; is also
685recognized at the end of any paragraph.  If immediately preceded by
686whitespace, both colons will be removed from the output.  When text
687immediately precedes the &quot;<tt class="docutils literal">::</tt>&quot;, <em>one</em> colon will be removed from
688the output, leaving only one colon visible (i.e., &quot;<tt class="docutils literal">::</tt>&quot; will be
689replaced by &quot;<tt class="docutils literal">:</tt>&quot;).  For example, one colon will remain visible
690here:</p>
691<pre class="literal-block">
692Paragraph::
693
694    Literal block
695</pre>
696</div>
697<div class="section" id="lists">
698<h2><a class="toc-backref" href="#id34">Lists</a></h2>
699<p>Bullet list items begin with one of &quot;-&quot;, &quot;*&quot;, or &quot;+&quot; (hyphen,
700asterisk, or plus sign), followed by whitespace and the list item
701body.  List item bodies must be left-aligned and indented relative to
702the bullet; the text immediately after the bullet determines the
703indentation.  For example:</p>
704<pre class="literal-block">
705This paragraph is followed by a list.
706
707* This is the first bullet list item.  The blank line above the
708  first list item is required; blank lines between list items
709  (such as below this paragraph) are optional.
710
711* This is the first paragraph in the second item in the list.
712
713  This is the second paragraph in the second item in the list.
714  The blank line above this paragraph is required.  The left edge
715  of this paragraph lines up with the paragraph above, both
716  indented relative to the bullet.
717
718  - This is a sublist.  The bullet lines up with the left edge of
719    the text blocks above.  A sublist is a new list so requires a
720    blank line above and below.
721
722* This is the third item of the main list.
723
724This paragraph is not part of the list.
725</pre>
726<p>Enumerated (numbered) list items are similar, but use an enumerator
727instead of a bullet.  Enumerators are numbers (1, 2, 3, ...), letters
728(A, B, C, ...; uppercase or lowercase), or Roman numerals (i, ii, iii,
729iv, ...; uppercase or lowercase), formatted with a period suffix
730(&quot;1.&quot;, &quot;2.&quot;), parentheses (&quot;(1)&quot;, &quot;(2)&quot;), or a right-parenthesis
731suffix (&quot;1)&quot;, &quot;2)&quot;).  For example:</p>
732<pre class="literal-block">
7331. As with bullet list items, the left edge of paragraphs must
734   align.
735
7362. Each list item may contain multiple paragraphs, sublists, etc.
737
738   This is the second paragraph of the second list item.
739
740   a) Enumerated lists may be nested.
741   b) Blank lines may be omitted between list items.
742</pre>
743<p>Definition lists are written like this:</p>
744<pre class="literal-block">
745what
746    Definition lists associate a term with a definition.
747
748how
749    The term is a one-line phrase, and the definition is one
750    or more paragraphs or body elements, indented relative to
751    the term.
752</pre>
753</div>
754<div class="section" id="tables">
755<h2><a class="toc-backref" href="#id35">Tables</a></h2>
756<p>Simple tables are easy and compact:</p>
757<pre class="literal-block">
758=====  =====  =======
759  A      B    A and B
760=====  =====  =======
761False  False  False
762True   False  False
763False  True   False
764True   True   True
765=====  =====  =======
766</pre>
767<p>There must be at least two columns in a table (to differentiate from
768section titles).  Column spans use underlines of hyphens (&quot;Inputs&quot;
769spans the first two columns):</p>
770<pre class="literal-block">
771=====  =====  ======
772   Inputs     Output
773------------  ------
774  A      B    A or B
775=====  =====  ======
776False  False  False
777True   False  True
778False  True   True
779True   True   True
780=====  =====  ======
781</pre>
782<p>Text in a first-column cell starts a new row.  No text in the first
783column indicates a continuation line; the rest of the cells may
784consist of multiple lines.  For example:</p>
785<pre class="literal-block">
786=====  =========================
787col 1  col 2
788=====  =========================
7891      Second column of row 1.
7902      Second column of row 2.
791       Second line of paragraph.
7923      - Second column of row 3.
793
794       - Second item in bullet
795         list (row 3, column 2).
796=====  =========================
797</pre>
798</div>
799<div class="section" id="hyperlinks">
800<h2><a class="toc-backref" href="#id36">Hyperlinks</a></h2>
801<p>When referencing an external web page in the body of a CEP, you should
802include the title of the page in the text, with either an inline
803hyperlink reference to the URL or a footnote reference (see
804<a class="reference internal" href="#footnotes">Footnotes</a> below).  Do not include the URL in the body text of the
805CEP.</p>
806<p>Hyperlink references use backquotes and a trailing underscore to mark
807up the reference text; backquotes are optional if the reference text
808is a single word.  For example:</p>
809<pre class="literal-block">
810In this paragraph, we refer to the `Python web site`_.
811</pre>
812<p>An explicit target provides the URL.  Put targets in a References
813section at the end of the CEP, or immediately after the reference.
814Hyperlink targets begin with two periods and a space (the &quot;explicit
815markup start&quot;), followed by a leading underscore, the reference text,
816a colon, and the URL (absolute or relative):</p>
817<pre class="literal-block">
818.. _Python web site: http://www.python.org/
819</pre>
820<p>The reference text and the target text must match (although the match
821is case-insensitive and ignores differences in whitespace).  Note that
822the underscore trails the reference text but precedes the target text.
823If you think of the underscore as a right-pointing arrow, it points
824<em>away</em> from the reference and <em>toward</em> the target.</p>
825<p>The same mechanism can be used for internal references.  Every unique
826section title implicitly defines an internal hyperlink target.  We can
827make a link to the Abstract section like this:</p>
828<pre class="literal-block">
829Here is a hyperlink reference to the `Abstract`_ section.  The
830backquotes are optional since the reference text is a single word;
831we can also just write: Abstract_.
832</pre>
833<p>Footnotes containing the URLs from external targets will be generated
834automatically at the end of the References section of the CEP, along
835with footnote references linking the reference text to the footnotes.</p>
836<p>Text of the form &quot;CEP x&quot; or &quot;RFC x&quot; (where &quot;x&quot; is a number) will be
837linked automatically to the appropriate URLs.</p>
838</div>
839<div class="section" id="footnotes">
840<h2><a class="toc-backref" href="#id37">Footnotes</a></h2>
841<p>Footnote references consist of a left square bracket, a number, a
842right square bracket, and a trailing underscore:</p>
843<pre class="literal-block">
844This sentence ends with a footnote reference [1]_.
845</pre>
846<p>Whitespace must precede the footnote reference.  Leave a space between
847the footnote reference and the preceding word.</p>
848<p>When referring to another CEP, include the CEP number in the body
849text, such as &quot;CEP 1&quot;.  The title may optionally appear.  Add a
850footnote reference following the title.  For example:</p>
851<pre class="literal-block">
852Refer to CEP 1 [2]_ for more information.
853</pre>
854<p>Add a footnote that includes the CEP's title and author.  It may
855optionally include the explicit URL on a separate line, but only in
856the References section.  Footnotes begin with &quot;.. &quot; (the explicit
857markup start), followed by the footnote marker (no underscores),
858followed by the footnote body.  For example:</p>
859<pre class="literal-block">
860References
861==========
862
863.. [1] CEP 1, &quot;CEP Purpose and Guidelines&quot;, Hart
864   (http://www.coin-or.org/Coopr/ceps/cep-0001.html)
865</pre>
866<p>If you decide to provide an explicit URL for a CEP, please use this as
867the URL template:</p>
868<pre class="literal-block">
869http://www.coin-or.org/Coopr/ceps/cep-xxxx.html
870</pre>
871<p>CEP numbers in URLs must be padded with zeros from the left, so as to
872be exactly 4 characters wide, however CEP numbers in the text are
873never padded.</p>
874<p>During the course of developing your CEP, you may have to add, remove,
875and rearrange footnote references, possibly resulting in mismatched
876references, obsolete footnotes, and confusion.  Auto-numbered
877footnotes allow more freedom.  Instead of a number, use a label of the
878form &quot;#word&quot;, where &quot;word&quot; is a mnemonic consisting of alphanumerics
879plus internal hyphens, underscores, and periods (no whitespace or
880other characters are allowed).  For example:</p>
881<pre class="literal-block">
882Refer to CEP 1 [#CEP-1]_ for more information.
883
884References
885==========
886
887.. [#CEP-1] CEP 1, &quot;CEP Purpose and Guidelines&quot;, Hart
888
889   http://www.coin-or.org/Coopr/ceps/cep-0001.html
890</pre>
891<p>Footnotes and footnote references will be numbered automatically, and
892the numbers will always match.  Once a CEP is finalized, auto-numbered
893labels should be replaced by numbers for simplicity.</p>
894</div>
895<div class="section" id="images">
896<h2><a class="toc-backref" href="#id38">Images</a></h2>
897<p>If your CEP contains a diagram, you may include it in the processed
898output using the &quot;image&quot; directive:</p>
899<pre class="literal-block">
900.. image:: diagram.png
901</pre>
902<p>Any browser-friendly graphics format is possible: .png, .jpeg, .gif,
903.tiff, etc.</p>
904<p>Since this image will not be visible to readers of the CEP in source
905text form, you should consider including a description or ASCII art
906alternative, using a comment (below).</p>
907</div>
908<div class="section" id="comments">
909<h2><a class="toc-backref" href="#id39">Comments</a></h2>
910<p>A comment block is an indented block of arbitrary text immediately
911following an explicit markup start: two periods and whitespace.  Leave
912the &quot;..&quot; on a line by itself to ensure that the comment is not
913misinterpreted as another explicit markup construct.  Comments are not
914visible in the processed document.  For the benefit of those reading
915your CEP in source form, please consider including a descriptions of
916or ASCII art alternatives to any images you include.  For example:</p>
917<pre class="literal-block">
918.. image:: dataflow.png
919
920..
921   Data flows from the input module, through the &quot;black box&quot;
922   module, and finally into (and through) the output module.
923</pre>
924<p>The Emacs stanza at the bottom of this document is inside a comment.</p>
925</div>
926<div class="section" id="escaping-mechanism">
927<h2><a class="toc-backref" href="#id40">Escaping Mechanism</a></h2>
928<p>reStructuredText uses backslashes (&quot;<tt class="docutils literal">\</tt>&quot;) to override the special
929meaning given to markup characters and get the literal characters
930themselves.  To get a literal backslash, use an escaped backslash
931(&quot;<tt class="docutils literal">\\</tt>&quot;).  There are two contexts in which backslashes have no
932special meaning: <a class="reference internal" href="#literal-blocks">literal blocks</a> and inline literals (see <a class="reference internal" href="#inline-markup">Inline
933Markup</a> above).  In these contexts, no markup recognition is done,
934and a single backslash represents a literal backslash, without having
935to double up.</p>
936<p>If you find that you need to use a backslash in your text, consider
937using inline literals or a literal block instead.</p>
938</div>
939</div>
940<div class="section" id="habits-to-avoid">
941<h1><a class="toc-backref" href="#id41">Habits to Avoid</a></h1>
942<p>Many programmers who are familiar with TeX often write quotation marks
943like this:</p>
944<pre class="literal-block">
945`single-quoted' or ``double-quoted''
946</pre>
947<p>Backquotes are significant in reStructuredText, so this practice
948should be avoided.  For ordinary text, use ordinary 'single-quotes' or
949&quot;double-quotes&quot;.  For inline literal text (see <a class="reference internal" href="#inline-markup">Inline Markup</a>
950above), use double-backquotes:</p>
951<pre class="literal-block">
952``literal text: in here, anything goes!``
953</pre>
954</div>
955<div class="section" id="resources">
956<h1><a class="toc-backref" href="#id42">Resources</a></h1>
957<p>Many other constructs and variations are possible.  For more details
958about the reStructuredText markup, in increasing order of
959thoroughness, please see:</p>
960<ul class="simple">
961<li><a class="reference external" href="http://docutils.sourceforge.net/docs/rst/quickstart.html">A ReStructuredText Primer</a> <a class="footnote-reference" href="#id18" id="id19">[7]</a>, a gentle introduction.</li>
962<li><a class="reference external" href="http://docutils.sourceforge.net/docs/rst/quickref.html">Quick reStructuredText</a> <a class="footnote-reference" href="#id20" id="id21">[8]</a>, a users' quick reference.</li>
963<li><a class="reference external" href="http://docutils.sourceforge.net/spec/rst/reStructuredText.html">reStructuredText Markup Specification</a> <a class="footnote-reference" href="#id22" id="id23">[9]</a>, the final authority.</li>
964</ul>
965<p>The processing of reStructuredText CEPs is done using <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> <a class="footnote-reference" href="#id9" id="id11">[3]</a>.  If
966you have a question or require assistance with reStructuredText or
967Docutils, please <a class="reference external" href="mailto:docutils-users&#64;lists.sourceforge.net?subject=CEPs">post a message</a> <a class="footnote-reference" href="#id12" id="id13">[4]</a> to the <a class="reference external" href="http://docutils.sf.net/docs/user/mailing-lists.html#docutils-users">Docutils-users mailing
968list</a> <a class="footnote-reference" href="#id14" id="id15">[5]</a>.  The <a class="reference external" href="http://docutils.sourceforge.net/">Docutils project web site</a> <a class="footnote-reference" href="#id9" id="id10">[3]</a> has more information.</p>
969</div>
970<div class="section" id="references">
971<h1><a class="toc-backref" href="#id43">References</a></h1>
972<table class="docutils footnote" frame="void" id="id7" rules="none">
973<colgroup><col class="label" /><col /></colgroup>
974<tbody valign="top">
975<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>CEP 1, CEP Purpose and Guidelines, Hart
976(<a class="reference external" href="http://www.coin-or.org/Coopr/ceps/cep-0001.html">http://www.coin-or.org/Coopr/ceps/cep-0001.html</a>)</td></tr>
977</tbody>
978</table>
979<table class="docutils footnote" frame="void" id="id8" rules="none">
980<colgroup><col class="label" /><col /></colgroup>
981<tbody valign="top">
982<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>CEP 2, Sample Plaintext CEP Template, Hart
983(<a class="reference external" href="http://www.coin-or.org/Coopr/ceps/cep-0002.html">http://www.coin-or.org/Coopr/ceps/cep-0002.html</a>)</td></tr>
984</tbody>
985</table>
986<table class="docutils footnote" frame="void" id="id9" rules="none">
987<colgroup><col class="label" /><col /></colgroup>
988<tbody valign="top">
989<tr><td class="label">[3]</td><td><em>(<a class="fn-backref" href="#id10">1</a>, <a class="fn-backref" href="#id11">2</a>)</em> <a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a></td></tr>
990</tbody>
991</table>
992<table class="docutils footnote" frame="void" id="id12" rules="none">
993<colgroup><col class="label" /><col /></colgroup>
994<tbody valign="top">
995<tr><td class="label"><a class="fn-backref" href="#id13">[4]</a></td><td><a class="reference external" href="mailto:docutils-users&#64;lists.sourceforge.net?subject=CEPs">mailto:docutils-users&#64;lists.sourceforge.net?subject=CEPs</a></td></tr>
996</tbody>
997</table>
998<table class="docutils footnote" frame="void" id="id14" rules="none">
999<colgroup><col class="label" /><col /></colgroup>
1000<tbody valign="top">
1001<tr><td class="label"><a class="fn-backref" href="#id15">[5]</a></td><td><a class="reference external" href="http://docutils.sf.net/docs/user/mailing-lists.html#docutils-users">http://docutils.sf.net/docs/user/mailing-lists.html#docutils-users</a></td></tr>
1002</tbody>
1003</table>
1004<table class="docutils footnote" frame="void" id="id16" rules="none">
1005<colgroup><col class="label" /><col /></colgroup>
1006<tbody valign="top">
1007<tr><td class="label"><a class="fn-backref" href="#id17">[6]</a></td><td><a class="reference external" href="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</a></td></tr>
1008</tbody>
1009</table>
1010<table class="docutils footnote" frame="void" id="id18" rules="none">
1011<colgroup><col class="label" /><col /></colgroup>
1012<tbody valign="top">
1013<tr><td class="label"><a class="fn-backref" href="#id19">[7]</a></td><td><a class="reference external" href="http://docutils.sourceforge.net/docs/rst/quickstart.html">http://docutils.sourceforge.net/docs/rst/quickstart.html</a></td></tr>
1014</tbody>
1015</table>
1016<table class="docutils footnote" frame="void" id="id20" rules="none">
1017<colgroup><col class="label" /><col /></colgroup>
1018<tbody valign="top">
1019<tr><td class="label"><a class="fn-backref" href="#id21">[8]</a></td><td><a class="reference external" href="http://docutils.sourceforge.net/docs/rst/quickref.html">http://docutils.sourceforge.net/docs/rst/quickref.html</a></td></tr>
1020</tbody>
1021</table>
1022<table class="docutils footnote" frame="void" id="id22" rules="none">
1023<colgroup><col class="label" /><col /></colgroup>
1024<tbody valign="top">
1025<tr><td class="label"><a class="fn-backref" href="#id23">[9]</a></td><td><a class="reference external" href="http://docutils.sourceforge.net/spec/rst/reStructuredText.html">http://docutils.sourceforge.net/spec/rst/reStructuredText.html</a></td></tr>
1026</tbody>
1027</table>
1028</div>
1029<div class="section" id="copyright">
1030<h1><a class="toc-backref" href="#id44">Copyright</a></h1>
1031<p>Copyright 2010 by Sandia National Laboratories.  Sandia National
1032Laboratories is a multi-program laboratory operated by Sandia
1033Corporation, a wholly owned subsidiary of Lockheed Martin company, for
1034the U.S. Department of Energy's National Nuclear Security Administration
1035under contract DE-AC04-94AL85000.</p>
1036<!-- Local Variables:
1037mode: indented-text
1038indent-tabs-mode: nil
1039sentence-end-double-space: t
1040fill-column: 70
1041coding: utf-8
1042End: -->
1043</div>
1044
1045</div>
1046</body>
1047</html>
Note: See TracBrowser for help on using the repository browser.