aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.txt59
-rw-r--r--docutils.conf15
-rw-r--r--glep-0001.txt366
-rw-r--r--glep-0002.txt622
-rw-r--r--tools/glep-html-template27
-rw-r--r--tools/glep.css240
6 files changed, 1329 insertions, 0 deletions
diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..8e1f4c3
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,59 @@
+Gentoo Linux Enhancement Proposals
+==================================
+
+This directory contains the official (CVS-controlled)
+texts of current and past Gentoo Linux Enhancement
+Proposals (GLEPs), along with some necessary scripts
+and configuration files to facilitate converting the
+GLEPs from (really quite readable) raw ASCII text
+to html or xml.
+
+Requirements
+============
+
+GLEPs are written in ReStructuredText [#ReST]_, which
+is text with some minimal markup so that it is still
+quite readable in source form, yet it can be readily
+converted to html or xml for viewing with a browser.
+
+Converting ReST to html or xml requires the "docutils" python package
+[#docutils]_::
+
+ # emerge docutils
+
+The Gentoo Linux docutils package includes the *glep.py* program
+which transforms a GLEP in text form to the equivalent html version::
+
+ # glep.py glep-0001.txt glep-0001.html
+
+(Incidentally, *glep.py* contains special code to verify that
+the GLEP header is reasonable. This README lacks that header,
+so to convert this file to html using docutils you need to
+use the more generic transformation program::
+
+ # html.py --stylesheet-path=tools/glep.css README.txt README.html
+
+to convert README.txt to README.html.)
+
+Files
+=====
+
+======================== ======================================
+File Purpose
+======================== ======================================
+README.txt This file (duh!)
+docutils.conf Configuration file for GLEP conversion
+ from txt to html
+glep-xxxx.txt GLEPs in text (ReST) form
+tools/glep.css GLEP html stylesheet
+tools/glep-html-template GLEP boilerplate template
+======================== ======================================
+
+
+References
+==========
+
+.. [#ReST] ReStructuredText,
+ http://docutils.sourceforge.net/docs/rst/quickstart.html
+
+.. [#docutils] http://docutils.sourceforge.net/
diff --git a/docutils.conf b/docutils.conf
new file mode 100644
index 0000000..3961b12
--- /dev/null
+++ b/docutils.conf
@@ -0,0 +1,15 @@
+[options]
+
+# These entries affect all processing:
+source-link: 1
+datestamp: %Y-%m-%d %H:%M UTC
+generator: 1
+
+# These entries affect HTML output:
+stylesheet-path: stylesheets/default.css
+
+# These entries affect reStructuredText-style PEPs:
+pep-template: tools/glep-html-template
+pep-stylesheet-path: tools/glep.css
+python-home: http://www.gentoo.org
+no-random: 1
diff --git a/glep-0001.txt b/glep-0001.txt
new file mode 100644
index 0000000..89296e9
--- /dev/null
+++ b/glep-0001.txt
@@ -0,0 +1,366 @@
+GLEP: 1
+Title: GLEP Purpose and Guidelines
+Version: $Revision: 1.1 $
+Last-Modified: $Date: 2003/06/01 04:33:49 $
+Author: Grant Goodyear
+Status: Draft
+Type: Informational
+Content-Type: text/x-rst
+Created: 31 May 2003
+Post-History:
+
+
+What is a GLEP?
+===============
+
+GLEP stands for "Gentoo Linux Enhancement Proposal". A GLEP is a design
+document providing information to the Gentoo Linux community, or describing
+a new feature for Gentoo Linux. (The GLEP concept, and, in fact,
+much of the text of this document, is liberally stolen from Python's
+`PEP-0001`_.) The GLEP should provide a concise technical
+specification of the feature and rationale for the feature.
+
+We intend GLEPs to be the primary mechanisms for proposing *significant* new
+features, for collecting community input on an issue, and for
+documenting the design decisions that have gone into Gentoo Linux. The GLEP
+author is responsible for building consensus within the community and
+documenting dissenting opinions.
+
+Because the GLEPs are maintained as text files under CVS control, their
+revision history is the historical record of the feature proposal
+[1]_.
+
+
+Kinds of GLEPs
+==============
+
+There are two kinds of GLEPs. A Standards Track GLEP describes a new
+feature or implementation for Gentoo Linux. An Informational GLEP describes
+provides general guidelines or information
+to the Gentoo Linux community, but does not propose a new feature.
+Informational GLEPs do not necessarily represent a Gentoo Linux community
+consensus or recommendation, so users and implementors are free to
+ignore Informational GLEPs or follow their advice.
+
+
+GLEP Work Flow
+==============
+
+The GLEP editors assign GLEP numbers and change their status. The
+current GLEP editors are Grant Goodyear and hopefully somebody
+else. Please send
+all GLEP-related email to <glep@gentoo.org>.
+
+The GLEP process begins with a new idea for Gentoo Linux. It is highly
+recommended that a single GLEP contain a single key proposal or new
+idea. The more focussed the GLEP, the more successful it tends to
+be. The GLEP editor reserves the right to reject GLEP proposals if they
+appear too unfocussed or too broad. If in doubt, split your GLEP into
+several well-focussed ones.
+
+Each GLEP must have a champion -- someone who writes the GLEP using the
+style and format described below, shepherds the discussions in the
+appropriate forums, and attempts to build community consensus around
+the idea. The GLEP champion (a.k.a. Author) should first attempt to
+ascertain whether the idea is GLEP-able. Small enhancements or patches
+often don't need a GLEP and can be injected into the Gentoo Linux development
+work flow with an enhancement "bug" submitted to the Gentoo Linux bugzilla_.
+
+The GLEP champion then emails the GLEP editor <glep@gentoo.org> with a
+proposed title and a rough, but fleshed out, draft of the GLEP. This
+draft must be written in GLEP style as described below.
+
+If the GLEP editor approves, he will assign the GLEP a number, label it
+as Standards Track (a better name would be nice here -- suggestions?)
+or Informational, give it status "Draft", and
+create and check-in the initial draft of the GLEP. The GLEP editors will
+not unreasonably deny a GLEP. Reasons for denying GLEP status include
+duplication of effort, being technically unsound, not providing proper
+motivation or addressing backwards compatibility, or not in keeping
+with Gentoo Linux philosophy.
+
+If a pre-GLEP is rejected, the author may elect to take the pre-GLEP to
+the gentoo-dev@gentoo.org mailing list
+to help flesh it out, gain feedback and consensus from the
+community at large, and improve the GLEP for re-submission.
+
+The author of the GLEP is then responsible for posting the GLEP to the
+gentoo-dev mailing list and to the `Gentoo Linux forums`_,
+and marshaling community support for it. As updates
+are necessary, the GLEP author can check in new versions if they have
+CVS commit permissions, or can email new GLEP versions to the GLEP
+editors for committing.
+
+Standards Track GLEPs consist of two parts, a design document and a
+reference implementation. The GLEP should be reviewed and accepted
+before a reference implementation is begun, unless a reference
+implementation will aid people in studying the GLEP. Standards Track
+GLEPs must include an implementation -- in the form of code, patch, or
+URL to same -- before it can be considered Final.
+
+GLEP authors are responsible for collecting community feedback on a GLEP
+before submitting it for review. A GLEP that has not been discussed on
+gentoo-dev@gentoo.org and/or the `Gentoo Linux forums`_ will not be
+accepted. However, wherever possible, long open-ended discussions on
+public mailing lists should be avoided. Strategies to keep the
+discussions efficient include setting up a specific forums thread
+for the topic, having the GLEP author accept private comments in the
+early design phases, etc. GLEP authors should use their discretion
+here.
+
+Once the authors have completed a GLEP, they must inform the GLEP editors
+that it is ready for review. GLEPs are reviewed by the Gentoo Linux
+Chief Architect or Development Manager, who may accept or reject a GLEP
+outright, or send it back to
+the author(s) for revision. For a GLEP that is pre-determined to be
+acceptable (e.g., it is an obvious win as-is and/or its implementation
+has already been checked in) the Chief Architect or the Development
+Manager may also initiate a GLEP review,
+first notifying the GLEP author(s) and giving them a chance to make
+revisions.
+
+For a GLEP to be accepted it must meet certain minimum criteria. It
+must be a clear and complete description of the proposed enhancement.
+The enhancement must represent a net improvement. The proposed
+implementation, if applicable, must be solid and must not complicate
+the distrubution unduly. Finally, a proposed enhancement must
+satisfy the philosophy of Gentoo Linux.
+
+Once a GLEP has been accepted, the reference implementation must be
+completed. When the reference implementation is complete and accepted,
+the status will be changed to "Final".
+
+A GLEP can also be assigned status "Deferred". The GLEP author or
+editor can assign the GLEP this status when no progress is being made
+on the GLEP. Once a GLEP is deferred, the GLEP editor can re-assign it
+to draft status.
+
+A GLEP can also be "Rejected". Perhaps after all is said and done it
+was not a good idea. It is still important to have a record of this
+fact.
+
+GLEPs can also be replaced by a different GLEP, rendering the original
+obsolete. This is intended for Informational GLEPs, where version 2 of
+a policy, for example, can replace version 1.
+
+GLEP work flow is as follows::
+
+ Draft -> Accepted -> Final -> Replaced
+ ^
+ +----> Rejected
+ v
+ Deferred
+
+Some Informational GLEPs may also have a status of "Active" if they are
+never meant to be completed. E.g. GLEP 1 (this GLEP).
+
+
+What belongs in a successful GLEP?
+==================================
+
+Each GLEP should have the following parts:
+
+1. Preamble -- RFC 822 style headers containing meta-data about the
+ GLEP, including the GLEP number, a short descriptive title (limited
+ to a maximum of 44 characters), the names, and optionally the
+ contact info for each author, etc.
+
+2. Abstract -- a short (~200 word) description of the technical issue
+ being addressed.
+
+3. Copyright/public domain -- Each GLEP must either be explicitly
+ labelled as placed in the public domain (see this GLEP as an
+ example) or licensed under the `Open Publication License`_.
+
+4. Motivation -- The motivation is critical for GLEPs that want to
+ change the Gentoo Linux functionality. It should clearly explain why the
+ existing functionality or policy is inadequate to address the
+ problem that the GLEP solves. GLEP submissions without sufficient
+ motivation may be rejected outright.
+
+5. Specification -- The technical specification should describe the
+ specific areas of Gentoo Linux that would be touched by this GLEP.
+ If new functionality is being introduced, what packages will that
+ functionality affect? If new policy, who will be affected?
+
+6. Rationale -- The rationale fleshes out the specification by
+ describing what motivated the design and why particular design
+ decisions were made. It should describe alternate designs that
+ were considered and related work, e.g. how the feature is supported
+ in other distributions.
+
+ The rationale should provide evidence of consensus within the
+ community and discuss important objections or concerns raised
+ during discussion.
+
+7. Backwards Compatibility -- All GLEPs
+ must include a section describing any issues of backwards
+ incompatibilities and their severity.
+ The GLEP must explain how the
+ author proposes to deal with these incompatibilities.
+ (Even if there are none, this section should be included to clearly
+ state that fact.)
+ GLEP
+ submissions without a sufficient backwards compatibility treatise
+ may be rejected outright.
+
+8. Reference Implementation -- The reference implementation must be
+ completed before any GLEP is given status "Final", but it need not
+ be completed before the GLEP is accepted. It is better to finish
+ the specification and rationale first and reach consensus on it
+ before writing code or significantly modifying ebuilds.
+
+
+GLEP Formating and Template
+===========================
+
+GLEPs are written in a just-barely-marked-up version of plain, ASCII text
+called ReStructuredText_ that is then converted to HTML using Docutils_.
+Using ReStructuredText_ GLEPs allows for rich markup that is still quite easy
+to read, but results in much better-looking and more functional HTML.
+Moreover, it should be straightforward to convert GLEPs to `guide xml`_
+if needed.
+GLEP 2 contains a boilerplate template [4]_ for use with
+reStructuredText GLEPs.
+
+
+GLEP Header Preamble
+====================
+
+Each GLEP must begin with an RFC 822 style header preamble. The headers
+must appear in the following order. Headers marked with "*" are
+optional and are described below. All other headers are required. ::
+
+ GLEP: <glep number>
+ Title: <glep title>
+ Version: <cvs version string>
+ Last-Modified: <cvs date string>
+ Author: <list of authors' real names and optionally, email addrs>
+ * Discussions-To: <email address>
+ Status: <Draft | Active | Accepted | Deferred | Rejected |
+ Final | Replaced>
+ Type: <Informational | Standards Track>
+ * Content-Type: <text/plain | text/x-rst>
+ * Requires: <glep numbers>
+ Created: <date created on, in dd-mmm-yyyy format>
+ Post-History: <dates of postings to gentoo-dev>
+ * Replaces: <glep number>
+ * Replaced-By: <glep number>
+
+The Author header lists the names, and optionally the email addresses
+of all the authors/owners of the GLEP. The format of the Author header
+value must be
+
+ Random J. User <address@dom.ain>
+
+if the email address is included, and just
+
+ Random J. User
+
+if the address is not given.
+
+If there are multiple authors, each should be on a separate line
+following RFC 2822 continuation line conventions. Note that personal
+email addresses in GLEPs will be obscured as a defense against spam
+harvesters.
+
+While a GLEP is in private discussions (usually during the initial
+Draft phase), a Discussions-To header will indicate the mailing list
+or URL where the GLEP is being discussed. No Discussions-To header is
+necessary if the GLEP is being discussed privately with the author, or
+on the gentoo-dev mailing lists. Note that email
+addresses in the Discussions-To header will not be obscured.
+
+The Type header specifies the type of GLEP: Informational or Standards
+Track.
+
+The format of a GLEP is specified with a Content-Type header, which
+for now should always read "text/x-rst" for reStructuredText GLEPs (see GLEP 2 [4]_).
+
+The Created header records the date that the GLEP was assigned a
+number, while Post-History is used to record the dates of when new
+versions of the GLEP are posted to gentoo-dev. Both
+headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001.
+
+GLEPs may have a Requires header, indicating the GLEP numbers that this
+GLEP depends on.
+
+GLEPs may also have a Replaced-By header indicating that a GLEP has been
+rendered obsolete by a later document; the value is the number of the
+GLEP that replaces the current document. The newer GLEP must have a
+Replaces header containing the number of the GLEP that it rendered
+obsolete.
+
+
+Reporting GLEP Bugs, or Submitting GLEP Updates
+===============================================
+
+How you report a bug, or submit a GLEP update depends on several
+factors, such as the maturity of the GLEP, the preferences of the GLEP
+author, and the nature of your comments. For the early draft stages
+of the GLEP, it's probably best to send your comments and changes
+directly to the GLEP author. For more mature, or finished GLEPs you may
+want to submit corrections to the Gentoo Linux bugzilla_
+so that your changes don't get
+lost. If the GLEP author is a Gentoo Linux developer, assign the bug/patch to
+him, otherwise assign it to the GLEP editor.
+
+When in doubt about where to send your changes, please check first
+with the GLEP author and/or GLEP editors.
+
+GLEP authors who are also Gentoo Linux developers can update the GLEPs themselves
+by using "cvs commit" to commit their changes.
+
+Transferring GLEP Ownership
+===========================
+
+It occasionally becomes necessary to transfer ownership of GLEPs to a
+new champion. In general, we'd like to retain the original author as
+a co-author of the transferred GLEP, but that's really up to the
+original author. A good reason to transfer ownership is because the
+original author no longer has the time or interest in updating it or
+following through with the GLEP process, or has fallen off the face of
+the 'net (i.e. is unreachable or not responding to email). A bad
+reason to transfer ownership is because you don't agree with the
+direction of the GLEP. We try to build consensus around a GLEP, but if
+that's not possible, you can always submit a competing GLEP.
+
+If you are interested in assuming ownership of a GLEP, send a message
+asking to take over, addressed to both the original author and the GLEP
+editor <glep@gentoo.org>. If the original author doesn't respond to
+email in a timely manner, the GLEP editor will make a unilateral
+decision (it's not like such decisions can't be reversed :).
+
+
+References and Footnotes
+========================
+
+.. _PEP-0001: http://www.python.org/peps/pep-0001.html
+
+.. [1] This historical record is available by the normal CVS commands
+ for retrieving older revisions. For those without direct access to
+ the CVS tree, you can browse the current and past GLEP revisions via
+ the Gentoo Linux viewcvs web site at
+ http://cvs.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-x86/glep/
+
+.. [4] GLEP 2, Sample reStructuredText GLEP Template, Goodyear, Goodger, Warsaw
+ (http://www.gentoo.org/glep/glep-0002.html)
+
+
+.. _bugzilla: http://bugs.gentoo.org
+
+.. _Gentoo Linux forums: http://forums.gentoo.org
+
+.. _Open Publication License: http://www.opencontent.org/openpub/
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+
+.. _guide xml: http://www.gentoo.org/doc/en/xml-guide.xml
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+
+Copyright
+=========
+
+This document has been placed in the public domain.
diff --git a/glep-0002.txt b/glep-0002.txt
new file mode 100644
index 0000000..9679be5
--- /dev/null
+++ b/glep-0002.txt
@@ -0,0 +1,622 @@
+GLEP: 2
+Title: Sample reStructuredText GLEP Template
+Version: $Revision: 1.1 $
+Last-Modified: $Date: 2003/06/01 04:33:49 $
+Author: Grant Goodyear <g2boojum@gentoo.org>,
+ David Goodger <goodger@users.sourceforge.net>,
+ Barry A. Warsaw <barry@zope.com>
+Status: Draft
+Type: Informational
+Content-Type: text/x-rst
+Created: 31 May 2003
+Post-History:
+
+
+Abstract
+========
+
+This GLEP provides a boilerplate or sample template for creating your
+own reStructuredText GLEPs. In conjunction with the content guidelines
+in GLEP 1 [1]_, 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 (``.txt`` 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.
+
+- Leave the Version and Last-Modified headers alone; we'll take care
+ of those when we check your GLEP into CVS.
+
+- 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. Your e-mail address
+ here will e automatically obfuscated.
+
+- If there is a forum thread or a mailing list for discussion
+ of your new feature, add a
+ Discussions-To header right after the Author header. You should not
+ add a Discussions-To header if the mailing list to be used is
+ gentoo-dev@gentoo.org, or if discussions
+ should be sent to you directly. Most Informational GLEPs don't have
+ a Discussions-To header.
+
+- Change the Status header to "Draft".
+
+- For Standards Track GLEPs, change the Type header to "Standards
+ Track".
+
+- For Informational GLEPs, change the Type header to "Informational".
+
+- 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.
+
+- Change the Created header to today's date. Be sure to follow the
+ format carefully: it must be in ``dd-mmm-yyyy`` format, where the
+ ``mmm`` is the 3 English letter month abbreviation, i.e. one of Jan,
+ Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.
+
+- Leave Post-History alone for now; you'll add dates to this header
+ each time you post your GLEP to gentoo-dev@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: 14-Aug-2003, 03-Sept-2003
+
+ 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.
+
+- 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 and Copyright section. Usually you'll place
+ your GLEP into the public domain, in which case just leave the
+ Copyright section alone. Alternatively, you can use the `Open
+ Publication License`__, but public domain is still strongly
+ preferred.
+
+ __ http://www.opencontent.org/openpub/
+
+- 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://www.gentoo.org/gleps/glep-0001.html)
+
+If you decide to provide an explicit URL for a GLEP, please use this as
+the URL template::
+
+ http://www.gentoo.org/glep/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, Warsaw, Hylton
+
+ http://www.gentoo.org/glep/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
+==========
+
+.. [1] GLEP 1, GLEP Purpose and Guidelines, Goodyear, Warsaw, Hylton
+ (http://www.gentoo.org/glep/glep-0001.html)
+
+
+Copyright
+=========
+
+This document has been placed in the public domain.
+
diff --git a/tools/glep-html-template b/tools/glep-html-template
new file mode 100644
index 0000000..2f40be8
--- /dev/null
+++ b/tools/glep-html-template
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="%(encoding)s" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<!--
+This HTML is auto-generated. DO NOT EDIT THIS FILE! If you are writing a new
+PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
+to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
+-->
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=%(encoding)s" />
+ <meta name="generator" content="Docutils %(version)s: http://docutils.sourceforge.net/" />
+ <title>GLEP %(pep)s -- %(title)s</title>
+ %(stylesheet)s</head>
+<body bgcolor="white">
+<table class="navigation" cellpadding="0" cellspacing="0"
+ width="100%%" border="0">
+<tr><td class="navicon" width="150" height="35">
+<a href="%(pyhome)s/" title="Gentoo Linux Home Page">
+<img src="%(pyhome)s/images/gentoo-new.gif" alt="[Gentoo]"
+ border="0" width="150" height="35" /></a></td>
+<td class="textlinks" align="left">
+[<b><a href="%(pyhome)s/">Gentoo Linux Home</a></b>]
+[<b><a href="%(pepindex)s">GLEP Index</a></b>]
+[<b><a href="%(pephome)s/pep-%(pepnum)s.txt">GLEP Source</a></b>]
+</td></tr></table>
+%(body)s
+%(body_suffix)s
diff --git a/tools/glep.css b/tools/glep.css
new file mode 100644
index 0000000..67e9f01
--- /dev/null
+++ b/tools/glep.css
@@ -0,0 +1,240 @@
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date: 2003/06/01 04:33:49 $
+:version: $Revision: 1.1 $
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the PEP HTML output of Docutils.
+*/
+
+.first {
+ margin-top: 0 }
+
+.last {
+ margin-bottom: 0 }
+
+.navigation {
+ width: 100% ;
+ background: #cc99ff ;
+ margin-top: 0px ;
+ margin-bottom: 0px }
+
+.navigation .navicon {
+ width: 150px ;
+ height: 35px }
+
+.navigation .textlinks {
+ padding-left: 1em ;
+ text-align: left }
+
+.navigation td, .navigation th {
+ padding-left: 0em ;
+ padding-right: 0em ;
+ vertical-align: middle }
+
+.rfc2822 {
+ margin-top: 0.5em ;
+ margin-left: 0.5em ;
+ margin-right: 0.5em ;
+ margin-bottom: 0em }
+
+.rfc2822 td {
+ text-align: left }
+
+.rfc2822 th.field-name {
+ text-align: right ;
+ font-family: sans-serif ;
+ padding-right: 0.5em ;
+ font-weight: bold ;
+ margin-bottom: 0em }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+body {
+ margin: 0px ;
+ margin-bottom: 1em ;
+ padding: 0px }
+
+dd {
+ margin-bottom: 0.5em }
+
+div.section {
+ margin-left: 1em ;
+ margin-right: 1em ;
+ margin-bottom: 1.5em }
+
+div.section div.section {
+ margin-left: 0em ;
+ margin-right: 0em ;
+ margin-top: 1.5em }
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.figure {
+ margin-left: 2em }
+
+div.footer, div.header {
+ font-size: smaller }
+
+div.footer {
+ margin-left: 1em ;
+ margin-right: 1em }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1 {
+ font-family: sans-serif ;
+ font-size: large }
+
+h2 {
+ font-family: sans-serif ;
+ font-size: medium }
+
+h3 {
+ font-family: sans-serif ;
+ font-size: small }
+
+h4 {
+ font-family: sans-serif ;
+ font-style: italic ;
+ font-size: small }
+
+h5 {
+ font-family: sans-serif;
+ font-size: x-small }
+
+h6 {
+ font-family: sans-serif;
+ font-style: italic ;
+ font-size: x-small }
+
+.section hr {
+ width: 75% }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.topic-title {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+pre.line-block {
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em ;
+ background-color: #eeeeee }
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option-argument {
+ font-style: italic }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+table {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+td, th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+td.num {
+ text-align: right }
+
+th.field-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+ font-size: 100% }
+
+tt {
+ background-color: #eeeeee }
+
+ul.auto-toc {
+ list-style-type: none }