Hi Philip, Am Freitag, 4. Oktober 2013, 05:31:20 schrieb Philip Peitsch:
Hi all,
Just quickly brain-dumping some recommendations for how to improve the clarity and reduce terminology confusion within SelectionMover.
Some commonly repeated terms that appear badly overloaded in SelectionMover are steps, positions and points.
Add to this, the functions available are also extremely confusing both in terms of their names, and the internal code (there is a patch coming today to help with the code side).
I agree that the current object and method names make a nice jungle, well, nice for people who like rather chaotic systems. Just I have to say that the proposed use of the lingo machete will still leave me in the danger of being lost and entangled by liana and consumed by selection snakes or cursor tigers. E.g. to me (as non-native speaker obviously) steps are a more relative measure, giving a distance, while position is a more absolute measure, giving a, well, position or location. Then also the meaning of "Point", "Position" and "Step" is slightly arbitrary and will have to be learned and cannot directly derived from the terms itself. So I will forget that again and again. The only one? Perhaps because my brain is structured by my German mother tongue, but I would prefer prefixes to mark the meaning of the positions. Let's see how that can be derived from the definitions of the terms you gave:
Points ====== Raw DOM positions. This is any valid node & offset pair.
Positions ========= A set of positions as returned by the position iterator. This is a subset of points as these can be filtered at the node level via a NodeFilter.
Steps ===== A filtered subset of positions as returned by the position iterator. This is controlled using a PositionFilter.
So "Positions" depend on the type of the node filter (+ built-in EmptyTextNodeFilter). Now given the variety of possible filters the semantics of "Positions" is quite broad, and I actually see no real advantage in having an explicit general distinctive name for a set of non-raw-DOM positions. Especially as the positions are not direct subsets, but actually in different address spaces, as the "offset" property depends on the "seen" nodes, so node:x, offset:y can mean something different with a node-filtered view on the DOM. I would propose to call real DOM positions always "DomPositions" and equally prefix the node-filtered positions by whatever xmltree-view the nodefilter is used for, e.g. with "ODF" or "WebODF" (webodf-extended ODF) to "OdfPosition" or "WebOdfPosition". That way it is more clear against what nodefilter view on the raw DOM a certain position is valid. Similar for "Steps" vs. "Position". While the position-filtered set of positions is in the same address space like the position-unfiltered set, the exact meaning depends on the type of the positionfilter, so that should be indicated by a proper prefix. They are still positions in a certain (virtual) node tree, and by their object type themselves not restricted to other positions. Actually in the current code steps are always used as distance between two (filtered) positions, with the single-numeric distance estimated from the mapping of the position to the number in the iterating sequence, so actually another address system, but with 1:1 mapping (you know that, just noting for myself for the record). Now SelectionMover operates on a certain node tree, defined by the passed root node, which then is node-filtered by the CursorFilter+EmptyTextNodeFilter. And thus has a certain address space, in which the used positions (by node & offset) are valid. Which makes me wonder if there are not incompatibilities, as the users of SelectionMover only pass in a position filter and get back distances which are only valid against that position filter and the address space of the SelectionMover node tree. Seems any results from the methods of SelectionMover are only used again with SelectionMover and thus the same address space, so possibly no problem exists. Okay. One thing I am missing: what is the purpose of the CursorFilter? Why does it filter only webodf-namespaced elements? And not more, like skipping HTML elements, as odf.OdfNodeFilter does? (hm, btw, could there already be alien elements matching HTML tags be loaded from the odt file? not expected, but might need handling WRT to our extension of )
My recommendations (I'm assuming you want to hear these :) )
1. Standardise SelectionMover on Points and Steps only. Any attempts to move a cursor to a Position that is not also a Step is likely a bug. The only place where we deliberately move in non-Step increments is when trying to put the cursor back into a filtered Step. This same effect could be achieved by calling moveForwardStep(0, filter).
2. Remove or rewrite convert(Forward|Backward)StepsBetweenFilters. The current implementation will not work for arbitrary filter pairs. These should likely be re-written to return the number of filter1-steps when travelling filter2-steps in distance. I would also suggest this takes the same approach as countStepsToPosition and round the cursor back to the Point of the last filter2-step that is smaller-than or equal-to the current cursor Point.
Still undecided on these recommendations (to be blamed on my lack of experience in this field and current state of my mind, thank you, cold). As if things are not confusing enough we also use the term "position" with regard to the cursor-walkable textpositions in the linear addressing system. Not only in the op specs, but also in the API of OdtDocument etc. Seems we will get out of words #) I need some more time for this. Cheers Friedrich PS: I also think in the var names we should always explicitly talk about nodeFilter or positionFilter, because that makes a difference as I only now fully realized :) -- Friedrich W. H. Kossebau // KO GmbH http://kogmbh.com/legal/