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