Learning the vi Editor/Vim/Vim Touch

< Learning the vi Editor < Vim
For general information about, and history of Vim, see its corresponding article in Wikipedia.
Screenshot of Vim Touch. The Slate theme is used, with command bar seen at the bottom.

Vim Touch (also VimTouch) is a powerful text editor based on Vim ported to the Android operating system, which OS runs on more than one billion individual devices, of which most of them are mobile phones.

This tutorial is about how to use Vim Touch, the useful commands one might immediately need, user interface walkthroughs and certain use case scenarios that are specific to Vim Touch on mobile devices.

The tutorial should be helpful to people who are beginners to Vim, but expects some familiarity with it, such as users, who already know the basics, but would prefer to skip most lists of commands. Although useful, seeing whole lists of Vim commands can be overwhelming to beginners who would want to do work with Vim right away.

So, one could also consider this a primer or a small handbook.

Usage notes and Prerequisites

Some computer proficiency is required, as this tutorial won't cover all use cases.

An additional option to learn Vim and its common commands on the fly — is to install gVim on a PC. gVim (graphical Vim) runs in a graphical environment, and is available for most computer operating systems. In graphical Linux or BSD distributions, gVim might already be installed.
gVim shows a traditional menu bar with menus containing the most common commands and their corresponding keyboard shortcuts. gVim would thus serve like a live visual aid.

Commands in Vim are case-sensitive, such that gj and gJ do different things. This means, that if a command or a part of it is shown in uppercase, use of the Shift key should be assumed by default. In command mode, the same character can mean different things for regular commands, and colon-based commands.

Commands native to Vim will work there, too.

Availability

Vim Touch is available from Google Play Store and the F-Droid app repository of free and open source (FOSS) apps. F-Droid has its own 'store' app to download FOSS apps from its repository, as well as from other repos that use infrastructure based on F-Droid.

The recommended virtual keyboard app for use with Vim Touch is Hacker's Keyboard, as it contains all the necessary keys on display on the first keyboard screen — keys, that are absent from the main screen of traditional Android keyboards. The Hacker's Keyboard app is also available from the F-Droid repository.

For heavy-duty work, a Bluetooth keyboard is recommended.

Specifics of Vim Touch

As a text-based app, VimTouch utilises text commands and heavy use of the keyboard. VimTouch improves on this by having its own menus, touch-based movement across the screen, and a customisable command bar for frequently-used commands.

Unlike most text editors in Android, Vim Touch starts as a service. This has many advantages, as it prevents a situation, where a user would have to frequently save their file in a basic text editor and start the app again, if they are multitasking in another app, and the basic text editor has quit in the meantime. That often happens in devices with insufficient RAM memory.

App menu and command bar

Pressing the hardware or virtual menu key on the phone invokes the app menu, which contains some of the following:

The sliding command bar is useful both for frequently-used commands, and for commands that require several keystrokes. The command bar is pre-filled by default, but can be changed according to user preferences.

For example, people using non-US keyboard layouts are likely to populate the command bar with commands using characters that require frequent use of the Shift key.

How to quit Vim Touch

Otherwise, it is usual for text-based Unix and Linux programs not to show instructions on how to quit them. This also includes Vim's predecessor vi, but Vim is different in this case:

At startup, Vim proper shows its version, author name and instructions to quit. If you don't see that, but want to quit the app, then —

press Esc key and type :q!

Yes, you have to type the colon : and the letter q and the exclamation mark !.

The exclamation mark is optional, and is used, if there are unsaved changes in a file, but you want to quit anyway.

Modal editing

Vim has several modes of operation: two of these being the edit mode and command mode. In the former, one edits text; and in the latter, one uses the keyboard to move through text and enter commands to manipulate text, search, replace, sort, and more.

Vim has more modes, but we'll concentrate on these two for the time being.

If you're not editing text, it's useful to switch to command mode with Esc key.

Command mode

At launch, Vim defaults to command mode. In command mode, a number of keys can be used to switch between modes, move around and manipulate text.

More important commands require writing a colon : and a command, and optionally a number of parameters after that.

