summaryrefslogtreecommitdiffstats
path: root/Doc/doc/doc.tex
diff options
context:
space:
mode:
authorFred Drake <fdrake@acm.org>2000-07-06 05:24:41 (GMT)
committerFred Drake <fdrake@acm.org>2000-07-06 05:24:41 (GMT)
commit5802e4803347524813c3d34add55851450ff8ddc (patch)
tree61b25f16c403574d3586f9c05fcd918d1e6f79a1 /Doc/doc/doc.tex
parent3c62d9e65651a505072df7a760e4876d45d4814a (diff)
downloadcpython-5802e4803347524813c3d34add55851450ff8ddc.zip
cpython-5802e4803347524813c3d34add55851450ff8ddc.tar.gz
cpython-5802e4803347524813c3d34add55851450ff8ddc.tar.bz2
Added some further description to the usage of the seealso environment.
Documented the \seerfc and \seeurl macros used in that environment as well.
Diffstat (limited to 'Doc/doc/doc.tex')
-rw-r--r--Doc/doc/doc.tex31
1 files changed, 30 insertions, 1 deletions
diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex
index 4540267..6de8a7b 100644
--- a/Doc/doc/doc.tex
+++ b/Doc/doc/doc.tex
@@ -751,11 +751,21 @@ distribution, to create or maintain whole documents or sections.
additional macros to support creating reference entries in a
reasonable manner.
+ The \env{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{envdesc}{seealso}{}
This environment creates a ``See also:'' heading and defines the
markup used to describe individual references.
\end{envdesc}
+ For each of the following macros, \var{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.
+
\begin{macrodesc}{seemodule}{\op{key}\p{name}\p{why}}
Refer to another module. \var{why} should be a brief
explanation of why the reference may be interesting. The module
@@ -766,10 +776,29 @@ distribution, to create or maintain whole documents or sections.
document (the corresponding \macro{declaremodule} is required).
\end{macrodesc}
+ \begin{macrodesc}{seerfc}{\p{number}\p{title}\p{why}}
+ Refer to an IETF Request for Comments (RFC). \var{number}
+ should be the official number assigned by the RFC Editor,
+ \var{title} should be the human-readable title of the RFC as
+ found in the official copy of the document, and \var{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.
+ \end{macrodesc}
+
\begin{macrodesc}{seetext}{\p{text}}
Add arbitrary text \var{text} to the ``See also:'' list. This
can be used to refer to off-line materials or on-line materials
- using the \macro{url} macro.
+ using the \macro{url} macro. This should consist of one or more
+ complete sentences.
+ \end{macrodesc}
+
+ \begin{macrodesc}{seeurl}{\p{url}\p{why}}
+ References to specific on-line resources should be given using
+ the \macro{seeurl} macro. No title is associated with the
+ reference, but the \var{why} text may include a title marked
+ using the \macro{citetitle} macro.
\end{macrodesc}