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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.4 - (show annotations) (download)
Sat Jul 19 12:09:20 2003 UTC (11 years ago) by liquidx
Branch: MAIN
CVS Tags: HEAD
Changes since 1.3: +3 -3 lines
File MIME type: text/plain
marking GLEP1 GLEP2 active

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

  ViewVC Help
Powered by ViewVC 1.1.20