From bc3e935688b124c446854c9eebc81452b8b92d46 Mon Sep 17 00:00:00 2001
From: Marco Hinz <mh.codebro@gmail.com>
Date: Tue, 19 Jan 2016 13:20:07 +0100
Subject: [PATCH] Basics: completion

---
 CHANGELOG.md |  1 +
 README.md    | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f6a7e85..8820884 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ All notable changes to this project will be documented in this file.
 - Basics: [Folding?](README.md#folding)
 - Basics: [Macros?](README.md#macros)
 - Basics: [Ranges?](README.md#ranges)
+- Basics: [Completion?](README.md#completion)
 - Commands: [:redir](README.md#redir)
 - Tips: [Saner command-line history](README.md#saner-command-line-history)
 - Tips: [Reload a file on saving](README.md#reload-a-file-on-saving)
diff --git a/README.md b/README.md
index 7747e80..96835df 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,7 @@ added every day. Things about to be added can be found here:
 - [Registers?](#registers)
 - [Ranges?](#ranges)
 - [Marks?](#marks)
+- [Completion?](#completion)
 - [Motions? Operators? Text objects?](#motions-operators-text-objects)
 - [Autocmds?](#autocmds)
 - [Changelist? Jumplist?](#changelist-jumplist)
@@ -526,6 +527,59 @@ would get a range that denotes the visual selection.
 
 Use `:marks` to list all marks. Read everything in `:h mark-motions`.
 
+#### Completion?
+
+Vim provides many different kinds of insert mode completions. If there are
+multiple matches, a popup menu will let you navigate to the match of your
+choice.
+
+Typical kinds of completion are tags, functions from imported modules or
+libraries, file names, dictionary or simply words from the current buffer.
+
+Vim provides a mapping for each kind of completion and they all start with
+`<c-x>`:
+
+| Mapping | Kind | Related help |
+|---------|------|--------------|
+| `<c-x><c-l>` | whole lines | `:h i^x^l` |
+| `<c-x><c-n>` | keywords from current file | `:h i^x^n` |
+| `<c-x><c-k>` | keywords from `'dictionary'` option | `:h i^x^k` |
+| `<c-x><c-t>` | keywords from `'thesaurus'` option | `:h i^x^t` |
+| `<c-x><c-i>` | keywords from current and included files | `:h i^x^i` |
+| `<c-x><c-]>` | tags | `:h i^x^]` |
+| `<c-x><c-f>` | file names | `:h i^x^f` |
+| `<c-x><c-d>` | definitions or macros | `:h i^x^d` |
+| `<c-x><c-v>` | Vim commands | `:h i^x^v` |
+| `<c-x><c-u>` | user defined (as specified in `'completefunc'`) | `:h i^x^u` |
+| `<c-x><c-o>` | omni completion (as specified in `'omnifunc'`) | `:h i^x^o` |
+| `<c-x>s`     | spelling suggestions | `:h i^Xs` |
+
+People might be confused about the difference between user defined completion
+and omni completion, but technically they do the same thing. They take a
+function that inspects the current position and return a list of suggestions.
+User defined completion is defined by the user for their own personal purposes.
+(Surprise!) It could be anything. Omni completion is meant for filetype-specific
+purposes, like completing struct members or class methods, and is often set by
+filetype plugins.
+
+Vim also allows for completing multiple kinds at once by setting the
+`'complete'` option. By default that option includes quite a lot, so be sure to
+trim it to your taste. You can trigger this completion by using either `<c-n>`
+(next) and `<c-p>` (previous), which also happen to be the keys used for
+choosing entries in the popup menu. See `:h i^n` and `:h 'complete'` for more on
+this.
+
+Be sure to check out `:h 'completeopt'` for configuring the behaviour of the
+popup menu. The default is quite sane, but I prefer adding "noselect" as well.
+
+Related help:
+
+```
+:h ins-completion
+:h popupmenu-keys
+:h new-omni-completion
+```
+
 #### Motions? Operators? Text objects?
 
 **Motions** move the cursor. You all know `h`/`j`/`k`/`l`. Or `w` and `b`. Even