Improve the documented advice on how to best use heapq.heapreplace().

Doc/lib/libheapq.tex

@@ -59,7 +59,11 @@ If the heap is empty, \exception{IndexError} is raised.
 This is more efficient than \function{heappop()} followed
 by  \function{heappush()}, and can be more appropriate when using
 a fixed-size heap.  Note that the value returned may be larger
-than \var{item}!  That constrains reasonable uses of this routine.
+than \var{item}!  That constrains reasonable uses of this routine
+unless written as part of a larger expression:
+\begin{verbatim}
+        result = item <= heap[0] and item  or  heapreplace(heap, item)
+\end{verbatim}
 \end{funcdesc}
 
 Example of use:

Lib/heapq.py

@@ -154,7 +154,9 @@ def heapreplace(heap, item):
     This is more efficient than heappop() followed by heappush(), and can be
     more appropriate when using a fixed-size heap.  Note that the value
     returned may be larger than item!  That constrains reasonable uses of
-    this routine.
+    this routine unless written as part of a larger expression:
+
+        result = item <= heap[0] and item  or  heapreplace(heap, item)
     """
     returnitem = heap[0]    # raises appropriate IndexError if heap is empty
     heap[0] = item

Modules/_heapqmodule.c

@@ -186,7 +186,8 @@ PyDoc_STRVAR(heapreplace_doc,
 This is more efficient than heappop() followed by heappush(), and can be\n\
 more appropriate when using a fixed-size heap.  Note that the value\n\
 returned may be larger than item!  That constrains reasonable uses of\n\
-this routine.\n");
+this routine unless written as part of a larger expression:\n\n\
+    result = item <= heap[0] and item  or  heapreplace(heap, item)\n");
 
 static PyObject *
 heapify(PyObject *self, PyObject *heap)