More documentation of behavior and upstream spec

Also refactor the private method '.escape' so that we
can better describe its function in terms of the spec.
This commit should have no effect on behavior.

We shorten the non-comment code by 10 lines in net,
while adding 26 lines of comments.