documentation: update documentation for :mode  #1009

see #588