The attached patch fixes a couple of bugs (one of which could put the system into an infinite loop under some circumstances), and adds some documentation.

I hope someone can apply it to the repository, assuming it looks okay.

Robin