1 files changed, 104 insertions, 0 deletions
diff --git a/doc/dw-out-of-flow-floats.doc b/doc/dw-out-of-flow-floats.doc
new file mode 100644
index 00000000..ee26bc4d
--- /dev/null
+++ b/doc/dw-out-of-flow-floats.doc
@@ -0,0 +1,104 @@
+/** \page dw-out-of-flow-floats Handling Elements Out Of Flow: Floats
+
+(Note: Bases on work at <http://flpsed.org/hgweb/dillo_grows>, I plan
+to split the documentation on elements out of flow into different
+parts: general part, floats, positioned elements. In this document,
+informations about floats are collected.)
+
+
+GB lists and CB lists
+=====================
+
+Floats generated by a block which is not yet allocated are initially
+put into a list related to the *generator*:
+
+- dw::OutOfFlowMgr::TBInfo::leftFloatsGB or
+- dw::OutOfFlowMgr::TBInfo::rightFloatsGB.
+
+These lists are also called GB lists.
+
+Floats of allocated generators are put into lists related to the
+*container* (called CB lists):
+
+- dw::OutOfFlowMgr::leftFloatsCB or
+- dw::OutOfFlowMgr::rightFloatsCB.
+
+As soon as the container is allocated, all floats are moved from the
+GB lists to the CB lists (dw::OutOfFlowMgr::sizeAllocateStart →
+dw::OutOfFlowMgr::moveFromGBToCB).
+
+Here, it is important to preserve the *generation order* (for reasons,
+see below: *Sorting floats*), i. e. the order in which floats have
+been added (dw::OutOfFlowMgr::addWidgetOOF).  This may become a bit
+more complicated in a case like this:
+
+    <head>
+      <style>
+	#fl-1, #fl-2, #fl-3 { float: right }
+      </style>
+    </head>
+    <body>
+      <div id="bl-1">
+	<div id="fl-1">float 1</div>
+	<div id="bl-2">
+	  <div id="fl-2">float 2</div>
+	</div>
+	<div id="fl-3">float 3</div>
+      </div>
+    </body>
+
+The floats are generated in this order:
+
+- #fl-1 (generated by #bl-1),
+- #fl-2 (generated by #bl-2),
+- #fl-3 (generated by #bl-1).
+
+Since the floats must be moved into the CB list in this order, it
+becomes clear that the floats from one GB list cannot be moved at
+once. For this reason, each float is assigned a "mark", which is
+different from the last one as soon as the generator is *before* the
+generator of the float added before. In the example above, there are
+three generators: body, #bl-1, and #bl-2 (in this order), and floats
+are assigned these marks:
+
+- #fl-1: 0,
+- #fl-2: also 0,
+- #fl-3 is assigned 1, since its generator (#bl-1) lies before the
+   last generator (#bl-2).
+
+dw::OutOfFlowMgr::moveFromGBToCB will then iterate over all marks, so
+that the generation order is preserved.
+
+
+Sorting floats
+==============
+
+Floats are sorted, to make binary search possible, in these lists:
+
+- for each generator: dw::OutOfFlowMgr::TBInfo::leftFloatsGB and
+  dw::OutOfFlowMgr::TBInfo::rightFloatsGB;
+- for the container: dw::OutOfFlowMgr::leftFloatsCB and
+  dw::OutOfFlowMgr::rightFloatsCB.
+
+The other two lists, dw::OutOfFlowMgr::leftFloatsAll and
+dw::OutOfFlowMgr::rightFloatsAll are not sorted at all.
+
+New floats are always added to the end of either list; this order is
+called *generation order*. See also above: *GB lists and CB lists*.
+
+On the other hand, there are different sorting criteria, implemented
+by different comparators, so that different kinds of keys may be used
+for searching. These sorting criteria are equivalent to the generation
+order.
+
+dw::OutOfFlowMgr::Float::CompareSideSpanningIndex compares
+*sideSpanningIndex* (used to compare floats to those on the respective
+other side); if you look at the definition
+(dw::OutOfFlowMgr::addWidgetOOF) it becomes clear that this order is
+equivalent to the generation order.
+
+dw::OutOfFlowMgr::Float::CompareGBAndExtIndex ...
+
+dw::OutOfFlowMgr::Float::ComparePosition ...
+
+*/