en/glep/glep-0043.html

<?xml version="1.0" encoding="utf-8" ?>
<!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=utf-8" />
  <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
  <title>GLEP 43 -- GLEP File Hosting</title>
  <style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:date: $Date: 2003/06/02 17:03:08 $
: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 }

</style>
</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="http://www.gentoo.org/" title="Gentoo Linux Home Page">
<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
 border="0" width="150" height="35" /></a></td>
<td class="textlinks" align="left">
[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
[<b><a href="http://www.gentoo.org/peps">GLEP Index</a></b>]
[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0043.txt">GLEP Source</a></b>]
</td></tr></table>
<table class="rfc2822 docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">43</td>
</tr>
<tr class="field"><th class="field-name">Title:</th><td class="field-body">GLEP File Hosting</td>
</tr>
<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.2</td>
</tr>
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Ciaran McCreesh &lt;ciaranm&#32;&#97;t&#32;gentoo.org&gt;</td>
</tr>
<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0043.txt?cvsroot=gentoo">2005/11/13 17:16:16</a></td>
</tr>
<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
</tr>
<tr class="field"><th class="field-name">Type:</th><td class="field-body">Informational</td>
</tr>
<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="glep-0002.html">text/x-rst</a></td>
</tr>
<tr class="field"><th class="field-name">Created:</th><td class="field-body">7-Nov-2005</td>
</tr>
<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">7-Nov-2005</td>
</tr>
</tbody>
</table>
<hr />
<div class="contents topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#abstract" id="id2" name="id2">Abstract</a></li>
<li><a class="reference" href="#status" id="id3" name="id3">Status</a></li>
<li><a class="reference" href="#motivation" id="id4" name="id4">Motivation</a></li>
<li><a class="reference" href="#specification" id="id5" name="id5">Specification</a><ul>
<li><a class="reference" href="#example" id="id6" name="id6">Example</a></li>
</ul>
</li>
<li><a class="reference" href="#backwards-compatibility" id="id7" name="id7">Backwards Compatibility</a></li>
<li><a class="reference" href="#references" id="id8" name="id8">References</a></li>
<li><a class="reference" href="#copyright" id="id9" name="id9">Copyright</a></li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id2" id="abstract" name="abstract">Abstract</a></h1>
<p>This GLEP proposes the creation of a reliable hosting location for data (e.g.
sample code) associated with GLEPs.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id3" id="status" name="status">Status</a></h1>
<p>This GLEP has been approved by the GLEP editor and marked Final on
13 Nov. 2005.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id4" id="motivation" name="motivation">Motivation</a></h1>
<p>Some GLEPs come with non-trivial example files or code which are part of the
specification. There are two methods which have been used to handle this
previously:</p>
<ul class="simple">
<li>Include the code inline in the GLEP using a code (<tt class="docutils literal"><span class="pre">::</span></tt>) segment. This is
less than ideal for larger code samples as it leads to considerable clutter.</li>
<li>Place the files on a developer's webspace on <tt class="docutils literal"><span class="pre">dev.gentoo.org</span></tt>. This is not
particularly reliable -- developers may leave or accidentally restructure
their webspace, and a GLEP is intended to be a <em>permanent</em> specification.</li>
</ul>
<p>This GLEP proposes that GLEP authors be allowed to make use of the main Gentoo
webserver for hosting content relevant to their GLEP.</p>
<div class="important">
<p class="first admonition-title">Important</p>
<p class="last">The hosting proposed is for files related to the <strong>proposal</strong>
(e.g. example code which clarifies part of the specification), not a full
implementation of the proposal.</p>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id5" id="specification" name="specification">Specification</a></h1>
<p>Once a GLEP number has been allocated, developers (or the GLEP editors) may
create a directory in CVS named <tt class="docutils literal"><span class="pre">glep-xxxx-extras/</span></tt> (where <tt class="docutils literal"><span class="pre">xxxx</span></tt> is the
GLEP's number) under the main GLEP directory. This directory may be used by
files which are part of the proposal.</p>
<p>Any hyperlinks to files inside this directory should use relative paths. This
prevents breakages in the case of directory structure changes.</p>
<p>GLEPs which use this directory may include an 'Example Files' heading with a
list of links to the associated files.</p>
<div class="section">
<h2><a class="toc-backref" href="#id6" id="example" name="example">Example</a></h2>
<p>Consider the following GLEP segment, which has been taken from a draft of
GLEP 42 <a class="footnote-reference" href="#glep-42" id="id1" name="id1">[1]</a>:</p>
<pre class="literal-block">
Example News Item
'''''''''''''''''

The following hypothetical news item could be used for an upgrade to the
``YourSQL`` database format which breaks forward compatibility. It should be
named ``2005-11/2005-11-01-yoursql-upgrades.en.txt``.

::

    # Lots and lots of lines of example news item
</pre>
<p>The news item in question is clearly part of the proposal, but including it
inline is messy. Under this proposal, the main GLEP segment would read:</p>
<pre class="literal-block">
Example News Item
'''''''''''''''''

`This hypothetical news item`__ could be used for an upgrade to the
``YourSQL`` database format which breaks forward compatibility. It would be
named ``2005-11/2005-11-01-yoursql-upgrades.en.txt``.

.. __: glep-0042-extras/example-news-item.txt
</pre>
<p>The example news item would then be placed in
<tt class="docutils literal"><span class="pre">glep-0042-extras/example-news-item.txt</span></tt>.</p>
<p>Similar changes would be made for the longer example code segments. The GLEP
could also gain a new section along the lines of:</p>
<pre class="literal-block">
Example Files
=============

`example-news-item.txt &lt;glep-0042-extras/example-news-item.txt&gt;`_
    An example news item.
`news-mailer.bash &lt;glep-0042-extras/news-mailer.bash&gt;`_
    A ``bash`` script which delivers news items via email.
</pre>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id7" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
<p>Not an issue.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id8" id="references" name="references">References</a></h1>
<table class="docutils footnote" frame="void" id="glep-42" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1" name="glep-42">[1]</a></td><td>GLEP 42: Critical news reporting, Ciaran McCreesh,
<a class="reference" href="http://www.gentoo.org/proj/en/glep/glep-0042.html">http://www.gentoo.org/proj/en/glep/glep-0042.html</a></td></tr>
</tbody>
</table>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id9" id="copyright" name="copyright">Copyright</a></h1>
<p>This document has been placed in the public domain.</p>
<!-- vim: set tw=80 fileencoding=utf-8 spell spelllang=en et : -->
</div>

</div>
<div class="footer">
<hr class="footer" />
<a class="reference" href="glep-0043.txt">View document source</a>.
Generated on: 2006-10-10 20:23 UTC.
Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.

</div>
</body>
</html>
1	ciaranm	1.1	<?xml version="1.0" encoding="utf-8" ?>
2			<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3			<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4			<!--
5			This HTML is auto-generated. DO NOT EDIT THIS FILE! If you are writing a new
6			PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
7			to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
8			-->
9			<head>
10			<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11	g2boojum	1.3	<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
12	ciaranm	1.1	<title>GLEP 43 -- GLEP File Hosting</title>
13	g2boojum	1.3	<style type="text/css">
14
15			/*
16			:Author: David Goodger
17			:Contact: goodger@users.sourceforge.net
18			:date: $Date: 2003/06/02 17:03:08 $
19			:version: $Revision: 1.1 $
20			:copyright: This stylesheet has been placed in the public domain.
21
22			Default cascading style sheet for the PEP HTML output of Docutils.
23			*/
24
25			.first {
26			margin-top: 0 }
27
28			.last {
29			margin-bottom: 0 }
30
31			.navigation {
32			width: 100% ;
33			background: #cc99ff ;
34			margin-top: 0px ;
35			margin-bottom: 0px }
36
37			.navigation .navicon {
38			width: 150px ;
39			height: 35px }
40
41			.navigation .textlinks {
42			padding-left: 1em ;
43			text-align: left }
44
45			.navigation td, .navigation th {
46			padding-left: 0em ;
47			padding-right: 0em ;
48			vertical-align: middle }
49
50			.rfc2822 {
51			margin-top: 0.5em ;
52			margin-left: 0.5em ;
53			margin-right: 0.5em ;
54			margin-bottom: 0em }
55
56			.rfc2822 td {
57			text-align: left }
58
59			.rfc2822 th.field-name {
60			text-align: right ;
61			font-family: sans-serif ;
62			padding-right: 0.5em ;
63			font-weight: bold ;
64			margin-bottom: 0em }
65
66			a.toc-backref {
67			text-decoration: none ;
68			color: black }
69
70			body {
71			margin: 0px ;
72			margin-bottom: 1em ;
73			padding: 0px }
74
75			dd {
76			margin-bottom: 0.5em }
77
78			div.section {
79			margin-left: 1em ;
80			margin-right: 1em ;
81			margin-bottom: 1.5em }
82
83			div.section div.section {
84			margin-left: 0em ;
85			margin-right: 0em ;
86			margin-top: 1.5em }
87
88			div.abstract {
89			margin: 2em 5em }
90
91			div.abstract p.topic-title {
92			font-weight: bold ;
93			text-align: center }
94
95			div.attention, div.caution, div.danger, div.error, div.hint,
96			div.important, div.note, div.tip, div.warning {
97			margin: 2em ;
98			border: medium outset ;
99			padding: 1em }
100
101			div.attention p.admonition-title, div.caution p.admonition-title,
102			div.danger p.admonition-title, div.error p.admonition-title,
103			div.warning p.admonition-title {
104			color: red ;
105			font-weight: bold ;
106			font-family: sans-serif }
107
108			div.hint p.admonition-title, div.important p.admonition-title,
109			div.note p.admonition-title, div.tip p.admonition-title {
110			font-weight: bold ;
111			font-family: sans-serif }
112
113			div.figure {
114			margin-left: 2em }
115
116			div.footer, div.header {
117			font-size: smaller }
118
119			div.footer {
120			margin-left: 1em ;
121			margin-right: 1em }
122
123			div.system-messages {
124			margin: 5em }
125
126			div.system-messages h1 {
127			color: red }
128
129			div.system-message {
130			border: medium outset ;
131			padding: 1em }
132
133			div.system-message p.system-message-title {
134			color: red ;
135			font-weight: bold }
136
137			div.topic {
138			margin: 2em }
139
140			h1 {
141			font-family: sans-serif ;
142			font-size: large }
143
144			h2 {
145			font-family: sans-serif ;
146			font-size: medium }
147
148			h3 {
149			font-family: sans-serif ;
150			font-size: small }
151
152			h4 {
153			font-family: sans-serif ;
154			font-style: italic ;
155			font-size: small }
156
157			h5 {
158			font-family: sans-serif;
159			font-size: x-small }
160
161			h6 {
162			font-family: sans-serif;
163			font-style: italic ;
164			font-size: x-small }
165
166			.section hr {
167			width: 75% }
168
169			ol.simple, ul.simple {
170			margin-bottom: 1em }
171
172			ol.arabic {
173			list-style: decimal }
174
175			ol.loweralpha {
176			list-style: lower-alpha }
177
178			ol.upperalpha {
179			list-style: upper-alpha }
180
181			ol.lowerroman {
182			list-style: lower-roman }
183
184			ol.upperroman {
185			list-style: upper-roman }
186
187			p.caption {
188			font-style: italic }
189
190			p.credits {
191			font-style: italic ;
192			font-size: smaller }
193
194			p.label {
195			white-space: nowrap }
196
197			p.topic-title {
198			font-family: sans-serif ;
199			font-weight: bold }
200
201			pre.line-block {
202			font-family: serif ;
203			font-size: 100% }
204
205			pre.literal-block, pre.doctest-block {
206			margin-left: 2em ;
207			margin-right: 2em ;
208			background-color: #eeeeee }
209
210			span.classifier {
211			font-family: sans-serif ;
212			font-style: oblique }
213
214			span.classifier-delimiter {
215			font-family: sans-serif ;
216			font-weight: bold }
217
218			span.interpreted {
219			font-family: sans-serif }
220
221			span.option-argument {
222			font-style: italic }
223
224			span.pre {
225			white-space: pre }
226
227			span.problematic {
228			color: red }
229
230			table {
231			margin-top: 0.5em ;
232			margin-bottom: 0.5em }
233
234			td, th {
235			padding-left: 0.5em ;
236			padding-right: 0.5em ;
237			vertical-align: top }
238
239			td.num {
240			text-align: right }
241
242			th.field-name {
243			font-weight: bold ;
244			text-align: left ;
245			white-space: nowrap }
246
247			h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
248			font-size: 100% }
249
250			tt {
251			background-color: #eeeeee }
252
253			ul.auto-toc {
254			list-style-type: none }
255
256			</style>
257	ciaranm	1.1	</head>
258			<body bgcolor="white">
259			<table class="navigation" cellpadding="0" cellspacing="0"
260			width="100%" border="0">
261			<tr><td class="navicon" width="150" height="35">
262			<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
263			<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
264			border="0" width="150" height="35" /></a></td>
265			<td class="textlinks" align="left">
266			[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
267	g2boojum	1.3	[<b><a href="http://www.gentoo.org/peps">GLEP Index</a></b>]
268			[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0043.txt">GLEP Source</a></b>]
269	ciaranm	1.1	</td></tr></table>
270			<table class="rfc2822 docutils field-list" frame="void" rules="none">
271			<col class="field-name" />
272			<col class="field-body" />
273			<tbody valign="top">
274			<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">43</td>
275			</tr>
276			<tr class="field"><th class="field-name">Title:</th><td class="field-body">GLEP File Hosting</td>
277			</tr>
278	g2boojum	1.2	<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.2</td>
279	ciaranm	1.1	</tr>
280			<tr class="field"><th class="field-name">Author:</th><td class="field-body">Ciaran McCreesh <ciaranm at gentoo.org></td>
281			</tr>
282	g2boojum	1.3	<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0043.txt?cvsroot=gentoo">2005/11/13 17:16:16</a></td>
283	ciaranm	1.1	</tr>
284			<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
285			</tr>
286			<tr class="field"><th class="field-name">Type:</th><td class="field-body">Informational</td>
287			</tr>
288	g2boojum	1.3	<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="glep-0002.html">text/x-rst</a></td>
289	ciaranm	1.1	</tr>
290			<tr class="field"><th class="field-name">Created:</th><td class="field-body">7-Nov-2005</td>
291			</tr>
292			<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">7-Nov-2005</td>
293			</tr>
294			</tbody>
295			</table>
296			<hr />
297	g2boojum	1.3	<div class="contents topic">
298			<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
299	ciaranm	1.1	<ul class="simple">
300			<li><a class="reference" href="#abstract" id="id2" name="id2">Abstract</a></li>
301	g2boojum	1.2	<li><a class="reference" href="#status" id="id3" name="id3">Status</a></li>
302			<li><a class="reference" href="#motivation" id="id4" name="id4">Motivation</a></li>
303			<li><a class="reference" href="#specification" id="id5" name="id5">Specification</a><ul>
304			<li><a class="reference" href="#example" id="id6" name="id6">Example</a></li>
305	ciaranm	1.1	</ul>
306			</li>
307	g2boojum	1.2	<li><a class="reference" href="#backwards-compatibility" id="id7" name="id7">Backwards Compatibility</a></li>
308			<li><a class="reference" href="#references" id="id8" name="id8">References</a></li>
309			<li><a class="reference" href="#copyright" id="id9" name="id9">Copyright</a></li>
310	ciaranm	1.1	</ul>
311			</div>
312	g2boojum	1.3	<div class="section">
313			<h1><a class="toc-backref" href="#id2" id="abstract" name="abstract">Abstract</a></h1>
314	ciaranm	1.1	<p>This GLEP proposes the creation of a reliable hosting location for data (e.g.
315			sample code) associated with GLEPs.</p>
316			</div>
317	g2boojum	1.3	<div class="section">
318			<h1><a class="toc-backref" href="#id3" id="status" name="status">Status</a></h1>
319	g2boojum	1.2	<p>This GLEP has been approved by the GLEP editor and marked Final on
320			13 Nov. 2005.</p>
321			</div>
322	g2boojum	1.3	<div class="section">
323			<h1><a class="toc-backref" href="#id4" id="motivation" name="motivation">Motivation</a></h1>
324	ciaranm	1.1	<p>Some GLEPs come with non-trivial example files or code which are part of the
325			specification. There are two methods which have been used to handle this
326			previously:</p>
327			<ul class="simple">
328			<li>Include the code inline in the GLEP using a code (<tt class="docutils literal"><span class="pre">::</span></tt>) segment. This is
329			less than ideal for larger code samples as it leads to considerable clutter.</li>
330			<li>Place the files on a developer's webspace on <tt class="docutils literal"><span class="pre">dev.gentoo.org</span></tt>. This is not
331			particularly reliable -- developers may leave or accidentally restructure
332			their webspace, and a GLEP is intended to be a <em>permanent</em> specification.</li>
333			</ul>
334			<p>This GLEP proposes that GLEP authors be allowed to make use of the main Gentoo
335			webserver for hosting content relevant to their GLEP.</p>
336			<div class="important">
337			<p class="first admonition-title">Important</p>
338			<p class="last">The hosting proposed is for files related to the <strong>proposal</strong>
339			(e.g. example code which clarifies part of the specification), not a full
340			implementation of the proposal.</p>
341			</div>
342			</div>
343	g2boojum	1.3	<div class="section">
344			<h1><a class="toc-backref" href="#id5" id="specification" name="specification">Specification</a></h1>
345	ciaranm	1.1	<p>Once a GLEP number has been allocated, developers (or the GLEP editors) may
346			create a directory in CVS named <tt class="docutils literal"><span class="pre">glep-xxxx-extras/</span></tt> (where <tt class="docutils literal"><span class="pre">xxxx</span></tt> is the
347			GLEP's number) under the main GLEP directory. This directory may be used by
348			files which are part of the proposal.</p>
349			<p>Any hyperlinks to files inside this directory should use relative paths. This
350			prevents breakages in the case of directory structure changes.</p>
351			<p>GLEPs which use this directory may include an 'Example Files' heading with a
352			list of links to the associated files.</p>
353	g2boojum	1.3	<div class="section">
354			<h2><a class="toc-backref" href="#id6" id="example" name="example">Example</a></h2>
355	ciaranm	1.1	<p>Consider the following GLEP segment, which has been taken from a draft of
356			GLEP 42 <a class="footnote-reference" href="#glep-42" id="id1" name="id1">[1]</a>:</p>
357			<pre class="literal-block">
358			Example News Item
359			'''''''''''''''''
360
361			The following hypothetical news item could be used for an upgrade to the
362			``YourSQL`` database format which breaks forward compatibility. It should be
363			named ``2005-11/2005-11-01-yoursql-upgrades.en.txt``.
364
365			::
366
367			# Lots and lots of lines of example news item
368			</pre>
369			<p>The news item in question is clearly part of the proposal, but including it
370			inline is messy. Under this proposal, the main GLEP segment would read:</p>
371			<pre class="literal-block">
372			Example News Item
373			'''''''''''''''''
374
375			`This hypothetical news item`__ could be used for an upgrade to the
376			``YourSQL`` database format which breaks forward compatibility. It would be
377			named ``2005-11/2005-11-01-yoursql-upgrades.en.txt``.
378
379			.. __: glep-0042-extras/example-news-item.txt
380			</pre>
381			<p>The example news item would then be placed in
382			<tt class="docutils literal"><span class="pre">glep-0042-extras/example-news-item.txt</span></tt>.</p>
383			<p>Similar changes would be made for the longer example code segments. The GLEP
384			could also gain a new section along the lines of:</p>
385			<pre class="literal-block">
386			Example Files
387			=============
388
389			`example-news-item.txt <glep-0042-extras/example-news-item.txt>`_
390			An example news item.
391			`news-mailer.bash <glep-0042-extras/news-mailer.bash>`_
392			A ``bash`` script which delivers news items via email.
393			</pre>
394			</div>
395			</div>
396	g2boojum	1.3	<div class="section">
397			<h1><a class="toc-backref" href="#id7" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
398	ciaranm	1.1	<p>Not an issue.</p>
399			</div>
400	g2boojum	1.3	<div class="section">
401			<h1><a class="toc-backref" href="#id8" id="references" name="references">References</a></h1>
402	ciaranm	1.1	<table class="docutils footnote" frame="void" id="glep-42" rules="none">
403			<colgroup><col class="label" /><col /></colgroup>
404			<tbody valign="top">
405			<tr><td class="label"><a class="fn-backref" href="#id1" name="glep-42">[1]</a></td><td>GLEP 42: Critical news reporting, Ciaran McCreesh,
406			<a class="reference" href="http://www.gentoo.org/proj/en/glep/glep-0042.html">http://www.gentoo.org/proj/en/glep/glep-0042.html</a></td></tr>
407			</tbody>
408			</table>
409			</div>
410	g2boojum	1.3	<div class="section">
411			<h1><a class="toc-backref" href="#id9" id="copyright" name="copyright">Copyright</a></h1>
412	ciaranm	1.1	<p>This document has been placed in the public domain.</p>
413			<!-- vim: set tw=80 fileencoding=utf-8 spell spelllang=en et : -->
414			</div>
415
416			</div>
417			<div class="footer">
418			<hr class="footer" />
419			<a class="reference" href="glep-0043.txt">View document source</a>.
420	g2boojum	1.3	Generated on: 2006-10-10 20:23 UTC.
421	ciaranm	1.1	Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
422
423			</div>
424			</body>
425			</html>