increase robustness in handling global variables, add prerequisite to documentation