Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

clarify where \versionadded and \versionchanged should be placed when 

they are used
This commit is contained in:
Fred Drake 2004-07-13 21:04:26 +00:00
parent e45d5a3b00
commit c0ed9c4956
1 changed files with 31 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
Doc/doc/doc.tex
View File

@ -1018,29 +1018,6 @@ This \UNIX\ is also followed by a space.
\macro{shortversion} macro. \macro{shortversion} macro.
\end{macrodesc} \end{macrodesc}
\begin{macrodesc}{versionadded}{\op{explanation}\p{version}}
The version of Python which added the described feature to the
library or C API. \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. The location should
be selected so the explanation makes sense and may vary as
needed.
\end{macrodesc}
\begin{macrodesc}{versionchanged}{\op{explanation}\p{version}}
The version of Python in which the named feature was changed in
some way (new parameters, changed side effects, etc.).
\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}} \begin{macrodesc}{warning}{\p{text}}
An important bit of information about an API that a user should An important bit of information about an API that a user should
be very aware of when using whatever bit of API the warning be very aware of when using whatever bit of API the warning
@ -1052,6 +1029,37 @@ This \UNIX\ is also followed by a space.
information regarding security. information regarding security.
\end{macrodesc} \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
library or C API. \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.
When this applies to an entire module, it should be placed at
the top of the module section before any prose.
\end{macrodesc}
\begin{macrodesc}{versionchanged}{\op{explanation}\p{version}}
The version of Python in which the named feature was changed in
some way (new parameters, changed side effects, etc.).
\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}
\subsection{Miscellaneous Text Markup \label{misc-text-markup}} \subsection{Miscellaneous Text Markup \label{misc-text-markup}}