From 97acac9a81cb16992c8f6ff856ffcbeede667eeb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Sun, 9 Sep 2018 09:45:45 +0100
Subject: [PATCH] doc/vim: improve plugin documentation

---
 doc/languages-frameworks/vim.section.md | 70 ++++++++++++++++++++++---
 1 file changed, 62 insertions(+), 8 deletions(-)

diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md
index 1d6a4fe8da8d..26aa9c25f06f 100644
--- a/doc/languages-frameworks/vim.section.md
+++ b/doc/languages-frameworks/vim.section.md
@@ -5,11 +5,16 @@ date: 2016-06-25
 ---
 # User's Guide to Vim Plugins/Addons/Bundles/Scripts in Nixpkgs
 
-You'll get a vim(-your-suffix) in PATH also loading the plugins you want.
+Both Neovim and Vim can be configured to include your favorite plugins
+and additional libraries.
+
 Loading can be deferred; see examples.
 
-Vim packages, VAM (=vim-addon-manager) and Pathogen are supported to load
-packages.
+At the moment we support three different methods for managing plugins:
+
+- Vim packages (*recommend*)
+- VAM (=vim-addon-manager)
+- Pathogen
 
 ## Custom configuration
 
@@ -25,7 +30,19 @@ vim_configurable.customize {
 }
 ```
 
-## Vim packages
+For Neovim the `configure` argument can be overridden to achieve the same:
+
+```
+neovim.override {
+  configure = {
+    customRC = ''
+      # here your custom configuration goes!
+    '';
+  };
+}
+```
+
+## Managing plugins with Vim packages
 
 To store you plugins in Vim packages the following example can be used:
 
@@ -38,13 +55,50 @@ vim_configurable.customize {
     opt = [ phpCompletion elm-vim ];
     # To automatically load a plugin when opening a filetype, add vimrc lines like:
     # autocmd FileType php :packadd phpCompletion
-  }
-};
+  };
+}
 ```
 
-## VAM
+For Neovim the syntax is
 
-### dependencies by Vim plugins
+```
+neovim.override {
+  configure = {
+    customRC = ''
+      # here your custom configuration goes!
+    '';
+    packages.myVimPackage = with pkgs.vimPlugins; {
+      # see examples below how to use custom packages
+      start = [ ];
+      opt = [ ];
+    };
+  };
+}
+```
+
+The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.nix` to make it installable:
+
+```
+{
+  packageOverrides = pkgs: with pkgs; {
+    myVim = vim_configurable.customize {
+      name = "vim-with-plugins";
+      # add here code from the example section
+    };
+    myNeovim = neovim.override {
+      configure = {
+      # add here code from the example section
+      };
+    };
+  };
+}
+```
+
+After that you can install your special grafted `myVim` or `myNeovim` packages.
+
+## Managing plugins with VAM
+
+### Handling dependencies of Vim plugins
 
 VAM introduced .json files supporting dependencies without versioning
 assuming that "using latest version" is ok most of the time.