9. Reading help files

ESS provides an easy-to-use facility for reading S help files from within Emacs. From within the ESS process buffer or any ESS edit buffer, typing C-c C-v (ess-display-help-on-object) will prompt you for the name of an object for which you would like documentation. Completion is provided over all objects which have help files.

If the requested object has documentation, you will be popped into a buffer (named *help(obj-name)*) containing the help file. This buffer is placed in a special `S Help' mode which disables the usual editing commands but which provides a number of keys for paging through the help file:

Help commands:
• ? (ess-describe-help-mode)
  Pops up a help buffer with a list of the commands available in S help mode.

• h (ess-display-help-on-object)
  Pop up a help buffer for a different object

  Paging commands:

• b or DEL (scroll-down)
  Move one page backwards through the help file.

• SPC (scroll-up)
  Move one page forwards through the help file.

• > (beginning-of-buffer) and < (end-of-buffer)
  Move to the beginning and end of the help file, respectively.

  Section-based motion commands:

• n (ess-skip-to-next-section) and p (ess-skip-to-previous-section)
  Move to the next and previous section header in the help file, respectively. A section header consists of a number of capitalized words, followed by a colon.

  In addition, the s key followed by one of the following letters will jump to a particular section in the help file:

  `a'

  ARGUMENTS:

  `b'

  BACKGROUND:

  `B'

  BUGS:

  `d'

  DETAILS:

  `D'

  DESCRIPTION:

  `e'

  EXAMPLES:

  `n'

  NOTE:

  `o'

  OPTIONAL ARGUMENTS:

  `r'

  REQUIRED ARGUMENTS:

  `R'

  REFERENCES:

  `s'

  SIDE EFFECTS:

  `s'

  SEE ALSO:

  `u'

  USAGE:

  `v'

  VALUE:

  `<'

  Jumps to beginning of file

  `>'

  Jumps to end of file

  `?'

  Pops up a help buffer with a list of the defined section motion keys.

  Miscellaneous:

• l (ess-eval-line-and-step)
  Evaluates the current line in the ESS process, and moves to the next line. Useful for running examples in help files.

• r (ess-eval-region)
  Send the contents of the current region to the ESS process. Useful for running examples in help files.

• / (isearch-forward)
  Same as C-s.

  Quit commands:

• q (ess-switch-to-end-of-ESS)
  Returns to the ESS process buffer in another window, leaving the help window visible.

• k (kill-buffer)
  Kills the help buffer.

• x (ess-kill-buffer-and-go)
  Return to the ESS process, killing this help buffer.

In addition, all of the ESS commands available in the edit buffers are also available in S help mode (see section 7.1 Creating or modifying S objects). Of course, the usual (non-editing) Emacs commands are available, and for convenience the digits and - act as prefix arguments.

If a help buffer already exists for an object for which help is requested, that buffer is popped to immediately; the ESS process is not consulted at all. If the contents of the help file have changed, you either need to kill the help buffer first, or pass a prefix argument (with C-u) to ess-display-help-on-object.

Help buffers are marked as temporary buffers in ESS, and are deleted when ess-quit or ess-cleanup are called.

Help buffers normally appear in another window within the current frame. If you wish help buffers to appear in their own frame (either one per help buffer, or one for all help buffers), you can customize the variable ess-help-own-frame.