+
+\subsection{Merging lists}
+
+The following machinery merges lists representing a partial order. The
+primary use for this is in computing class precedence lists during class
+finalization. By building the input lists and choosing the tie-breaking
+@<pick> function appropriately, many different linearization algorithms can
+be implemented fairly easily using @|merge-lists| below.
+
+\begin{describe*}
+ {\dhead{cls}
+ {inconsistent-merge-error (error) \&key :candidates :present}
+ \dhead{gf}{merge-error-candidates @<error> @> @<list>}
+ \dhead{gf}{merge-error-present-function @<error> @> @<function>}}
+ The @|inconsistent-merge-error| condition class used to represent a failure
+ of the \descref{fun}{merge-lists}[function].
+
+ The @<candidates> are a list of offending items from the input lists, in
+ some order: the error is reporting that the function has failed because it
+ is not possible to order the items listed in @<candidates> in any way
+ without being inconsistent with at least one of the input lists. There is
+ no default.
+
+ The @<present> function is used to convert the input items into
+ human-readable descriptions (printed using @|princ|); the default is
+ @|identity|, which will simply print the items in a `friendly' format.
+ (Using @|prin1-to-string| would print their machine-readable escaped forms
+ instead.)
+
+ The functions @|merge-error-candidates| and @|merge-error-present-function|
+ respectively retrieve the candidates list and presentation function
+ assigned to a condition when it was created.
+\end{describe*}
+
+\begin{describe}{fun}
+ {merge-lists @<lists> \&key :pick :test :present @> @<list>}
+ Return a merge of the @<lists>, considered as partial orderings.
+
+ In more detail: @<lists> should be a list of lists. Each distinct item, as
+ determined by the @<test> function (by default, @|eql|) appears in the
+ result list exactly once. Furthermore, if, in some input list, an item $x$
+ appears earlier than a different item $y$, then $x$ will also precede $y$
+ in the output list.
+
+ If the input lists contradict each other (e.g., list $A$ has $x$ before
+ $y$, but list $B$ has $y$ before $x$), then an error of type
+ @|inconsistent-merge-error| is signalled, with the offending items attached
+ as candidates, and the function @<present> (by default, @|identity|) as the
+ presentation function.
+
+ Frequently, a collection of input lists has multiple valid merges.
+ Whenever @|merge-lists| must decide between two or more equally good
+ candidates, it calls the @<pick> function to choose one of them.
+ Specifically, it invokes @|(funcall @<pick> @<candidates>
+ @<merge-so-far>)|, where @<candidates> are the items it needs to choose
+ between, and @<merge-so-far> is the currently determined prefix of the
+ final merge. The order of items in the @<candidates> list reflects their
+ order in the input lists: item $x$ precedes item $y$ in @<candidates> if
+ any only if an occurrence of $x$ appears in an earlier input list than
+ $y$. (This completely determines the order of candidates: if two items
+ appear in the same list, then that list would have ordered them and we
+ wouldn't have to call @<pick> to break the tie.) The default @<pick>
+ function simply chooses the item appearing in the earliest list, i.e.,
+ effectively
+ \begin{prog}
+ (lambda (candidates merge-so-far) \\ \ind
+ (declare (ignore merge-so-far)) \\
+ (car candidates))
+ \end{prog}
+\end{describe}
+
+
+\subsection{Other list utilities}
+