[Python-checkins] CVS: python/dist/src/Doc/doc doc.tex,1.21,1.22

Wed, 5 Jul 2000 22:24:44 -0700

Update of /cvsroot/python/python/dist/src/Doc/doc
In directory slayer.i.sourceforge.net:/tmp/cvs-serv14329/doc
Modified Files:
	doc.tex 
Log Message:
Added some further description to the usage of the seealso environment.
Documented the \seerfc and \seeurl macros used in that environment as well.
Index: doc.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/doc/doc.tex,v
retrieving revision 1.21
retrieving revision 1.22
diff -C2 -r1.21 -r1.22
*** doc.tex	2000年06月30日 15:54:18	1.21
--- doc.tex	2000年07月06日 05:24:41	1.22
***************
*** 752,755 ****
--- 752,760 ----
 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
***************
*** 757,760 ****
--- 762,770 ----
 \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
***************
*** 767,774 ****
 \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.
 \end{macrodesc}

--- 777,803 ----
 \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. 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}