6.5 Inline Markup

Python 2.4

previous page next page

6.5 Inline Markup

The macros described in this section are used to mark just about anything interesting in the document text. They may be used in headings (though anything involving hyperlinks should be avoided there) as well as in the body text.

\bfcode {text}: Like \code, but also makes the font bold-face.

\cdata {name}: The name of a C-language variable.

\cfunction {name}: The name of a C-language function. name should include the function name and the trailing parentheses.

\character {char}: A character when discussing the character rather than a one-byte string value. The character will be typeset as with \samp.

\citetitle [url]{title}: A title for a referenced publication. If url is specified, the title will be made into a hyperlink when formatted as HTML.

\class {name}: A class name; a dotted name may be used.

\code {text}: A short code fragment or literal constant value. Typically, it should not include any spaces since no quotation marks are added.

\constant {name}: The name of a ``defined'' constant. This may be a C-language #define or a Python variable that is not intended to be changed.

\csimplemacro {name}: The name of a ``simple'' macro. Simple macros are macros which are used for code expansion, but which do not take arguments so cannot be described as functions. This is not to be used for simple constant definitions. Examples of it's use in the Python documentation include PyObject_HEAD and Py_BEGIN_ALLOW_THREADS.

\ctype {name}: The name of a C typedef or structure. For structures defined without a typedef, use \ctype{struct struct_tag} to make it clear that the struct is required.

\deprecated {version}{what to do}: Declare whatever is being described as being deprecated starting with release version. The text given as what to do should recommend something to use instead. It should be complete sentences. The entire deprecation notice will be presented as a separate paragraph; it should either precede or succeed the description of the deprecated feature.

\dfn {term}: Mark the defining instance of term in the text. (No index entries are generated.)

\e: Produces a backslash. This is convenient in \code, \file, and similar macros, and the \alltt environment, and is only defined there. To create a backslash in ordinary text (such as the contents of the \citetitle macro), use the standard \textbackslash macro.

\email {address}: An email address. Note that this is not hyperlinked in any of the possible output formats. The domain name portion of the address should be lower case.

\emph {text}: Emphasized text; this will be presented in an italic font.

\envvar {name}: An environment variable. Index entries are generated.

\exception {name}: The name of an exception. A dotted name may be used.

\file {file or dir}: The name of a file or directory. In the PDF and PostScript outputs, single quotes and a font change are used to indicate the file name, but no quotes are used in the HTML output. Warning: The \file macro cannot be used in the content of a section title due to processing limitations.

\filenq {file or dir}: Like \file, but single quotes are never used. This can be used in conjunction with tables if a column will only contain file or directory names. Warning: The \filenq macro cannot be used in the content of a section title due to processing limitations.

\function {name}: The name of a Python function; dotted names may be used.

\infinity: The symbol for mathematical infinity: ∞. Some Web browsers are not able to render the HTML representation of this symbol properly, but support is growing.

\kbd {key sequence}: Mark a sequence of keystrokes. What form key sequence takes may depend on platform- or application-specific conventions. When there are no relevant conventions, the names of modifier keys should be spelled out, to improve accessibility for new users and non-native speakers. For example, an xemacs key sequence may be marked like \kbd{C-x C-f}, but without reference to a specific application or platform, the same sequence should be marked as \kbd{Control-x Control-f}.

\keyword {name}: The name of a keyword in a programming language.

\mailheader {name}: The name of an RFC 822-style mail header. This markup does not imply that the header is being used in an email message, but can be used to refer to any header of the same ``style.'' This is also used for headers defined by the various MIME specifications. The header name should be entered in the same way it would normally be found in practice, with the camel-casing conventions being preferred where there is more than one common usage. The colon which follows the name of the header should not be included. For example: \mailheader{Content-Type}.

\makevar {name}: The name of a make variable.

\manpage {name}{section}: A reference to a Unix manual page.

\member {name}: The name of a data attribute of an object.

\method {name}: The name of a method of an object. name should include the method name and the trailing parentheses. A dotted name may be used.

\mimetype {name}: The name of a MIME type, or a component of a MIME type (the major or minor portion, taken alone).

\module {name}: The name of a module; a dotted name may be used. This should also be used for package names.