Command history

Vim preserves command histories, so it's easy to go back to previous commands with the Up key and repeat or modify one or more previously-used commands, whether they were successful or not. The command history is useful on a mobile device with a virtual keyboard, as it reduces the need to type excessively.

The Up key can be pressed several times to access commands stored in reverse chronological order (newest to oldest).

/ Up — search history
: Up — general command history
:s Up — search/replace (substitution) history
:%s Up — history for substitutions performed across the whole file
:w Up — save history

If a more complex command has been used, then it's possible to get to it faster by writing the first parts of it:

Opening files

Vim Touch allows files to be opened from the app menu and the filepicker: use the device menu key, then tap 'More' for a longer list of commands. Choose one of the open commands, and from the app list, tap on 'Choose file'.

The file is then opened in a new Vim window. The user can choose to keep the empty file, or tap into its window to focus on it, and close that file/window by using the :q! menuitem.

Saving files

Although UNIX/Linux operating systems have a long-time practice of having a default home directory in the form of <root>/home/username, the Android operating system that uses the Linux kernel, uses /data/media/<userid>.

Users can create their own folder in the root directory, and /home is often the shortest and most meaningful folder name. Thus, the folder would be located in /sdcard/home (in Android 2.3). Saving in Vim Touch to that path:

:w /sdcard/home/filename.ext

• .ext may mean any file extension. For text files, it's .txt.
It's important to save a file with an extension, as it allows Android to recognise the type of file and offer a number of suggested apps — including VimTouch — that can handle such a file.
• As a mnemonic, it's convenient to save text files edited in Vim as filename.vim.txt. This would later allow seeing in the file manager, that the file was edited in Vim, and the user can then choose to open the file in Vim.
⚠ Note, that unless it's a script or a plugin for Vim, it's not recommended to save normal text files as filename.vim, because Vim handles files with a .vim extension differently.

Insert mode–or writing text

i — start writing (insert|ing) text before a character under block cursor
a — start writing (append|ing) text after a character under block cursor
I — start writing text from the beginning of a line
A — start writing text from the end of a line

The text cursor also has different behaviors. In command mode, the text cursor is a block, and in insert/append mode, the text cursor can be an I-beam. The appearance can differ from configuration to configuration, but is mostly uniform.

Legibility

For the purpose of legibility, and to compose text, set word wrapping --

:set lbr

To unset it, use

:set lbr!

Setting word wrapping increases the virtual length of a line, as it takes up more screen space.

Moving around text

Vim Touch uses the functionality of touch-enabled displays, and thus offers some features not available in regular Vim installations:

In insert/editing mode, avoid sliding fingers across the screen, since it's interpeted as input, and you might accidentally input lots of gibberish. This can be undone by escaping into command mode, and using the undo u command.

Using the keyboard

In Vim Touch, press the device menu key, and then the 'Toggle virtual keyboard' menuitem to show the keyboard.

The appearance of the keyboard reduces the Vim viewport size, and if there are more than one windows open in Vim, then this can reduce the size of the bottom-most window to just one line. The workaround to that is Ctrl+w5_ — this increases minimum window size to 5 screen lines.

w — move cursor one word forward
b — move cursor one word back
5w — move cursor five words forward
10b — move cursor ten words back

You can use any other number.

gg — go to beginning of file and the first character of the first line
G — go to end of file and the beginning of last line. (YMMV; could be the end of last line, too.)

When using Hacker's Keyboard:

Moving across long lines

In a situation, where one has very long lines of text, a small-screen device, and a virtual keyboard, then moving the cursor in the screen requires several creative approaches, because up-down navigation happens from one actual text line to another.

( — move to beginning of sentence
) — move to end of sentence

This requires the presence of a period and a space . 

3( — move the cursor three sentences up
4) — move the cursor four sentences down

In the absence of this...

Sometimes it's useful to go to the very next screen line, or several in a row. To display just these, for example. To do so, use —

gj — move cursor one screen line down
gk — move cursor one screen line up
Screen lines are sometimes called virtual lines.

