fixing public user documentation (rebased onto dev_4_4)



This is the same as gh-520 but rebased onto dev_4_4.

----