diff options
-rw-r--r-- | docutils.conf | 1 | ||||
-rw-r--r-- | glep-0001.txt | 381 | ||||
-rw-r--r-- | glep-0002.txt | 201 | ||||
-rw-r--r-- | tools/glep-html-template | 2 |
4 files changed, 284 insertions, 301 deletions
diff --git a/docutils.conf b/docutils.conf index 3961b12..f746e75 100644 --- a/docutils.conf +++ b/docutils.conf @@ -12,4 +12,5 @@ stylesheet-path: stylesheets/default.css pep-template: tools/glep-html-template pep-stylesheet-path: tools/glep.css python-home: http://www.gentoo.org +pep-home: http://www.gentoo.org/glep no-random: 1 diff --git a/glep-0001.txt b/glep-0001.txt index 89296e9..36c3f2e 100644 --- a/glep-0001.txt +++ b/glep-0001.txt @@ -1,7 +1,7 @@ GLEP: 1 Title: GLEP Purpose and Guidelines -Version: $Revision: 1.1 $ -Last-Modified: $Date: 2003/06/01 04:33:49 $ +Version: $Revision: 1.2 $ +Last-Modified: $Date: 2003/06/01 14:05:29 $ Author: Grant Goodyear Status: Draft Type: Informational @@ -10,14 +10,20 @@ Created: 31 May 2003 Post-History: +Credits +======= + +The GLEP concept, and, in fact, much of the text of this document, +is liberally stolen from Python's [#Python]_ PEPs +[#PEPS]_, especially +PEP-0001 [#PEP1]_ by Barry A. Warsaw, Jeremy Hylton, and David Goodger. + 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 +a new feature for Gentoo Linux. 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 @@ -28,47 +34,44 @@ 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]_. +[#CVS]_. 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. +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 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_. +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 editors +reserve 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 [#BUGS]_. 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. +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?) @@ -79,69 +82,59 @@ 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. +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. +gentoo-dev mailing list and to the Gentoo Linux forums [#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. +gentoo-dev@gentoo.org and/or the Gentoo Linux forums [#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 distribution 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. +obsolete (where version 2 of a policy, for example, might replace version 1). GLEP work flow is as follows:: @@ -151,8 +144,8 @@ GLEP work flow is as follows:: 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). +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? @@ -168,66 +161,59 @@ Each GLEP should have the following parts: 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 +3. 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. + existing functionality or policy is inadequate to address the problem that + the GLEP solves. GLEP submissions without sufficient motivation may be + rejected outright. + +4. 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? + +5. 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. + +6. 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. + +7. 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. + +8. 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 [#OPL]. 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. +GLEPs are written in a just-barely-marked-up version of plain ASCII text +called ReStructuredText [#ReSTHOME]_ that is then converted to HTML using +Docutils [#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 +Gentoo Linux guide xml [#GUIDEXML]_ if needed. GLEP 2 contains a boilerplate +template [#ReST]_ for use with ReStructuredText GLEPs. GLEP Header Preamble ==================== -Each GLEP must begin with an RFC 822 style header preamble. The headers +Each GLEP must begin with an RFC 2822 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. :: @@ -264,100 +250,101 @@ 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. +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 list. 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 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 +[#ReST]_). -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. +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 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. +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. +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 [#BUGS]_ 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 editors. -When in doubt about where to send your changes, please check first -with the GLEP author and/or GLEP editors. +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. +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 +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 :). +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 editors +<glep@gentoo.org>. If the original author doesn't respond to email in a +timely manner, the GLEP editors 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 +.. [#PYTHON] http://www.python.org -.. [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 +.. [#PEPS] http://www.python.org/peps + +.. [#PEP1] http://www.python.org/peps/pep-0001.html + +.. [#CVS] 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 +.. [#ReST] GLEP 2, Sample ReStructuredText GLEP Template, (http://www.gentoo.org/glep/glep-0002.html) +.. [#BUGS] http://bugs.gentoo.org -.. _bugzilla: http://bugs.gentoo.org - -.. _Gentoo Linux forums: http://forums.gentoo.org +.. [#FORUMS] http://forums.gentoo.org -.. _Open Publication License: http://www.opencontent.org/openpub/ +.. [#OPL] http://www.opencontent.org/openpub/ -.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. [#ReSTHOME] http://docutils.sourceforge.net/rst.html -.. _guide xml: http://www.gentoo.org/doc/en/xml-guide.xml +.. [#GUIDEXML] http://www.gentoo.org/doc/en/xml-guide.xml -.. _Docutils: http://docutils.sourceforge.net/ +.. [#DOCUTILS] http://docutils.sourceforge.net/ Copyright diff --git a/glep-0002.txt b/glep-0002.txt index 9679be5..2f2f2b9 100644 --- a/glep-0002.txt +++ b/glep-0002.txt @@ -1,10 +1,8 @@ GLEP: 2 -Title: Sample reStructuredText GLEP Template -Version: $Revision: 1.1 $ -Last-Modified: $Date: 2003/06/01 04:33:49 $ +Title: Sample ReStructuredText GLEP Template +Version: $Revision: 1.2 $ +Last-Modified: $Date: 2003/06/01 14:05:29 $ 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 @@ -12,61 +10,63 @@ Created: 31 May 2003 Post-History: +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 [1]_, this should make it easy for you to conform your own -GLEPs to the format outlined below. +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!** +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". +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. +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. +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. +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. +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>. +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. @@ -83,19 +83,17 @@ directions below. 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 + 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. + 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". @@ -105,43 +103,40 @@ directions below. - 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. + 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. + 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:: + 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. + 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. + 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. + 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. + 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/ @@ -151,34 +146,32 @@ directions below. 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. +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. +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:: +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 ================= @@ -189,9 +182,8 @@ apostrophes). For example:: 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:: +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) @@ -210,25 +202,24 @@ levels as follows:: 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 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. +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. +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). +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 @@ -611,7 +602,11 @@ list`_. The `Docutils project web site`_ has more information. References ========== -.. [1] GLEP 1, GLEP Purpose and Guidelines, Goodyear, Warsaw, Hylton +.. [#PYTHON] http://www.python.org + +.. [#PEP12] http://www.python.org/peps/pep-0012.html + +.. [#GLEP1] GLEP 1, GLEP Purpose and Guidelines, Goodyear, (http://www.gentoo.org/glep/glep-0001.html) diff --git a/tools/glep-html-template b/tools/glep-html-template index 2f40be8..77a2028 100644 --- a/tools/glep-html-template +++ b/tools/glep-html-template @@ -21,7 +21,7 @@ to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE! <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>] +[<b><a href="%(pephome)s/glep-%(pepnum)s.txt">GLEP Source</a></b>] </td></tr></table> %(body)s %(body_suffix)s |