Context Navigation

← Previous Changeset
Next Changeset →

Changeset 10535

Timestamp:

02/04/08 17:52:40 (2 years ago)

Author:

dave

Message:

modify docutils beps.py to use pep_base_url.

I tried using bep_base_url to disambiguate the base URL for beps and peps, but this required reaching
into the source code for restructured text (which has some hard-coded notion of PEPs). I decided
not to touch that code just now.

regenerate updated html files.

Location:

dotorg/trunk_fixed

Files:

: 7 modified

docutils/docutils/transforms/beps.py (modified) (4 diffs)
html/beps/bep_0000.html (modified) (1 diff)
html/beps/bep_0001.rst (modified) (4 diffs)
html/beps/bep_0002.html (modified) (1 diff)
html/beps/bep_0002.rst (modified) (3 diffs)
html/beps/bep_0003.html (modified) (3 diffs)
html/beps/makefile (modified) (2 diffs)

Legend:

: Unmodified
: Added
: Removed

dotorg/trunk_fixed/docutils/docutils/transforms/beps.py

r10307	r10535
33	33	default_priority = 360
34	34
	35	# NOTE: There is no bep_base_url. The base of the BEP directory is specified with pep_base_url
	36	# because changing this requires modifying the rst repository. This value can be changed with the pep-base-url
	37	# argument. For now, I don't want to modify restructured text parsing code. It means we cannot currently
	38	# disambiguate between peps and beps for specifying the base url.
35	39	bep_url = 'bep-%04d'
36	40	bep_cvs_url = ('https://svn.bittorrent.com/trac.cgi/browser/dotorg/trunk/html/beps/bep_%04d.rst')
37		//bep_cvs_url = ('http://svn.bittorrent.com/view/checkout'
38		// '/peps/trunk/bep-%04d.txt')
	41	#bep_cvs_url = ('http://svn.bittorrent.com/view/checkout'
	42	# '/peps/trunk/bep-%04d.txt')
