Rough and incomplete documentation on augmented assignment, which follows
shortly. Markup also needs checking.
diff --git a/Doc/lib/libdis.tex b/Doc/lib/libdis.tex
index b89bf3d..593daca 100644
--- a/Doc/lib/libdis.tex
+++ b/Doc/lib/libdis.tex
@@ -130,6 +130,11 @@
to position three.
\end{opcodedesc}
+\begin{opcodedesc}{ROT_FOUR}{}
+Lifts second, third and forth stack item one position up, moves top down to
+position four.
+\end{opcodedesc}
+
\begin{opcodedesc}{DUP_TOP}{}
Duplicates the reference on top of the stack.
\end{opcodedesc}
@@ -209,6 +214,55 @@
Implements \code{TOS = TOS1 | TOS}.
\end{opcodedesc}
+In-place operations are like binary operations, in that they remove TOS and
+TOS1, and push the result back on the stack, but the operation is done
+in-place when TOS1 supports it, and the resulting TOS may be (but does not
+have to be) the original TOS1.
+
+\begin{opcodedesc}{INPLACE_POWER}{}
+Implements in-place \code{TOS = TOS1 ** TOS}.
+\end{opcodedesc}
+
+\begin{opcodedesc}{INPLACE_MULTIPLY}{}
+Implements in-place \code{TOS = TOS1 * TOS}.
+\end{opcodedesc}
+
+\begin{opcodedesc}{INPLACE_DIVIDE}{}
+Implements in-place \code{TOS = TOS1 / TOS}.
+\end{opcodedesc}
+
+\begin{opcodedesc}{INPLACE_MODULO}{}
+Implements in-place \code{TOS = TOS1 \%{} TOS}.
+\end{opcodedesc}
+
+\begin{opcodedesc}{INPLACE_ADD}{}
+Implements in-place \code{TOS = TOS1 + TOS}.
+\end{opcodedesc}
+
+\begin{opcodedesc}{INPLACE_SUBTRACT}{}
+Implements in-place \code{TOS = TOS1 - TOS}.
+\end{opcodedesc}
+
+\begin{opcodedesc}{INPLACE_LSHIFT}{}
+Implements in-place \code{TOS = TOS1 << TOS}.
+\end{opcodedesc}
+
+\begin{opcodedesc}{INPLACE_RSHIFT}{}
+Implements in-place \code{TOS = TOS1 >> TOS}.
+\end{opcodedesc}
+
+\begin{opcodedesc}{INPLACE_AND}{}
+Implements in-place \code{TOS = TOS1 \&\ TOS}.
+\end{opcodedesc}
+
+\begin{opcodedesc}{INPLACE_XOR}{}
+Implements in-place \code{TOS = TOS1 \^\ TOS}.
+\end{opcodedesc}
+
+\begin{opcodedesc}{INPLACE_OR}{}
+Implements in-place \code{TOS = TOS1 | TOS}.
+\end{opcodedesc}
+
The slice opcodes take up to three parameters.
\begin{opcodedesc}{SLICE+0}{}
@@ -366,6 +420,11 @@
%This opcode is obsolete.
%\end{opcodedesc}
+\begin{opcodedesc}{DUP_TOPX}{count}
+Duplicate \var{count} items, keeping them in the same order. Due to
+implementation limits, \var{count} should be between 1 and 5 inclusive.
+\end{opcodedesc}
+
\begin{opcodedesc}{STORE_ATTR}{namei}
Implements \code{TOS.name = TOS1}, where \var{namei} is the index
of name in \member{co_names}.
diff --git a/Doc/ref/ref2.tex b/Doc/ref/ref2.tex
index ba4c684..64853fb 100644
--- a/Doc/ref/ref2.tex
+++ b/Doc/ref/ref2.tex
@@ -523,10 +523,14 @@
\begin{verbatim}
( ) [ ] { }
, : . ` = ;
++= -= *= /= %= **=
+&= |= ^= >>= <<=
\end{verbatim}
The period can also occur in floating-point and imaginary literals. A
sequence of three periods has a special meaning as an ellipsis in slices.
+The second half of the list, the augmented assignment operators, serve
+lexically as delimiters, but also perform an operation.
The following printing ASCII characters have special meaning as part
of other tokens or are otherwise significant to the lexical analyzer:
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
index ec56d81..1b07296 100644
--- a/Doc/ref/ref3.tex
+++ b/Doc/ref/ref3.tex
@@ -1054,9 +1054,10 @@
and \method{sort()}, like Python standard list objects. Finally,
sequence types should implement addition (meaning concatenation) and
multiplication (meaning repetition) by defining the methods
-\method{__add__()}, \method{__radd__()}, \method{__mul__()} and
-\method{__rmul__()} described below; they should not define
-\method{__coerce__()} or other numerical operators.
+\method{__add__()}, \method{__radd__()}, \method{__iadd__()},
+\method{__mul__()}, \method{__rmul__()} and \method{__imul__()} described
+below; they should not define \method{__coerce__()} or other numerical
+operators.
\withsubitem{(mapping object method)}{
\ttindex{keys()}
\ttindex{values()}
@@ -1077,8 +1078,10 @@
\ttindex{sort()}
\ttindex{__add__()}
\ttindex{__radd__()}
+ \ttindex{__iadd__()}
\ttindex{__mul__()}
- \ttindex{__rmul__()}}
+ \ttindex{__rmul__()}
+ \ttindex{__imul__()}}
\withsubitem{(numeric object method)}{\ttindex{__coerce__()}}
\begin{methoddesc}[mapping object]{__len__}{self}