bsongen: add comments to explain the madness