[whatwg] Question about the bookmark in the adoption agency algorithm

[David Flanagan]

I'm trying to implement the HTML parser's adoption agency algorithm and 
am puzzled by this step:
> Let a bookmark note the position of the formatting element in the list 
> of active formatting elements 
> <http://www.whatwg.org/specs/web-apps/current-work/multipage/parsing.html#list-of-active-formatting-elements> 
> relative to the elements on either side of it in the list.
The metaphor of a bookmark is such that it marks a position between two 
pages (or list elements in this case), and I'm having trouble with the 
phrase "the elements on either side of it": I don't understand how this 
bookmark can mark the position of one element relative to both the 
element before and the element after.  That would require two 
bookmarks!  My guess, from the other steps that involve the bookmark is 
that it is supposed to mark the position after the formatting element, 
but I'm hoping that someone can confirm that for me.

The second time the bookmark is mentioned it is to be moved " 
immediately after the new node".  This is a bookmark position that I can 
understand. And the final time the bookmark is mentioned, it is to " 
insert the new element into the list...at the position of the 
aforementioned bookmark." Like a cursor in text, a bookmark works as an 
insertion position, so I get this part.

I think that the first mention of the bookmark in the spec should be 
clarified so that it is clear whether the bookmark marks the position 
before the formatting element or the position after the formatting element.

Finally, I assume that the reason this algorithm uses a bookmark 
metaphor in the first place is that simply storing a numeric index into 
the list is not sufficient--that intervening insertions or deletions 
would make maintaining that index overly complicated.  I'm guessing, 
therefore that the most straightforward implemenation of the algorithm 
is to actually insert a special-purpose bookmark object onto the list 
(like the scope markers in the stack).  Anyone who has implemented it 
care to comment?

Thanks!

     David