6.10 Reference List Markup

Many sections include a list of references to module documentation or external documents. These lists are created using the \seealso or \seealso* environments. These environments define some additional macros to support creating reference entries in a reasonable manner.

The \seealso environment is typically placed in a section just before any sub-sections. This is done to ensure that reference links related to the section are not hidden in a subsection in the hypertext renditions of the documentation. For the HTML output, it is shown as a ``side bar,'' boxed off from the main flow of the text. The \seealso* environment is different in that it should be used when a list of references is being presented as part of the primary content; it is not specially set off from the text.

\begin{seealso} \end{seealso}: This environment creates a ``See also:'' heading and defines the markup used to describe individual references.

\begin{seealso*} \end{seealso*}: This environment is used to create a list of references which form part of the main content. It is not given a special header and is not set off from the main flow of the text. It provides the same additional markup used to describe individual references.

For each of the following macros, why should be one or more complete sentences, starting with a capital letter (unless it starts with an identifier, which should not be modified), and ending with the appropriate punctuation.

These macros are only defined within the content of the \seealso and \seealso* environments.

\seelink {url}{linktext}{why}: References to specific on-line resources should be given using the \seelink macro if they don't have a meaningful title but there is some short description of what's at the end of the link. Online documents which have identifiable titles should be referenced using the \seetitle macro, using the optional parameter to that macro to provide the URL.

\seemodule [key]{name}{why}: Refer to another module. why should be a brief explanation of why the reference may be interesting. The module name is given in name, with the link key given in key if necessary. In the HTML and PDF conversions, the module name will be a hyperlink to the referred-to module. Note: The module must be documented in the same document (the corresponding \declaremodule is required).

\seepep {number}{title}{why}: Refer to an Python Enhancement Proposal (PEP). number should be the official number assigned by the PEP Editor, title should be the human-readable title of the PEP as found in the official copy of the document, and why should explain what's interesting about the PEP. This should be used to refer the reader to PEPs which specify interfaces or language features relevant to the material in the annotated section of the documentation.

\seerfc {number}{title}{why}: Refer to an IETF Request for Comments (RFC). Otherwise very similar to \seepep. This should be used to refer the reader to PEPs which specify protocols or data formats relevant to the material in the annotated section of the documentation.

\seetext {text}: Add arbitrary text text to the ``See also:'' list. This can be used to refer to off-line materials or on-line materials using the \url macro. This should consist of one or more complete sentences.

\seetitle [url]{title}{why}: Add a reference to an external document named title. If url is given, the title is made a hyperlink in the HTML version of the documentation, and displayed below the title in the typeset versions of the documentation.

\seeurl {url}{why}: References to specific on-line resources should be given using the \seeurl macro if they don't have a meaningful title. Online documents which have identifiable titles should be referenced using the \seetitle macro, using the optional parameter to that macro to provide the URL.

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