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