Rough and incomplete documentation on augmented assignment, which follows

shortly. Markup also needs checking.

Doc/lib/libdis.tex

@@ -130,6 +130,11 @@ Lifts second and third stack item one position up, moves top down
 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}.
 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 @@ the stack right-to-left.
 %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}.

Doc/ref/ref2.tex

@@ -523,10 +523,14 @@ The following tokens serve as delimiters in the grammar:
 \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:

Doc/ref/ref3.tex

@@ -1054,9 +1054,10 @@ methods \method{append()}, \method{count()}, \method{index()},
 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 @@ multiplication (meaning repetition) by defining the methods
   \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}