\newsgroup {name}: The name of a Usenet newsgroup.

\note {text}: An especially important bit of information about an API that a user should be aware of when using whatever bit of API the note pertains to. This should be the last thing in the paragraph as the end of the note is not visually marked in any way. The content of text should be written in complete sentences and include all appropriate punctuation.

\pep {number}: A reference to a Python Enhancement Proposal. This generates appropriate index entries. The text "PEP number" is generated; in the HTML output, this text is a hyperlink to an online copy of the specified PEP.

\plusminus: The symbol for indicating a value that may take a positive or negative value of a specified magnitude, typically represented by a plus sign placed over a minus sign. For example: \plusminus 3%.

\program {name}: The name of an executable program. This may differ from the file name for the executable for some platforms. In particular, the .exe (or other) extension should be omitted for Windows programs.

\programopt {option}: A command-line option to an executable program. Use this only for ``short'' options, and include the leading hyphen.

\longprogramopt {option}: A long command-line option to an executable program. This should only be used for long option names which will be prefixed by two hyphens; the hyphens should not be provided as part of option.

\refmodule [key]{name}: Like \module, but create a hyperlink to the documentation for the named module. Note that the corresponding \declaremodule must be in the same document. If the \declaremodule defines a module key different from the module name, it must also be provided as key to the \refmodule macro.

\regexp {string}: Mark a regular expression.

\rfc {number}: A reference to an Internet Request for Comments. This generates appropriate index entries. The text "RFC number" is generated; in the HTML output, this text is a hyperlink to an online copy of the specified RFC.

\samp {text}: A short code sample, but possibly longer than would be given using \code. Since quotation marks are added, spaces are acceptable.

\shortversion: The ``short'' version number of the documented software, as specified using the \setshortversion macro in the preamble. For Python, the short version number for a release is the first three characters of the sys.version value. For example, versions 2.0b1 and 2.0.1 both have a short version of 2.0. This may not apply for all packages; if \setshortversion is not used, this produces an empty expansion. See also the \version macro.

\strong {text}: Strongly emphasized text; this will be presented using a bold font.

\ulink {text}{url}: A hypertext link with a target specified by a URL, but for which the link text should not be the title of the resource. For resources being referenced by name, use the \citetitle macro. Not all formatted versions support arbitrary hypertext links. Note that many characters are special to LaTeX and this macro does not always do the right thing. In particular, the tilde character ("~") is mis-handled; encoding it as a hex-sequence does work, use "%7e" in place of the tilde character.

\url {url}: A URL (or URN). The URL will be presented as text. In the HTML and PDF formatted versions, the URL will also be a hyperlink. This can be used when referring to external resources without specific titles; references to resources which have titles should be marked using the \citetitle macro. See the comments about special characters in the description of the \ulink macro for special considerations.

\var {name}: The name of a variable or formal parameter in running text.

\version: The version number of the described software, as specified using \release in the preamble. See also the \shortversion macro.

\warning {text}: An important bit of information about an API that a user should be very aware of when using whatever bit of API the warning pertains to. This should be the last thing in the paragraph as the end of the warning is not visually marked in any way. The content of text should be written in complete sentences and include all appropriate punctuation. This differs from \note in that it is recommended over \note for information regarding security.

The following two macros are used to describe information that's associated with changes from one release to another. For features which are described by a single paragraph, these are typically added as separate source lines at the end of the paragraph. When adding these to features described by multiple paragraphs, they are usually collected in a single separate paragraph after the description. When both \versionadded and \versionchanged are used, \versionadded should come first; the versions should be listed in chronological order. Both of these should come before availability statements. The location should be selected so the explanation makes sense and may vary as needed.

\versionadded [explanation]{version}: The version of Python which added the described feature to the library or C API. explanation should be a brief explanation of the change consisting of a capitalized sentence fragment; a period will be appended by the formatting process. When this applies to an entire module, it should be placed at the top of the module section before any prose.

\versionchanged [explanation]{version}: The version of Python in which the named feature was changed in some way (new parameters, changed side effects, etc.). explanation should be a brief explanation of the change consisting of a capitalized sentence fragment; a period will be appended by the formatting process. This should not generally be applied to modules.

See About this document... for information on suggesting changes.

previous page start next page