| 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><a href="bep_0000.html"><span>For Developers</span></a></li> |
|---|
| 23 | <!-- <li><a href="./blog">Blog</a></li> --> |
|---|
| 24 | <li><a href="http://forum.bittorrent.org"> Forums </li> |
|---|
| 25 | <li><a href="../donate.html">Donate!</a></li> |
|---|
| 26 | </ul> |
|---|
| 27 | </div> <!-- nav --> |
|---|
| 28 | <!-- ### Begin Content ### --> |
|---|
| 29 | <div id="second"> |
|---|
| 30 | |
|---|
| 31 | |
|---|
| 32 | |
|---|
| 33 | <table class="rfc2822 docutils field-list" frame="void" rules="none"> |
|---|
| 34 | <col class="field-name" /> |
|---|
| 35 | <col class="field-body" /> |
|---|
| 36 | <tbody valign="top"> |
|---|
| 37 | <tr class="field"><th class="field-name">BEP:</th><td class="field-body">2</td> |
|---|
| 38 | </tr> |
|---|
| 39 | <tr class="field"><th class="field-name">Title:</th><td class="field-body">Sample reStructured Text BEP Template</td> |
|---|
| 40 | </tr> |
|---|
| 41 | <tr class="field"><th class="field-name">Version:</th><td class="field-body">11083</td> |
|---|
| 42 | </tr> |
|---|
| 43 | <tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="http://bittorrent.org/trac/browser/dotorg/trunk/html/beps/bep_0002.rst">2008-05-13 17:34:56 -0700 (Tue, 13 May 2008)</a></td> |
|---|
| 44 | </tr> |
|---|
| 45 | <tr class="field"><th class="field-name">Author:</th><td class="field-body">David Harrison <dave at bittorrent.com></td> |
|---|
| 46 | </tr> |
|---|
| 47 | <tr class="field"><th class="field-name">Status:</th><td class="field-body">Active</td> |
|---|
| 48 | </tr> |
|---|
| 49 | <tr class="field"><th class="field-name">Type:</th><td class="field-body">Process</td> |
|---|
| 50 | </tr> |
|---|
| 51 | <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> |
|---|
| 52 | </tr> |
|---|
| 53 | <tr class="field"><th class="field-name">Created:</th><td class="field-body">02-Feb-2008</td> |
|---|
| 54 | </tr> |
|---|
| 55 | <tr class="field"><th class="field-name">Post-History:</th><td class="field-body"></td> |
|---|
| 56 | </tr> |
|---|
| 57 | </tbody> |
|---|
| 58 | </table> |
|---|
| 59 | <hr /> |
|---|
| 60 | <div class="contents topic" id="contents"> |
|---|
| 61 | <p class="topic-title first">Contents</p> |
|---|
| 62 | <ul class="simple"> |
|---|
| 63 | <li><a class="reference internal" href="#abstract" id="id22">Abstract</a></li> |
|---|
| 64 | <li><a class="reference internal" href="#rationale" id="id23">Rationale</a></li> |
|---|
| 65 | <li><a class="reference internal" href="#how-to-use-this-template" id="id24">How to Use This Template</a></li> |
|---|
| 66 | <li><a class="reference internal" href="#restructuredtext-bep-formatting-requirements" id="id25">ReStructuredText BEP Formatting Requirements</a><ul> |
|---|
| 67 | <li><a class="reference internal" href="#general" id="id26">General</a></li> |
|---|
| 68 | <li><a class="reference internal" href="#section-headings" id="id27">Section Headings</a></li> |
|---|
| 69 | <li><a class="reference internal" href="#paragraphs" id="id28">Paragraphs</a></li> |
|---|
| 70 | <li><a class="reference internal" href="#inline-markup" id="id29">Inline Markup</a></li> |
|---|
| 71 | <li><a class="reference internal" href="#block-quotes" id="id30">Block Quotes</a></li> |
|---|
| 72 | <li><a class="reference internal" href="#literal-blocks" id="id31">Literal Blocks</a></li> |
|---|
| 73 | <li><a class="reference internal" href="#lists" id="id32">Lists</a></li> |
|---|
| 74 | <li><a class="reference internal" href="#tables" id="id33">Tables</a></li> |
|---|
| 75 | <li><a class="reference internal" href="#hyperlinks" id="id34">Hyperlinks</a></li> |
|---|
| 76 | <li><a class="reference internal" href="#footnotes" id="id35">Footnotes</a></li> |
|---|
| 77 | <li><a class="reference internal" href="#images" id="id36">Images</a></li> |
|---|
| 78 | <li><a class="reference internal" href="#comments" id="id37">Comments</a></li> |
|---|
| 79 | <li><a class="reference internal" href="#escaping-mechanism" id="id38">Escaping Mechanism</a></li> |
|---|
| 80 | </ul> |
|---|
| 81 | </li> |
|---|
| 82 | <li><a class="reference internal" href="#habits-to-avoid" id="id39">Habits to Avoid</a></li> |
|---|
| 83 | <li><a class="reference internal" href="#resources" id="id40">Resources</a></li> |
|---|
| 84 | <li><a class="reference internal" href="#acknowledgements" id="id41">Acknowledgements</a></li> |
|---|
| 85 | <li><a class="reference internal" href="#references" id="id42">References</a></li> |
|---|
| 86 | <li><a class="reference internal" href="#copyright" id="id43">Copyright</a></li> |
|---|
| 87 | </ul> |
|---|
| 88 | </div> |
|---|
| 89 | <div class="section" id="abstract"> |
|---|
| 90 | <h1>Abstract</h1> |
|---|
| 91 | <p>This BEP provides a boilerplate or sample template for creating your |
|---|
| 92 | own reStructuredText BEPs. In conjunction with the content guidelines |
|---|
| 93 | 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 |
|---|
| 94 | BEPs to the format outlined below.</p> |
|---|
| 95 | <p>Note: if you are reading this BEP via the web, you should first grab |
|---|
| 96 | the text (reStructuredText) source of this BEP in order to complete |
|---|
| 97 | the steps below. <strong>DO NOT USE THE HTML FILE AS YOUR TEMPLATE!</strong></p> |
|---|
| 98 | <p>To get the source this (or any) BEP, look at the top of the HTML page |
|---|
| 99 | and click on the date & time on the "Last-Modified" line. It is a |
|---|
| 100 | link to the source text in the BitTorrent.org subversion repository.</p> |
|---|
| 101 | </div> |
|---|
| 102 | <div class="section" id="rationale"> |
|---|
| 103 | <h1>Rationale</h1> |
|---|
| 104 | <p>BEP submissions come in a wide variety of forms, not all adhering |
|---|
| 105 | to the format guidelines set forth below. Use this template, in |
|---|
| 106 | conjunction with the format guidelines below, to ensure that your |
|---|
| 107 | BEP submission won't get automatically rejected because of form.</p> |
|---|
| 108 | <p>ReStructuredText is offered as an alternative to plaintext BEPs, to |
|---|
| 109 | allow BEP authors more functionality and expressivity, while |
|---|
| 110 | maintaining easy readability in the source text. The processed HTML |
|---|
| 111 | form makes the functionality accessible to readers: live hyperlinks, |
|---|
| 112 | styled text, tables, images, and automatic tables of contents, among |
|---|
| 113 | other advantages.</p> |
|---|
| 114 | </div> |
|---|
| 115 | <div class="section" id="how-to-use-this-template"> |
|---|
| 116 | <h1>How to Use This Template</h1> |
|---|
| 117 | <p>To use this template you must first decide whether your BEP is going |
|---|
| 118 | to be an Informational or Standards Track BEP. Most BEPs are |
|---|
| 119 | Standards Track because they propose a new feature for the BitTorrent |
|---|
| 120 | system including the BitTorrent suite of protocols. When in doubt, |
|---|
| 121 | read BEP 1 for details or contact the BEP editors |
|---|
| 122 | <<a class="reference external" href="mailto:editor%40bittorrent.org">editor<span>@</span>bittorrent<span>.</span>org</a>>.</p> |
|---|
| 123 | <p>Once you've decided which type of BEP yours is going to be, follow the |
|---|
| 124 | directions below.</p> |
|---|
| 125 | <ul> |
|---|
| 126 | <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 |
|---|
| 127 | the following edits.</p> |
|---|
| 128 | </li> |
|---|
| 129 | <li><p class="first">Replace the "BEP: 2" header with "BEP: XXX" since you don't yet have |
|---|
| 130 | a BEP number assignment.</p> |
|---|
| 131 | </li> |
|---|
| 132 | <li><p class="first">Change the Title header to the title of your BEP.</p> |
|---|
| 133 | </li> |
|---|
| 134 | <li><p class="first">Leave the Version and Last-Modified headers alone; we'll take care |
|---|
| 135 | of those when we check your BEP into BitTorrent's Subversion repository. |
|---|
| 136 | These headers consist of keywords ("Revision" and "Date" enclosed in |
|---|
| 137 | "$"-signs) which are automatically expanded by the repository. |
|---|
| 138 | Please do not edit the expanded date or revision text.</p> |
|---|
| 139 | </li> |
|---|
| 140 | <li><p class="first">Change the Author header to include your name, and optionally your |
|---|
| 141 | email address. Be sure to follow the format carefully: your name |
|---|
| 142 | must appear first, and it must not be contained in parentheses. |
|---|
| 143 | Your email address may appear second (or it can be omitted) and if |
|---|
| 144 | it appears, it must appear in angle brackets. It is okay to |
|---|
| 145 | obfuscate your email address.</p> |
|---|
| 146 | </li> |
|---|
| 147 | <li><p class="first">If there is a mailing list for discussion of your new feature, add a |
|---|
| 148 | Discussions-To header right after the Author header. You should not |
|---|
| 149 | add a Discussions-To header if the mailing list to be used is |
|---|
| 150 | <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 |
|---|
| 151 | you directly. Most Informational BEPs don't have a Discussions-To |
|---|
| 152 | header.</p> |
|---|
| 153 | </li> |
|---|
| 154 | <li><p class="first">Change the Status header to "Draft".</p> |
|---|
| 155 | </li> |
|---|
| 156 | <li><p class="first">For Standards Track BEPs, change the Type header to "Standards |
|---|
| 157 | Track".</p> |
|---|
| 158 | </li> |
|---|
| 159 | <li><p class="first">For Informational BEPs, change the Type header to "Informational".</p> |
|---|
| 160 | </li> |
|---|
| 161 | <li><p class="first">For Standards Track BEPs, if your feature depends on the acceptance |
|---|
| 162 | of some other currently in-development BEP, add a Requires header |
|---|
| 163 | right after the Type header. The value should be the BEP number of |
|---|
| 164 | the BEP yours depends on. Don't add this header if your dependent |
|---|
| 165 | feature is described in a Final BEP.</p> |
|---|
| 166 | </li> |
|---|
| 167 | <li><p class="first">Change the Created header to today's date. Be sure to follow the |
|---|
| 168 | format carefully: it must be in <tt class="docutils literal"><span class="pre">dd-mmm-yyyy</span></tt> format, where the |
|---|
| 169 | <tt class="docutils literal"><span class="pre">mmm</span></tt> is the 3 English letter month abbreviation, i.e. one of Jan, |
|---|
| 170 | Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.</p> |
|---|
| 171 | </li> |
|---|
| 172 | <li><p class="first">Leave Post-History alone for now; you'll add dates to this header |
|---|
| 173 | 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 |
|---|
| 174 | you posted your BEP to the lists on August 14, 2001 and September 3, |
|---|
| 175 | 2001, the Post-History header would look like:</p> |
|---|
| 176 | <pre class="literal-block"> |
|---|
| 177 | Post-History: 14-Aug-2001, 03-Sept-2001 |
|---|
| 178 | </pre> |
|---|
| 179 | <p>You must manually add new dates and check them in. If you don't |
|---|
| 180 | have check-in privileges, send your changes to the BEP editors.</p> |
|---|
| 181 | </li> |
|---|
| 182 | <li><p class="first">Add a Replaces header if your BEP obsoletes an earlier BEP. The |
|---|
| 183 | value of this header is the number of the BEP that your new BEP is |
|---|
| 184 | replacing. Only add this header if the older BEP is in "final" |
|---|
| 185 | form, i.e. is either Accepted, Final, or Rejected. You aren't |
|---|
| 186 | replacing an older open BEP if you're submitting a competing idea.</p> |
|---|
| 187 | </li> |
|---|
| 188 | <li><p class="first">Now write your Abstract, Rationale, and other content for your BEP, |
|---|
| 189 | replacing all this gobbledygook with your own text. Be sure to |
|---|
| 190 | adhere to the format guidelines below, specifically on the |
|---|
| 191 | prohibition of tab characters and the indentation requirements.</p> |
|---|
| 192 | </li> |
|---|
| 193 | <li><p class="first">Update your References and Copyright section. Usually you'll place |
|---|
| 194 | your BEP into the public domain, in which case just leave the |
|---|
| 195 | Copyright section alone. Alternatively, you can use the <a class="reference external" href="http://www.opencontent.org/openpub/">Open |
|---|
| 196 | Publication License</a> <a class="footnote-reference" href="#id14" id="id15">[6]</a>, but public domain is still strongly |
|---|
| 197 | preferred.</p> |
|---|
| 198 | </li> |
|---|
| 199 | <li><p class="first">Leave the Emacs stanza at the end of this file alone, including the |
|---|
| 200 | formfeed character ("^L", or <tt class="docutils literal"><span class="pre">\f</span></tt>).</p> |
|---|
| 201 | </li> |
|---|
| 202 | <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> |
|---|
| 203 | </li> |
|---|
| 204 | </ul> |
|---|
| 205 | </div> |
|---|
| 206 | <div class="section" id="restructuredtext-bep-formatting-requirements"> |
|---|
| 207 | <h1>ReStructuredText BEP Formatting Requirements</h1> |
|---|
| 208 | <p>The following is a BEP-specific summary of reStructuredText syntax. |
|---|
| 209 | For the sake of simplicity and brevity, much detail is omitted. For |
|---|
| 210 | 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 |
|---|
| 211 | markup processing is done) are used for examples throughout, to |
|---|
| 212 | illustrate the plaintext markup.</p> |
|---|
| 213 | <div class="section" id="general"> |
|---|
| 214 | <h2>General</h2> |
|---|
| 215 | <p>You must adhere to the Emacs convention of adding two spaces at the |
|---|
| 216 | end of every sentence.</p> |
|---|
| 217 | <p>Tab characters must never appear in the document at all. A BEP should |
|---|
| 218 | include the standard Emacs stanza included by example at the bottom of |
|---|
| 219 | this BEP.</p> |
|---|
| 220 | </div> |
|---|
| 221 | <div class="section" id="section-headings"> |
|---|
| 222 | <h2>Section Headings</h2> |
|---|
| 223 | <p>BEP headings must begin in column zero and the initial letter of each |
|---|
| 224 | word must be capitalized as in book titles. Acronyms should be in all |
|---|
| 225 | capitals. Section titles must be adorned with an underline, a single |
|---|
| 226 | repeated punctuation character, which begins in column zero and must |
|---|
| 227 | extend at least as far as the right edge of the title text (4 |
|---|
| 228 | characters minimum). First-level section titles are underlined with |
|---|
| 229 | "=" (equals signs), second-level section titles with "-" (hyphens), |
|---|
| 230 | and third-level section titles with "'" (single quotes or |
|---|
| 231 | apostrophes). For example:</p> |
|---|
| 232 | <pre class="literal-block"> |
|---|
| 233 | First-Level Title |
|---|
| 234 | ================= |
|---|
| 235 | |
|---|
| 236 | Second-Level Title |
|---|
| 237 | ------------------ |
|---|
| 238 | |
|---|
| 239 | Third-Level Title |
|---|
| 240 | ''''''''''''''''' |
|---|
| 241 | </pre> |
|---|
| 242 | <p>If there are more than three levels of sections in your BEP, you may |
|---|
| 243 | insert overline/underline-adorned titles for the first and second |
|---|
| 244 | levels as follows:</p> |
|---|
| 245 | <pre class="literal-block"> |
|---|
| 246 | ============================ |
|---|
| 247 | First-Level Title (optional) |
|---|
| 248 | ============================ |
|---|
| 249 | |
|---|
| 250 | ----------------------------- |
|---|
| 251 | Second-Level Title (optional) |
|---|
| 252 | ----------------------------- |
|---|
| 253 | |
|---|
| 254 | Third-Level Title |
|---|
| 255 | ================= |
|---|
| 256 | |
|---|
| 257 | Fourth-Level Title |
|---|
| 258 | ------------------ |
|---|
| 259 | |
|---|
| 260 | Fifth-Level Title |
|---|
| 261 | ''''''''''''''''' |
|---|
| 262 | </pre> |
|---|
| 263 | <p>You shouldn't have more than five levels of sections in your BEP. If |
|---|
| 264 | you do, you should consider rewriting it.</p> |
|---|
| 265 | <p>You must use two blank lines between the last line of a section's body |
|---|
| 266 | and the next section heading. If a subsection heading immediately |
|---|
| 267 | follows a section heading, a single blank line in-between is |
|---|
| 268 | sufficient.</p> |
|---|
| 269 | <p>The body of each section is not normally indented, although some |
|---|
| 270 | constructs do use indentation, as described below. Blank lines are |
|---|
| 271 | used to separate constructs.</p> |
|---|
| 272 | </div> |
|---|
| 273 | <div class="section" id="paragraphs"> |
|---|
| 274 | <h2>Paragraphs</h2> |
|---|
| 275 | <p>Paragraphs are left-aligned text blocks separated by blank lines. |
|---|
| 276 | Paragraphs are not indented unless they are part of an indented |
|---|
| 277 | construct (such as a block quote or a list item).</p> |
|---|
| 278 | </div> |
|---|
| 279 | <div class="section" id="inline-markup"> |
|---|
| 280 | <h2>Inline Markup</h2> |
|---|
| 281 | <p>Portions of text within paragraphs and other text blocks may be |
|---|
| 282 | styled. For example:</p> |
|---|
| 283 | <pre class="literal-block"> |
|---|
| 284 | Text may be marked as *emphasized* (single asterisk markup, |
|---|
| 285 | typically shown in italics) or **strongly emphasized** (double |
|---|
| 286 | asterisks, typically boldface). ``Inline literals`` (using double |
|---|
| 287 | backquotes) are typically rendered in a monospaced typeface. No |
|---|
| 288 | further markup recognition is done within the double backquotes, |
|---|
| 289 | so they're safe for any kind of code snippets. |
|---|
| 290 | </pre> |
|---|
| 291 | </div> |
|---|
| 292 | <div class="section" id="block-quotes"> |
|---|
| 293 | <h2>Block Quotes</h2> |
|---|
| 294 | <p>Block quotes consist of indented body elements. For example:</p> |
|---|
| 295 | <pre class="literal-block"> |
|---|
| 296 | This is a paragraph. |
|---|
| 297 | |
|---|
| 298 | This is a block quote. |
|---|
| 299 | |
|---|
| 300 | A block quote may contain many paragraphs. |
|---|
| 301 | </pre> |
|---|
| 302 | <p>Block quotes are used to quote extended passages from other sources. |
|---|
| 303 | Block quotes may be nested inside other body elements. Use 4 spaces |
|---|
| 304 | per indent level.</p> |
|---|
| 305 | </div> |
|---|
| 306 | <div class="section" id="literal-blocks"> |
|---|
| 307 | <h2>Literal Blocks</h2> |
|---|
| 308 | <!-- In the text below, double backquotes are used to denote inline |
|---|
| 309 | literals. "``::``" is written so that the colons will appear in a |
|---|
| 310 | monospaced font; the backquotes (``) are markup, not part of the |
|---|
| 311 | text. See "Inline Markup" above. |
|---|
| 312 | |
|---|
| 313 | By the way, this is a comment, described in "Comments" below. --> |
|---|
| 314 | <p>Literal blocks are used for code samples or preformatted ASCII art. To |
|---|
| 315 | indicate a literal block, preface the indented text block with |
|---|
| 316 | "<tt class="docutils literal"><span class="pre">::</span></tt>" (two colons). The literal block continues until the end of |
|---|
| 317 | the indentation. Indent the text block by 4 spaces. For example:</p> |
|---|
| 318 | <pre class="literal-block"> |
|---|
| 319 | This is a typical paragraph. A literal block follows. |
|---|
| 320 | |
|---|
| 321 | :: |
|---|
| 322 | |
|---|
| 323 | for a in [5,4,3,2,1]: # this is program code, shown as-is |
|---|
| 324 | print a |
|---|
| 325 | print "it's..." |
|---|
| 326 | # a literal block continues until the indentation ends |
|---|
| 327 | </pre> |
|---|
| 328 | <p>The paragraph containing only "<tt class="docutils literal"><span class="pre">::</span></tt>" will be completely removed from |
|---|
| 329 | the output; no empty paragraph will remain. "<tt class="docutils literal"><span class="pre">::</span></tt>" is also |
|---|
| 330 | recognized at the end of any paragraph. If immediately preceded by |
|---|
| 331 | whitespace, both colons will be removed from the output. When text |
|---|
| 332 | immediately precedes the "<tt class="docutils literal"><span class="pre">::</span></tt>", <em>one</em> colon will be removed from |
|---|
| 333 | the output, leaving only one colon visible (i.e., "<tt class="docutils literal"><span class="pre">::</span></tt>" will be |
|---|
| 334 | replaced by "<tt class="docutils literal"><span class="pre">:</span></tt>"). For example, one colon will remain visible |
|---|
| 335 | here:</p> |
|---|
| 336 | <pre class="literal-block"> |
|---|
| 337 | Paragraph:: |
|---|
| 338 | |
|---|
| 339 | Literal block |
|---|
| 340 | </pre> |
|---|
| 341 | </div> |
|---|
| 342 | <div class="section" id="lists"> |
|---|
| 343 | <h2>Lists</h2> |
|---|
| 344 | <p>Bullet list items begin with one of "-", "*", or "+" (hyphen, |
|---|
| 345 | asterisk, or plus sign), followed by whitespace and the list item |
|---|
| 346 | body. List item bodies must be left-aligned and indented relative to |
|---|
| 347 | the bullet; the text immediately after the bullet determines the |
|---|
| 348 | indentation. For example:</p> |
|---|
| 349 | <pre class="literal-block"> |
|---|
| 350 | This paragraph is followed by a list. |
|---|
| 351 | |
|---|
| 352 | * This is the first bullet list item. The blank line above the |
|---|
| 353 | first list item is required; blank lines between list items |
|---|
| 354 | (such as below this paragraph) are optional. |
|---|
| 355 | |
|---|
| 356 | * This is the first paragraph in the second item in the list. |
|---|
| 357 | |
|---|
| 358 | This is the second paragraph in the second item in the list. |
|---|
| 359 | The blank line above this paragraph is required. The left edge |
|---|
| 360 | of this paragraph lines up with the paragraph above, both |
|---|
| 361 | indented relative to the bullet. |
|---|
| 362 | |
|---|
| 363 | - This is a sublist. The bullet lines up with the left edge of |
|---|
| 364 | the text blocks above. A sublist is a new list so requires a |
|---|
| 365 | blank line above and below. |
|---|
| 366 | |
|---|
| 367 | * This is the third item of the main list. |
|---|
| 368 | |
|---|
| 369 | This paragraph is not part of the list. |
|---|
| 370 | </pre> |
|---|
| 371 | <p>Enumerated (numbered) list items are similar, but use an enumerator |
|---|
| 372 | instead of a bullet. Enumerators are numbers (1, 2, 3, ...), letters |
|---|
| 373 | (A, B, C, ...; uppercase or lowercase), or Roman numerals (i, ii, iii, |
|---|
| 374 | iv, ...; uppercase or lowercase), formatted with a period suffix |
|---|
| 375 | ("1.", "2."), parentheses ("(1)", "(2)"), or a right-parenthesis |
|---|
| 376 | suffix ("1)", "2)"). For example:</p> |
|---|
| 377 | <pre class="literal-block"> |
|---|
| 378 | 1. As with bullet list items, the left edge of paragraphs must |
|---|
| 379 | align. |
|---|
| 380 | |
|---|
| 381 | 2. Each list item may contain multiple paragraphs, sublists, etc. |
|---|
| 382 | |
|---|
| 383 | This is the second paragraph of the second list item. |
|---|
| 384 | |
|---|
| 385 | a) Enumerated lists may be nested. |
|---|
| 386 | b) Blank lines may be omitted between list items. |
|---|
| 387 | </pre> |
|---|
| 388 | <p>Definition lists are written like this:</p> |
|---|
| 389 | <pre class="literal-block"> |
|---|
| 390 | what |
|---|
| 391 | Definition lists associate a term with a definition. |
|---|
| 392 | |
|---|
| 393 | how |
|---|
| 394 | The term is a one-line phrase, and the definition is one |
|---|
| 395 | or more paragraphs or body elements, indented relative to |
|---|
| 396 | the term. |
|---|
| 397 | </pre> |
|---|
| 398 | </div> |
|---|
| 399 | <div class="section" id="tables"> |
|---|
| 400 | <h2>Tables</h2> |
|---|
| 401 | <p>Simple tables are easy and compact but you are not required to use |
|---|
| 402 | simple tables:</p> |
|---|
| 403 | <pre class="literal-block"> |
|---|
| 404 | ===== ===== ======= |
|---|
| 405 | A B A and B |
|---|
| 406 | ===== ===== ======= |
|---|
| 407 | False False False |
|---|
| 408 | True False False |
|---|
| 409 | False True False |
|---|
| 410 | True True True |
|---|
| 411 | ===== ===== ======= |
|---|
| 412 | </pre> |
|---|
| 413 | <p>There must be at least two columns in a table (to differentiate from |
|---|
| 414 | section titles). Column spans use underlines of hyphens ("Inputs" |
|---|
| 415 | spans the first two columns):</p> |
|---|
| 416 | <pre class="literal-block"> |
|---|
| 417 | ===== ===== ====== |
|---|
| 418 | Inputs Output |
|---|
| 419 | ------------ ------ |
|---|
| 420 | A B A or B |
|---|
| 421 | ===== ===== ====== |
|---|
| 422 | False False False |
|---|
| 423 | True False True |
|---|
| 424 | False True True |
|---|
| 425 | True True True |
|---|
| 426 | ===== ===== ====== |
|---|
| 427 | </pre> |
|---|
| 428 | <p>Text in a first-column cell starts a new row. No text in the first |
|---|
| 429 | column indicates a continuation line; the rest of the cells may |
|---|
| 430 | consist of multiple lines. For example:</p> |
|---|
| 431 | <pre class="literal-block"> |
|---|
| 432 | ===== ========================= |
|---|
| 433 | col 1 col 2 |
|---|
| 434 | ===== ========================= |
|---|
| 435 | 1 Second column of row 1. |
|---|
| 436 | 2 Second column of row 2. |
|---|
| 437 | Second line of paragraph. |
|---|
| 438 | 3 - Second column of row 3. |
|---|
| 439 | |
|---|
| 440 | - Second item in bullet |
|---|
| 441 | list (row 3, column 2). |
|---|
| 442 | ===== ========================= |
|---|
| 443 | </pre> |
|---|
| 444 | </div> |
|---|
| 445 | <div class="section" id="hyperlinks"> |
|---|
| 446 | <h2>Hyperlinks</h2> |
|---|
| 447 | <p>When referencing an external web page in the body of a BEP, you should |
|---|
| 448 | include the title of the page in the text, with either an inline |
|---|
| 449 | hyperlink reference to the URL or a footnote reference (see |
|---|
| 450 | <a class="reference internal" href="#footnotes">Footnotes</a> below). Do not include the URL in the body text of the |
|---|
| 451 | BEP.</p> |
|---|
| 452 | <p>Hyperlink references use backquotes and a trailing underscore to mark |
|---|
| 453 | up the reference text; backquotes are optional if the reference text |
|---|
| 454 | is a single word. For example:</p> |
|---|
| 455 | <pre class="literal-block"> |
|---|
| 456 | In this paragraph, we refer to the `BitTorrent web site`_. |
|---|
| 457 | </pre> |
|---|
| 458 | <p>An explicit target provides the URL. Put targets in a References |
|---|
| 459 | section at the end of the BEP, or immediately after the reference. |
|---|
| 460 | Hyperlink targets begin with two periods and a space (the "explicit |
|---|
| 461 | markup start"), followed by a leading underscore, the reference text, |
|---|
| 462 | a colon, and the URL (absolute or relative):</p> |
|---|
| 463 | <pre class="literal-block"> |
|---|
| 464 | .. _BitTorrent web site: http://www.bittorrent.org/ |
|---|
| 465 | </pre> |
|---|
| 466 | <p>The reference text and the target text must match (although the match |
|---|
| 467 | is case-insensitive and ignores differences in whitespace). Note that |
|---|
| 468 | the underscore trails the reference text but precedes the target text. |
|---|
| 469 | If you think of the underscore as a right-pointing arrow, it points |
|---|
| 470 | <em>away</em> from the reference and <em>toward</em> the target.</p> |
|---|
| 471 | <p>The same mechanism can be used for internal references. Every unique |
|---|
| 472 | section title implicitly defines an internal hyperlink target. We can |
|---|
| 473 | make a link to the Abstract section like this:</p> |
|---|
| 474 | <pre class="literal-block"> |
|---|
| 475 | Here is a hyperlink reference to the `Abstract`_ section. The |
|---|
| 476 | backquotes are optional since the reference text is a single word; |
|---|
| 477 | we can also just write: Abstract_. |
|---|
| 478 | </pre> |
|---|
| 479 | <p>Footnotes containing the URLs from external targets will be generated |
|---|
| 480 | automatically at the end of the References section of the BEP, along |
|---|
| 481 | with footnote references linking the reference text to the footnotes.</p> |
|---|
| 482 | <p>Text of the form "BEP x" or "RFC x" (where "x" is a number) will be |
|---|
| 483 | linked automatically to the appropriate URLs.</p> |
|---|
| 484 | </div> |
|---|
| 485 | <div class="section" id="footnotes"> |
|---|
| 486 | <h2>Footnotes</h2> |
|---|
| 487 | <p>Footnote references consist of a left square bracket, a number, a |
|---|
| 488 | right square bracket, and a trailing underscore:</p> |
|---|
| 489 | <pre class="literal-block"> |
|---|
| 490 | This sentence ends with a footnote reference [1]_. |
|---|
| 491 | </pre> |
|---|
| 492 | <p>Whitespace must precede the footnote reference. Leave a space between |
|---|
| 493 | the footnote reference and the preceding word.</p> |
|---|
| 494 | <p>When referring to another BEP, include the BEP number in the body |
|---|
| 495 | text, such as "BEP 1". The title may optionally appear. Add a |
|---|
| 496 | footnote reference following the title. For example:</p> |
|---|
| 497 | <pre class="literal-block"> |
|---|
| 498 | Refer to BEP 1 [2]_ for more information. |
|---|
| 499 | </pre> |
|---|
| 500 | <p>Add a footnote that includes the BEP's title and author. It may |
|---|
| 501 | optionally include the explicit URL on a separate line, but only in |
|---|
| 502 | the References section. Footnotes begin with ".. " (the explicit |
|---|
| 503 | markup start), followed by the footnote marker (no underscores), |
|---|
| 504 | followed by the footnote body. For example:</p> |
|---|
| 505 | <pre class="literal-block"> |
|---|
| 506 | References |
|---|
| 507 | ========== |
|---|
| 508 | |
|---|
| 509 | .. [2] BEP 1, "BEP Purpose and Guidelines", Harrison |
|---|
| 510 | (http://www.bittorrent.org/beps/bep_0001.html) |
|---|
| 511 | </pre> |
|---|
| 512 | <p>If you decide to provide an explicit URL for a BEP, please use this as |
|---|
| 513 | the URL template:</p> |
|---|
| 514 | <pre class="literal-block"> |
|---|
| 515 | http://www.bittorrent.org/beps/bep_xxxx |
|---|
| 516 | </pre> |
|---|
| 517 | <p>BEP numbers in URLs must be padded with zeros from the left, so as to |
|---|
| 518 | be exactly 4 characters wide, however BEP numbers in the text are |
|---|
| 519 | never padded.</p> |
|---|
| 520 | <p>During the course of developing your BEP, you may have to add, remove, |
|---|
| 521 | and rearrange footnote references, possibly resulting in mismatched |
|---|
| 522 | references, obsolete footnotes, and confusion. Auto-numbered |
|---|
| 523 | footnotes allow more freedom. Instead of a number, use a label of the |
|---|
| 524 | form "#word", where "word" is a mnemonic consisting of alphanumerics |
|---|
| 525 | plus internal hyphens, underscores, and periods (no whitespace or |
|---|
| 526 | other characters are allowed). For example:</p> |
|---|
| 527 | <pre class="literal-block"> |
|---|
| 528 | Refer to BEP 1 [#BEP-1]_ for more information. |
|---|
| 529 | |
|---|
| 530 | References |
|---|
| 531 | ========== |
|---|
| 532 | |
|---|
| 533 | .. [#BEP-1] BEP 1, "BEP Purpose and Guidelines", Harrison |
|---|
| 534 | |
|---|
| 535 | http://www.bittorrent.org/beps/bep-0001 |
|---|
| 536 | </pre> |
|---|
| 537 | <p>Footnotes and footnote references will be numbered automatically, and |
|---|
| 538 | the numbers will always match. Once a BEP is finalized, auto-numbered |
|---|
| 539 | labels should be replaced by numbers for simplicity.</p> |
|---|
| 540 | </div> |
|---|
| 541 | <div class="section" id="images"> |
|---|
| 542 | <h2>Images</h2> |
|---|
| 543 | <p>If your BEP contains a diagram, you may include it in the processed |
|---|
| 544 | output using the "image" directive:</p> |
|---|
| 545 | <pre class="literal-block"> |
|---|
| 546 | .. image:: diagram.png |
|---|
| 547 | |
|---|