items.sjbach.com

i. Integrated help

The :help command in Vim is not just for new users; it is also a great boon for experienced users. Each section and subsection of Vim’s extensive documentation includes one or more descriptive keywords. These appear in the :help command’s completion list to make it easier to find what you are looking for, even when you do not know exactly what it is.

Imagine we wish to know the syntax for ignoring character case in a regex. Typing “:help ignore<TAB>” shows:

:help ignore
/ignorecase          filetype-ignore      +wildignore
'ignorecase'         g:netrw_ignorenetrc  'eventignore'
ignore-errors        'foldignore'         'noignorecase'
efm-ignore           'wildignore'

Trial-and-error will prove /ignorecase as the help section we want. “:help case<TAB>” shows a similar list.

The equivalent in Emacs is probably C-h d, apropos-documentation. It is actually handier than :help: because the convention in Emacs Lisp is to supply docstrings for API symbols, apropos-documentation searches a larger space having a higher chance of relevancy.

Relatedly, there are C-h f, describe-function, and C-h v, describe-variable, which present full API documentation and can even jump to the definition of a given symbol. Really convenient.

ii. Reference material

When programming, no matter your skill or experience, it is imperative to have some kind of reference material. Documentation is okay, but existing code is the real blessing. Here is a place where Emacs shines. The basic core of the editor is written in C (opaquely), but the rest of its functionality is written in Emacs Lisp and is immediately available for viewing.

$ dpkg -L emacs-snapshot-el | grep '\.el\.gz$' | wc -l
1125
$ gunzip --stdout `dpkg -L emacs-snapshot-el | grep '\.el\.gz$'` | wc -l
1243201

Over one million lines-of-code in 1125 files — a treasure trove.

This is harder to measure in Vim. Its base package includes about 1000 .vim files, but the vast majority are filetype or indentation specifiers, or colour themes, none of which are generally of use to a programmer. There is an unofficial vim-scripts package in Debian-based distributions, though it too skews toward themes. Here are the numbers anyway:

$ dpkg -L vim-scripts | grep '\.vim$' | wc -l
172
$ cat `dpkg -L vim-scripts | grep '\.vim$'` | wc -l
47972

i. Key capture/filename entry

• As a convenience for input, Emacs provides simple minibuffer functions such as read-file-name and read-buffer as well as more general read-from-minibuffer and read-string, which offer a lot of customization. Capturing key presses is made easy with read-key-sequence; to respond to general user action, watch functions can be added to hook variables such as post-command-hook.
• Vim offers input() for using the command-line in a script, but it is limited. Key capture is very difficult; getchar() exists, but is incomplete. Inexplicably, there is no CharacterPress autocmd event (or anything similar). The only certain way to capture keys is to remap all of them to call a user function, then later restore all previous mappings. A bad hack.

ii. Specialized buffers

• Creating a new temporary buffer or a special-purpose buffer in Emacs can be done using with-temp-buffer and generate-new-buffer, or several other calls.
• Vim provides no standard means to create a special buffer; the documentation recommends to create a new buffer and to set these options:

  :setlocal buftype=nofile
  :setlocal bufhidden=hide
  :setlocal noswapfile

  The problem is, this new buffer will also inherit many user settings, such as wrap, number, foldcolumn, cursorline, spell, and sidescroll. There is no way — that I know of — to create a fresh, blank buffer. For correctness, all of these settings should be enumerated and explicitly turned off upon buffer creation. To make this even less satisfactory, not all buffer settings can be set per-buffer.

iii. Programmatic window cycling/traversal

Emacs has many useful functions:

• walk-windows — equivalent to mapping (window-list) through a given function.
• window-tree — returns a tree representing the window layout in the given frame.
• save-window-excursion — screw around with the current layout temporarily, without repercussion.
• Much more. And as a bonus, the minibuffer can be manipulated with standard window functions.

Similar functions in Vim:

• Like walk-windows: there is :windo, but it only works on commands, not functions, and gives up completely on any minor error.
• The closest analogue to window-tree may be winnr(), a multi-purpose function. It returns the following, depending on context:
  1. The number of the current window (to be used as an argument in other functions)
  2. The count of open windows
  3. The number of the last accessed window
• Like save-window-excursion: winrestcmd() generates a sequence of storable window commands that can be called to restore the current window configuration; but it does not always work. There are also winsaveview() and winrestview(), but they also do not always work.

iv. Buffer ordering

When enumerating buffers for some purpose, the most suitable ordering is often most-recently used (MRU). This is how Emacs acts by default with e.g. buffer-list. Vim seems to order buffers by most recently opened, or maybe it is more arbitrary. MRU is possible in Vim, but it must be tracked manually within a plugin by use of autocmds, watching these events:

• BufEnter
• BufDelete
• BufWipeout

v. Environment variable interpretation

• Emacs: getenv/setenv, process-environment, various helper functions.
• Vim:

  :let $VAR = value  " set
  :let var = $VAR    " get

  Sometimes works when setting options:

  :set term=$TERM    " works
  :set history=$NUM  " does not work

vi. Text deletion

A minor problem (or convenience) of Vim is that every scripted delete action will clobber the unnamed register and numbered registers that we use for quick cut+pastes. (Emacs folks: this could be like losing your kill ring every time you run find-file or dired.) I struggled with this for a long time before learning of Vim’s blackhole register. In general, the behaviour of Vim’s delete registers are intricate and unlikeable.

vii. Completion

• Emacs has heavy-duty completion support, from simple, high-level functions such as read-buffer and read-variable to accept values at the minibuffer, to try-completion and all-completions which can be used programmatically without action from a user.
• Vim command definitions can be specified with a special argument to include completion support at the ex command line. It is a little awkward, though. Copy/paste the following block and then type “:Finger <TAB>” in Vim for a demonstration:

  command -complete=custom,ListUsers -nargs=1 Finger !finger <args>
  fun ListUsers(A,L,P)
      return system("cut -d: -f1 /etc/ passwd")
  endfun

  See :help :command-completion for an explanation. I do not think Vim has built-in support for programmatic completion.