GLEP:2

Warning
This GLEP is no longer maintained in the Gentoo Wiki and remains here only as a historical record. Please visit https://www.gentoo.org/glep/glep-0002.html for the current version of this GLEP.

GLEP 2: Sample Wiki Markup GLEP Template
Type	Informational
Status	Active
Author	Grant Goodyear <g2boojum@gentoo.org>, Chris Reffett <creffett@gentoo.org>
Editor
Replaces
Replaced by	(none)
Requires
Post History

Credits

The text of this GLEP was, to a significant extent, stolen from Python's PEP-0012 by David Goodger and Barry A. Warsaw.

Note: if you are reading this GLEP via the web, you should first grab the text (Wiki Markup) 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 page and click on the link titled "View source".

Abstract

This GLEP provides a boilerplate or sample template for creating your own Wiki text GLEPs. In conjunction with the content guidelines in GLEP 1 , this should make it easy for you to conform your own GLEPs to the format outlined below.

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.

Wiki Markup is used to allow GLEP authors more functionality and expressivity, while maintaining easy readability in the source text. The format 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 the source as described under "Abstract" 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 header alone; we'll take care of those when we add your GLEP to the wiki.

• 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.

• 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 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.

Wiki Markup GLEP Formatting Requirements

The following is a GLEP-specific summary of Wiki Markup syntax. For the sake of simplicity and brevity, much detail is omitted. For more detail, see Resources below. <nowiki> 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. There are no longer line length restrictions when creating GLEPs.

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 properly marked as such using the "=" (equals sign) character, with the number of equals corresponding to the level of the heading plus one, so two equals signs on each side for a first-level title, three on each side for a second-level title, and so on up to five levels. For example:

==First-Level Title==
===Second-Level Title===
====Third-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). Wiki Markup formatting interprets newlines in a specific way. A single newline is treated as formatting and so there is no line inserted into the displayed product, but two newlines is interpreted as a line break and inserts a newline into the final product. For example, this does not display a line break, but

this has two newlines and therefore does.

Inline Markup

Portions of text within paragraphs and other text blocks may be styled. For example:

Text may be marked as emphasized (double apostrophe markup, typically shown in italics) or strongly emphasized (triple apostrophes, typically boldface). Preformatted sections (set off using <pre> tags) are typically rendered in a monospaced typeface. No further markup recognition is done within the tags, so they're safe for any kind of code snippets. Alternatively, if the snippet should not be set aside in a monospaced typeface, the <nowiki> tag may be used, but this strips line breaks and other whitespace.

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. A contiguous block quote should not have extra spacing between lines; this causes the wiki to break them up into separate quotes.

Literal Blocks

Literal blocks are used for code samples or preformatted ASCII art. To indicate a literal block, preface the text block with <pre>. The literal block continues until the </pre> block is reached. 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..."

Lists

Bullet list items begin with "*" (asterisk) for a bulleted list followed by whitespace and the list item body. Sub-lists may be created by adding additional list symbols, so "**" would add a bullet for a sub-list, "***" would add a bullet for a sub-sub-list, and so on. For example:

This paragraph is followed by a list.

• This is the first bullet list item.
• This is the first paragraph in the second item in the list.
  This is the second paragraph in the second item in the list. In order to add extra paragraphs to a list item, add the <br /> tag before the second paragraph.
  • This is is a sublist.
• 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 the "#" symbol instead of the "*" symbol.

1. First entry of an enumerated list.
2. Each list item may contain multiple paragraphs, sublists, etc.
   This is the second paragraph of the second list item.
   1. Enumerated lists may be nested.
   2. Keep in mind that you should not have extra newlines between list elements, since they must be in a contiguous group in order to be numbered properly

Definition lists are written like this:

what

Definition lists associate a term with a definition.

how

the term is a one-line phrase preceded by ; (a semicolon), and the definition is preceded by : (a colon).

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 can be accomplished using single brackets. These brackets should contain the link, a space, then the text to display for the hyperlink. For example:

In this paragraph, we refer to the [http://www.python.org/ Python web site]

There are certain limitations to embedding hyperlinks like this, mostly related to special characters requiring replacement. Wikipedia has a list of these special cases.

A similar mechanism can be used for internal references or references within the wiki, although these use double brackets instead of single brackets and a vertical pipe to differentiate between the target and the display text. 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|Abstract]] section.

Footnotes

The references section will be generated via the Mediawiki "Cite" extension. In order to add a refence, use <ref name="(name)">(Link/name of source)</ref>. Any subsequent references to the same source may use <ref name="(name)"/> to refer to the same source. All references should have a name associated with them. Under the References section, the tag <references/> should be used to output all of the references in a list.

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, which should include the title and author's name, and may optionally include an explicit URL. If you decide to provide an explicit URL for a GLEP, please use this as the URL template:

   http://wiki.gentoo.org/wiki/GLEP:xxxx.html 

A citation of GLEP 1 done like this might look like:

Refer to GLEP 1 for more information.<ref name="glep1">
GLEP 1, GLEP Purpose and Guidelines, Goodyear, (http://wiki.gentoo.org/wiki/GLEP:0001.html)</ref>

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.

Footnotes and footnote references will be numbered and inserted automatically, and the numbers will always match.

Images

If your GLEP contains a diagram, you first must upload it at the [[Special:Upload|upload page.] You may then include it in the processed output using a File: tag:

[[File: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 a block of markup text that will not appear in the final page. It is delimited by <!-- and -->, and so looks like this:

<!--Here is a comment!-->

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:

[[File:dataflow.png]]
<!--Data flows from the input module, through the "black box" module, and finally into (and through) the output module.-->

Resources

Wiki Markup has a large number of formatting options, this guide should only be considered to be a basic introduction. For more information, the following links may be useful:

• The Wikipedia Cheat Sheet, which is a quick reference for basic formatting.
• The Wikipedia help page on Wiki Markup, which is much more in-depth and has many subpages for specific topics.

References

This section should include a <references /> tag, which will automatically generate all footnotes from the above document.

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/.