Rename all GLEPs to .rst

1 files changed, 605 insertions, 0 deletions

diff --git a/glep-0002.rst b/glep-0002.rst
new file mode 100644
index 0000000..65b00fb
--- /dev/null
+++ b/glep-0002.rst
@@ -0,0 +1,605 @@
+GLEP: 2
+Title: Sample ReStructuredText GLEP Template
+Version: $Revision$
+Last-Modified: $Date$
+Author: Grant Goodyear <g2boojum@gentoo.org>,
+        Chris Reffett <creffett@gentoo.org>,
+        Ulrich Müller <ulm@gentoo.org>
+Status: Active
+Type: Informational
+Content-Type: text/x-rst
+Created: 31 May 2003
+Post-History: 2-Jun-2003, 17-Dec-2013
+
+
+Credits
+=======
+
+The text of this GLEP was, to a significant extent, stolen from Python's
+[#PYTHON]_ PEP-0012 [#PEP12]_ by David Goodger and Barry A. Warsaw.
+
+
+Abstract
+========
+
+This GLEP provides a boilerplate or sample template for creating your own
+reStructuredText GLEPs.  In conjunction with the content guidelines in GLEP 1
+[#GLEP1]_, this should make it easy for you to conform your own GLEPs to the
+format outlined below.
+
+Note: if you are reading this GLEP via the web, you should first grab the text
+(reStructuredText) source of this GLEP in order to complete the steps below.
+**DO NOT USE THE HTML FILE AS YOUR TEMPLATE!**
+
+To get the source of this (or any) GLEP, look at the top of the HTML page and
+click on the link titled "GLEP Source".
+
+Motivation
+==========
+
+Provide adequate motivation here.  In this particular case, we need to provide
+people with the information necessary to submit GLEPs in the proper form.
+
+Rationale
+=========
+
+GLEP submissions come in a wide variety of forms, not all adhering to the
+format guidelines set forth below.  Use this template, in conjunction with the
+format guidelines below, to ensure that your GLEP submission won't get
+automatically rejected because of form.
+
+ReStructuredText is used to allow GLEP authors more functionality and
+expressivity, while maintaining easy readability in the source text.  The
+processed HTML form makes the functionality accessible to readers: live
+hyperlinks, styled text, tables, images, and automatic tables of contents,
+among other advantages.  
+
+
+Backwards Compatibility
+=======================
+
+Not a problem for this GLEP.  This section should be included *even* when it
+is only to state that there are no backwards compatibility issues.
+
+
+How to Use This Template
+========================
+
+To use this template you must first decide whether your GLEP is going to be an
+Informational or Standards Track GLEP.  Most GLEPs are Standards Track because
+they propose new functionality for some aspect of Gentoo Linux.  When in
+doubt, read GLEP 1 for details or contact the GLEP editors <glep@gentoo.org>.
+
+Once you've decided which type of GLEP yours is going to be, follow the
+directions below.
+
+- Make a copy of this file (``.rst`` file, **not** HTML!) and perform
+  the following edits.
+
+- Replace the "GLEP: 2" header with "GLEP: XXX" since you don't yet have
+  a GLEP number assignment.
+
+- Change the Title header to the title of your GLEP.
+
+- Change the Author header to include your name, and optionally your
+  email address.  Be sure to follow the format carefully: your name must
+  appear first, and it must not be contained in parentheses.  Your email
+  address may appear second (or it can be omitted) and if it appears, it must
+  appear in angle brackets.
+
+- For Standards Track GLEPs, change the Type header to "Standards Track".
+
+- For Informational GLEPs, change the Type header to "Informational".
+
+- Change the Status header to "Draft".
+
+- Reset the Version to "1".
+
+- Change the Created and Last-Modified headers to today's date.  Be sure to
+  follow the format carefully: it must be in ISO 8601 ``yyyy-mm-dd`` format.
+
+- Reset the Post-History to empty for now; you'll add dates to this header
+  each time you post your GLEP to gentoo-dev@lists.gentoo.org.  If you
+  posted your GLEP to the list on August 14, 2003 and September 3, 2003,
+  the Post-History header would look like::
+
+      Post-History: 2003-08-14, 2003-09-03
+
+  You must manually add new dates and check them in.  If you don't have
+  check-in privileges, send your changes to the GLEP editors.
+
+- For Standards Track GLEPs, if your feature depends on the acceptance
+  of some other currently in-development GLEP, add a Requires header right
+  after the Type header.  The value should be the GLEP number of the GLEP
+  yours depends on.  Don't add this header if your dependent feature is
+  described in a Final GLEP.
+
+- Add a Replaces header if your GLEP obsoletes an earlier GLEP.  The
+  value of this header is the number of the GLEP that your new GLEP is
+  replacing.  Only add this header if the older GLEP is in "final" form, i.e.
+  is either Accepted, Final, or Rejected.  You aren't replacing an older open
+  GLEP if you're submitting a competing idea.
+
+- Now write your Abstract, Rationale, and other content for your GLEP,
+  replacing all of this gobbledygook with your own text. Be sure to adhere to
+  the format guidelines below, specifically on the indentation requirements.
+
+- Update your References section.  You should leave the Copyright section
+  as-is, since all new GLEPs are to be licensed under the Creative Commons
+  Attribution-ShareAlike License, Version 3.0.
+
+- Send your GLEP submission to the GLEP editors at glep@gentoo.org.
+
+
+ReStructuredText GLEP Formatting Requirements
+=============================================
+
+The following is a GLEP-specific summary of reStructuredText syntax.  For the
+sake of simplicity and brevity, much detail is omitted.  For more detail, see
+`Resources`_ below.  `Literal blocks`_ (in which no markup processing is done)
+are used for examples throughout, to illustrate the plaintext markup.
+
+
+General
+-------
+
+You must adhere to the convention of adding two spaces at the end of every
+sentence.  You should fill your paragraphs to column 70, but under no
+circumstances should your lines extend past column 79.  If your code samples
+spill over column 79, you should rewrite them.
+
+
+Section Headings
+----------------
+
+GLEP headings must begin in column zero and the initial letter of each word
+must be capitalized as in book titles.  Acronyms should be in all capitals.
+Section titles must be adorned with an underline, a single repeated
+punctuation character, which begins in column zero and must extend at least as
+far as the right edge of the title text (4 characters minimum).  First-level
+section titles are underlined with "=" (equals signs), second-level section
+titles with "-" (hyphens), and third-level section titles with "'" (single
+quotes or apostrophes).  For example::
+
+    First-Level Title
+    =================
+
+    Second-Level Title
+    ------------------
+
+    Third-Level Title
+    '''''''''''''''''
+
+If there are more than three levels of sections in your GLEP, you may insert
+overline/underline-adorned titles for the first and second levels as follows::
+
+    ============================
+    First-Level Title (optional)
+    ============================
+
+    -----------------------------
+    Second-Level Title (optional)
+    -----------------------------
+
+    Third-Level Title
+    =================
+
+    Fourth-Level Title
+    ------------------
+
+    Fifth-Level Title
+    '''''''''''''''''
+
+You shouldn't have more than five levels of sections in your GLEP.  If you do,
+you should consider rewriting it.
+
+You must use two blank lines between the last line of a section's body and the
+next section heading.  If a subsection heading immediately follows a section
+heading, a single blank line in-between is sufficient.
+
+The body of each section is not normally indented, although some constructs do
+use indentation, as described below.  Blank lines are used to separate
+constructs.
+
+
+Paragraphs
+----------
+
+Paragraphs are left-aligned text blocks separated by blank lines.  Paragraphs
+are not indented unless they are part of an indented construct (such as a
+block quote or a list item).
+
+
+Inline Markup
+-------------
+
+Portions of text within paragraphs and other text blocks may be
+styled.  For example::
+
+    Text may be marked as *emphasized* (single asterisk markup,
+    typically shown in italics) or **strongly emphasized** (double
+    asterisks, typically boldface).  ``Inline literals`` (using double
+    backquotes) are typically rendered in a monospaced typeface.  No
+    further markup recognition is done within the double backquotes,
+    so they're safe for any kind of code snippets.
+
+
+Block Quotes
+------------
+
+Block quotes consist of indented body elements.  For example::
+
+    This is a paragraph.
+
+        This is a block quote.
+
+        A block quote may contain many paragraphs.
+
+Block quotes are used to quote extended passages from other sources.
+Block quotes may be nested inside other body elements.  Use a 4-space tab
+per indent level.
+
+
+Literal Blocks
+--------------
+
+..  
+    In the text below, double backquotes are used to denote inline
+    literals.  "``::``" is written so that the colons will appear in a
+    monospaced font; the backquotes (``) are markup, not part of the
+    text.  See "Inline Markup" above.
+
+    By the way, this is a comment, described in "Comments" below.
+
+Literal blocks are used for code samples or preformatted ASCII art. To
+indicate a literal block, preface the indented text block with
+"``::``" (two colons).  The literal block continues until the end of
+the indentation.  Indent the text block by a tab.  For example::
+
+    This is a typical paragraph.  A literal block follows.
+
+    ::
+
+        for a in [5,4,3,2,1]:   # this is program code, shown as-is
+            print a
+        print "it's..."
+        # a literal block continues until the indentation ends
+
+The paragraph containing only "``::``" will be completely removed from
+the output; no empty paragraph will remain.  "``::``" is also
+recognized at the end of any paragraph.  If immediately preceded by
+whitespace, both colons will be removed from the output.  When text
+immediately precedes the "``::``", *one* colon will be removed from
+the output, leaving only one colon visible (i.e., "``::``" will be
+replaced by "``:``").  For example, one colon will remain visible
+here::
+
+    Paragraph::
+
+        Literal block
+
+
+Lists
+-----
+
+Bullet list items begin with one of "-", "*", or "+" (hyphen,
+asterisk, or plus sign), followed by whitespace and the list item
+body.  List item bodies must be left-aligned and indented relative to
+the bullet; the text immediately after the bullet determines the
+indentation.  For example::
+
+    This paragraph is followed by a list.
+
+    * This is the first bullet list item.  The blank line above the
+      first list item is required; blank lines between list items
+      (such as below this paragraph) are optional.
+
+    * This is the first paragraph in the second item in the list.
+
+      This is the second paragraph in the second item in the list.
+      The blank line above this paragraph is required.  The left edge
+      of this paragraph lines up with the paragraph above, both
+      indented relative to the bullet.
+
+      - This is a sublist.  The bullet lines up with the left edge of
+        the text blocks above.  A sublist is a new list so requires a
+        blank line above and below.
+
+    * This is the third item of the main list.
+
+    This paragraph is not part of the list.
+
+Enumerated (numbered) list items are similar, but use an enumerator
+instead of a bullet.  Enumerators are numbers (1, 2, 3, ...), letters
+(A, B, C, ...; uppercase or lowercase), or Roman numerals (i, ii, iii,
+iv, ...; uppercase or lowercase), formatted with a period suffix
+("1.", "2."), parentheses ("(1)", "(2)"), or a right-parenthesis
+suffix ("1)", "2)").  For example::
+
+    1. As with bullet list items, the left edge of paragraphs must
+       align.
+
+    2. Each list item may contain multiple paragraphs, sublists, etc.
+
+       This is the second paragraph of the second list item.
+
+       a) Enumerated lists may be nested.
+       b) Blank lines may be omitted between list items.
+
+Definition lists are written like this::
+
+    what
+        Definition lists associate a term with a definition.
+
+    how
+        The term is a one-line phrase, and the definition is one
+        or more paragraphs or body elements, indented relative to
+        the term.
+
+
+Tables
+------
+
+Simple tables are easy and compact::
+
+    =====  =====  =======
+      A      B    A and B
+    =====  =====  =======
+    False  False  False
+    True   False  False
+    False  True   False
+    True   True   True
+    =====  =====  =======
+
+There must be at least two columns in a table (to differentiate from
+section titles).  Column spans use underlines of hyphens ("Inputs"
+spans the first two columns)::
+
+    =====  =====  ======
+       Inputs     Output
+    ------------  ------
+      A      B    A or B
+    =====  =====  ======
+    False  False  False
+    True   False  True
+    False  True   True
+    True   True   True
+    =====  =====  ======
+
+Text in a first-column cell starts a new row.  No text in the first
+column indicates a continuation line; the rest of the cells may
+consist of multiple lines.  For example::
+
+    =====  =========================
+    col 1  col 2
+    =====  =========================
+    1      Second column of row 1.
+    2      Second column of row 2.
+           Second line of paragraph.
+    3      - Second column of row 3.
+
+           - Second item in bullet
+             list (row 3, column 2).
+    =====  =========================
+
+
+Hyperlinks
+----------
+
+When referencing an external web page in the body of a GLEP, you should
+include the title of the page in the text, with either an inline
+hyperlink reference to the URL or a footnote reference (see
+`Footnotes`_ below).  Do not include the URL in the body text of the
+GLEP.
+
+Hyperlink references use backquotes and a trailing underscore to mark
+up the reference text; backquotes are optional if the reference text
+is a single word.  For example::
+
+    In this paragraph, we refer to the `Python web site`_.
+
+An explicit target provides the URL.  Put targets in a References
+section at the end of the GLEP, or immediately after the reference.
+Hyperlink targets begin with two periods and a space (the "explicit
+markup start"), followed by a leading underscore, the reference text,
+a colon, and the URL (absolute or relative)::
+
+    .. _Python web site: http://www.python.org/
+
+The reference text and the target text must match (although the match
+is case-insensitive and ignores differences in whitespace).  Note that
+the underscore trails the reference text but precedes the target text.
+If you think of the underscore as a right-pointing arrow, it points
+*away* from the reference and *toward* the target.
+
+The same mechanism can be used for internal references.  Every unique
+section title implicitly defines an internal hyperlink target.  We can
+make a link to the Abstract section like this::
+
+    Here is a hyperlink reference to the `Abstract`_ section.  The
+    backquotes are optional since the reference text is a single word;
+    we can also just write: Abstract_.
+
+Footnotes containing the URLs from external targets will be generated
+automatically at the end of the References section of the GLEP, along
+with footnote references linking the reference text to the footnotes.
+
+Text of the form "GLEP x" or "RFC x" (where "x" is a number) will be
+linked automatically to the appropriate URLs.
+
+
+Footnotes
+---------
+
+Footnote references consist of a left square bracket, a number, a
+right square bracket, and a trailing underscore::
+
+    This sentence ends with a footnote reference [1]_.
+
+Whitespace must precede the footnote reference.  Leave a space between
+the footnote reference and the preceding word.
+
+When referring to another GLEP, include the GLEP number in the body
+text, such as "GLEP 1".  The title may optionally appear.  Add a
+footnote reference following the title.  For example::
+
+    Refer to GLEP 1 [2]_ for more information.
+
+Add a footnote that includes the GLEP's title and author.  It may
+optionally include the explicit URL on a separate line, but only in
+the References section.  Footnotes begin with ".. " (the explicit
+markup start), followed by the footnote marker (no underscores),
+followed by the footnote body.  For example::
+
+    References
+    ==========
+
+    .. [2] GLEP 1, "GLEP Purpose and Guidelines", Goodyear, Warsaw, Hylton
+       (http://glep.gentoo.org/glep-0001.html)
+
+If you decide to provide an explicit URL for a GLEP, please use this as
+the URL template::
+
+    http://glep.gentoo.org/glep-xxxx.html
+
+GLEP numbers in URLs must be padded with zeros from the left, so as to
+be exactly 4 characters wide, however GLEP numbers in the text are
+never padded.
+
+During the course of developing your GLEP, you may have to add, remove,
+and rearrange footnote references, possibly resulting in mismatched
+references, obsolete footnotes, and confusion.  Auto-numbered
+footnotes allow more freedom.  Instead of a number, use a label of the
+form "#word", where "word" is a mnemonic consisting of alphanumerics
+plus internal hyphens, underscores, and periods (no whitespace or
+other characters are allowed).  For example::
+
+    Refer to GLEP 1 [#GLEP-1]_ for more information.
+
+    References
+    ==========
+
+    .. [#GLEP-1] GLEP 1, "GLEP Purpose and Guidelines", Goodyear
+       http://glep.gentoo.org/glep-0001.html
+
+Footnotes and footnote references will be numbered automatically, and
+the numbers will always match.  Once a GLEP is finalized, auto-numbered
+labels should be replaced by numbers for simplicity.
+
+
+Images
+------
+
+If your GLEP contains a diagram, you may include it in the processed
+output using the "image" directive::
+
+    .. image:: diagram.png
+
+Any browser-friendly graphics format is possible: .png, .jpeg, .gif,
+.tiff, etc.
+
+Since this image will not be visible to readers of the GLEP in source
+text form, you should consider including a description or ASCII art
+alternative, using a comment (below).
+
+
+Comments
+--------
+
+A comment block is an indented block of arbitrary text immediately
+following an explicit markup start: two periods and whitespace.  Leave
+the ".." on a line by itself to ensure that the comment is not
+misinterpreted as another explicit markup construct.  Comments are not
+visible in the processed document.  For the benefit of those reading
+your GLEP in source form, please consider including a descriptions of
+or ASCII art alternatives to any images you include.  For example::
+
+     .. image:: dataflow.png
+
+     ..
+        Data flows from the input module, through the "black box"
+        module, and finally into (and through) the output module.
+
+
+
+Escaping Mechanism
+------------------
+
+reStructuredText uses backslashes ("``\``") to override the special
+meaning given to markup characters and get the literal characters
+themselves.  To get a literal backslash, use an escaped backslash
+("``\\``").  There are two contexts in which backslashes have no
+special meaning: `literal blocks`_ and inline literals (see `Inline
+Markup`_ above).  In these contexts, no markup recognition is done,
+and a single backslash represents a literal backslash, without having
+to double up.
+
+If you find that you need to use a backslash in your text, consider
+using inline literals or a literal block instead.
+
+
+Habits to Avoid
+===============
+
+Many programmers who are familiar with TeX often write quotation marks
+like this::
+
+    `single-quoted' or ``double-quoted''
+
+Backquotes are significant in reStructuredText, so this practice
+should be avoided.  For ordinary text, use ordinary 'single-quotes' or
+"double-quotes".  For inline literal text (see `Inline Markup`_
+above), use double-backquotes::
+
+    ``literal text: in here, anything goes!``
+
+
+Resources
+=========
+
+Many other constructs and variations are possible.  For more details
+about the reStructuredText markup, in increasing order of
+thoroughness, please see:
+
+* `A ReStructuredText Primer`__, a gentle introduction.
+
+  __ http://docutils.sourceforge.net/docs/rst/quickstart.html
+
+* `Quick reStructuredText`__, a users' quick reference.
+
+  __ http://docutils.sourceforge.net/docs/rst/quickref.html
+
+* `reStructuredText Markup Specification`__, the final authority.
+
+  __ http://docutils.sourceforge.net/spec/rst/reStructuredText.html
+
+The processing of reStructuredText GLEPs is done using Docutils_.  If
+you have a question or require assistance with reStructuredText or
+Docutils, please `post a message`_ to the `Docutils-Users mailing
+list`_.  The `Docutils project web site`_ has more information.
+
+.. _Docutils: http://docutils.sourceforge.net/
+.. _post a message:
+   mailto:docutils-users@lists.sourceforge.net?subject=GLEPs
+.. _Docutils-Users mailing list:
+   http://lists.sourceforge.net/lists/listinfo/docutils-users
+.. _Docutils project web site: http://docutils.sourceforge.net/
+
+
+References
+==========
+
+.. [#PYTHON] http://www.python.org
+
+.. [#PEP12] http://www.python.org/peps/pep-0012.html
+
+.. [#GLEP1] GLEP 1, GLEP Purpose and Guidelines, Goodyear, 
+   (http://glep.gentoo.org/glep-0001.html)
+
+
+Copyright
+=========
+
+This work is licensed under the Creative Commons Attribution-ShareAlike 3.0
+Unported License.  To view a copy of this license, visit
+http://creativecommons.org/licenses/by-sa/3.0/.