Add docs for heapq.py.
diff --git a/Doc/lib/libheapq.tex b/Doc/lib/libheapq.tex
new file mode 100644
index 0000000..fe8c411
--- /dev/null
+++ b/Doc/lib/libheapq.tex
@@ -0,0 +1,164 @@
+\section{\module{heapq} ---
+ Heap queue algorithm}
+
+\declaremodule{standard}{heapq}
+\modulesynopsis{Heap queue algorithm (a.k.a. priority queue).}
+\sectionauthor{Guido van Rossum}{guido@python.org}
+% Implementation contributed by Kevin O'Connor
+% Theoretical explanation by François Pinard
+
+
+This module provides an implementation of the heap queue algorithm,
+also known as the priority queue algorithm.
+\versionadded{2.3}
+
+Heaps are arrays for which
+\code{\var{heap}[\var{k}] <= \var{heap}[2*\var{k}+1]} and
+\code{\var{heap}[\var{k}] <= \var{heap}[2*\var{k}+2]}
+for all \var{k}, counting elements from zero. For the sake of
+comparison, non-existing elements are considered to be infinite. The
+interesting property of a heap is that \code{\var{heap}[0]} is always
+its smallest element.
+
+The API below differs from textbook heap algorithms in two aspects:
+(a) We use zero-based indexing. This makes the relationship between the
+index for a node and the indexes for its children slightly less
+obvious, but is more suitable since Python uses zero-based indexing.
+(b) Our pop method returns the smallest item, not the largest.
+
+These two make it possible to view the heap as a regular Python list
+without surprises: \code{\var{heap}[0]} is the smallest item, and
+\code{\var{heap}.sort()} maintains the heap invariant!
+
+To create a heap, use a list initialized to \code{[]}.
+
+The following functions are provided:
+
+\begin{funcdesc}{heappush}{heap, item}
+Push the value \var{item} onto the \var{heap}, maintaining the
+heap invariant.
+\end{funcdesc}
+
+\begin{funcdesc}{heappop}{heap}
+Pop and return the smallest item from the \var{heap}, maintaining the
+heap invariant.
+\end{funcdesc}
+
+Example of use:
+
+\begin{verbatim}
+>>> from heapq import heappush, heappop
+>>> heap = []
+>>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
+>>> for item in data:
+... heappush(heap, item)
+...
+>>> sorted = []
+>>> while heap:
+... sorted.append(heappop(heap))
+...
+>>> print sorted
+[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+>>> data.sort()
+>>> print data == sorted
+True
+>>>
+\end{verbatim}
+
+
+\subsection{Theory}
+
+(This explanation is due to François Pinard. The Python
+code for this module was contributed by Kevin O'Connor.)
+
+Heaps are arrays for which \code{a[\var{k}] <= a[2*\var{k}+1]} and
+\code{a[\var{k}] <= a[2*\var{k}+2]}
+for all \var{k}, counting elements from 0. For the sake of comparison,
+non-existing elements are considered to be infinite. The interesting
+property of a heap is that \code{a[0]} is always its smallest element.
+
+The strange invariant above is meant to be an efficient memory
+representation for a tournament. The numbers below are \var{k}, not
+\code{a[\var{k}]}:
+
+\begin{verbatim}
+ 0
+
+ 1 2
+
+ 3 4 5 6
+
+ 7 8 9 10 11 12 13 14
+
+ 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
+\end{verbatim}
+
+In the tree above, each cell \var{k} is topping \code{2*\var{k}+1} and
+\code{2*\var{k}+2}.
+In an usual binary tournament we see in sports, each cell is the winner
+over the two cells it tops, and we can trace the winner down the tree
+to see all opponents s/he had. However, in many computer applications
+of such tournaments, we do not need to trace the history of a winner.
+To be more memory efficient, when a winner is promoted, we try to
+replace it by something else at a lower level, and the rule becomes
+that a cell and the two cells it tops contain three different items,
+but the top cell "wins" over the two topped cells.
+
+If this heap invariant is protected at all time, index 0 is clearly
+the overall winner. The simplest algorithmic way to remove it and
+find the "next" winner is to move some loser (let's say cell 30 in the
+diagram above) into the 0 position, and then percolate this new 0 down
+the tree, exchanging values, until the invariant is re-established.
+This is clearly logarithmic on the total number of items in the tree.
+By iterating over all items, you get an O(n log n) sort.
+
+A nice feature of this sort is that you can efficiently insert new
+items while the sort is going on, provided that the inserted items are
+not "better" than the last 0'th element you extracted. This is
+especially useful in simulation contexts, where the tree holds all
+incoming events, and the "win" condition means the smallest scheduled
+time. When an event schedule other events for execution, they are
+scheduled into the future, so they can easily go into the heap. So, a
+heap is a good structure for implementing schedulers (this is what I
+used for my MIDI sequencer :-).
+
+Various structures for implementing schedulers have been extensively
+studied, and heaps are good for this, as they are reasonably speedy,
+the speed is almost constant, and the worst case is not much different
+than the average case. However, there are other representations which
+are more efficient overall, yet the worst cases might be terrible.
+
+Heaps are also very useful in big disk sorts. You most probably all
+know that a big sort implies producing "runs" (which are pre-sorted
+sequences, which size is usually related to the amount of CPU memory),
+followed by a merging passes for these runs, which merging is often
+very cleverly organised\footnote{The disk balancing algorithms which
+are current, nowadays, are
+more annoying than clever, and this is a consequence of the seeking
+capabilities of the disks. On devices which cannot seek, like big
+tape drives, the story was quite different, and one had to be very
+clever to ensure (far in advance) that each tape movement will be the
+most effective possible (that is, will best participate at
+"progressing" the merge). Some tapes were even able to read
+backwards, and this was also used to avoid the rewinding time.
+Believe me, real good tape sorts were quite spectacular to watch!
+From all times, sorting has always been a Great Art! :-)}.
+It is very important that the initial
+sort produces the longest runs possible. Tournaments are a good way
+to that. If, using all the memory available to hold a tournament, you
+replace and percolate items that happen to fit the current run, you'll
+produce runs which are twice the size of the memory for random input,
+and much better for input fuzzily ordered.
+
+Moreover, if you output the 0'th item on disk and get an input which
+may not fit in the current tournament (because the value "wins" over
+the last output value), it cannot fit in the heap, so the size of the
+heap decreases. The freed memory could be cleverly reused immediately
+for progressively building a second heap, which grows at exactly the
+same rate the first heap is melting. When the first heap completely
+vanishes, you switch heaps and start a new run. Clever and quite
+effective!
+
+In a word, heaps are useful memory structures to know. I use them in
+a few applications, and I think it is good to keep a `heap' module
+around. :-)