39	43	rcs_keyword_substitutions = (
40	44	(re.compile(r'\$' r'RCSfile: (.+),v \$$', re.IGNORECASE), r'\1'),
…	…
120	124	newbody.append(nodes.reference(
121	125	refbep, refbep,
122		refuri=(self.document.settings.bep_base_url
	126	refuri=(self.document.settings.pep_base_url
123	127	+ self.bep_url % bepno)))
124	128	newbody.append(space)
…	…
131	135	elif name == 'content-type':
132	136	bep_type = para.astext()
133		uri = self.document.settings.bep_base_url + self.bep_url % 12
	137	uri = self.document.settings.pep_base_url + self.bep_url % 12
134	138	para[:] = [nodes.reference('', bep_type, refuri=uri)]
135	139	elif name == 'version' and len(body):
…	…
269	273	try:
270	274	bep = int(text)
271		ref = (self.document.settings.bep_base_url
	275	ref = (self.document.settings.pep_base_url
272	276	+ self.bep_url % bep)
273	277	p[0] = nodes.reference(text, text, refuri=ref)

dotorg/trunk_fixed/html/beps/bep_0000.html

r10530	r10535
	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	<head>
	5	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	6	<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
	7	<title></title>
	8	<link rel="stylesheet" href="../css/bep.css" type="text/css" />
	9	</head>
	10	<body>
	11	<div class="document">
	12
	13	<div id="upper" class="clear">
	14	<div id="wrap">
	15	<div id="header">
	16	<h1><a href="../index.html">BitTorrent<span>.org</span></a></h1>
	17	</div>
	18	<div id="nav">
	19	<ul>
	20	<li><a href="../index.html">Home</a></li>
	21	<li><a href="../introduction.html">For Users</a></li>
	22	<li><span>For Developers</span></li>
	23	<!-- <li><a href="./blog">Blog</a></li> -->
	24	<li><a href="../donate.html">Donate!</a></li>
	25	</ul>
	26	</div> <!-- nav -->
	27	<!-- ### Begin Content ### -->
	28	<div id="second">
	29
	30
	31
	32	<table class="rfc2822 docutils field-list" frame="void" rules="none">
	33	<col class="field-name" />
	34	<col class="field-body" />
	35	<tbody valign="top">
	36	<tr class="field"><th class="field-name">BEP:</th><td class="field-body">0</td>
	37	</tr>
	38	<tr class="field"><th class="field-name">Title:</th><td class="field-body">Index of BitTorrent Enhancement Proposals</td>
	39	</tr>
	40	<tr class="field"><th class="field-name">Version:</th><td class="field-body">$Revision$</td>
	41	</tr>
	42	<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="https://svn.bittorrent.com/trac.cgi/browser/dotorg/trunk/html/beps/bep_0000.rst">$Date$</a></td>
	43	</tr>
	44	<tr class="field"><th class="field-name">Author:</th><td class="field-body">David Harrison <dave at bittorrent.com></td>
	45	</tr>
	46	<tr class="field"><th class="field-name">Status:</th><td class="field-body">Active</td>
	47	</tr>
	48	<tr class="field"><th class="field-name">Type:</th><td class="field-body">Process</td>
	49	</tr>
	50	<tr class="field"><th class="field-name">Created:</th><td class="field-body">10-Jan-2008</td>
	51	</tr>
	52	<tr class="field"><th class="field-name">Post-History:</th><td class="field-body"></td>
	53	</tr>
	54	</tbody>
	55	</table>
	56	<hr />
	57	<p>The BitTorrent Community Forum coordinates the development of the
	58	BitTorrent protocol suite and its reference implementation. It is the
	59	wish of Bram Cohen that the BitTorrent mainline python implementation
	60	remain open source and that the protocol development process be
	61	modelled after the Python Enhancement Proposal (PEP) process.</p>
	62	<p>This document indexes all BitTorrent Enhancement Proposals (BEPs).
	63	When a new proposal is submitted, one of the BitTorrent.org editors
	64	assigns a BEP number and updates this index appropriately. The process
	65	is modelled after the PEP process used in the python community <a class="footnote-reference" href="#python" id="id1">[1]</a>. Each
	66	document has a number that never changes and the history of document is
	67	maintained in subversion <a class="footnote-reference" href="#svn" id="id2">[2]</a>.</p>
	68	<table border="1" class="docutils">
	69	<colgroup>
	70	<col width="13%" />
	71	<col width="88%" />
	72	</colgroup>
	73	<thead valign="bottom">
	74	<tr><th class="head">Num</th>
	75	<th class="head">Title</th>
	76	</tr>
	77	</thead>
	78	<tbody valign="top">
	79	<tr><td><span class="raw-html"><A HREF="bep_0000.html">0</A></span></td>
	80	<td>Index of BitTorrent Enhancement Proporsals</td>
	81	</tr>
	82	<tr><td><span class="raw-html"><A HREF="bep_0001.html">1</A></span></td>
	83	<td>The BEP Process</td>
	84	</tr>
	85	<tr><td><span class="raw-html"><A HREF="bep_0002.html">2</A></span></td>
	86	<td>Sample reStructured Text BEP Template</td>
	87	</tr>
	88	<tr><td><span class="raw-html"><A HREF="bep_0003.html">3</A></span></td>
	89	<td>The BitTorrent Protocol Specification</td>
	90	</tr>
	91	<tr><td><span class="raw-html"><A HREF="bep_0004.html">4</A></span></td>
	92	<td>Known Number Allocations</td>
	93	</tr>
	94	<tr><td><span class="raw-html"><A HREF="bep_0005.html">5</A></span></td>
	95	<td>DHT Protocol</td>
	96	</tr>
	97	<tr><td><span class="raw-html"><A HREF="bep_0006.html">6</A></span></td>
	98	<td>Fast Extension</td>
	99	</tr>
	100	<tr><td><span class="raw-html"><A HREF="bep_0007.html">7</A></span></td>
	101	<td>IPv6 Tracker Extension</td>
	102	</tr>
	103	<tr><td><span class="raw-html"><A HREF="bep_0008.html">8</A></span></td>
	104	<td>Tracker Peer Obfuscation</td>
	105	</tr>
	106	<tr><td><span class="raw-html"><A HREF="bep_0009.html">9</A></span></td>
	107	<td>Metadata Extension</td>
	108	</tr>
	109	<tr><td><span class="raw-html"><A HREF="bep_0009.html">10</A></span></td>
	110	<td>Extension Protocol</td>
	111	</tr>
	112	<tr><td><span class="raw-html"><A HREF="bep_1000.html">1000</A></span></td>
	113	<td>Pending Standards Track Documents</td>
	114	</tr>
	115	</tbody>
	116	</table>
	117	<table class="docutils footnote" frame="void" id="python" rules="none">
	118	<colgroup><col class="label" /><col /></colgroup>
	119	<tbody valign="top">
	120	<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td><a class="reference external" href="http://www.python.org/dev/peps/">http://www.python.org/dev/peps/</a></td></tr>
	121	</tbody>
	122	</table>
	123	<table class="docutils footnote" frame="void" id="svn" rules="none">
	124	<colgroup><col class="label" /><col /></colgroup>
	125	<tbody valign="top">
	126	<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td><a class="reference external" href="http://svn.bittorrent.org">http://svn.bittorrent.org</a></td></tr>
	127	</tbody>
	128	</table>
	129
	130
	131	</div>
	132	<div id="footer">
	133	<hr/>
	134	</div>
	135
	136	</div>
	137	</body>
	138	</html>

dotorg/trunk_fixed/html/beps/bep_0001.rst

r10525	r10535
26	26	Because the BEPs are maintained as text files in a versioned
27	27	repository, their revision history is the historical record of the
28		feature proposal [#svn].
	28	feature proposal [#svn]_.
29	29
30	30	BEP Types
…	…
82	82	Standards Track, Informational, or Process, gives it status "Draft",
83	83	and creates and checks-in the initial draft of the BEP to the
84		subversion repository ~~[#svn]~~. The BEP editor will not unreasonably
	84	subversion repository. The BEP editor will not unreasonably
85	85	deny a BEP. Reasons for denying BEP status include duplication of
86	86	effort, being technically unsound, not providing proper motivation or
…	…
163	163	=======
164	164
165		This document was derived heavily from ~~`PEP-0001`_~~. In many places
166		text was simply copied and modified. Although the ~~`PEP-0001`_~~ text
	165	This document was derived heavily from PEP-0001 [#PEP-1]. In many places
	166	text was simply copied and modified. Although the PEP-0001 text
167	167	was written by Barry Warsaw, Jeremy Hylton, and David Goodger, they
168	168	are not responsible for its use in the BitTorent Enhancement Process,
…	…
178	178	guidance.
179	179
180		:: [#svn] This historical record is available by the normal SVN
181		commands for retrieving older revisions. For those without direct
182		access to the SVN tree, you can browse the current and past BEP
183		revisions here: http://svn.bittorrent.org/beps/trunk/
	180	.. [#svn] This historical record is available by the normal SVN
	181	commands for retrieving older revisions. For those without direct
	182	access to the SVN tree, you can browse the current and past BEP
	183	revisions here: http://svn.bittorrent.org/beps/trunk/
184	184
185		:: _`PEP-0001`: http://www.python.org/dev/peps/pep-0001/
	185	.. [#PEP-1] PEP-001: PEP Purposes and Guidelines, Warsaw, Hylton, Goodger.
	186	(http://www.python.org/dev/peps/pep-0001)
186	187
187	188

dotorg/trunk_fixed/html/beps/bep_0002.html

r10505	r10535
	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	<head>
	5	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	6	<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
	7	<title></title>
	8	<link rel="stylesheet" href="../css/bep.css" type="text/css" />
	9	</head>
	10	<body>
	11	<div class="document">
	12
	13	<div id="upper" class="clear">
	14	<div id="wrap">
	15	<div id="header">
	16	<h1><a href="../index.html">BitTorrent<span>.org</span></a></h1>
	17	</div>
	18	<div id="nav">
	19	<ul>
	20	<li><a href="../index.html">Home</a></li>
	21	<li><a href="../introduction.html">For Users</a></li>
	22	<li><span>For Developers</span></li>
	23	<!-- <li><a href="./blog">Blog</a></li> -->
	24	<li><a href="../donate.html">Donate!</a></li>
	25	</ul>
	26	</div> <!-- nav -->
	27	<!-- ### Begin Content ### -->
	28	<div id="second">
	29
	30
	31
	32	<table class="rfc2822 docutils field-list" frame="void" rules="none">
	33	<col class="field-name" />
	34	<col class="field-body" />
	35	<tbody valign="top">
	36	<tr class="field"><th class="field-name">BEP:</th><td class="field-body">2</td>
	37	</tr>
	38	<tr class="field"><th class="field-name">Title:</th><td class="field-body">Sample reStructured Text BEP Template</td>
	39	</tr>
	40	<tr class="field"><th class="field-name">Version:</th><td class="field-body">$Revision$</td>
	41	</tr>
	42	<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="https://svn.bittorrent.com/trac.cgi/browser/dotorg/trunk/html/beps/bep_0002.rst">$Date$</a></td>
	43	</tr>
	44	<tr class="field"><th class="field-name">Author:</th><td class="field-body">David Harrison <dave at bittorrent.com></td>
	45	</tr>
	46	<tr class="field"><th class="field-name">Status:</th><td class="field-body">Active</td>
	47	</tr>
	48	<tr class="field"><th class="field-name">Type:</th><td class="field-body">Process</td>
	49	</tr>
	50	<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference external" href="http://www.bittorrent.org/beps/bep-0012">text/x-rst</a></td>
	51	</tr>
	52	<tr class="field"><th class="field-name">Created:</th><td class="field-body">02-Feb-2008</td>
	53	</tr>
	54	<tr class="field"><th class="field-name">Post-History:</th><td class="field-body"></td>
	55	</tr>
	56	</tbody>
	57	</table>
	58	<hr />
	59	<div class="contents topic" id="contents">
	60	<p class="topic-title first">Contents</p>
	61	<ul class="simple">
	62	<li><a class="reference internal" href="#abstract" id="id22">Abstract</a></li>
	63	<li><a class="reference internal" href="#rationale" id="id23">Rationale</a></li>
	64	<li><a class="reference internal" href="#how-to-use-this-template" id="id24">How to Use This Template</a></li>
	65	<li><a class="reference internal" href="#restructuredtext-bep-formatting-requirements" id="id25">ReStructuredText BEP Formatting Requirements</a><ul>
	66	<li><a class="reference internal" href="#general" id="id26">General</a></li>
	67	<li><a class="reference internal" href="#section-headings" id="id27">Section Headings</a></li>
	68	<li><a class="reference internal" href="#paragraphs" id="id28">Paragraphs</a></li>
	69	<li><a class="reference internal" href="#inline-markup" id="id29">Inline Markup</a></li>
	70	<li><a class="reference internal" href="#block-quotes" id="id30">Block Quotes</a></li>
	71	<li><a class="reference internal" href="#literal-blocks" id="id31">Literal Blocks</a></li>
	72	<li><a class="reference internal" href="#lists" id="id32">Lists</a></li>
	73	<li><a class="reference internal" href="#tables" id="id33">Tables</a></li>
	74	<li><a class="reference internal" href="#hyperlinks" id="id34">Hyperlinks</a></li>
	75	<li><a class="reference internal" href="#footnotes" id="id35">Footnotes</a></li>
	76	<li><a class="reference internal" href="#images" id="id36">Images</a></li>
	77	<li><a class="reference internal" href="#comments" id="id37">Comments</a></li>
	78	<li><a class="reference internal" href="#escaping-mechanism" id="id38">Escaping Mechanism</a></li>
	79	</ul>
	80	</li>
	81	<li><a class="reference internal" href="#habits-to-avoid" id="id39">Habits to Avoid</a></li>
	82	<li><a class="reference internal" href="#resources" id="id40">Resources</a></li>
	83	<li><a class="reference internal" href="#acknowledgements" id="id41">Acknowledgements</a></li>
	84	<li><a class="reference internal" href="#references" id="id42">References</a></li>
	85	<li><a class="reference internal" href="#copyright" id="id43">Copyright</a></li>
	86	</ul>
	87	</div>
	88	<div class="section" id="abstract">
	89	<h1>Abstract</h1>
	90	<p>This BEP provides a boilerplate or sample template for creating your
	91	own reStructuredText BEPs. In conjunction with the content guidelines
	92	in BEP 1 <a class="footnote-reference" href="#bep-1" id="id1">[1]</a>, this should make it easy for you to conform your own
	93	BEPs to the format outlined below.</p>
	94	<p>Note: if you are reading this BEP via the web, you should first grab
	95	the text (reStructuredText) source of this BEP in order to complete
	96	the steps below. <strong>DO NOT USE THE HTML FILE AS YOUR TEMPLATE!</strong></p>
	97	<p>To get the source this (or any) BEP, look at the top of the HTML page
	98	and click on the date & time on the "Last-Modified" line. It is a
	99	link to the source text in the BitTorrent.org subversion repository.</p>
	100	</div>
	101	<div class="section" id="rationale">
	102	<h1>Rationale</h1>
	103	<p>BEP submissions come in a wide variety of forms, not all adhering
	104	to the format guidelines set forth below. Use this template, in
	105	conjunction with the format guidelines below, to ensure that your
	106	BEP submission won't get automatically rejected because of form.</p>
	107	<p>ReStructuredText is offered as an alternative to plaintext BEPs, to
	108	allow BEP authors more functionality and expressivity, while
	109	maintaining easy readability in the source text. The processed HTML
	110	form makes the functionality accessible to readers: live hyperlinks,
	111	styled text, tables, images, and automatic tables of contents, among
	112	other advantages.</p>
	113	</div>
	114	<div class="section" id="how-to-use-this-template">
	115	<h1>How to Use This Template</h1>
	116	<p>To use this template you must first decide whether your BEP is going
	117	to be an Informational or Standards Track BEP. Most BEPs are
	118	Standards Track because they propose a new feature for the BitTorrent
	119	system including the BitTorrent suite of protocols. When in doubt,
	120	read BEP 1 for details or contact the BEP editors
	121	<<a class="reference external" href="mailto:editor%40bittorrent.org">editor<span>@</span>bittorrent<span>.</span>org</a>>.</p>
	122	<p>Once you've decided which type of BEP yours is going to be, follow the
	123	directions below.</p>
	124	<ul>
	125	<li><p class="first">Make a copy of this file (<tt class="docutils literal"><span class="pre">.rst</span></tt> file, <strong>not</strong> HTML!) and perform
	126	the following edits.</p>
	127	</li>
	128	<li><p class="first">Replace the "BEP: 2" header with "BEP: XXX" since you don't yet have
	129	a BEP number assignment.</p>
	130	</li>
	131	<li><p class="first">Change the Title header to the title of your BEP.</p>
	132	</li>
	133	<li><p class="first">Leave the Version and Last-Modified headers alone; we'll take care
	134	of those when we check your BEP into BitTorrent's Subversion repository.
	135	These headers consist of keywords ("Revision" and "Date" enclosed in
	136	"$"-signs) which are automatically expanded by the repository.
	137	Please do not edit the expanded date or revision text.</p>
	138	</li>
	139	<li><p class="first">Change the Author header to include your name, and optionally your
	140	email address. Be sure to follow the format carefully: your name
	141	must appear first, and it must not be contained in parentheses.
	142	Your email address may appear second (or it can be omitted) and if
	143	it appears, it must appear in angle brackets. It is okay to
	144	obfuscate your email address.</p>
	145	</li>
	146	<li><p class="first">If there is a mailing list for discussion of your new feature, add a
	147	Discussions-To header right after the Author header. You should not
	148	add a Discussions-To header if the mailing list to be used is
	149	<a class="reference external" href="mailto:bittorrent-list%40bittorrent.org">bittorrent-list<span>@</span>bittorrent<span>.</span>org</a>, or if discussions should be sent to
	150	you directly. Most Informational BEPs don't have a Discussions-To
	151	header.</p>
	152	</li>
	153	<li><p class="first">Change the Status header to "Draft".</p>
	154	</li>
	155	<li><p class="first">For Standards Track BEPs, change the Type header to "Standards
	156	Track".</p>
	157	</li>
	158	<li><p class="first">For Informational BEPs, change the Type header to "Informational".</p>
	159	</li>
	160	<li><p class="first">For Standards Track BEPs, if your feature depends on the acceptance
	161	of some other currently in-development BEP, add a Requires header
	162	right after the Type header. The value should be the BEP number of
	163	the BEP yours depends on. Don't add this header if your dependent
	164	feature is described in a Final BEP.</p>
	165	</li>
	166	<li><p class="first">Change the Created header to today's date. Be sure to follow the
	167	format carefully: it must be in <tt class="docutils literal"><span class="pre">dd-mmm-yyyy</span></tt> format, where the
	168	<tt class="docutils literal"><span class="pre">mmm</span></tt> is the 3 English letter month abbreviation, i.e. one of Jan,
	169	Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.</p>
	170	</li>
	171	<li><p class="first">Leave Post-History alone for now; you'll add dates to this header
	172	each time you post your BEP to <a class="reference external" href="mailto:bittorrent-list%40bittorrent.org">bittorrent-list<span>@</span>bittorrent<span>.</span>org</a>. If
	173	you posted your BEP to the lists on August 14, 2001 and September 3,
	174	2001, the Post-History header would look like:</p>
	175	<pre class="literal-block">
	176	Post-History: 14-Aug-2001, 03-Sept-2001
	177	</pre>
	178	<p>You must manually add new dates and check them in. If you don't
	179	have check-in privileges, send your changes to the BEP editors.</p>
	180	</li>
	181	<li><p class="first">Add a Replaces header if your BEP obsoletes an earlier BEP. The
	182	value of this header is the number of the BEP that your new BEP is
	183	replacing. Only add this header if the older BEP is in "final"
	184	form, i.e. is either Accepted, Final, or Rejected. You aren't
	185	replacing an older open BEP if you're submitting a competing idea.</p>
	186	</li>
	187	<li><p class="first">Now write your Abstract, Rationale, and other content for your BEP,
	188	replacing all this gobbledygook with your own text. Be sure to
	189	adhere to the format guidelines below, specifically on the
	190	prohibition of tab characters and the indentation requirements.</p>
	191	</li>
	192	<li><p class="first">Update your References and Copyright section. Usually you'll place
	193	your BEP into the public domain, in which case just leave the
	194	Copyright section alone. Alternatively, you can use the <a class="reference external" href="http://www.opencontent.org/openpub/">Open
	195	Publication License</a> <a class="footnote-reference" href="#id14" id="id15">[6]</a>, but public domain is still strongly
	196	preferred.</p>
	197	</li>
	198	<li><p class="first">Leave the Emacs stanza at the end of this file alone, including the
	199	formfeed character ("^L", or <tt class="docutils literal"><span class="pre">\f</span></tt>).</p>
	200	</li>
	201	<li><p class="first">Send your BEP submission to the BEP editors at <a class="reference external" href="mailto:editor%40bittorrent.org">editor<span>@</span>bittorrent<span>.</span>org</a>.</p>
	202	</li>
	203	</ul>
	204	</div>
	205	<div class="section" id="restructuredtext-bep-formatting-requirements">
	206	<h1>ReStructuredText BEP Formatting Requirements</h1>
	207	<p>The following is a BEP-specific summary of reStructuredText syntax.
	208	For the sake of simplicity and brevity, much detail is omitted. For
	209	more detail, see <a class="reference internal" href="#resources">Resources</a> below. <a class="reference internal" href="#literal-blocks">Literal blocks</a> (in which no
	210	markup processing is done) are used for examples throughout, to
	211	illustrate the plaintext markup.</p>
	212	<div class="section" id="general">
	213	<h2>General</h2>
	214	<p>You must adhere to the Emacs convention of adding two spaces at the
	215	end of every sentence.</p>
	216	<p>Tab characters must never appear in the document at all. A BEP should
	217	include the standard Emacs stanza included by example at the bottom of
	218	this BEP.</p>
	219	</div>
	220	<div class="section" id="section-headings">
	221	<h2>Section Headings</h2>
	222	<p>BEP headings must begin in column zero and the initial letter of each
	223	word must be capitalized as in book titles. Acronyms should be in all
	224	capitals. Section titles must be adorned with an underline, a single
	225	repeated punctuation character, which begins in column zero and must
	226	extend at least as far as the right edge of the title text (4
	227	characters minimum). First-level section titles are underlined with
	228	"=" (equals signs), second-level section titles with "-" (hyphens),
	229	and third-level section titles with "'" (single quotes or
	230	apostrophes). For example:</p>
	231	<pre class="literal-block">
	232	First-Level Title
	233	=================
	234
	235	Second-Level Title
	236	------------------
	237
	238	Third-Level Title
	239	'''''''''''''''''
	240	</pre>
	241	<p>If there are more than three levels of sections in your BEP, you may
	242	insert overline/underline-adorned titles for the first and second
	243	levels as follows:</p>
	244	<pre class="literal-block">
	245	============================
	246	First-Level Title (optional)
	247	============================
	248
	249	-----------------------------
	250	Second-Level Title (optional)
	251	-----------------------------
	252
	253	Third-Level Title
	254	=================
	255
	256	Fourth-Level Title
	257	------------------
	258
	259	Fifth-Level Title
	260	'''''''''''''''''
	261	</pre>
	262	<p>You shouldn't have more than five levels of sections in your BEP. If
	263	you do, you should consider rewriting it.</p>
	264	<p>You must use two blank lines between the last line of a section's body
	265	and the next section heading. If a subsection heading immediately
	266	follows a section heading, a single blank line in-between is
	267	sufficient.</p>
	268	<p>The body of each section is not normally indented, although some
	269	constructs do use indentation, as described below. Blank lines are
	270	used to separate constructs.</p>
	271	</div>
	272	<div class="section" id="paragraphs">
	273	<h2>Paragraphs</h2>
	274	<p>Paragraphs are left-aligned text blocks separated by blank lines.
	275	Paragraphs are not indented unless they are part of an indented
	276	construct (such as a block quote or a list item).</p>
	277	</div>
	278	<div class="section" id="inline-markup">
	279	<h2>Inline Markup</h2>
	280	<p>Portions of text within paragraphs and other text blocks may be
	281	styled. For example:</p>
	282	<pre class="literal-block">
	283	Text may be marked as emphasized (single asterisk markup,
	284	typically shown in italics) or strongly emphasized (double
	285	asterisks, typically boldface). ``Inline literals`` (using double
	286	backquotes) are typically rendered in a monospaced typeface. No
	287	further markup recognition is done within the double backquotes,
	288	so they're safe for any kind of code snippets.
	289	</pre>
	290	</div>
	291	<div class="section" id="block-quotes">
	292	<h2>Block Quotes</h2>
	293	<p>Block quotes consist of indented body elements. For example:</p>
	294	<pre class="literal-block">
	295	This is a paragraph.
	296
	297	This is a block quote.
	298
	299	A block quote may contain many paragraphs.
	300	</pre>
	301	<p>Block quotes are used to quote extended passages from other sources.
	302	Block quotes may be nested inside other body elements. Use 4 spaces
	303	per indent level.</p>
	304	</div>
	305	<div class="section" id="literal-blocks">
	306	<h2>Literal Blocks</h2>
	307	<!-- In the text below, double backquotes are used to denote inline
	308	literals. "``::``" is written so that the colons will appear in a
	309	monospaced font; the backquotes (``) are markup, not part of the
	310	text. See "Inline Markup" above.
	311
	312	By the way, this is a comment, described in "Comments" below. -->
	313	<p>Literal blocks are used for code samples or preformatted ASCII art. To
	314	indicate a literal block, preface the indented text block with
	315	"<tt class="docutils literal"><span class="pre">::</span></tt>" (two colons). The literal block continues until the end of
	316	the indentation. Indent the text block by 4 spaces. For example:</p>
	317	<pre class="literal-block">
	318	This is a typical paragraph. A literal block follows.
	319
	320	::
	321
	322	for a in [5,4,3,2,1]: # this is program code, shown as-is
	323	print a
	324	print "it's..."
	325	# a literal block continues until the indentation ends
	326	</pre>
	327	<p>The paragraph containing only "<tt class="docutils literal"><span class="pre">::</span></tt>" will be completely removed from
	328	the output; no empty paragraph will remain. "<tt class="docutils literal"><span class="pre">::</span></tt>" is also
	329	recognized at the end of any paragraph. If immediately preceded by
	330	whitespace, both colons will be removed from the output. When text
	331	immediately precedes the "<tt class="docutils literal"><span class="pre">::</span></tt>", <em>one</em> colon will be removed from
	332	the output, leaving only one colon visible (i.e., "<tt class="docutils literal"><span class="pre">::</span></tt>" will be
	333	replaced by "<tt class="docutils literal"><span class="pre">:</span></tt>"). For example, one colon will remain visible
	334	here:</p>
	335	<pre class="literal-block">
	336	Paragraph::
	337
	338	Literal block
	339	</pre>
	340	</div>
	341	<div class="section" id="lists">
	342	<h2>Lists</h2>
	343	<p>Bullet list items begin with one of "-", "*", or "+" (hyphen,
	344	asterisk, or plus sign), followed by whitespace and the list item
	345	body. List item bodies must be left-aligned and indented relative to
	346	the bullet; the text immediately after the bullet determines the
	347	indentation. For example:</p>
	348	<pre class="literal-block">
	349	This paragraph is followed by a list.
	350
	351	* This is the first bullet list item. The blank line above the
	352	first list item is required; blank lines between list items
	353	(such as below this paragraph) are optional.
	354
	355	* This is the first paragraph in the second item in the list.
	356
	357	This is the second paragraph in the second item in the list.
	358	The blank line above this paragraph is required. The left edge
	359	of this paragraph lines up with the paragraph above, both
	360	indented relative to the bullet.
	361
	362	- This is a sublist. The bullet lines up with the left edge of
	363	the text blocks above. A sublist is a new list so requires a
	364	blank line above and below.
	365
	366	* This is the third item of the main list.
	367
	368	This paragraph is not part of the list.
	369	</pre>
	370	<p>Enumerated (numbered) list items are similar, but use an enumerator
	371	instead of a bullet. Enumerators are numbers (1, 2, 3, ...), letters
	372	(A, B, C, ...; uppercase or lowercase), or Roman numerals (i, ii, iii,
	373	iv, ...; uppercase or lowercase), formatted with a period suffix
	374	("1.", "2."), parentheses ("(1)", "(2)"), or a right-parenthesis
	375	suffix ("1)", "2)"). For example:</p>
	376	<pre class="literal-block">
	377	1. As with bullet list items, the left edge of paragraphs must
	378	align.
	379
	380	2. Each list item may contain multiple paragraphs, sublists, etc.
	381
	382	This is the second paragraph of the second list item.
	383
	384	a) Enumerated lists may be nested.
	385	b) Blank lines may be omitted between list items.
	386	</pre>
	387	<p>Definition lists are written like this:</p>
	388	<pre class="literal-block">
	389	what
	390	Definition lists associate a term with a definition.
	391
	392	how
	393	The term is a one-line phrase, and the definition is one
	394	or more paragraphs or body elements, indented relative to
	395	the term.
	396	</pre>
	397	</div>
	398	<div class="section" id="tables">
	399	<h2>Tables</h2>
	400	<p>Simple tables are easy and compact but you are not required to use
	401	simple tables:</p>
	402	<pre class="literal-block">
	403	===== ===== =======
	404	A B A and B
	405	===== ===== =======
	406	False False False
	407	True False False
	408	False True False
	409	True True True
	410	===== ===== =======
	411	</pre>
	412	<p>There must be at least two columns in a table (to differentiate from
	413	section titles). Column spans use underlines of hyphens ("Inputs"
	414	spans the first two columns):</p>
	415	<pre class="literal-block">
	416	===== ===== ======
	417	Inputs Output
	418	------------ ------
	419	A B A or B
	420	===== ===== ======
	421	False False False
	422	True False True
	423	False True True
	424	True True True
	425	===== ===== ======
	426	</pre>
	427	<p>Text in a first-column cell starts a new row. No text in the first
	428	column indicates a continuation line; the rest of the cells may
	429	consist of multiple lines. For example:</p>
	430	<pre class="literal-block">
	431	===== =========================
	432	col 1 col 2
	433	===== =========================
	434	1 Second column of row 1.
	435	2 Second column of row 2.
	436	Second line of paragraph.
	437	3 - Second column of row 3.
	438
	439	- Second item in bullet
	440	list (row 3, column 2).
	441	===== =========================
	442	</pre>
	443	</div>
	444	<div class="section" id="hyperlinks">
	445	<h2>Hyperlinks</h2>
	446	<p>When referencing an external web page in the body of a BEP, you should
	447	include the title of the page in the text, with either an inline
	448	hyperlink reference to the URL or a footnote reference (see
	449	<a class="reference internal" href="#footnotes">Footnotes</a> below). Do not include the URL in the body text of the
	450	BEP.</p>
	451	<p>Hyperlink references use backquotes and a trailing underscore to mark
	452	up the reference text; backquotes are optional if the reference text
	453	is a single word. For example:</p>
	454	<pre class="literal-block">
	455	In this paragraph, we refer to the `BitTorrent web site`_.
	456	</pre>
	457	<p>An explicit target provides the URL. Put targets in a References
	458	section at the end of the BEP, or immediately after the reference.
	459	Hyperlink targets begin with two periods and a space (the "explicit
	460	markup start"), followed by a leading underscore, the reference text,
	461	a colon, and the URL (absolute or relative):</p>
	462	<pre class="literal-block">
	463	.. _BitTorrent web site: http://www.bittorrent.org/
	464	</pre>
	465	<p>The reference text and the target text must match (although the match
	466	is case-insensitive and ignores differences in whitespace). Note that
	467	the underscore trails the reference text but precedes the target text.
	468	If you think of the underscore as a right-pointing arrow, it points
	469	<em>away</em> from the reference and <em>toward</em> the target.</p>
	470	<p>The same mechanism can be used for internal references. Every unique
	471	section title implicitly defines an internal hyperlink target. We can
	472	make a link to the Abstract section like this:</p>
	473	<pre class="literal-block">
	474	Here is a hyperlink reference to the `Abstract`_ section. The
	475	backquotes are optional since the reference text is a single word;
	476	we can also just write: Abstract_.
	477	</pre>
	478	<p>Footnotes containing the URLs from external targets will be generated
	479	automatically at the end of the References section of the BEP, along
	480	with footnote references linking the reference text to the footnotes.</p>
	481	<p>Text of the form "BEP x" or "RFC x" (where "x" is a number) will be
	482	linked automatically to the appropriate URLs.</p>
	483	</div>
	484	<div class="section" id="footnotes">
	485	<h2>Footnotes</h2>
	486	<p>Footnote references consist of a left square bracket, a number, a
	487	right square bracket, and a trailing underscore:</p>
	488	<pre class="literal-block">
	489	This sentence ends with a footnote reference [1]_.
	490	</pre>
	491	<p>Whitespace must precede the footnote reference. Leave a space between
	492	the footnote reference and the preceding word.</p>
	493	<p>When referring to another BEP, include the BEP number in the body
	494	text, such as "BEP 1". The title may optionally appear. Add a
	495	footnote reference following the title. For example:</p>
	496	<pre class="literal-block">
	497	Refer to BEP 1 [2]_ for more information.
	498	</pre>
	499	<p>Add a footnote that includes the BEP's title and author. It may
	500	optionally include the explicit URL on a separate line, but only in
	501	the References section. Footnotes begin with ".. " (the explicit
	502	markup start), followed by the footnote marker (no underscores),
	503	followed by the footnote body. For example:</p>
	504	<pre class="literal-block">
	505	References
	506	==========
	507
	508	.. [2] BEP 1, "BEP Purpose and Guidelines", Harrison
	509	(http://www.bittorrent.org/beps/bep_0001)
	510	</pre>
	511	<p>If you decide to provide an explicit URL for a BEP, please use this as
	512	the URL template:</p>
	513	<pre class="literal-block">
	514	http://www.bittorrent.org/beps/bep_xxxx
	515	</pre>
	516	<p>BEP numbers in URLs must be padded with zeros from the left, so as to
	517	be exactly 4 characters wide, however BEP numbers in the text are
	518	never padded.</p>
	519	<p>During the course of developing your BEP, you may have to add, remove,
	520	and rearrange footnote references, possibly resulting in mismatched
	521	references, obsolete footnotes, and confusion. Auto-numbered
	522	footnotes allow more freedom. Instead of a number, use a label of the
	523	form "#word", where "word" is a mnemonic consisting of alphanumerics
	524	plus internal hyphens, underscores, and periods (no whitespace or
	525	other characters are allowed). For example:</p>
	526	<pre class="literal-block">
	527	Refer to BEP 1 [#BEP-1]_ for more information.
	528
	529	References
	530	==========
	531
	532	.. [#BEP-1] BEP 1, "BEP Purpose and Guidelines", Harrison
	533
	534	http://www.bittorrent.org/beps/bep-0001
	535	</pre>
	536	<p>Footnotes and footnote references will be numbered automatically, and
	537	the numbers will always match. Once a BEP is finalized, auto-numbered
	538	labels should be replaced by numbers for simplicity.</p>
	539	</div>
	540	<div class="section" id="images">
	541	<h2>Images</h2>
	542	<p>If your BEP contains a diagram, you may include it in the processed
	543	output using the "image" directive:</p>
	544	<pre class="literal-block">
	545	.. image:: diagram.png
	546	</pre>
	547	<p>Any browser-friendly graphics format is possible: .png, .jpeg, .gif,
	548	.tiff, etc.</p>
	549	<p>Since this image will not be visible to readers of the BEP in source
	550	text form, you should consider including a description or ASCII art
	551	alternative, using a comment (below).</p>
	552	</div>
	553	<div class="section" id="comments">
	554	<h2>Comments</h2>
	555	<p>A comment block is an indented block of arbitrary text immediately
	556	following an explicit markup start: two periods and whitespace. Leave
	557	the ".." on a line by itself to ensure that the comment is not
	558	misinterpreted as another explicit markup construct. Comments are not
	559	visible in the processed document. For the benefit of those reading
	560	your BEP in source form, please consider including a descriptions of
	561	or ASCII art alternatives to any images you include. For example:</p>
	562	<pre class="literal-block">
	563	.. image:: dataflow.png
	564
	565	..
	566	Data flows from the input module, through the "black box"
	567	module, and finally into (and through) the output module.
	568	</pre>
	569	<p>The Emacs stanza at the bottom of this document is inside a comment.</p>
	570	</div>
	571	<div class="section" id="escaping-mechanism">
	572	<h2>Escaping Mechanism</h2>
	573	<p>reStructuredText uses backslashes ("<tt class="docutils literal"><span class="pre">\</span></tt>") to override the special
	574	meaning given to markup characters and get the literal characters
	575	themselves. To get a literal backslash, use an escaped backslash
	576	("<tt class="docutils literal"><span class="pre">\\</span></tt>"). There are two contexts in which backslashes have no
	577	special meaning: <a class="reference internal" href="#literal-blocks">literal blocks</a> and inline literals (see <a class="reference internal" href="#inline-markup">Inline
	578	Markup</a> above). In these contexts, no markup recognition is done,
	579	and a single backslash represents a literal backslash, without having
	580	to double up.</p>
	581	<p>If you find that you need to use a backslash in your text, consider
	582	using inline literals or a literal block instead.</p>
	583	</div>
	584	</div>
	585	<div class="section" id="habits-to-avoid">
	586	<h1>Habits to Avoid</h1>
	587	<p>Many programmers who are familiar with TeX often write quotation marks
	588	like this:</p>
	589	<pre class="literal-block">
	590	`single-quoted' or ``double-quoted''
	591	</pre>
	592	<p>Backquotes are significant in reStructuredText, so this practice
	593	should be avoided. For ordinary text, use ordinary 'single-quotes' or
	594	"double-quotes". For inline literal text (see <a class="reference internal" href="#inline-markup">Inline Markup</a>
	595	above), use double-backquotes:</p>
	596	<pre class="literal-block">
	597	``literal text: in here, anything goes!``
	598	</pre>
	599	</div>
	600	<div class="section" id="resources">
	601	<h1>Resources</h1>
	602	<p>Many other constructs and variations are possible. For more details
	603	about the reStructuredText markup, in increasing order of
	604	thoroughness, please see:</p>
	605	<ul class="simple">
	606	<li><a class="reference external" href="http://docutils.sourceforge.net/docs/rst/quickstart.html">A ReStructuredText Primer</a> <a class="footnote-reference" href="#id16" id="id17">[7]</a>, a gentle introduction.</li>
	607	<li><a class="reference external" href="http://docutils.sourceforge.net/docs/rst/quickref.html">Quick reStructuredText</a> <a class="footnote-reference" href="#id18" id="id19">[8]</a>, a users' quick reference.</li>
	608	<li><a class="reference external" href="http://docutils.sourceforge.net/spec/rst/reStructuredText.html">reStructuredText Markup Specification</a> <a class="footnote-reference" href="#id20" id="id21">[9]</a>, the final authority.</li>
	609	</ul>
	610	<p>The processing of reStructuredText BEPs is done using <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> <a class="footnote-reference" href="#id7" id="id9">[3]</a>. If
	611	you have a question or require assistance with reStructuredText or
	612	Docutils, please <a class="reference external" href="mailto:docutils-users%40lists.sourceforge.net?subject=BEPs">post a message</a> <a class="footnote-reference" href="#id10" id="id11">[4]</a> to the <a class="reference external" href="http://docutils.sf.net/docs/user/mailing-lists.html#docutils-users">Docutils-users mailing
	613	list</a> <a class="footnote-reference" href="#id12" id="id13">[5]</a>. The <a class="reference external" href="http://docutils.sourceforge.net/">Docutils project web site</a> <a class="footnote-reference" href="#id7" id="id8">[3]</a> has more information.</p>
	614	<p>This document was derived heavily from PEP-0012 <a class="footnote-reference" href="#pep-12" id="id6">[2]</a>. In many places
	615	text was simply copied and modified. Although the PEP-0012 text
	616	was written by David Goodger and Barry Warsaw, they are not
	617	responsible for its use in the BitTorent Enhancement Process, and
	618	should not be bothered with technical questions specific to BitTorrent
	619	or the BEP process. Please direct all comments to the BitTorrent
	620	editors <<a class="reference external" href="mailto:editor%40bittorrent.org">editor<span>@</span>bittorrent<span>.</span>org</a>> or the BitTorrent mailing list
	621	<<a class="reference external" href="mailto:bittorrent-list%40bittorrent.org">bittorrent-list<span>@</span>bittorrent<span>.</span>org</a>>.</p>
	622	</div>
	623	<div class="section" id="acknowledgements">
	624	<h1>Acknowledgements</h1>
	625	<p>Thanks to Barry Warsaw, David Goodger, and Guido van Rossum for their
	626	guidance.</p>
	627	</div>
	628	<div class="section" id="references">
	629	<h1>References</h1>
	630	<table class="docutils footnote" frame="void" id="bep-1" rules="none">
	631	<colgroup><col class="label" /><col /></colgroup>
	632	<tbody valign="top">
	633	<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>BEP_0001. BEP Purpose and Guidelines, Harrison
	634	(<a class="reference external" href="http://www.bittorrent.org/beps/bep_0001">http://www.bittorrent.org/beps/bep_0001</a>)</td></tr>
	635	</tbody>
	636	</table>
	637	<table class="docutils footnote" frame="void" id="pep-12" rules="none">
	638	<colgroup><col class="label" /><col /></colgroup>
	639	<tbody valign="top">
	640	<tr><td class="label"><a class="fn-backref" href="#id6">[2]</a></td><td>PEP-0012. Sample reStructuredText PEP Template, Goodger, Warsaw
	641	(<a class="reference external" href="http://www.python.org/peps/pep-0012">http://www.python.org/peps/pep-0012</a>)</td></tr>
	642	</tbody>
	643	</table>
	644	<table class="docutils footnote" frame="void" id="id7" rules="none">
	645	<colgroup><col class="label" /><col /></colgroup>
	646	<tbody valign="top">
	647	<tr><td class="label">[3]</td><td><em>(<a class="fn-backref" href="#id8">1</a>, <a class="fn-backref" href="#id9">2</a>)</em> <a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a></td></tr>
	648	</tbody>
	649	</table>
	650	<table class="docutils footnote" frame="void" id="id10" rules="none">
	651	<colgroup><col class="label" /><col /></colgroup>
	652	<tbody valign="top">
	653	<tr><td class="label"><a class="fn-backref" href="#id11">[4]</a></td><td><a class="reference external" href="mailto:docutils-users%40lists.sourceforge.net?subject=BEPs">mailto:docutils-users<span>@</span>lists<span>.</span>sourceforge<span>.</span>net?subject=BEPs</a></td></tr>
	654	</tbody>
	655	</table>
	656	<table class="docutils footnote" frame="void" id="id12" rules="none">
	657	<colgroup><col class="label" /><col /></colgroup>
	658	<tbody valign="top">
	659	<tr><td class="label"><a class="fn-backref" href="#id13">[5]</a></td><td><a class="reference external" href="http://docutils.sf.net/docs/user/mailing-lists.html#docutils-users">http://docutils.sf.net/docs/user/mailing-lists.html#docutils-users</a></td></tr>
	660	</tbody>
	661	</table>
	662	<table class="docutils footnote" frame="void" id="id14" rules="none">
	663	<colgroup><col class="label" /><col /></colgroup>
	664	<tbody valign="top">
	665	<tr><td class="label"><a class="fn-backref" href="#id15">[6]</a></td><td><a class="reference external" href="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</a></td></tr>
	666	</tbody>
	667	</table>
	668	<table class="docutils footnote" frame="void" id="id16" rules="none">
	669	<colgroup><col class="label" /><col /></colgroup>
	670	<tbody valign="top">
	671	<tr><td class="label"><a class="fn-backref" href="#id17">[7]</a></td><td><a class="reference external" href="http://docutils.sourceforge.net/docs/rst/quickstart.html">http://docutils.sourceforge.net/docs/rst/quickstart.html</a></td></tr>
	672	</tbody>
	673	</table>
	674	<table class="docutils footnote" frame="void" id="id18" rules="none">
	675	<colgroup><col class="label" /><col /></colgroup>
	676	<tbody valign="top">
	677	<tr><td class="label"><a class="fn-backref" href="#id19">[8]</a></td><td><a class="reference external" href="http://docutils.sourceforge.net/docs/rst/quickref.html">http://docutils.sourceforge.net/docs/rst/quickref.html</a></td></tr>
	678	</tbody>
	679	</table>
	680	<table class="docutils footnote" frame="void" id="id20" rules="none">
	681	<colgroup><col class="label" /><col /></colgroup>
	682	<tbody valign="top">
	683	<tr><td class="label"><a class="fn-backref" href="#id21">[9]</a></td><td><a class="reference external" href="http://docutils.sourceforge.net/spec/rst/reStructuredText.html">http://docutils.sourceforge.net/spec/rst/reStructuredText.html</a></td></tr>
	684	</tbody>
	685	</table>
	686	</div>
	687	<div class="section" id="copyright">
	688	<h1>Copyright</h1>
	689	<p>This document has been placed in the public domain.</p>
	690	<!-- Local Variables:
	691	mode: indented-text
	692	indent-tabs-mode: nil
	693	sentence-end-double-space: t
	694	fill-column: 70
	695	coding: utf-8
	696	End: -->
	697	</div>
	698
	699
	700	</div>
	701	<div id="footer">
	702	<hr/>
	703	</div>
	704
	705	</div>
	706	</body>
	707	</html>

dotorg/trunk_fixed/html/beps/bep_0002.rst

r10529	r10535
16	16	This BEP provides a boilerplate or sample template for creating your
17	17	own reStructuredText BEPs. In conjunction with the content guidelines
18		in BEP 1 [1]_, this should make it easy for you to conform your own
	18	in BEP 1 [#BEP-1]_, this should make it easy for you to conform your own
19	19	BEPs to the format outlined below.
20	20
…	…
602	602
603	603
604		This document was derived heavily from ~~`PEP-0012`~~_. In many places
605		text was simply copied and modified. Although the ~~`PEP-0012`_~~ text
	604	This document was derived heavily from PEP-0012 [#PEP-12]_. In many places
	605	text was simply copied and modified. Although the PEP-0012 text
606	606	was written by David Goodger and Barry Warsaw, they are not
607	607	responsible for its use in the BitTorent Enhancement Process, and
…	…
620	620	==========
621	621
622		.. [~~1] BEP 1,~~ BEP Purpose and Guidelines, Harrison
	622	.. [#BEP-1] BEP_0001. BEP Purpose and Guidelines, Harrison
623	623	(http://www.bittorrent.org/beps/bep_0001)
	624
	625	.. [#PEP-12] PEP-0012. Sample reStructuredText PEP Template, Goodger, Warsaw
	626	(http://www.python.org/peps/pep-0012)
	627
624	628
625	629	Copyright

dotorg/trunk_fixed/html/beps/bep_0003.html

r10492	r10535
2	2	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3	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		~~BEP, see http://www.bittorrent.org/beps/bep_0001.html for instructions and links~~
7		~~to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!~~
8		~~-->~~
9	4	<head>
10		<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11		<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
12		<title>BEP 3 -- Assigned Numbers</title>
13		<style type="text/css">
14
15		/*
16		:Author: David Goodger
17		:Contact: goodger@python.org
18		:date: $Date: 2006-05-21 22:44:42 +0200 (Sun, 21 May 2006) $
19		:version: $Revision: 4564 $
20		:copyright: This stylesheet has been placed in the public domain.
21
22		Default cascading style sheet for the BEP HTML output of Docutils.
23		*/
24
25		/* "! important" is used here to override other ``margin-top`` and
26		``margin-bottom`` styles that are later in the stylesheet or
27		more specific. See http://www.w3.org/TR/CSS1#the-cascade */
28		.first {
29		margin-top: 0 ! important }
30
31		.last, .with-subtitle {
32		margin-bottom: 0 ! important }
33
34		.hidden {
35		display: none }
36
37		.navigation {
38		width: 100% ;
39		background: #99ccff ;
40		margin-top: 0px ;
41		margin-bottom: 0px }
42
43		.navigation .navicon {
44		width: 150px ;
45		height: 35px }
46
47		.navigation .textlinks {
48		padding-left: 1em ;
49		text-align: left }
50
51		.navigation td, .navigation th {
52		padding-left: 0em ;
53		padding-right: 0em ;
54		vertical-align: middle }
55
56		.rfc2822 {
57		margin-top: 0.5em ;
58		margin-left: 0.5em ;
59		margin-right: 0.5em ;
60		margin-bottom: 0em }
61
62		.rfc2822 td {
63		text-align: left }
64
65		.rfc2822 th.field-name {
66		text-align: right ;
67		font-family: sans-serif ;
68		padding-right: 0.5em ;
69		font-weight: bold ;
70		margin-bottom: 0em }
71
72		a.toc-backref {
73		text-decoration: none ;
74		color: black }
75
76		blockquote.epigraph {
77		margin: 2em 5em ; }
78
79		body {
80		margin: 0px ;
81		margin-bottom: 1em ;
82		padding: 0px }
83
84		dl.docutils dd {
85		margin-bottom: 0.5em }
86
87		div.section {
88		margin-left: 1em ;
89		margin-right: 1em ;
90		margin-bottom: 1.5em }
91
92		div.section div.section {
93		margin-left: 0em ;
94		margin-right: 0em ;
95		margin-top: 1.5em }
96
97		div.abstract {
98		margin: 2em 5em }
99
100		div.abstract p.topic-title {
101		font-weight: bold ;
102		text-align: center }
103
104		div.admonition, div.attention, div.caution, div.danger, div.error,
105		div.hint, div.important, div.note, div.tip, div.warning {
106		margin: 2em ;
107		border: medium outset ;
108		padding: 1em }
109
110		div.admonition p.admonition-title, div.hint p.admonition-title,
111		div.important p.admonition-title, div.note p.admonition-title,
112		div.tip p.admonition-title {
113		font-weight: bold ;
114		font-family: sans-serif }
115
116		div.attention p.admonition-title, div.caution p.admonition-title,
117		div.danger p.admonition-title, div.error p.admonition-title,
118		div.warning p.admonition-title {
119		color: red ;
120		font-weight: bold ;
121		font-family: sans-serif }
122
123		/* Uncomment (and remove this text!) to get reduced vertical space in
124		compound paragraphs.
125		div.compound .compound-first, div.compound .compound-middle {
126		margin-bottom: 0.5em }
127
128		div.compound .compound-last, div.compound .compound-middle {
129		margin-top: 0.5em }
130		*/
131
132		div.dedication {
133		margin: 2em 5em ;
134		text-align: center ;
135		font-style: italic }
136
137		div.dedication p.topic-title {
138		font-weight: bold ;
139		font-style: normal }
140
141		div.figure {
142		margin-left: 2em ;
143		margin-right: 2em }
144
145		div.footer, div.header {
146		clear: both;
147		font-size: smaller }
148
149		div.footer {
150		margin-left: 1em ;
151		margin-right: 1em }
152
153		div.line-block {
154		display: block ;
155		margin-top: 1em ;
156		margin-bottom: 1em }
157
158		div.line-block div.line-block {
159		margin-top: 0 ;
160		margin-bottom: 0 ;
161		margin-left: 1.5em }
162
163		div.sidebar {
164		margin-left: 1em ;
165		border: medium outset ;
166		padding: 1em ;
167		background-color: #ffffee ;
168		width: 40% ;
169		float: right ;
170		clear: right }
171
172		div.sidebar p.rubric {
173		font-family: sans-serif ;
174		font-size: medium }
175
176		div.system-messages {
177		margin: 5em }
178
179		div.system-messages h1 {
180		color: red }
181
182		div.system-message {
183		border: medium outset ;
184		padding: 1em }
185
186		div.system-message p.system-message-title {
187		color: red ;
188		font-weight: bold }
189
190		div.topic {
191		margin: 2em }
192
193		h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
194		h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
195		margin-top: 0.4em }
196
197		h1 {
198		font-family: sans-serif ;
199		font-size: large }
200
201		h2 {
202		font-family: sans-serif ;
203		font-size: medium }
204
205		h3 {
206		font-family: sans-serif ;
207		font-size: small }
208
209		h4 {
210		font-family: sans-serif ;
211		font-style: italic ;
212		font-size: small }
213
214		h5 {
215		font-family: sans-serif;
216		font-size: x-small }
217
218		h6 {
219		font-family: sans-serif;
220		font-style: italic ;
221		font-size: x-small }
222
223		hr.docutils {
224		width: 75% }
225
226		img.align-left {
227		clear: left }
228
229		img.align-right {
230		clear: right }
231
232		img.borderless {
233		border: 0 }
234
235		ol.simple, ul.simple {
236		margin-bottom: 1em }
237
238		ol.arabic {
239		list-style: decimal }
240
241		ol.loweralpha {
242		list-style: lower-alpha }
243
244		ol.upperalpha {
245		list-style: upper-alpha }
246
247		ol.lowerroman {
248		list-style: lower-roman }
249
250		ol.upperroman {
251		list-style: upper-roman }
252
253		p.attribution {
254		text-align: right ;
255		margin-left: 50% }
256
257		p.caption {
258		font-style: italic }
259
260		p.credits {
261		font-style: italic ;
262		font-size: smaller }
263
264		p.label {
265		white-space: nowrap }
266
267		p.rubric {
268		font-weight: bold ;
269		font-size: larger ;
270		color: maroon ;
271		text-align: center }
272
273		p.sidebar-title {
274		font-family: sans-serif ;
275		font-weight: bold ;
276		font-size: larger }
277
278		p.sidebar-subtitle {
279		font-family: sans-serif ;
280		font-weight: bold }
281
282		p.topic-title {
283		font-family: sans-serif ;
284		font-weight: bold }
285
286		pre.address {
287		margin-bottom: 0 ;
288		margin-top: 0 ;
289		font-family: serif ;
290		font-size: 100% }
291
292		pre.literal-block, pre.doctest-block {
293		margin-left: 2em ;
294		margin-right: 2em }
295
296		span.classifier {
297		font-family: sans-serif ;
298		font-style: oblique }
299
300		span.classifier-delimiter {
301		font-family: sans-serif ;
302		font-weight: bold }
303
304		span.interpreted {
305		font-family: sans-serif }
306
307		span.option {
308		white-space: nowrap }
309
310		span.option-argument {
311		font-style: italic }
312
313		span.pre {
314		white-space: pre }
315
316		span.problematic {
317		color: red }
318
319		span.section-subtitle {
320		/* font-size relative to parent (h1..h6 element) */
321		font-size: 80% }
322
323		table.citation {
324		border-left: solid 1px gray;
325		margin-left: 1px }
326
327		table.docinfo {
328		margin: 2em 4em }
329
330		table.docutils {
331		margin-top: 0.5em ;
332		margin-bottom: 0.5em }
333
334		table.footnote {
335		border-left: solid 1px black;
336		margin-left: 1px }
337
338		table.docutils td, table.docutils th,
339		table.docinfo td, table.docinfo th {
340		padding-left: 0.5em ;
341		padding-right: 0.5em ;
342		vertical-align: top }
343
344		td.num {
345		text-align: right }
346
347		th.field-name {
348		font-weight: bold ;
349		text-align: left ;
350		white-space: nowrap ;
351		padding-left: 0 }
352
353		h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
354		h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
355		font-size: 100% }
356
357		ul.auto-toc {
358		list-style-type: none }
359
360		</style>
	5	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	6	<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
	7	<title></title>
	8	<link rel="stylesheet" href="../css/bep.css" type="text/css" />
361	9	</head>
362		<body bgcolor="white">
363		<table class="navigation" cellpadding="0" cellspacing="0"
364		width="100%" border="0">
365		<tr><td class="navicon" width="150" height="35">
366		<!--<a href="http://www.python.org/" title="Python Home Page">
367		<img src="http://www.python.org/pics/PyBanner007.gif" alt="[Python]"
368		border="0" width="150" height="35" /></a></td>
369		<td class="textlinks" align="left">
370		[<b><a href="http://www.bittorrent.org/">bittorrent.org</a></b>]-->
371		[<b><a href="http://www.bittorrent.org/beps/">BEP Index</a></b>]
372		[<b><a href="./bep-0003.txt">BEP Source</a></b>]
373		</td></tr></table>
	10	<body>
374	11	<div class="document">
	12
	13	<div id="upper" class="clear">
	14	<div id="wrap">
	15	<div id="header">
	16	<h1><a href="../index.html">BitTorrent<span>.org</span></a></h1>
	17	</div>
	18	<div id="nav">
	19	<ul>
	20	<li><a href="../index.html">Home</a></li>
	21	<li><a href="../introduction.html">For Users</a></li>
	22	<li><span>For Developers</span></li>
	23	<!-- <li><a href="./blog">Blog</a></li> -->
	24	<li><a href="../donate.html">Donate!</a></li>
	25	</ul>
	26	</div> <!-- nav -->
	27	<!-- ### Begin Content ### -->
	28	<div id="second">
	29
	30
	31
375	32	<table class="rfc2822 docutils field-list" frame="void" rules="none">
376	33	<col class="field-name" />
…	…
379	36	<tr class="field"><th class="field-name">BEP:</th><td class="field-body">3</td>
380	37	</tr>
381		<tr class="field"><th class="field-name">Title:</th><td class="field-body">~~Assigned Numbers~~</td>
382		</tr>
383		<tr class="field"><th class="field-name">Version:</th><td class="field-body">1</td>
384		</tr>
385		<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="https://svn.bittorrent.com/trac.cgi/browser/dotorg/trunk/html/beps/bep_0003.rst">~~31-Jan-2008~~</a></td>
386		</tr>
387		<tr class="field"><th class="field-name">Author:</th><td class="field-body">~~David Harrison~~</td>
388		</tr>
389		<tr class="field"><th class="field-name">Status:</th><td class="field-body">~~Active~~</td>
390		</tr>
391		<tr class="field"><th class="field-name">Type:</th><td class="field-body">~~Process~~</td>
	38	<tr class="field"><th class="field-name">Title:</th><td class="field-body">The BitTorrent Protocol Specification</td>
	39	</tr>
	40	<tr class="field"><th class="field-name">Version:</th><td class="field-body">$Revision$</td>
	41	</tr>
	42	<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="https://svn.bittorrent.com/trac.cgi/browser/dotorg/trunk/html/beps/bep_0003.rst">$Date$</a></td>
	43	</tr>
	44	<tr class="field"><th class="field-name">Author:</th><td class="field-body">Bram Cohen <bram at bittorrent.com></td>
	45	</tr>
	46	<tr class="field"><th class="field-name">Status:</th><td class="field-body">Final</td>
	47	</tr>
	48	<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standard</td>
392	49	</tr>
393	50	<tr class="field"><th class="field-name">Created:</th><td class="field-body">10-Jan-2008</td>
…	…
401	58	<p class="topic-title first">Contents</p>
402	59	<ul class="simple">
403		<li><a class="reference internal" href="#bittorrent-org-for-developers-assigned-numbers" id="id2">BitTorrent.org » For Developers » Assigned Numbers</a><ul>
404		<li><a class="reference internal" href="#reserved-bit-allocations" id="id3">Reserved Bit Allocations</a></li>
405		<li><a class="reference internal" href="#reserved-message-ids" id="id4">Reserved Message IDs</a></li>
406		</ul>
407		</li>
408		</ul>
409		</div>
410		<div class="section" id="bittorrent-org-for-developers-assigned-numbers">
411		<h1><a class="toc-backref" href="#id2">BitTorrent.org » For Developers » Assigned Numbers</a></h1>
412		<p>This document describes the known bit allocations and message IDs for
413		the BitTorrent protocol. To request a bit allocation contact
414		<a class="reference external" href="mailto:editor@bittorrent.org">editor@bittorrent.org</a>. Contact the same address if you are aware of
415		any omissions.</p>
416		<div class="section" id="reserved-bit-allocations">
417		<h2><a class="toc-backref" href="#id3">Reserved Bit Allocations</a></h2>
418		<pre class="literal-block">
419		reserved[0]
420		0x80 Azureus Messaging Protocol
421
422		reserved[5]
423		0x10 LTEP (LibTorrent Extension Protocol)
424
425		reserved[7]
426		0x01 BitTorrent DHT
427		0x04 suggest, haveall, havenone, reject request, and allow fast extensions
428		</pre>
429		</div>
430		<div class="section" id="reserved-message-ids">
431		<h2><a class="toc-backref" href="#id4">Reserved Message IDs</a></h2>
432		<pre class="literal-block">
433		Core Protocol:
434		0x00 choke
435		0x01 unchoke
436		0x02 interested
437		0x03 not interested
438		0x04 have
439		0x05 bitfield
440		0x06 request
441		0x07 piece
442		0x08 cancel
443		0x09 port
444
445		Fast Extensions
446
447		0x0D suggest
448		0x0E have all
449		0x0F have none
450		0x10 reject request
451		0x11 allowed fast
452
453		Additional IDs used in deployed clients
454		0x14 LTEP Handshake (implemented in libtorrent, uTorrent,...)
455		</pre>
456		</div>
	60	<li><a class="reference internal" href="#a-bittorrent-file-distribution-consists-of-these-entities" id="id2">A BitTorrent file distribution consists of these entities:</a></li>
	61	<li><a class="reference internal" href="#to-start-serving-a-host-goes-through-the-following-steps" id="id3">To start serving, a host goes through the following steps:</a></li>
	62	<li><a class="reference internal" href="#to-start-downloading-a-user-does-the-following" id="id4">To start downloading, a user does the following:</a></li>
	63	<li><a class="reference internal" href="#the-connectivity-is-as-follows" id="id5">The connectivity is as follows:</a></li>
	64	<li><a class="reference internal" href="#metainfo-files-are-bencoded-dictionaries-with-the-following-keys" id="id6">Metainfo files are bencoded dictionaries with the following keys:</a></li>
	65	<li><a class="reference internal" href="#tracker-get-requests-have-the-following-keys" id="id7">Tracker GET requests have the following keys:</a></li>
	66	<li><a class="reference internal" href="#all-non-keepalive-messages-start-with-a-single-byte-which-gives-their-type" id="id8">All non-keepalive messages start with a single byte which gives their type.</a></li>
	67	<li><a class="reference internal" href="#the-possible-values-are" id="id9">The possible values are:</a></li>
	68	</ul>
	69	</div>
	70	<p>BitTorrent is a protocol for distributing files. It identifies content
	71	by URL and is designed to integrate seamlessly with the web. Its
	72	advantage over plain HTTP is that when multiple downloads of the same
	73	file happen concurrently, the downloaders upload to each other, making
	74	it possible for the file source to support very large numbers of
	75	downloaders with only a modest increase in its load.</p>
	76	<div class="section" id="a-bittorrent-file-distribution-consists-of-these-entities">
	77	<h1>A BitTorrent file distribution consists of these entities:</h1>
	78	<ul class="simple">
	79	<li>An ordinary web server</li>
	80	<li>A static 'metainfo' file</li>
	81	<li>A BitTorrent tracker</li>
	82	<li>An 'original' downloader</li>
	83	<li>The end user web browsers</li>
	84	<li>The end user downloaders</li>
	85	</ul>
	86	<p>There are ideally many end users for a single file.</p>
	87	</div>
	88	<div class="section" id="to-start-serving-a-host-goes-through-the-following-steps">
	89	<h1>To start serving, a host goes through the following steps:</h1>
	90	<ol class="arabic simple">
	91	<li>Start running a tracker (or, more likely, have one running already).</li>
	92	<li>Start running an ordinary web server, such as apache, or have one already.</li>
	93	<li>Associate the extension .torrent with mimetype application/x-bittorrent on their web server (or have done so already).</li>
	94	<li>Generate a metainfo (.torrent) file using the complete file to be served and the URL of the tracker.</li>
	95	<li>Put the metainfo file on the web server.</li>
	96	<li>Link to the metainfo (.torrent) file from some other web page.</li>
	97	<li>Start a downloader which already has the complete file (the 'origin').</li>
	98	</ol>
	99	</div>
	100	<div class="section" id="to-start-downloading-a-user-does-the-following">
	101	<h1>To start downloading, a user does the following:</h1>
	102	<ol class="arabic simple">
	103	<li>Install BitTorrent (or have done so already).</li>
	104	<li>Surf the web.</li>
	105	<li>Click on a link to a .torrent file.</li>
	106	<li>Select where to save the file locally, or select a partial download to resume.</li>
	107	<li>Wait for download to complete.</li>
	108	<li>Tell downloader to exit (it keeps uploading until this happens).</li>
	109	</ol>
	110	</div>
	111	<div class="section" id="the-connectivity-is-as-follows">
	112	<h1>The connectivity is as follows:</h1>
	113	<ul class="simple">
	114	<li>Strings are length-prefixed base ten followed by a colon and the string. For example <tt class="docutils literal"><span class="pre">4:spam</span></tt> corresponds to 'spam'.</li>
	115	<li>Integers are represented by an 'i' followed by the number in base 10
	116	followed by an 'e'. For example <tt class="docutils literal"><span class="pre">i3e</span></tt> corresponds to 3 and
	117	<tt class="docutils literal"><span class="pre">i-3e</span></tt> corresponds to -3. Integers have no size
	118	limitation. <tt class="docutils literal"><span class="pre">i-0e</span></tt> is invalid. All encodings with a leading
	119	zero, such as <tt class="docutils literal"><span class="pre">i03e</span></tt>, are invalid, other than
	120	<tt class="docutils literal"><span class="pre">i0e</span></tt>, which of course corresponds to 0.</li>
	121	<li>Lists are encoded as an 'l' followed by their elements (also
	122	bencoded) followed by an 'e'. For example <tt class="docutils literal"><span class="pre">l4:spam4:eggse</span></tt>
	123	corresponds to ['spam', 'eggs'].</li>
	124	<li>Dictionaries are encoded as a 'd' followed by a list of alternating
	125	keys and their corresponding values followed by an 'e'. For example,
	126	<tt class="docutils literal"><span class="pre">d3:cow3:moo4:spam4:eggse</span></tt> corresponds to {'cow': 'moo',
	127	'spam': 'eggs'} and <tt class="docutils literal"><span class="pre">d4:spaml1:a1:bee</span></tt> corresponds to
	128	{'spam': ['a', 'b']}. Keys must be strings and appear in sorted order
	129	(sorted as raw strings, not alphanumerics).</li>
	130	</ul>
	131	</div>
	132	<div class="section" id="metainfo-files-are-bencoded-dictionaries-with-the-following-keys">
	133	<h1>Metainfo files are bencoded dictionaries with the following keys:</h1>
	134	<dl class="docutils">
	135	<dt>announce</dt>
	136	<dd>The URL of the tracker.</dd>
	137	<dt>info</dt>
	138	<dd><p class="first">This maps to a dictionary, with keys described below.</p>
	139	<p>The <tt class="docutils literal"><span class="pre">name</span></tt> key maps to a string which is the suggested name
	140	to save the file (or directory) as. It is purely advisory.</p>
	141	<p><tt class="docutils literal"><span class="pre">piece</span> <span class="pre">length</span></tt> maps to the number of bytes in each piece
	142	the file is split into. For the purposes of transfer, files are
	143	split into fixed-size pieces which are all the same length except for
	144	possibly the last one which may be truncated. <tt class="docutils literal"><span class="pre">piece</span>
	145	<span class="pre">length</span></tt> is almost always a power of two, most commonly 2 18 =
	146	256 K (BitTorrent prior to version 3.2 uses 2 20 = 1 M as
	147	default).</p>
	148	<p><tt class="docutils literal"><span class="pre">pieces</span></tt> maps to a string whose length is a multiple of
	149	20. It is to be subdivided into strings of length 20, each of which is
	150	the SHA1 hash of the piece at the corresponding index.</p>
	151	<p>There is also a key <tt class="docutils literal"><span class="pre">length</span></tt> or a key <tt class="docutils literal"><span class="pre">files</span></tt>,
	152	but not both or neither. If <tt class="docutils literal"><span class="pre">length</span></tt> is present then the
	153	download represents a single file, otherwise it represents a set of
	154	files which go in a directory structure.</p>
	155	<p>In the single file case, <tt class="docutils literal"><span class="pre">length</span></tt> maps to the length of
	156	the file in bytes.</p>
	157	<p>For the purposes of the other keys, the multi-file case is treated as
	158	only having a single file by concatenating the files in the order they
	159	appear in the files list. The files list is the value
	160	<tt class="docutils literal"><span class="pre">files</span></tt> maps to, and is a list of dictionaries containing
	161	the following keys:</p>
	162	<p><tt class="docutils literal"><span class="pre">length</span></tt> - The length of the file, in bytes.</p>
	163	<p><tt class="docutils literal"><span class="pre">path</span></tt> - A list of strings corresponding to subdirectory
	164	names, the last of which is the actual file name (a zero length list
	165	is an error case).</p>
	166	<p class="last">In the single file case, the name key is the name of a file, in the
	167	muliple file case, it's the name of a directory.</p>
	168	</dd>
	169	</dl>
	170	</div>
	171	<div class="section" id="tracker-get-requests-have-the-following-keys">
	172	<h1>Tracker GET requests have the following keys:</h1>
	173	<dl class="docutils">
	174	<dt>info_hash</dt>
	175	<dd>The 20 byte sha1 hash of the bencoded form of the info value from the
	176	metainfo file. Note that this is a substring of the metainfo
	177	file. This value will almost certainly have to be escaped.</dd>
	178	<dt>peer_id</dt>
	179	<dd>A string of length 20 which this downloader uses as its id. Each
	180	downloader generates its own id at random at the start of a new
	181	download. This value will also almost certainly have to be escaped.</dd>
	182	<dt>ip</dt>
	183	<dd>An optional parameter giving the IP (or dns name) which this peer is
	184	at. Generally used for the origin if it's on the same machine as the
	185	tracker.</dd>
	186	<dt>port</dt>
	187	<dd>The port number this peer is listening on. Common behavior is for a
	188	downloader to try to listen on port 6881 and if that port is taken try
	189	6882, then 6883, etc. and give up after 6889.</dd>
	190	<dt>uploaded</dt>
	191	<dd>The total amount uploaded so far, encoded in base ten ascii.</dd>
	192	<dt>downloaded</dt>
	193	<dd>The total amount downloaded so far, encoded in base ten ascii.</dd>
	194	<dt>left</dt>
	195	<dd>The number of bytes this peer still has to download, encoded in
	196	base ten ascii. Note that this can't be computed from downloaded and
	197	the file length since it might be a resume, and there's a chance that
	198	some of the downloaded data failed an integrity check and had to be
	199	re-downloaded.</dd>
	200	<dt>event</dt>
	201	<dd>This is an optional key which maps to <tt class="docutils literal"><span class="pre">started</span></tt>,
	202	<tt class="docutils literal"><span class="pre">completed</span></tt>, or <tt class="docutils literal"><span class="pre">stopped</span></tt> (or
	203	<tt class="docutils literal"><span class="pre">empty</span></tt>, which is the same as not being present). If not
	204	present, this is one of the announcements done at regular
	205	intervals. An announcement using <tt class="docutils literal"><span class="pre">started</span></tt> is sent when a
	206	download first begins, and one using <tt class="docutils literal"><span class="pre">completed</span></tt> is sent
	207	when the download is complete. No <tt class="docutils literal"><span class="pre">completed</span></tt> is sent if
	208	the file was complete when started. Downloaders send an announcement
	209	using <tt class="docutils literal"><span class="pre">stopped</span></tt> when they cease downloading.</dd>
	210	</dl>
	211	<p>Tracker responses are bencoded dictionaries. If a tracker response
	212	has a key <tt class="docutils literal"><span class="pre">failure</span> <span class="pre">reason</span></tt>, then that maps to a human
	213	readable string which explains why the query failed, and no other keys
	214	are required. Otherwise, it must have two keys: <tt class="docutils literal"><span class="pre">interval</span></tt>,
	215	which maps to the number of seconds the downloader should wait between
	216	regular rerequests, and <tt class="docutils literal"><span class="pre">peers</span></tt>. <tt class="docutils literal"><span class="pre">peers</span></tt> maps to
	217	a list of dictionaries corresponding to <tt class="docutils literal"><span class="pre">peers</span></tt>, each of
	218	which contains the keys <tt class="docutils literal"><span class="pre">peer</span> <span class="pre">id</span></tt>, <tt class="docutils literal"><span class="pre">ip</span></tt>, and
	219	<tt class="docutils literal"><span class="pre">port</span></tt>, which map to the peer's self-selected ID, IP
	220	address or dns name as a string, and port number, respectively. Note
	221	that downloaders may rerequest on nonscheduled times if an event
	222	happens or they need more peers.</p>
	223	<p>If you want to make any extensions to metainfo files or tracker
	224	queries, please coordinate with Bram Cohen to make sure that all
	225	extensions are done compatibly.</p>
	226	<p>BitTorrent's peer protocol operates over TCP. It performs efficiently
	227	without setting any socket options.</p>
	228	<p>Peer connections are symmetrical. Messages sent in both directions
	229	look the same, and data can flow in either direction.</p>
	230	<p>The peer protocol refers to pieces of the file by index as
	231	described in the metainfo file, starting at zero. When a peer finishes
	232	downloading a piece and checks that the hash matches, it announces
	233	that it has that piece to all of its peers.</p>
	234	<p>Connections contain two bits of state on either end: choked or not,
	235	and interested or not. Choking is a notification that no data will be
	236	sent until unchoking happens. The reasoning and common techniques
	237	behind choking are explained later in this document.</p>
	238	<p>Data transfer takes place whenever one side is interested and the
	239	other side is not choking. Interest state must be kept up to date at
	240	all times - whenever a downloader doesn't have something they
	241	currently would ask a peer for in unchoked, they must express lack of
	242	interest, despite being choked. Implementing this properly is tricky,
	243	but makes it possible for downloaders to know which peers will start
	244	downloading immediately if unchoked.</p>
	245	<p>Connections start out choked and not interested.</p>
	246	<p>When data is being transferred, downloaders should keep several
	247	piece requests queued up at once in order to get good TCP performance
	248	(this is called 'pipelining'.) On the other side, requests which can't
	249	be written out to the TCP buffer immediately should be queued up in
	250	memory rather than kept in an application-level network buffer, so
	251	they can all be thrown out when a choke happens.</p>
	252	<p>The peer wire protocol consists of a handshake followed by a
	253	never-ending stream of length-prefixed messages. The handshake starts
	254	with character ninteen (decimal) followed by the string 'BitTorrent
	255	protocol'. The leading character is a length prefix, put there in the
	256	hope that other new protocols may do the same and thus be trivially
	257	distinguishable from each other.</p>
	258	<p>All later integers sent in the protocol are encoded as four bytes
	259	big-endian.</p>
	260	<p>After the fixed headers come eight reserved bytes, which are all
	261	zero in all current implementations. If you wish to extend the
	262	protocol using these bytes, please coordinate with Bram Cohen to make
	263	sure all extensions are done compatibly.</p>
	264	<p>Next comes the 20 byte sha1 hash of the bencoded form of the info
	265	value from the metainfo file. (This is the same value which is
	266	announced as <tt class="docutils literal"><span class="pre">info_hash</span></tt> to the tracker, only here it's raw
	267	instead of quoted here). If both sides don't send the same value, they
	268	sever the connection. The one possible exception is if a downloader
	269	wants to do multiple downloads over a single port, they may wait for
	270	incoming connections to give a download hash first, and respond with
	271	the same one if it's in their list.</p>
	272	<p>After the download hash comes the 20-byte peer id which is reported
	273	in tracker requests and contained in peer lists in tracker
	274	responses. If the receiving side's peer id doesn't match the one the
	275	initiating side expects, it severs the connection.</p>
	276	<p>That's it for handshaking, next comes an alternating stream of
	277	length prefixes and messages. Messages of length zero are keepalives,
	278	and ignored. Keepalives are generally sent once every two minutes, but
	279	note that timeouts can be done much more quickly when data is
	280	expected.</p>
	281	</div>
	282	<div class="section" id="all-non-keepalive-messages-start-with-a-single-byte-which-gives-their-type">
	283	<h1>All non-keepalive messages start with a single byte which gives their type.</h1>
	284	</div>
	285	<div class="section" id="the-possible-values-are">
	286	<h1>The possible values are:</h1>
	287	<ul class="simple">
	288	<li>0 - choke</li>
	289	<li>1 - unchoke</li>
	290	<li>2 - interested</li>
	291	<li>3 - not interested</li>
	292	<li>4 - have</li>
	293	<li>5 - bitfield</li>
	294	<li>6 - request</li>
	295	<li>7 - piece</li>
	296	<li>8 - cancel</li>
	297	</ul>
	298	<p>'choke', 'unchoke', 'interested', and 'not interested' have no payload.</p>
	299	<p>'bitfield' is only ever sent as the first message. Its payload is a
	300	bitfield with each index that downloader has sent set to one and the
	301	rest set to zero. Downloaders which don't have anything yet may skip
	302	the 'bitfield' message. The first byte of the bitfield corresponds to
	303	indices 0 - 7 from high bit to low bit, respectively. The next one
	304	8-15, etc. Spare bits at the end are set to zero.</p>
	305	<p>The 'have' message's payload is a single number, the index which
	306	that downloader just completed and checked the hash of.</p>
	307	<p>'request' messages contain an index, begin, and length. The last
	308	two are byte offsets. Length is generally a power of two unless it
	309	gets truncated by the end of the file. All current implementations use
	310	2 15 , and close connections which request an amount greater than 2
	311	17.</p>
	312	<p>'cancel' messages have the same payload as request messages. They
	313	are generally only sent towards the end of a download, during what's
	314	called 'endgame mode'. When a download is almost complete, there's a
	315	tendency for the last few pieces to all be downloaded off a single
	316	hosed modem line, taking a very long time. To make sure the last few
	317	pieces come in quickly, once requests for all pieces a given
	318	downloader doesn't have yet are currently pending, it sends requests
	319	for everything to everyone it's downloading from. To keep this from
	320	becoming horribly inefficient, it sends cancels to everyone else every
	321	time a piece arrives.</p>
	322	<p>'piece' messages contain an index, begin, and piece. Note that they
	323	are correlated with request messages implicitly. It's possible for an
	324	unexpected piece to arrive if choke and unchoke messages are sent in
	325	quick succession and/or transfer is going very slowly.</p>
	326	<p>Downloaders generally download pieces in random order, which does a
	327	reasonably good job of keeping them from having a strict subset or
	328	superset of the pieces of any of their peers.</p>
	329	<p>Choking is done for several reasons. TCP congestion control behaves
	330	very poorly when sending over many connections at once. Also, choking
	331	lets each peer use a tit-for-tat-ish algorithm to ensure that they get
	332	a consistent download rate.</p>
	333	<p>The choking algorithm described below is the currently deployed
	334	one. It is very important that all new algorithms work well both in a
	335	network consisting entirely of themselves and in a network consisting
	336	mostly of this one.</p>
	337	<p>There are several criteria a good choking algorithm should meet. It
	338	should cap the number of simultaneous uploads for good TCP
	339	performance. It should avoid choking and unchoking quickly, known as
	340	'fibrillation'. It should reciprocate to peers who let it
	341	download. Finally, it should try out unused connections once in a
	342	while to find out if they might be better than the currently used
	343	ones, known as optimistic unchoking.</p>
	344	<p>The currently deployed choking algorithm avoids fibrillation by
	345	only changing who's choked once every ten seconds. It does
	346	reciprocation and number of uploads capping by unchoking the four
	347	peers which it has the best download rates from and are
	348	interested. Peers which have a better upload rate but aren't
	349	interested get unchoked and if they become interested the worst
	350	uploader gets choked. If a downloader has a complete file, it uses its
	351	upload rate rather than its download rate to decide who to
	352	unchoke.</p>
	353	<p>For optimistic unchoking, at any one time there is a single peer
	354	which is unchoked regardless of it's upload rate (if interested, it
	355	counts as one of the four allowed downloaders.) Which peer is
	356	optimistically unchoked rotates every 30 seconds. To give them a
	357	decent chance of getting a complete piece to upload, new connections
	358	are three times as likely to start as the current optimistic unchoke
	359	as anywhere else in the rotation.</p>
	360	<!-- Local Variables:
	361	mode: indented-text
	362	indent-tabs-mode: nil
	363	sentence-end-double-space: t
	364	fill-column: 70
	365	coding: utf-8
	366	End: -->
	367	</div>
	368
	369
	370	</div>
	371	<div id="footer">
	372	<hr/>
457	373	</div>
458	374

dotorg/trunk_fixed/html/beps/makefile

r10530	r10535
11	11	bep_0008.html \
12	12	bep_0009.html \
	13	bep_0010.html \
13	14	bep_1000.html \
14	15
…	…
16	17
17	18	%.html:%.rst
18		rstbep2html.py --template=template.txt --cloak-email-addresses --link-stylesheet --stylesheet=../css/bep.css --no-toc-backlinks $? >$@ --traceback
	19	rstbep2html.py --template=template.txt --pep-base-url=http://www.bittorrent.org/beps/ --cloak-email-addresses --link-stylesheet --stylesheet=../css/bep.css --no-toc-backlinks $? >$@ --traceback
19	20
20		#~/docutils/tools/rst2html.py --template=../template.txt --cloak-email-addresses --link-stylesheet --stylesheet=../css/screen.css --no-doc-title --no-toc-backlinks $? >$@
	21	#%.html:%.rst
	22	# rstpep2html.py --template=template.txt --cloak-email-addresses --link-stylesheet --stylesheet=../css/bep.css --no-toc-backlinks $? >$@ --traceback
21	23
22	24
	25

Context Navigation

Changeset 10535

Legend:

Download in other formats: