better readibility in code and tweak to docs/Makefile