[Python-checkins] python/dist/src/Doc/doc doc.tex,1.85,1.86

Tue Jul 13 23:04:29 CEST 2004

Update of /cvsroot/python/python/dist/src/Doc/doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv11722
Modified Files:
	doc.tex 
Log Message:
clarify where \versionadded and \versionchanged should be placed when
they are used
Index: doc.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/doc/doc.tex,v
retrieving revision 1.85
retrieving revision 1.86
diff -C2 -d -r1.85 -r1.86
*** doc.tex	10 May 2004 18:39:32 -0000	1.85
--- doc.tex	13 Jul 2004 21:04:26 -0000	1.86
***************
*** 1019,1022 ****
--- 1019,1046 ----
 \end{macrodesc}

+ \begin{macrodesc}{warning}{\p{text}}
+ An important bit of information about an API that a user should
+ be very aware of when using whatever bit of API the warning
+ pertains to. This should be the last thing in the paragraph as
+ the end of the warning is not visually marked in any way. The
+ content of \var{text} should be written in complete sentences
+ and include all appropriate punctuation. This differs from
+ \macro{note} in that it is recommended over \macro{note} for
+ information regarding security.
+ \end{macrodesc}
+ 
+ The following two macros are used to describe information that's
+ associated with changes from one release to another. For features
+ which are described by a single paragraph, these are typically
+ added as separate source lines at the end of the paragraph. When
+ adding these to features described by multiple paragraphs, they
+ are usually collected in a single separate paragraph after the
+ description. When both \macro{versionadded} and
+ \macro{versionchanged} are used, \macro{versionadded} should come
+ first; the versions should be listed in chronological order. Both
+ of these should come before availability statements. The location
+ should be selected so the explanation makes sense and may vary as
+ needed.
+ 
 \begin{macrodesc}{versionadded}{\op{explanation}\p{version}}
 The version of Python which added the described feature to the
***************
*** 1024,1031 ****
 explanation of the change consisting of a capitalized sentence
 fragment; a period will be appended by the formatting process.
! This is typically added to the end of the first paragraph of the
! description before any availability notes. The location should
! be selected so the explanation makes sense and may vary as
! needed.
 \end{macrodesc}

--- 1048,1053 ----
 explanation of the change consisting of a capitalized sentence
 fragment; a period will be appended by the formatting process.
! When this applies to an entire module, it should be placed at
! the top of the module section before any prose.
 \end{macrodesc}

***************
*** 1035,1054 ****
 \var{explanation} should be a \emph{brief} explanation of the
 change consisting of a capitalized sentence fragment; a
! period will be appended by the formatting process.
! This is typically added to the end of the first paragraph of the
! description before any availability notes and after
! \macro{versionadded}. The location should be selected so the
! explanation makes sense and may vary as needed.
! \end{macrodesc}
! 
! \begin{macrodesc}{warning}{\p{text}}
! An important bit of information about an API that a user should
! be very aware of when using whatever bit of API the warning
! pertains to. This should be the last thing in the paragraph as
! the end of the warning is not visually marked in any way. The
! content of \var{text} should be written in complete sentences
! and include all appropriate punctuation. This differs from
! \macro{note} in that it is recommended over \macro{note} for
! information regarding security.
 \end{macrodesc}

--- 1057,1062 ----
 \var{explanation} should be a \emph{brief} explanation of the
 change consisting of a capitalized sentence fragment; a
! period will be appended by the formatting process. This should
! not generally be applied to modules.
 \end{macrodesc}