remove misleading and misformatted note
fix some doc problems
move variables together
more bad links