5.8 Reference List Markup
Many sections include a list of references to module documentation
or external documents. These lists are created using the
\seealso environment. This environment defines 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.
- \begin{seealso}
\end{seealso}
-
This environment creates a ``See also:'' heading and defines the
markup used to describe individual references.
For each of the following macros, why should be a complete
sentence, start with a capital letter (unless it starts with an
identifier, which should not be modified), and end with the
apropriate punctuation.
- \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).
- \seerfc
{number}{title}{why}
-
Refer to an IETF Request for Comments (RFC). number
should be the official number assigned by the RFC Editor,
title should be the human-readable title of the RFC as
found in the official copy of the document, and why should
explain what's interesting about the RFC. This should be used
to refer the reader to RFCs 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.
- \seeurl
{url}{why}
-
References to specific on-line resources should be given using
the \seeurl macro. No title is associated with the
reference, but the why text may include a title marked
using the \citetitle macro.
See About this document... for information on suggesting changes.