diff options
-rw-r--r-- | README.txt | 59 | ||||
-rw-r--r-- | docutils.conf | 15 | ||||
-rw-r--r-- | glep-0001.txt | 366 | ||||
-rw-r--r-- | glep-0002.txt | 622 | ||||
-rw-r--r-- | tools/glep-html-template | 27 | ||||
-rw-r--r-- | tools/glep.css | 240 |
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 } |