initial commit of hints doc and couple new macros