diff options
author | Fred Drake <fdrake@acm.org> | 2000-07-06 05:24:41 (GMT) |
---|---|---|
committer | Fred Drake <fdrake@acm.org> | 2000-07-06 05:24:41 (GMT) |
commit | 5802e4803347524813c3d34add55851450ff8ddc (patch) | |
tree | 61b25f16c403574d3586f9c05fcd918d1e6f79a1 /Doc/doc/doc.tex | |
parent | 3c62d9e65651a505072df7a760e4876d45d4814a (diff) | |
download | cpython-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.tex | 31 |
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} |