| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="doc.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="doc.html" title='Documenting Python' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='last' href='about.html' title='About this document...' /> |
| 10 | <link rel='help' href='about.html' title='About this document...' /> |
| 11 | <link rel="next" href="misc-text-markup.html" /> |
| 12 | <link rel="prev" href="showing-examples.html" /> |
| 13 | <link rel="parent" href="special-constructs.html" /> |
| 14 | <link rel="next" href="misc-text-markup.html" /> |
| 15 | <meta name='aesop' content='information' /> |
| 16 | <title>6.5 Inline Markup </title> |
| 17 | </head> |
| 18 | <body> |
| 19 | <DIV CLASS="navigation"> |
| 20 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 21 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 22 | <tr> |
| 23 | <td class='online-navigation'><a rel="prev" title="6.4 Showing Code Examples" |
| 24 | href="showing-examples.html"><img src='../icons/previous.png' |
| 25 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 26 | <td class='online-navigation'><a rel="parent" title="6 Special Markup Constructs" |
| 27 | href="special-constructs.html"><img src='../icons/up.png' |
| 28 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 29 | <td class='online-navigation'><a rel="next" title="6.6 Miscellaneous Text Markup" |
| 30 | href="misc-text-markup.html"><img src='../icons/next.png' |
| 31 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 32 | <td align="center" width="100%">Documenting Python</td> |
| 33 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 34 | href="contents.html"><img src='../icons/contents.png' |
| 35 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 36 | <td class='online-navigation'><img src='../icons/blank.png' |
| 37 | border='0' height='32' alt='' width='32' /></td> |
| 38 | <td class='online-navigation'><img src='../icons/blank.png' |
| 39 | border='0' height='32' alt='' width='32' /></td> |
| 40 | </tr></table> |
| 41 | <div class='online-navigation'> |
| 42 | <b class="navlabel">Previous:</b> |
| 43 | <a class="sectref" rel="prev" href="showing-examples.html">6.4 Showing Code Examples</A> |
| 44 | <b class="navlabel">Up:</b> |
| 45 | <a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A> |
| 46 | <b class="navlabel">Next:</b> |
| 47 | <a class="sectref" rel="next" href="misc-text-markup.html">6.6 Miscellaneous Text Markup</A> |
| 48 | </div> |
| 49 | <hr /></div> |
| 50 | </DIV> |
| 51 | <!--End of Navigation Panel--> |
| 52 | |
| 53 | <H2><A NAME="SECTION000750000000000000000"></A><A NAME="inline-markup"></A> |
| 54 | <BR> |
| 55 | 6.5 Inline Markup |
| 56 | </H2> |
| 57 | |
| 58 | <P> |
| 59 | The macros described in this section are used to mark just about |
| 60 | anything interesting in the document text. They may be used in |
| 61 | headings (though anything involving hyperlinks should be avoided |
| 62 | there) as well as in the body text. |
| 63 | |
| 64 | <P> |
| 65 | |
| 66 | <dl class='macrodesc'> |
| 67 | <dt><b><tt class='macro'>\bfcode</tt></b> |
| 68 | <tt>{</tt><var>text</var><tt>}</tt></dt> |
| 69 | <dd> |
| 70 | Like <tt class='macro'>\code</tt>, but also makes the font bold-face. |
| 71 | </dd></dl> |
| 72 | |
| 73 | <P> |
| 74 | |
| 75 | <dl class='macrodesc'> |
| 76 | <dt><b><tt class='macro'>\cdata</tt></b> |
| 77 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 78 | <dd> |
| 79 | The name of a C-language variable. |
| 80 | </dd></dl> |
| 81 | |
| 82 | <P> |
| 83 | |
| 84 | <dl class='macrodesc'> |
| 85 | <dt><b><tt class='macro'>\cfunction</tt></b> |
| 86 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 87 | <dd> |
| 88 | The name of a C-language function. <var>name</var> should include the |
| 89 | function name and the trailing parentheses. |
| 90 | </dd></dl> |
| 91 | |
| 92 | <P> |
| 93 | |
| 94 | <dl class='macrodesc'> |
| 95 | <dt><b><tt class='macro'>\character</tt></b> |
| 96 | <tt>{</tt><var>char</var><tt>}</tt></dt> |
| 97 | <dd> |
| 98 | A character when discussing the character rather than a one-byte |
| 99 | string value. The character will be typeset as with <tt class='macro'>\samp</tt>. |
| 100 | </dd></dl> |
| 101 | |
| 102 | <P> |
| 103 | |
| 104 | <dl class='macrodesc'> |
| 105 | <dt><b><tt class='macro'>\citetitle</tt></b> |
| 106 | <tt>[</tt><var>url</var><tt>]</tt><tt>{</tt><var>title</var><tt>}</tt></dt> |
| 107 | <dd> |
| 108 | A title for a referenced publication. If <var>url</var> is specified, |
| 109 | the title will be made into a hyperlink when formatted as HTML. |
| 110 | </dd></dl> |
| 111 | |
| 112 | <P> |
| 113 | |
| 114 | <dl class='macrodesc'> |
| 115 | <dt><b><tt class='macro'>\class</tt></b> |
| 116 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 117 | <dd> |
| 118 | A class name; a dotted name may be used. |
| 119 | </dd></dl> |
| 120 | |
| 121 | <P> |
| 122 | |
| 123 | <dl class='macrodesc'> |
| 124 | <dt><b><tt class='macro'>\code</tt></b> |
| 125 | <tt>{</tt><var>text</var><tt>}</tt></dt> |
| 126 | <dd> |
| 127 | A short code fragment or literal constant value. Typically, it |
| 128 | should not include any spaces since no quotation marks are |
| 129 | added. |
| 130 | </dd></dl> |
| 131 | |
| 132 | <P> |
| 133 | |
| 134 | <dl class='macrodesc'> |
| 135 | <dt><b><tt class='macro'>\constant</tt></b> |
| 136 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 137 | <dd> |
| 138 | The name of a ``defined'' constant. This may be a C-language |
| 139 | <code>#define</code> or a Python variable that is not intended to be |
| 140 | changed. |
| 141 | </dd></dl> |
| 142 | |
| 143 | <P> |
| 144 | |
| 145 | <dl class='macrodesc'> |
| 146 | <dt><b><tt class='macro'>\csimplemacro</tt></b> |
| 147 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 148 | <dd> |
| 149 | The name of a ``simple'' macro. Simple macros are macros |
| 150 | which are used for code expansion, but which do not take |
| 151 | arguments so cannot be described as functions. This is not to |
| 152 | be used for simple constant definitions. Examples of it's use |
| 153 | in the Python documentation include |
| 154 | PyObject_HEAD and |
| 155 | Py_BEGIN_ALLOW_THREADS. |
| 156 | </dd></dl> |
| 157 | |
| 158 | <P> |
| 159 | |
| 160 | <dl class='macrodesc'> |
| 161 | <dt><b><tt class='macro'>\ctype</tt></b> |
| 162 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 163 | <dd> |
| 164 | The name of a C <tt class="keyword">typedef</tt> or structure. For structures |
| 165 | defined without a <tt class="keyword">typedef</tt>, use <code>\ctype{struct |
| 166 | struct_tag}</code> to make it clear that the <tt class="keyword">struct</tt> is |
| 167 | required. |
| 168 | </dd></dl> |
| 169 | |
| 170 | <P> |
| 171 | |
| 172 | <dl class='macrodesc'> |
| 173 | <dt><b><tt class='macro'>\deprecated</tt></b> |
| 174 | <tt>{</tt><var>version</var><tt>}</tt><tt>{</tt><var>what to do</var><tt>}</tt></dt> |
| 175 | <dd> |
| 176 | Declare whatever is being described as being deprecated starting |
| 177 | with release <var>version</var>. The text given as <var>what to do</var> |
| 178 | should recommend something to use instead. It should be |
| 179 | complete sentences. The entire deprecation notice will be |
| 180 | presented as a separate paragraph; it should either precede or |
| 181 | succeed the description of the deprecated feature. |
| 182 | </dd></dl> |
| 183 | |
| 184 | <P> |
| 185 | |
| 186 | <dl class='macrodesc'> |
| 187 | <dt><b><tt class='macro'>\dfn</tt></b> |
| 188 | <tt>{</tt><var>term</var><tt>}</tt></dt> |
| 189 | <dd> |
| 190 | Mark the defining instance of <var>term</var> in the text. (No index |
| 191 | entries are generated.) |
| 192 | </dd></dl> |
| 193 | |
| 194 | <P> |
| 195 | |
| 196 | <dl class='macrodesc'> |
| 197 | <dt><b><tt class='macro'>\e</tt></b> |
| 198 | </dt> |
| 199 | <dd> |
| 200 | Produces a backslash. This is convenient in <tt class='macro'>\code</tt>, |
| 201 | <tt class='macro'>\file</tt>, and similar macros, and the <tt class='environment'>\alltt</tt> |
| 202 | environment, and is only defined there. To |
| 203 | create a backslash in ordinary text (such as the contents of the |
| 204 | <tt class='macro'>\citetitle</tt> macro), use the standard <tt class='macro'>\textbackslash</tt> |
| 205 | macro. |
| 206 | </dd></dl> |
| 207 | |
| 208 | <P> |
| 209 | |
| 210 | <dl class='macrodesc'> |
| 211 | <dt><b><tt class='macro'>\email</tt></b> |
| 212 | <tt>{</tt><var>address</var><tt>}</tt></dt> |
| 213 | <dd> |
| 214 | An email address. Note that this is <em>not</em> hyperlinked in |
| 215 | any of the possible output formats. The domain name portion of |
| 216 | the address should be lower case. |
| 217 | </dd></dl> |
| 218 | |
| 219 | <P> |
| 220 | |
| 221 | <dl class='macrodesc'> |
| 222 | <dt><b><tt class='macro'>\emph</tt></b> |
| 223 | <tt>{</tt><var>text</var><tt>}</tt></dt> |
| 224 | <dd> |
| 225 | Emphasized text; this will be presented in an italic font. |
| 226 | </dd></dl> |
| 227 | |
| 228 | <P> |
| 229 | |
| 230 | <dl class='macrodesc'> |
| 231 | <dt><b><tt class='macro'>\envvar</tt></b> |
| 232 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 233 | <dd> |
| 234 | An environment variable. Index entries are generated. |
| 235 | </dd></dl> |
| 236 | |
| 237 | <P> |
| 238 | |
| 239 | <dl class='macrodesc'> |
| 240 | <dt><b><tt class='macro'>\exception</tt></b> |
| 241 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 242 | <dd> |
| 243 | The name of an exception. A dotted name may be used. |
| 244 | </dd></dl> |
| 245 | |
| 246 | <P> |
| 247 | |
| 248 | <dl class='macrodesc'> |
| 249 | <dt><b><tt class='macro'>\file</tt></b> |
| 250 | <tt>{</tt><var>file or dir</var><tt>}</tt></dt> |
| 251 | <dd> |
| 252 | The name of a file or directory. In the PDF and PostScript |
| 253 | outputs, single quotes and a font change are used to indicate |
| 254 | the file name, but no quotes are used in the HTML output. |
| 255 | <span class="warning"><b class="label">Warning:</b> |
| 256 | The <tt class='macro'>\file</tt> macro cannot be used in the |
| 257 | content of a section title due to processing limitations.</span> |
| 258 | </dd></dl> |
| 259 | |
| 260 | <P> |
| 261 | |
| 262 | <dl class='macrodesc'> |
| 263 | <dt><b><tt class='macro'>\filenq</tt></b> |
| 264 | <tt>{</tt><var>file or dir</var><tt>}</tt></dt> |
| 265 | <dd> |
| 266 | Like <tt class='macro'>\file</tt>, but single quotes are never used. This can |
| 267 | be used in conjunction with tables if a column will only contain |
| 268 | file or directory names. |
| 269 | <span class="warning"><b class="label">Warning:</b> |
| 270 | The <tt class='macro'>\filenq</tt> macro cannot be used in the |
| 271 | content of a section title due to processing limitations.</span> |
| 272 | </dd></dl> |
| 273 | |
| 274 | <P> |
| 275 | |
| 276 | <dl class='macrodesc'> |
| 277 | <dt><b><tt class='macro'>\function</tt></b> |
| 278 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 279 | <dd> |
| 280 | The name of a Python function; dotted names may be used. |
| 281 | </dd></dl> |
| 282 | |
| 283 | <P> |
| 284 | |
| 285 | <dl class='macrodesc'> |
| 286 | <dt><b><tt class='macro'>\infinity</tt></b> |
| 287 | </dt> |
| 288 | <dd> |
| 289 | The symbol for mathematical infinity: ∞. Some Web |
| 290 | browsers are not able to render the HTML representation of this |
| 291 | symbol properly, but support is growing. |
| 292 | </dd></dl> |
| 293 | |
| 294 | <P> |
| 295 | |
| 296 | <dl class='macrodesc'> |
| 297 | <dt><b><tt class='macro'>\kbd</tt></b> |
| 298 | <tt>{</tt><var>key sequence</var><tt>}</tt></dt> |
| 299 | <dd> |
| 300 | Mark a sequence of keystrokes. What form <var>key sequence</var> |
| 301 | takes may depend on platform- or application-specific |
| 302 | conventions. When there are no relevant conventions, the names |
| 303 | of modifier keys should be spelled out, to improve accessibility |
| 304 | for new users and non-native speakers. For example, an |
| 305 | <b class="program">xemacs</b> key sequence may be marked like |
| 306 | <code>\kbd{C-x C-f}</code>, but without reference to a specific |
| 307 | application or platform, the same sequence should be marked as |
| 308 | <code>\kbd{Control-x Control-f}</code>. |
| 309 | </dd></dl> |
| 310 | |
| 311 | <P> |
| 312 | |
| 313 | <dl class='macrodesc'> |
| 314 | <dt><b><tt class='macro'>\keyword</tt></b> |
| 315 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 316 | <dd> |
| 317 | The name of a keyword in a programming language. |
| 318 | </dd></dl> |
| 319 | |
| 320 | <P> |
| 321 | |
| 322 | <dl class='macrodesc'> |
| 323 | <dt><b><tt class='macro'>\mailheader</tt></b> |
| 324 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 325 | <dd> |
| 326 | The name of an <a class="rfc" id='rfcref-2637' xml:id='rfcref-2637' |
| 327 | href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a>-style mail header. This markup does |
| 328 | not imply that the header is being used in an email message, but |
| 329 | can be used to refer to any header of the same ``style.'' This |
| 330 | is also used for headers defined by the various MIME |
| 331 | specifications. The header name should be entered in the same |
| 332 | way it would normally be found in practice, with the |
| 333 | camel-casing conventions being preferred where there is more |
| 334 | than one common usage. The colon which follows the name of the |
| 335 | header should not be included. |
| 336 | For example: <code>\mailheader{Content-Type}</code>. |
| 337 | </dd></dl> |
| 338 | |
| 339 | <P> |
| 340 | |
| 341 | <dl class='macrodesc'> |
| 342 | <dt><b><tt class='macro'>\makevar</tt></b> |
| 343 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 344 | <dd> |
| 345 | The name of a <b class="program">make</b> variable. |
| 346 | </dd></dl> |
| 347 | |
| 348 | <P> |
| 349 | |
| 350 | <dl class='macrodesc'> |
| 351 | <dt><b><tt class='macro'>\manpage</tt></b> |
| 352 | <tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>section</var><tt>}</tt></dt> |
| 353 | <dd> |
| 354 | A reference to a <span class="Unix">Unix</span> manual page. |
| 355 | </dd></dl> |
| 356 | |
| 357 | <P> |
| 358 | |
| 359 | <dl class='macrodesc'> |
| 360 | <dt><b><tt class='macro'>\member</tt></b> |
| 361 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 362 | <dd> |
| 363 | The name of a data attribute of an object. |
| 364 | </dd></dl> |
| 365 | |
| 366 | <P> |
| 367 | |
| 368 | <dl class='macrodesc'> |
| 369 | <dt><b><tt class='macro'>\method</tt></b> |
| 370 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 371 | <dd> |
| 372 | The name of a method of an object. <var>name</var> should include the |
| 373 | method name and the trailing parentheses. A dotted name may be |
| 374 | used. |
| 375 | </dd></dl> |
| 376 | |
| 377 | <P> |
| 378 | |
| 379 | <dl class='macrodesc'> |
| 380 | <dt><b><tt class='macro'>\mimetype</tt></b> |
| 381 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 382 | <dd> |
| 383 | The name of a MIME type, or a component of a MIME type (the |
| 384 | major or minor portion, taken alone). |
| 385 | </dd></dl> |
| 386 | |
| 387 | <P> |
| 388 | |
| 389 | <dl class='macrodesc'> |
| 390 | <dt><b><tt class='macro'>\module</tt></b> |
| 391 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 392 | <dd> |
| 393 | The name of a module; a dotted name may be used. This should |
| 394 | also be used for package names. |
| 395 | </dd></dl> |
| 396 | |
| 397 | <P> |
| 398 | |
| 399 | <dl class='macrodesc'> |
| 400 | <dt><b><tt class='macro'>\newsgroup</tt></b> |
| 401 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 402 | <dd> |
| 403 | The name of a Usenet newsgroup. |
| 404 | </dd></dl> |
| 405 | |
| 406 | <P> |
| 407 | |
| 408 | <dl class='macrodesc'> |
| 409 | <dt><b><tt class='macro'>\note</tt></b> |
| 410 | <tt>{</tt><var>text</var><tt>}</tt></dt> |
| 411 | <dd> |
| 412 | An especially important bit of information about an API that a |
| 413 | user should be aware of when using whatever bit of API the |
| 414 | note pertains to. This should be the last thing in the |
| 415 | paragraph as the end of the note is not visually marked in |
| 416 | any way. The content of <var>text</var> should be written in |
| 417 | complete sentences and include all appropriate punctuation. |
| 418 | </dd></dl> |
| 419 | |
| 420 | <P> |
| 421 | |
| 422 | <dl class='macrodesc'> |
| 423 | <dt><b><tt class='macro'>\pep</tt></b> |
| 424 | <tt>{</tt><var>number</var><tt>}</tt></dt> |
| 425 | <dd> |
| 426 | A reference to a Python Enhancement Proposal. This generates |
| 427 | appropriate index entries. The text "<tt class="samp">PEP <var>number</var></tt>" is |
| 428 | generated; in the HTML output, this text is a hyperlink to an |
| 429 | online copy of the specified PEP. |
| 430 | </dd></dl> |
| 431 | |
| 432 | <P> |
| 433 | |
| 434 | <dl class='macrodesc'> |
| 435 | <dt><b><tt class='macro'>\plusminus</tt></b> |
| 436 | </dt> |
| 437 | <dd> |
| 438 | The symbol for indicating a value that may take a positive or |
| 439 | negative value of a specified magnitude, typically represented |
| 440 | by a plus sign placed over a minus sign. For example: |
| 441 | <code>\plusminus 3%</code>. |
| 442 | </dd></dl> |
| 443 | |
| 444 | <P> |
| 445 | |
| 446 | <dl class='macrodesc'> |
| 447 | <dt><b><tt class='macro'>\program</tt></b> |
| 448 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 449 | <dd> |
| 450 | The name of an executable program. This may differ from the |
| 451 | file name for the executable for some platforms. In particular, |
| 452 | the <span class="file">.exe</span> (or other) extension should be omitted for |
| 453 | Windows programs. |
| 454 | </dd></dl> |
| 455 | |
| 456 | <P> |
| 457 | |
| 458 | <dl class='macrodesc'> |
| 459 | <dt><b><tt class='macro'>\programopt</tt></b> |
| 460 | <tt>{</tt><var>option</var><tt>}</tt></dt> |
| 461 | <dd> |
| 462 | A command-line option to an executable program. Use this only |
| 463 | for ``short'' options, and include the leading hyphen. |
| 464 | </dd></dl> |
| 465 | |
| 466 | <P> |
| 467 | |
| 468 | <dl class='macrodesc'> |
| 469 | <dt><b><tt class='macro'>\longprogramopt</tt></b> |
| 470 | <tt>{</tt><var>option</var><tt>}</tt></dt> |
| 471 | <dd> |
| 472 | A long command-line option to an executable program. This |
| 473 | should only be used for long option names which will be prefixed |
| 474 | by two hyphens; the hyphens should not be provided as part of |
| 475 | <var>option</var>. |
| 476 | </dd></dl> |
| 477 | |
| 478 | <P> |
| 479 | |
| 480 | <dl class='macrodesc'> |
| 481 | <dt><b><tt class='macro'>\refmodule</tt></b> |
| 482 | <tt>[</tt><var>key</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt></dt> |
| 483 | <dd> |
| 484 | Like <tt class='macro'>\module</tt>, but create a hyperlink to the documentation |
| 485 | for the named module. Note that the corresponding |
| 486 | <tt class='macro'>\declaremodule</tt> must be in the same document. If the |
| 487 | <tt class='macro'>\declaremodule</tt> defines a module key different from the |
| 488 | module name, it must also be provided as <var>key</var> to the |
| 489 | <tt class='macro'>\refmodule</tt> macro. |
| 490 | </dd></dl> |
| 491 | |
| 492 | <P> |
| 493 | |
| 494 | <dl class='macrodesc'> |
| 495 | <dt><b><tt class='macro'>\regexp</tt></b> |
| 496 | <tt>{</tt><var>string</var><tt>}</tt></dt> |
| 497 | <dd> |
| 498 | Mark a regular expression. |
| 499 | </dd></dl> |
| 500 | |
| 501 | <P> |
| 502 | |
| 503 | <dl class='macrodesc'> |
| 504 | <dt><b><tt class='macro'>\rfc</tt></b> |
| 505 | <tt>{</tt><var>number</var><tt>}</tt></dt> |
| 506 | <dd> |
| 507 | A reference to an Internet Request for Comments. This generates |
| 508 | appropriate index entries. The text "<tt class="samp">RFC <var>number</var></tt>" is |
| 509 | generated; in the HTML output, this text is a hyperlink to an |
| 510 | online copy of the specified RFC. |
| 511 | </dd></dl> |
| 512 | |
| 513 | <P> |
| 514 | |
| 515 | <dl class='macrodesc'> |
| 516 | <dt><b><tt class='macro'>\samp</tt></b> |
| 517 | <tt>{</tt><var>text</var><tt>}</tt></dt> |
| 518 | <dd> |
| 519 | A short code sample, but possibly longer than would be given |
| 520 | using <tt class='macro'>\code</tt>. Since quotation marks are added, spaces are |
| 521 | acceptable. |
| 522 | </dd></dl> |
| 523 | |
| 524 | <P> |
| 525 | |
| 526 | <dl class='macrodesc'> |
| 527 | <dt><b><tt class='macro'>\shortversion</tt></b> |
| 528 | </dt> |
| 529 | <dd> |
| 530 | The ``short'' version number of the documented software, as |
| 531 | specified using the <tt class='macro'>\setshortversion</tt> macro in the |
| 532 | preamble. For Python, the short version number for a release is |
| 533 | the first three characters of the <code>sys.version</code> value. For |
| 534 | example, versions 2.0b1 and 2.0.1 both have a short version of |
| 535 | 2.0. This may not apply for all packages; if |
| 536 | <tt class='macro'>\setshortversion</tt> is not used, this produces an empty |
| 537 | expansion. See also the <tt class='macro'>\version</tt> macro. |
| 538 | </dd></dl> |
| 539 | |
| 540 | <P> |
| 541 | |
| 542 | <dl class='macrodesc'> |
| 543 | <dt><b><tt class='macro'>\strong</tt></b> |
| 544 | <tt>{</tt><var>text</var><tt>}</tt></dt> |
| 545 | <dd> |
| 546 | Strongly emphasized text; this will be presented using a bold |
| 547 | font. |
| 548 | </dd></dl> |
| 549 | |
| 550 | <P> |
| 551 | |
| 552 | <dl class='macrodesc'> |
| 553 | <dt><b><tt class='macro'>\ulink</tt></b> |
| 554 | <tt>{</tt><var>text</var><tt>}</tt><tt>{</tt><var>url</var><tt>}</tt></dt> |
| 555 | <dd> |
| 556 | A hypertext link with a target specified by a URL, but for which |
| 557 | the link text should not be the title of the resource. For |
| 558 | resources being referenced by name, use the <tt class='macro'>\citetitle</tt> |
| 559 | macro. Not all formatted versions support arbitrary hypertext |
| 560 | links. Note that many characters are special to <span class="LaTeX">LaTeX</span> and |
| 561 | this macro does not always do the right thing. In particular, |
| 562 | the tilde character ("<tt class="character">~</tt>") is mis-handled; encoding it |
| 563 | as a hex-sequence does work, use "<tt class="samp">%7e</tt>" in place of the |
| 564 | tilde character. |
| 565 | </dd></dl> |
| 566 | |
| 567 | <P> |
| 568 | |
| 569 | <dl class='macrodesc'> |
| 570 | <dt><b><tt class='macro'>\url</tt></b> |
| 571 | <tt>{</tt><var>url</var><tt>}</tt></dt> |
| 572 | <dd> |
| 573 | A URL (or URN). The URL will be presented as text. In the HTML |
| 574 | and PDF formatted versions, the URL will also be a hyperlink. |
| 575 | This can be used when referring to external resources without |
| 576 | specific titles; references to resources which have titles |
| 577 | should be marked using the <tt class='macro'>\citetitle</tt> macro. See the |
| 578 | comments about special characters in the description of the |
| 579 | <tt class='macro'>\ulink</tt> macro for special considerations. |
| 580 | </dd></dl> |
| 581 | |
| 582 | <P> |
| 583 | |
| 584 | <dl class='macrodesc'> |
| 585 | <dt><b><tt class='macro'>\var</tt></b> |
| 586 | <tt>{</tt><var>name</var><tt>}</tt></dt> |
| 587 | <dd> |
| 588 | The name of a variable or formal parameter in running text. |
| 589 | </dd></dl> |
| 590 | |
| 591 | <P> |
| 592 | |
| 593 | <dl class='macrodesc'> |
| 594 | <dt><b><tt class='macro'>\version</tt></b> |
| 595 | </dt> |
| 596 | <dd> |
| 597 | The version number of the described software, as specified using |
| 598 | <tt class='macro'>\release</tt> in the preamble. See also the |
| 599 | <tt class='macro'>\shortversion</tt> macro. |
| 600 | </dd></dl> |
| 601 | |
| 602 | <P> |
| 603 | |
| 604 | <dl class='macrodesc'> |
| 605 | <dt><b><tt class='macro'>\warning</tt></b> |
| 606 | <tt>{</tt><var>text</var><tt>}</tt></dt> |
| 607 | <dd> |
| 608 | An important bit of information about an API that a user should |
| 609 | be very aware of when using whatever bit of API the warning |
| 610 | pertains to. This should be the last thing in the paragraph as |
| 611 | the end of the warning is not visually marked in any way. The |
| 612 | content of <var>text</var> should be written in complete sentences |
| 613 | and include all appropriate punctuation. This differs from |
| 614 | <tt class='macro'>\note</tt> in that it is recommended over <tt class='macro'>\note</tt> for |
| 615 | information regarding security. |
| 616 | </dd></dl> |
| 617 | |
| 618 | <P> |
| 619 | The following two macros are used to describe information that's |
| 620 | associated with changes from one release to another. For features |
| 621 | which are described by a single paragraph, these are typically |
| 622 | added as separate source lines at the end of the paragraph. When |
| 623 | adding these to features described by multiple paragraphs, they |
| 624 | are usually collected in a single separate paragraph after the |
| 625 | description. When both <tt class='macro'>\versionadded</tt> and |
| 626 | <tt class='macro'>\versionchanged</tt> are used, <tt class='macro'>\versionadded</tt> should come |
| 627 | first; the versions should be listed in chronological order. Both |
| 628 | of these should come before availability statements. The location |
| 629 | should be selected so the explanation makes sense and may vary as |
| 630 | needed. |
| 631 | |
| 632 | <P> |
| 633 | |
| 634 | <dl class='macrodesc'> |
| 635 | <dt><b><tt class='macro'>\versionadded</tt></b> |
| 636 | <tt>[</tt><var>explanation</var><tt>]</tt><tt>{</tt><var>version</var><tt>}</tt></dt> |
| 637 | <dd> |
| 638 | The version of Python which added the described feature to the |
| 639 | library or C API. <var>explanation</var> should be a <em>brief</em> |
| 640 | explanation of the change consisting of a capitalized sentence |
| 641 | fragment; a period will be appended by the formatting process. |
| 642 | When this applies to an entire module, it should be placed at |
| 643 | the top of the module section before any prose. |
| 644 | </dd></dl> |
| 645 | |
| 646 | <P> |
| 647 | |
| 648 | <dl class='macrodesc'> |
| 649 | <dt><b><tt class='macro'>\versionchanged</tt></b> |
| 650 | <tt>[</tt><var>explanation</var><tt>]</tt><tt>{</tt><var>version</var><tt>}</tt></dt> |
| 651 | <dd> |
| 652 | The version of Python in which the named feature was changed in |
| 653 | some way (new parameters, changed side effects, etc.). |
| 654 | <var>explanation</var> should be a <em>brief</em> explanation of the |
| 655 | change consisting of a capitalized sentence fragment; a |
| 656 | period will be appended by the formatting process. This should |
| 657 | not generally be applied to modules. |
| 658 | </dd></dl> |
| 659 | |
| 660 | <P> |
| 661 | |
| 662 | <DIV CLASS="navigation"> |
| 663 | <div class='online-navigation'> |
| 664 | <p></p><hr /> |
| 665 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 666 | <tr> |
| 667 | <td class='online-navigation'><a rel="prev" title="6.4 Showing Code Examples" |
| 668 | href="showing-examples.html"><img src='../icons/previous.png' |
| 669 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 670 | <td class='online-navigation'><a rel="parent" title="6 Special Markup Constructs" |
| 671 | href="special-constructs.html"><img src='../icons/up.png' |
| 672 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 673 | <td class='online-navigation'><a rel="next" title="6.6 Miscellaneous Text Markup" |
| 674 | href="misc-text-markup.html"><img src='../icons/next.png' |
| 675 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 676 | <td align="center" width="100%">Documenting Python</td> |
| 677 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 678 | href="contents.html"><img src='../icons/contents.png' |
| 679 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 680 | <td class='online-navigation'><img src='../icons/blank.png' |
| 681 | border='0' height='32' alt='' width='32' /></td> |
| 682 | <td class='online-navigation'><img src='../icons/blank.png' |
| 683 | border='0' height='32' alt='' width='32' /></td> |
| 684 | </tr></table> |
| 685 | <div class='online-navigation'> |
| 686 | <b class="navlabel">Previous:</b> |
| 687 | <a class="sectref" rel="prev" href="showing-examples.html">6.4 Showing Code Examples</A> |
| 688 | <b class="navlabel">Up:</b> |
| 689 | <a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A> |
| 690 | <b class="navlabel">Next:</b> |
| 691 | <a class="sectref" rel="next" href="misc-text-markup.html">6.6 Miscellaneous Text Markup</A> |
| 692 | </div> |
| 693 | </div> |
| 694 | <hr /> |
| 695 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 696 | </DIV> |
| 697 | <!--End of Navigation Panel--> |
| 698 | <ADDRESS> |
| 699 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 700 | </ADDRESS> |
| 701 | </BODY> |
| 702 | </HTML> |