12.3 Online Help and Other Documentation

vile currently comes with a single (rather large) ASCII text file, vile.hlp. The :help command (which can be abbreviated to :h) will open a new window on that file. You can then search for information on a particular topic, using standard vi search techniques. Because it is a flat ASCII file, it is also easy to print out and read through.

In addition to the help file, vile has a number of built-in commands for displaying information about the facilities and state of the editor. Some of the most useful commands are:

:show-commands

Creates a new window that shows a complete list of all vile commands, with a brief description of each one. The information is placed in its own buffer that can be treated just like any other vile buffer. In particular, it is easy to write it out to a file for later printing.

:apropos

Shows all commands whose names contain a given substring. This is easier than just randomly searching through the help file to find information on a particular topic.

:describe-key

Prompts you for a key or key sequence, and then shows the description of that command. For instance, the x key will implement the delete-next-character function.

:describe-function

Prompts you for a function name, and then shows the description of that function. For instance, the delete-next-character function deletes a given number of characters to the right of the current cursor position.

The :apropos, :describe-function, and :describe-key commands all give the descriptive information, plus all other synonyms (since a function may have more than one name, for convenience), all other keys that are bound to it (since many key sequences may be bound to the same function), and whether the command is a "motion" or an "operator." A good example of this is the output of :describe-function next-line:

"next-line"			^J	j	#-B
  or	"down-arrow"
  or	"down-line"
  or	"forward-line"
  (motion:  move down CNT lines )

This shows all four of its names and its three key-bindings. (The sequence #-B is vile's terminal-independent representation of the up-arrow -- a complete list of those names is in the help file.)

The VILE_STARTUP_PATH environment variable can be set to a colon-separated search path for the help file.[1] The VILE_HELP_FILE environment variable can be used to override the name of the help file (typically vile.hlp).

[1] Although the help file says that this path is also used when searching for the startup file, the version 7.4 source code disagrees. It is actually the search path used for the :source command. In version 8.0, this is fixed -- the startup file and :source command use the same mechanism.

The combination of online searchable help, built-in command and key descriptions, and command completion makes the help facility straightforward to use.