documented OIL
rewrite a bit of implementation around commandline arguments which used an old version of the keyword parameter semantics. fixes #723