some well-needed documentation, working out an ugly part of the merging code