Alternately, the Vim statusline (the status bar) usually shows the cursor position at column number, which is the number of characters from the beginning of a (long) line. One can remember a column number and go to it within a line:

:goto 3000 — Goes to the 3000th character in a line

Manipulating text

Visual mode—select text

Vim uses Visual mode to select text, and is invoked in command mode. Use Esc key to exit it.

v — invoke visual mode, and then use text motion keys described above to select text, such as:

v and then press b or w multiple times to select a number of words before or after the cursor.
v5w — select the next five words
v + up or down arrows on the keyboard to select several lines.

ggVG — select all

^ gg goes to beginning of file, V selects one line, G extends selection to the end of a file.

V — select the whole current line (one under cursor).

Cut, copy, paste, and delete

Vim has several ways to do those things, and internal and external copy-paste commands are compartmentalised to within Vim and outside of it. This works in command mode.

Note, that cutting and copying often requires that text is already selected in Visual mode.

x, y, p (or P) are for cutting, copying and pasting within Vim
y means 'yank'
d is for 'delete', but works as 'Cut'

Outside of that, there are key sequences to copy-paste between Vim and other apps —

"*x — cut
"*y — copy
"*p — paste — or "*P

So, yes, one indeed has to type straight double quotes ", an asterisk * and the letter corresponding to the operation. Because these commands may require pressing the Shift key in many non-US keyboard layouts, it's better to put one or two of them into the command bar in Vim Touch.

One can replace a block of text selected in visual mode by pasting atop it.

Undo and Redo

u — undo, for as many undo steps as you like.

One undo step applies to all text manipulated in insert mode. That is why, if at the moment you're not editing text, it's important to switch (or default) to command mode. This keeps undo steps more granular.

Ctrl+R — redo

Join, sort

• To join lines throughout the whole file (all lines), text must be selected first with ggVG

Search

Use the slash / to search. Vim uses regular expressions, which allow complex searching.

/searchabletext
and then press Enter to search for 'searchabletext'
:noh — switches off search result highlighting
• The movement is down, and upon reaching the last match, can continue from the top of the file.
• Upwards movement to the 'previous' match is with the Shift+n combination.
• You can use the Up key several times to get to the desired previous search, or
• type in the beginning parts of a previous search (starting with the slash character), and then press the Up key. This universally applies to search-and-replace operations, too.

Search and replace

This also uses regular expressions, and makes it possible to perform complex manipulations of text.

The simple of it:

:s/searchabletext/textthatreplacesit
• This essentially finds all matches of 'searchabletext' and replaces it with 'textthatreplacesit'
• The normal slash / serves as a separator. To search for something containing a slash, the slash must escaped with a backslash: \/
• The letter s stands for substitute
:%s/apples/oranges
Finds 'apples' and replaces them with 'oranges'.
You won't need the percent character, if the file contains only one line.
:s/\,/&^M/g
• The comma , is escaped with a backslash \ to make sure it's treated as text: \,
• The ampersand & means addition of text instead of replacing it. Depending on where text is positioned relative to the ampersand, new content is added either before or after the search result; In this case, content is added after a comma.
• ^M stands for newline, but is entered in the query as Ctr+VEnter (aka <cr>/return key)
• g after the slash / searches throughout the line to match all occurrences in the line.

Syntax highlighting

Vim is also a tool for programmers, web developers, and Wikipedia editors, as it supports syntax highlighting, which color-codes different parts of text-based formatting or code, thus allowing people to see whether the displayed code is correctly written. If a particular syntax is not supported, it can be installed as a plugin in script form.

In Vim Touch, JavaScript syntax highlighting works only to up to the 3000th character in one line. On old or basic Android devices, syntax highlighting can be slow. Some syntax highlighting can cause temporary flickering of app content.

A separately-installed syntax script (such as for mediawiki), must be located in this path in Android 2.3:

/sdcard/.vim/syntax/mediawiki.vim

If these folders are not yet present, they must be created with a file manager or in a terminal app, such as Terminal Emulator.

This article is issued from Wikibooks. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.