/[gentoo]/xml/htdocs/proj/en/glep/glep-0002.html
Gentoo

Contents of /xml/htdocs/proj/en/glep/glep-0002.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.9 - (show annotations) (download) (as text)
Sun Oct 14 17:00:15 2007 UTC (6 years, 9 months ago) by antarus
Branch: MAIN
CVS Tags: HEAD
Changes since 1.8: +4 -251 lines
File MIME type: text/html
the canary on 53 went well, changing the rest

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
5 <head>
6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
8 <title>GLEP 2 -- Sample ReStructuredText GLEP Template</title>
9 <link rel="stylesheet" href="tools/glep.css" type="text/css" />
10 </head>
11 <body bgcolor="white">
12 <table class="navigation" cellpadding="0" cellspacing="0"
13 width="100%" border="0">
14 <tr><td class="navicon" width="150" height="35">
15 <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
16 <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
17 border="0" width="150" height="35" /></a></td>
18 <td class="textlinks" align="left">
19 [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
20 [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
21 [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0002.txt">GLEP Source</a></b>]
22 </td></tr></table>
23 <table class="rfc2822 docutils field-list" frame="void" rules="none">
24 <col class="field-name" />
25 <col class="field-body" />
26 <tbody valign="top">
27 <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">2</td>
28 </tr>
29 <tr class="field"><th class="field-name">Title:</th><td class="field-body">Sample ReStructuredText GLEP Template</td>
30 </tr>
31 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.4</td>
32 </tr>
33 <tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0002.txt?cvsroot=gentoo">2003/07/19 12:09:20</a></td>
34 </tr>
35 <tr class="field"><th class="field-name">Author:</th><td class="field-body">Grant Goodyear &lt;g2boojum&#32;&#97;t&#32;gentoo.org&gt;,</td>
36 </tr>
37 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Active</td>
38 </tr>
39 <tr class="field"><th class="field-name">Type:</th><td class="field-body">Informational</td>
40 </tr>
41 <tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="glep-0002.html">text/x-rst</a></td>
42 </tr>
43 <tr class="field"><th class="field-name">Created:</th><td class="field-body">31 May 2003</td>
44 </tr>
45 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">2-Jun-2003</td>
46 </tr>
47 </tbody>
48 </table>
49 <hr />
50 <div class="contents topic">
51 <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
52 <ul class="simple">
53 <li><a class="reference" href="#credits" id="id23" name="id23">Credits</a></li>
54 <li><a class="reference" href="#abstract" id="id24" name="id24">Abstract</a></li>
55 <li><a class="reference" href="#motivation" id="id25" name="id25">Motivation</a></li>
56 <li><a class="reference" href="#rationale" id="id26" name="id26">Rationale</a></li>
57 <li><a class="reference" href="#backwards-compatibility" id="id27" name="id27">Backwards Compatibility</a></li>
58 <li><a class="reference" href="#how-to-use-this-template" id="id28" name="id28">How to Use This Template</a></li>
59 <li><a class="reference" href="#restructuredtext-glep-formatting-requirements" id="id29" name="id29">ReStructuredText GLEP Formatting Requirements</a><ul>
60 <li><a class="reference" href="#general" id="id30" name="id30">General</a></li>
61 <li><a class="reference" href="#section-headings" id="id31" name="id31">Section Headings</a></li>
62 <li><a class="reference" href="#paragraphs" id="id32" name="id32">Paragraphs</a></li>
63 <li><a class="reference" href="#inline-markup" id="id33" name="id33">Inline Markup</a></li>
64 <li><a class="reference" href="#block-quotes" id="id34" name="id34">Block Quotes</a></li>
65 <li><a class="reference" href="#literal-blocks" id="id35" name="id35">Literal Blocks</a></li>
66 <li><a class="reference" href="#lists" id="id36" name="id36">Lists</a></li>
67 <li><a class="reference" href="#tables" id="id37" name="id37">Tables</a></li>
68 <li><a class="reference" href="#hyperlinks" id="id38" name="id38">Hyperlinks</a></li>
69 <li><a class="reference" href="#footnotes" id="id39" name="id39">Footnotes</a></li>
70 <li><a class="reference" href="#images" id="id40" name="id40">Images</a></li>
71 <li><a class="reference" href="#comments" id="id41" name="id41">Comments</a></li>
72 <li><a class="reference" href="#escaping-mechanism" id="id42" name="id42">Escaping Mechanism</a></li>
73 </ul>
74 </li>
75 <li><a class="reference" href="#habits-to-avoid" id="id43" name="id43">Habits to Avoid</a></li>
76 <li><a class="reference" href="#resources" id="id44" name="id44">Resources</a></li>
77 <li><a class="reference" href="#references" id="id45" name="id45">References</a></li>
78 <li><a class="reference" href="#copyright" id="id46" name="id46">Copyright</a></li>
79 </ul>
80 </div>
81 <div class="section">
82 <h1><a class="toc-backref" href="#id23" id="credits" name="credits">Credits</a></h1>
83 <p>The text of this GLEP was, to a significant extent, stolen from Python's
84 <a class="footnote-reference" href="#python" id="id1" name="id1">[1]</a> PEP-0012 <a class="footnote-reference" href="#pep12" id="id2" name="id2">[2]</a> by David Goodger and Barry A. Warsaw.</p>
85 </div>
86 <div class="section">
87 <h1><a class="toc-backref" href="#id24" id="abstract" name="abstract">Abstract</a></h1>
88 <p>This GLEP provides a boilerplate or sample template for creating your own
89 reStructuredText GLEPs. In conjunction with the content guidelines in GLEP 1
90 <a class="footnote-reference" href="#glep1" id="id3" name="id3">[3]</a>, this should make it easy for you to conform your own GLEPs to the
91 format outlined below.</p>
92 <p>Note: if you are reading this GLEP via the web, you should first grab the text
93 (reStructuredText) source of this GLEP in order to complete the steps below.
94 <strong>DO NOT USE THE HTML FILE AS YOUR TEMPLATE!</strong></p>
95 <p>To get the source of this (or any) GLEP, look at the top of the HTML page and
96 click on the link titled &quot;GLEP Source&quot;.</p>
97 </div>
98 <div class="section">
99 <h1><a class="toc-backref" href="#id25" id="motivation" name="motivation">Motivation</a></h1>
100 <p>Provide adequate motivation here. In this particular case, we need to provide
101 people with the information necessary to submit GLEPs in the proper form.</p>
102 </div>
103 <div class="section">
104 <h1><a class="toc-backref" href="#id26" id="rationale" name="rationale">Rationale</a></h1>
105 <p>GLEP submissions come in a wide variety of forms, not all adhering to the
106 format guidelines set forth below. Use this template, in conjunction with the
107 format guidelines below, to ensure that your GLEP submission won't get
108 automatically rejected because of form.</p>
109 <p>ReStructuredText is used to allow GLEP authors more functionality and
110 expressivity, while maintaining easy readability in the source text. The
111 processed HTML form makes the functionality accessible to readers: live
112 hyperlinks, styled text, tables, images, and automatic tables of contents,
113 among other advantages.</p>
114 </div>
115 <div class="section">
116 <h1><a class="toc-backref" href="#id27" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
117 <p>Not a problem for this GLEP. This section should be included <em>even</em> when it
118 is only to state that there are no backwards compatibility issues.</p>
119 </div>
120 <div class="section">
121 <h1><a class="toc-backref" href="#id28" id="how-to-use-this-template" name="how-to-use-this-template">How to Use This Template</a></h1>
122 <p>To use this template you must first decide whether your GLEP is going to be an
123 Informational or Standards Track GLEP. Most GLEPs are Standards Track because
124 they propose new functionality for some aspect of Gentoo Linux. When in
125 doubt, read GLEP 1 for details or contact the GLEP editors &lt;<a class="reference" href="mailto:glep&#64;gentoo.org">glep&#64;gentoo.org</a>&gt;.</p>
126 <p>Once you've decided which type of GLEP yours is going to be, follow the
127 directions below.</p>
128 <ul>
129 <li><p class="first">Make a copy of this file (<tt class="docutils literal"><span class="pre">.txt</span></tt> file, <strong>not</strong> HTML!) and perform
130 the following edits.</p>
131 </li>
132 <li><p class="first">Replace the &quot;GLEP: 2&quot; header with &quot;GLEP: XXX&quot; since you don't yet have
133 a GLEP number assignment.</p>
134 </li>
135 <li><p class="first">Change the Title header to the title of your GLEP.</p>
136 </li>
137 <li><p class="first">Leave the Version and Last-Modified headers alone; we'll take care
138 of those when we check your GLEP into CVS.</p>
139 </li>
140 <li><p class="first">Change the Author header to include your name, and optionally your
141 email address. Be sure to follow the format carefully: your name must
142 appear first, and it must not be contained in parentheses. Your email
143 address may appear second (or it can be omitted) and if it appears, it must
144 appear in angle brackets. Your e-mail address
145 here will e automatically obfuscated.</p>
146 </li>
147 <li><p class="first">If there is a forum thread or a mailing list for discussion
148 of your new feature, add a Discussions-To header right after the Author
149 header. You should not add a Discussions-To header if the mailing list to
150 be used is <a class="reference" href="mailto:gentoo-dev&#64;gentoo.org">gentoo-dev&#64;gentoo.org</a>, or if discussions should be sent to you
151 directly. Most Informational GLEPs don't have a Discussions-To header.</p>
152 </li>
153 <li><p class="first">Change the Status header to &quot;Draft&quot;.</p>
154 </li>
155 <li><p class="first">For Standards Track GLEPs, change the Type header to &quot;Standards
156 Track&quot;.</p>
157 </li>
158 <li><p class="first">For Informational GLEPs, change the Type header to &quot;Informational&quot;.</p>
159 </li>
160 <li><p class="first">For Standards Track GLEPs, if your feature depends on the acceptance
161 of some other currently in-development GLEP, add a Requires header right
162 after the Type header. The value should be the GLEP number of the GLEP
163 yours depends on. Don't add this header if your dependent feature is
164 described in a Final GLEP.</p>
165 </li>
166 <li><p class="first">Change the Created header to today's date. Be sure to follow the
167 format carefully: it must be in <tt class="docutils literal"><span class="pre">dd-mmm-yyyy</span></tt> format, where the <tt class="docutils literal"><span class="pre">mmm</span></tt> is
168 the 3 English letter month abbreviation, i.e. one of Jan, Feb, Mar, Apr,
169 May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.</p>
170 </li>
171 <li><p class="first">Leave Post-History alone for now; you'll add dates to this header
172 each time you post your GLEP to <a class="reference" href="mailto:gentoo-dev&#64;gentoo.org">gentoo-dev&#64;gentoo.org</a>. If you posted your
173 GLEP to the list on August 14, 2003 and September 3, 2003, the Post-History
174 header would look like:</p>
175 <pre class="literal-block">
176 Post-History: 14-Aug-2003, 03-Sept-2003
177 </pre>
178 <p>You must manually add new dates and check them in. If you don't have
179 check-in privileges, send your changes to the GLEP editors.</p>
180 </li>
181 <li><p class="first">Add a Replaces header if your GLEP obsoletes an earlier GLEP. The
182 value of this header is the number of the GLEP that your new GLEP is
183 replacing. Only add this header if the older GLEP is in &quot;final&quot; form, i.e.
184 is either Accepted, Final, or Rejected. You aren't replacing an older open
185 GLEP if you're submitting a competing idea.</p>
186 </li>
187 <li><p class="first">Now write your Abstract, Rationale, and other content for your GLEP,
188 replacing all of this gobbledygook with your own text. Be sure to adhere to
189 the format guidelines below, specifically on the indentation requirements.</p>
190 </li>
191 <li><p class="first">Update your References and Copyright section. Usually you'll place
192 your GLEP into the public domain, in which case just leave the Copyright
193 section alone. Alternatively, you can use the <a class="reference" href="http://www.opencontent.org/openpub/">Open Publication License</a> <a class="footnote-reference" href="#id15" id="id16" name="id16">[7]</a>,
194 but public domain is still strongly preferred.</p>
195 </li>
196 <li><p class="first">Send your GLEP submission to the GLEP editors at <a class="reference" href="mailto:glep&#64;gentoo.org">glep&#64;gentoo.org</a>.</p>
197 </li>
198 </ul>
199 </div>
200 <div class="section">
201 <h1><a class="toc-backref" href="#id29" id="restructuredtext-glep-formatting-requirements" name="restructuredtext-glep-formatting-requirements">ReStructuredText GLEP Formatting Requirements</a></h1>
202 <p>The following is a GLEP-specific summary of reStructuredText syntax. For the
203 sake of simplicity and brevity, much detail is omitted. For more detail, see
204 <a class="reference" href="#resources">Resources</a> below. <a class="reference" href="#literal-blocks">Literal blocks</a> (in which no markup processing is done)
205 are used for examples throughout, to illustrate the plaintext markup.</p>
206 <div class="section">
207 <h2><a class="toc-backref" href="#id30" id="general" name="general">General</a></h2>
208 <p>You must adhere to the convention of adding two spaces at the end of every
209 sentence. You should fill your paragraphs to column 70, but under no
210 circumstances should your lines extend past column 79. If your code samples
211 spill over column 79, you should rewrite them.</p>
212 </div>
213 <div class="section">
214 <h2><a class="toc-backref" href="#id31" id="section-headings" name="section-headings">Section Headings</a></h2>
215 <p>GLEP headings must begin in column zero and the initial letter of each word
216 must be capitalized as in book titles. Acronyms should be in all capitals.
217 Section titles must be adorned with an underline, a single repeated
218 punctuation character, which begins in column zero and must extend at least as
219 far as the right edge of the title text (4 characters minimum). First-level
220 section titles are underlined with &quot;=&quot; (equals signs), second-level section
221 titles with &quot;-&quot; (hyphens), and third-level section titles with &quot;'&quot; (single
222 quotes or apostrophes). For example:</p>
223 <pre class="literal-block">
224 First-Level Title
225 =================
226
227 Second-Level Title
228 ------------------
229
230 Third-Level Title
231 '''''''''''''''''
232 </pre>
233 <p>If there are more than three levels of sections in your GLEP, you may insert
234 overline/underline-adorned titles for the first and second levels as follows:</p>
235 <pre class="literal-block">
236 ============================
237 First-Level Title (optional)
238 ============================
239
240 -----------------------------
241 Second-Level Title (optional)
242 -----------------------------
243
244 Third-Level Title
245 =================
246
247 Fourth-Level Title
248 ------------------
249
250 Fifth-Level Title
251 '''''''''''''''''
252 </pre>
253 <p>You shouldn't have more than five levels of sections in your GLEP. If you do,
254 you should consider rewriting it.</p>
255 <p>You must use two blank lines between the last line of a section's body and the
256 next section heading. If a subsection heading immediately follows a section
257 heading, a single blank line in-between is sufficient.</p>
258 <p>The body of each section is not normally indented, although some constructs do
259 use indentation, as described below. Blank lines are used to separate
260 constructs.</p>
261 </div>
262 <div class="section">
263 <h2><a class="toc-backref" href="#id32" id="paragraphs" name="paragraphs">Paragraphs</a></h2>
264 <p>Paragraphs are left-aligned text blocks separated by blank lines. Paragraphs
265 are not indented unless they are part of an indented construct (such as a
266 block quote or a list item).</p>
267 </div>
268 <div class="section">
269 <h2><a class="toc-backref" href="#id33" id="inline-markup" name="inline-markup">Inline Markup</a></h2>
270 <p>Portions of text within paragraphs and other text blocks may be
271 styled. For example:</p>
272 <pre class="literal-block">
273 Text may be marked as *emphasized* (single asterisk markup,
274 typically shown in italics) or **strongly emphasized** (double
275 asterisks, typically boldface). ``Inline literals`` (using double
276 backquotes) are typically rendered in a monospaced typeface. No
277 further markup recognition is done within the double backquotes,
278 so they're safe for any kind of code snippets.
279 </pre>
280 </div>
281 <div class="section">
282 <h2><a class="toc-backref" href="#id34" id="block-quotes" name="block-quotes">Block Quotes</a></h2>
283 <p>Block quotes consist of indented body elements. For example:</p>
284 <pre class="literal-block">
285 This is a paragraph.
286
287 This is a block quote.
288
289 A block quote may contain many paragraphs.
290 </pre>
291 <p>Block quotes are used to quote extended passages from other sources.
292 Block quotes may be nested inside other body elements. Use a 4-space tab
293 per indent level.</p>
294 </div>
295 <div class="section">
296 <h2><a class="toc-backref" href="#id35" id="literal-blocks" name="literal-blocks">Literal Blocks</a></h2>
297 <!-- In the text below, double backquotes are used to denote inline
298 literals. "``::``" is written so that the colons will appear in a
299 monospaced font; the backquotes (``) are markup, not part of the
300 text. See "Inline Markup" above.
301
302 By the way, this is a comment, described in "Comments" below. -->
303 <p>Literal blocks are used for code samples or preformatted ASCII art. To
304 indicate a literal block, preface the indented text block with
305 &quot;<tt class="docutils literal"><span class="pre">::</span></tt>&quot; (two colons). The literal block continues until the end of
306 the indentation. Indent the text block by a tab. For example:</p>
307 <pre class="literal-block">
308 This is a typical paragraph. A literal block follows.
309
310 ::
311
312 for a in [5,4,3,2,1]: # this is program code, shown as-is
313 print a
314 print &quot;it's...&quot;
315 # a literal block continues until the indentation ends
316 </pre>
317 <p>The paragraph containing only &quot;<tt class="docutils literal"><span class="pre">::</span></tt>&quot; will be completely removed from
318 the output; no empty paragraph will remain. &quot;<tt class="docutils literal"><span class="pre">::</span></tt>&quot; is also
319 recognized at the end of any paragraph. If immediately preceded by
320 whitespace, both colons will be removed from the output. When text
321 immediately precedes the &quot;<tt class="docutils literal"><span class="pre">::</span></tt>&quot;, <em>one</em> colon will be removed from
322 the output, leaving only one colon visible (i.e., &quot;<tt class="docutils literal"><span class="pre">::</span></tt>&quot; will be
323 replaced by &quot;<tt class="docutils literal"><span class="pre">:</span></tt>&quot;). For example, one colon will remain visible
324 here:</p>
325 <pre class="literal-block">
326 Paragraph::
327
328 Literal block
329 </pre>
330 </div>
331 <div class="section">
332 <h2><a class="toc-backref" href="#id36" id="lists" name="lists">Lists</a></h2>
333 <p>Bullet list items begin with one of &quot;-&quot;, &quot;*&quot;, or &quot;+&quot; (hyphen,
334 asterisk, or plus sign), followed by whitespace and the list item
335 body. List item bodies must be left-aligned and indented relative to
336 the bullet; the text immediately after the bullet determines the
337 indentation. For example:</p>
338 <pre class="literal-block">
339 This paragraph is followed by a list.
340
341 * This is the first bullet list item. The blank line above the
342 first list item is required; blank lines between list items
343 (such as below this paragraph) are optional.
344
345 * This is the first paragraph in the second item in the list.
346
347 This is the second paragraph in the second item in the list.
348 The blank line above this paragraph is required. The left edge
349 of this paragraph lines up with the paragraph above, both
350 indented relative to the bullet.
351
352 - This is a sublist. The bullet lines up with the left edge of
353 the text blocks above. A sublist is a new list so requires a
354 blank line above and below.
355
356 * This is the third item of the main list.
357
358 This paragraph is not part of the list.
359 </pre>
360 <p>Enumerated (numbered) list items are similar, but use an enumerator
361 instead of a bullet. Enumerators are numbers (1, 2, 3, ...), letters
362 (A, B, C, ...; uppercase or lowercase), or Roman numerals (i, ii, iii,
363 iv, ...; uppercase or lowercase), formatted with a period suffix
364 (&quot;1.&quot;, &quot;2.&quot;), parentheses (&quot;(1)&quot;, &quot;(2)&quot;), or a right-parenthesis
365 suffix (&quot;1)&quot;, &quot;2)&quot;). For example:</p>
366 <pre class="literal-block">
367 1. As with bullet list items, the left edge of paragraphs must
368 align.
369
370 2. Each list item may contain multiple paragraphs, sublists, etc.
371
372 This is the second paragraph of the second list item.
373
374 a) Enumerated lists may be nested.
375 b) Blank lines may be omitted between list items.
376 </pre>
377 <p>Definition lists are written like this:</p>
378 <pre class="literal-block">
379 what
380 Definition lists associate a term with a definition.
381
382 how
383 The term is a one-line phrase, and the definition is one
384 or more paragraphs or body elements, indented relative to
385 the term.
386 </pre>
387 </div>
388 <div class="section">
389 <h2><a class="toc-backref" href="#id37" id="tables" name="tables">Tables</a></h2>
390 <p>Simple tables are easy and compact:</p>
391 <pre class="literal-block">
392 ===== ===== =======
393 A B A and B
394 ===== ===== =======
395 False False False
396 True False False
397 False True False
398 True True True
399 ===== ===== =======
400 </pre>
401 <p>There must be at least two columns in a table (to differentiate from
402 section titles). Column spans use underlines of hyphens (&quot;Inputs&quot;
403 spans the first two columns):</p>
404 <pre class="literal-block">
405 ===== ===== ======
406 Inputs Output
407 ------------ ------
408 A B A or B
409 ===== ===== ======
410 False False False
411 True False True
412 False True True
413 True True True
414 ===== ===== ======
415 </pre>
416 <p>Text in a first-column cell starts a new row. No text in the first
417 column indicates a continuation line; the rest of the cells may
418 consist of multiple lines. For example:</p>
419 <pre class="literal-block">
420 ===== =========================
421 col 1 col 2
422 ===== =========================
423 1 Second column of row 1.
424 2 Second column of row 2.
425 Second line of paragraph.
426 3 - Second column of row 3.
427
428 - Second item in bullet
429 list (row 3, column 2).
430 ===== =========================
431 </pre>
432 </div>
433 <div class="section">
434 <h2><a class="toc-backref" href="#id38" id="hyperlinks" name="hyperlinks">Hyperlinks</a></h2>
435 <p>When referencing an external web page in the body of a GLEP, you should
436 include the title of the page in the text, with either an inline
437 hyperlink reference to the URL or a footnote reference (see
438 <a class="reference" href="#footnotes">Footnotes</a> below). Do not include the URL in the body text of the
439 GLEP.</p>
440 <p>Hyperlink references use backquotes and a trailing underscore to mark
441 up the reference text; backquotes are optional if the reference text
442 is a single word. For example:</p>
443 <pre class="literal-block">
444 In this paragraph, we refer to the `Python web site`_.
445 </pre>
446 <p>An explicit target provides the URL. Put targets in a References
447 section at the end of the GLEP, or immediately after the reference.
448 Hyperlink targets begin with two periods and a space (the &quot;explicit
449 markup start&quot;), followed by a leading underscore, the reference text,
450 a colon, and the URL (absolute or relative):</p>
451 <pre class="literal-block">
452 .. _Python web site: http://www.python.org/
453 </pre>
454 <p>The reference text and the target text must match (although the match
455 is case-insensitive and ignores differences in whitespace). Note that
456 the underscore trails the reference text but precedes the target text.
457 If you think of the underscore as a right-pointing arrow, it points
458 <em>away</em> from the reference and <em>toward</em> the target.</p>
459 <p>The same mechanism can be used for internal references. Every unique
460 section title implicitly defines an internal hyperlink target. We can
461 make a link to the Abstract section like this:</p>
462 <pre class="literal-block">
463 Here is a hyperlink reference to the `Abstract`_ section. The
464 backquotes are optional since the reference text is a single word;
465 we can also just write: Abstract_.
466 </pre>
467 <p>Footnotes containing the URLs from external targets will be generated
468 automatically at the end of the References section of the GLEP, along
469 with footnote references linking the reference text to the footnotes.</p>
470 <p>Text of the form &quot;GLEP x&quot; or &quot;RFC x&quot; (where &quot;x&quot; is a number) will be
471 linked automatically to the appropriate URLs.</p>
472 </div>
473 <div class="section">
474 <h2><a class="toc-backref" href="#id39" id="footnotes" name="footnotes">Footnotes</a></h2>
475 <p>Footnote references consist of a left square bracket, a number, a
476 right square bracket, and a trailing underscore:</p>
477 <pre class="literal-block">
478 This sentence ends with a footnote reference [1]_.
479 </pre>
480 <p>Whitespace must precede the footnote reference. Leave a space between
481 the footnote reference and the preceding word.</p>
482 <p>When referring to another GLEP, include the GLEP number in the body
483 text, such as &quot;GLEP 1&quot;. The title may optionally appear. Add a
484 footnote reference following the title. For example:</p>
485 <pre class="literal-block">
486 Refer to GLEP 1 [2]_ for more information.
487 </pre>
488 <p>Add a footnote that includes the GLEP's title and author. It may
489 optionally include the explicit URL on a separate line, but only in
490 the References section. Footnotes begin with &quot;.. &quot; (the explicit
491 markup start), followed by the footnote marker (no underscores),
492 followed by the footnote body. For example:</p>
493 <pre class="literal-block">
494 References
495 ==========
496
497 .. [2] GLEP 1, &quot;GLEP Purpose and Guidelines&quot;, Goodyear, Warsaw, Hylton
498 (http://glep.gentoo.org/glep-0001.html)
499 </pre>
500 <p>If you decide to provide an explicit URL for a GLEP, please use this as
501 the URL template:</p>
502 <pre class="literal-block">
503 http://glep.gentoo.org/glep-xxxx.html
504 </pre>
505 <p>GLEP numbers in URLs must be padded with zeros from the left, so as to
506 be exactly 4 characters wide, however GLEP numbers in the text are
507 never padded.</p>
508 <p>During the course of developing your GLEP, you may have to add, remove,
509 and rearrange footnote references, possibly resulting in mismatched
510 references, obsolete footnotes, and confusion. Auto-numbered
511 footnotes allow more freedom. Instead of a number, use a label of the
512 form &quot;#word&quot;, where &quot;word&quot; is a mnemonic consisting of alphanumerics
513 plus internal hyphens, underscores, and periods (no whitespace or
514 other characters are allowed). For example:</p>
515 <pre class="literal-block">
516 Refer to GLEP 1 [#GLEP-1]_ for more information.
517
518 References
519 ==========
520
521 .. [#GLEP-1] GLEP 1, &quot;GLEP Purpose and Guidelines&quot;, Goodyear
522 http://glep.gentoo.org/glep-0001.html
523 </pre>
524 <p>Footnotes and footnote references will be numbered automatically, and
525 the numbers will always match. Once a GLEP is finalized, auto-numbered
526 labels should be replaced by numbers for simplicity.</p>
527 </div>
528 <div class="section">
529 <h2><a class="toc-backref" href="#id40" id="images" name="images">Images</a></h2>
530 <p>If your GLEP contains a diagram, you may include it in the processed
531 output using the &quot;image&quot; directive:</p>
532 <pre class="literal-block">
533 .. image:: diagram.png
534 </pre>
535 <p>Any browser-friendly graphics format is possible: .png, .jpeg, .gif,
536 .tiff, etc.</p>
537 <p>Since this image will not be visible to readers of the GLEP in source
538 text form, you should consider including a description or ASCII art
539 alternative, using a comment (below).</p>
540 </div>
541 <div class="section">
542 <h2><a class="toc-backref" href="#id41" id="comments" name="comments">Comments</a></h2>
543 <p>A comment block is an indented block of arbitrary text immediately
544 following an explicit markup start: two periods and whitespace. Leave
545 the &quot;..&quot; on a line by itself to ensure that the comment is not
546 misinterpreted as another explicit markup construct. Comments are not
547 visible in the processed document. For the benefit of those reading
548 your GLEP in source form, please consider including a descriptions of
549 or ASCII art alternatives to any images you include. For example:</p>
550 <pre class="literal-block">
551 .. image:: dataflow.png
552
553 ..
554 Data flows from the input module, through the &quot;black box&quot;
555 module, and finally into (and through) the output module.
556 </pre>
557 </div>
558 <div class="section">
559 <h2><a class="toc-backref" href="#id42" id="escaping-mechanism" name="escaping-mechanism">Escaping Mechanism</a></h2>
560 <p>reStructuredText uses backslashes (&quot;<tt class="docutils literal"><span class="pre">\</span></tt>&quot;) to override the special
561 meaning given to markup characters and get the literal characters
562 themselves. To get a literal backslash, use an escaped backslash
563 (&quot;<tt class="docutils literal"><span class="pre">\\</span></tt>&quot;). There are two contexts in which backslashes have no
564 special meaning: <a class="reference" href="#literal-blocks">literal blocks</a> and inline literals (see <a class="reference" href="#inline-markup">Inline
565 Markup</a> above). In these contexts, no markup recognition is done,
566 and a single backslash represents a literal backslash, without having
567 to double up.</p>
568 <p>If you find that you need to use a backslash in your text, consider
569 using inline literals or a literal block instead.</p>
570 </div>
571 </div>
572 <div class="section">
573 <h1><a class="toc-backref" href="#id43" id="habits-to-avoid" name="habits-to-avoid">Habits to Avoid</a></h1>
574 <p>Many programmers who are familiar with TeX often write quotation marks
575 like this:</p>
576 <pre class="literal-block">
577 `single-quoted' or ``double-quoted''
578 </pre>
579 <p>Backquotes are significant in reStructuredText, so this practice
580 should be avoided. For ordinary text, use ordinary 'single-quotes' or
581 &quot;double-quotes&quot;. For inline literal text (see <a class="reference" href="#inline-markup">Inline Markup</a>
582 above), use double-backquotes:</p>
583 <pre class="literal-block">
584 ``literal text: in here, anything goes!``
585 </pre>
586 </div>
587 <div class="section">
588 <h1><a class="toc-backref" href="#id44" id="resources" name="resources">Resources</a></h1>
589 <p>Many other constructs and variations are possible. For more details
590 about the reStructuredText markup, in increasing order of
591 thoroughness, please see:</p>
592 <ul class="simple">
593 <li><a class="reference" href="http://docutils.sourceforge.net/docs/rst/quickstart.html">A ReStructuredText Primer</a> <a class="footnote-reference" href="#id17" id="id18" name="id18">[8]</a>, a gentle introduction.</li>
594 <li><a class="reference" href="http://docutils.sourceforge.net/docs/rst/quickref.html">Quick reStructuredText</a> <a class="footnote-reference" href="#id19" id="id20" name="id20">[9]</a>, a users' quick reference.</li>
595 <li><a class="reference" href="http://docutils.sourceforge.net/spec/rst/reStructuredText.html">reStructuredText Markup Specification</a> <a class="footnote-reference" href="#id21" id="id22" name="id22">[10]</a>, the final authority.</li>
596 </ul>
597 <p>The processing of reStructuredText GLEPs is done using <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> <a class="footnote-reference" href="#id8" id="id9" name="id9">[4]</a>. If
598 you have a question or require assistance with reStructuredText or
599 Docutils, please <a class="reference" href="mailto:docutils-users&#64;lists.sourceforge.net?subject=GLEPs">post a message</a> <a class="footnote-reference" href="#id10" id="id11" name="id11">[5]</a> to the <a class="reference" href="http://lists.sourceforge.net/lists/listinfo/docutils-users">Docutils-Users mailing
600 list</a> <a class="footnote-reference" href="#id12" id="id13" name="id13">[6]</a>. The <a class="reference" href="http://docutils.sourceforge.net/">Docutils project web site</a> <a class="footnote-reference" href="#id8" id="id14" name="id14">[4]</a> has more information.</p>
601 </div>
602 <div class="section">
603 <h1><a class="toc-backref" href="#id45" id="references" name="references">References</a></h1>
604 <table class="docutils footnote" frame="void" id="python" rules="none">
605 <colgroup><col class="label" /><col /></colgroup>
606 <tbody valign="top">
607 <tr><td class="label"><a class="fn-backref" href="#id1" name="python">[1]</a></td><td><a class="reference" href="http://www.python.org">http://www.python.org</a></td></tr>
608 </tbody>
609 </table>
610 <table class="docutils footnote" frame="void" id="pep12" rules="none">
611 <colgroup><col class="label" /><col /></colgroup>
612 <tbody valign="top">
613 <tr><td class="label"><a class="fn-backref" href="#id2" name="pep12">[2]</a></td><td><a class="reference" href="http://www.python.org/peps/pep-0012.html">http://www.python.org/peps/pep-0012.html</a></td></tr>
614 </tbody>
615 </table>
616 <table class="docutils footnote" frame="void" id="glep1" rules="none">
617 <colgroup><col class="label" /><col /></colgroup>
618 <tbody valign="top">
619 <tr><td class="label"><a class="fn-backref" href="#id3" name="glep1">[3]</a></td><td>GLEP 1, GLEP Purpose and Guidelines, Goodyear,
620 (<a class="reference" href="http://glep.gentoo.org/glep-0001.html">http://glep.gentoo.org/glep-0001.html</a>)</td></tr>
621 </tbody>
622 </table>
623 <table class="docutils footnote" frame="void" id="id8" rules="none">
624 <colgroup><col class="label" /><col /></colgroup>
625 <tbody valign="top">
626 <tr><td class="label"><a name="id8">[4]</a></td><td><em>(<a class="fn-backref" href="#id9">1</a>, <a class="fn-backref" href="#id14">2</a>)</em> <a class="reference" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a></td></tr>
627 </tbody>
628 </table>
629 <table class="docutils footnote" frame="void" id="id10" rules="none">
630 <colgroup><col class="label" /><col /></colgroup>
631 <tbody valign="top">
632 <tr><td class="label"><a class="fn-backref" href="#id11" name="id10">[5]</a></td><td><a class="reference" href="mailto:docutils-users&#64;lists.sourceforge.net?subject=GLEPs">mailto:docutils-users&#64;lists.sourceforge.net?subject=GLEPs</a></td></tr>
633 </tbody>
634 </table>
635 <table class="docutils footnote" frame="void" id="id12" rules="none">
636 <colgroup><col class="label" /><col /></colgroup>
637 <tbody valign="top">
638 <tr><td class="label"><a class="fn-backref" href="#id13" name="id12">[6]</a></td><td><a class="reference" href="http://lists.sourceforge.net/lists/listinfo/docutils-users">http://lists.sourceforge.net/lists/listinfo/docutils-users</a></td></tr>
639 </tbody>
640 </table>
641 <table class="docutils footnote" frame="void" id="id15" rules="none">
642 <colgroup><col class="label" /><col /></colgroup>
643 <tbody valign="top">
644 <tr><td class="label"><a class="fn-backref" href="#id16" name="id15">[7]</a></td><td><a class="reference" href="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</a></td></tr>
645 </tbody>
646 </table>
647 <table class="docutils footnote" frame="void" id="id17" rules="none">
648 <colgroup><col class="label" /><col /></colgroup>
649 <tbody valign="top">
650 <tr><td class="label"><a class="fn-backref" href="#id18" name="id17">[8]</a></td><td><a class="reference" href="http://docutils.sourceforge.net/docs/rst/quickstart.html">http://docutils.sourceforge.net/docs/rst/quickstart.html</a></td></tr>
651 </tbody>
652 </table>
653 <table class="docutils footnote" frame="void" id="id19" rules="none">
654 <colgroup><col class="label" /><col /></colgroup>
655 <tbody valign="top">
656 <tr><td class="label"><a class="fn-backref" href="#id20" name="id19">[9]</a></td><td><a class="reference" href="http://docutils.sourceforge.net/docs/rst/quickref.html">http://docutils.sourceforge.net/docs/rst/quickref.html</a></td></tr>
657 </tbody>
658 </table>
659 <table class="docutils footnote" frame="void" id="id21" rules="none">
660 <colgroup><col class="label" /><col /></colgroup>
661 <tbody valign="top">
662 <tr><td class="label"><a class="fn-backref" href="#id22" name="id21">[10]</a></td><td><a class="reference" href="http://docutils.sourceforge.net/spec/rst/reStructuredText.html">http://docutils.sourceforge.net/spec/rst/reStructuredText.html</a></td></tr>
663 </tbody>
664 </table>
665 </div>
666 <div class="section">
667 <h1><a class="toc-backref" href="#id46" id="copyright" name="copyright">Copyright</a></h1>
668 <p>This document has been placed in the public domain.</p>
669 </div>
670
671 </div>
672 <div class="footer">
673 <hr class="footer" />
674 <a class="reference" href="glep-0002.txt">View document source</a>.
675 Generated on: 2007-10-13 13:39 UTC.
676 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
677
678 </div>
679 </body>
680 </html>

  ViewVC Help
Powered by ViewVC 1.1.20