From c3f56e912a29dbfa965eb4061dc22045c3abbd5a Mon Sep 17 00:00:00 2001
From: Marc Weber <marco-oweber@gmx.de>
Date: Sat, 25 Jun 2016 21:36:44 +0200
Subject: [PATCH] Add nixpkgs documentation about how to create a derivation
 with Vim + plugins

---
 doc/default.nix                     |   4 ++
 doc/languages-frameworks/index.xml  |   1 +
 doc/languages-frameworks/vim.md     | 102 ++++++++++++++++++++++++++++
 pkgs/misc/vim-plugins/vim-utils.nix |   2 +
 4 files changed, 109 insertions(+)
 create mode 100644 doc/languages-frameworks/vim.md

diff --git a/doc/default.nix b/doc/default.nix
index 6a44587a31b1..791ed28369a0 100644
--- a/doc/default.nix
+++ b/doc/default.nix
@@ -64,6 +64,10 @@ stdenv.mkDerivation {
       inputFile = ./../pkgs/development/r-modules/README.md;
       outputFile = "languages-frameworks/r.xml";
     }
+  + toDocbook {
+      inputFile = ./languages-frameworks/vim.md;
+      outputFile = "./languages-frameworks/vim.xml";
+    }
   + ''
     echo ${nixpkgsVersion} > .version
 
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index 8076c33f1b3f..850da51e8207 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -27,6 +27,7 @@ such as Perl or Haskell.  These are described in this chapter.</para>
 <xi:include href="r.xml" /> <!-- generated from ../../pkgs/development/r-modules/README.md  -->
 <xi:include href="ruby.xml" />
 <xi:include href="texlive.xml" />
+<xi:include href="vim.xml" />
 
 
 </chapter>
diff --git a/doc/languages-frameworks/vim.md b/doc/languages-frameworks/vim.md
new file mode 100644
index 000000000000..d0bcf92a54f6
--- /dev/null
+++ b/doc/languages-frameworks/vim.md
@@ -0,0 +1,102 @@
+---
+title: User's Guide for Vim in Nixpkgs
+author: Peter Simons
+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.
+Loading can be deferred, see example
+
+VAM (=vim-addon-manager) and Pathogen plugin managers are supported.
+Vundle,NeoBundle could be your turn.
+
+## dependencies by Vim plugins
+
+VAM introduced .json files supporting dependencies without versioning
+assuming that "using latest version" is ok most of the time.
+
+## HOWTO
+
+First create a vim-scripts file having one plugin name per line. Example:
+
+    "tlib"
+    {'name': 'vim-addon-sql'}
+    {'filetype_regex': '\%(vim)$', 'names': ['reload', 'vim-dev-plugin']}
+
+Such vim-scripts file can be read by VAM as well like this:
+
+    call vam#Scripts(expand('~/.vim-scripts'), {})
+
+Create a default.nix file:
+
+    { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
+    nixpkgs.vim_configurable.customize { name = "vim"; vimrcConfig.vam.pluginDictionaries = [ "vim-addon-vim2nix" ]; }
+
+Create a generate.vim file:
+
+    ActivateAddons vim-addon-vim2nix
+    let vim_scripts = "vim-scripts"
+    call nix#ExportPluginsForNix({
+    \  'path_to_nixpkgs': eval('{"'.substitute(substitute(substitute($NIX_PATH, ':', ',', 'g'), '=',':', 'g'), '\([:,]\)', '"\1"',"g").'"}')["nixpkgs"],
+    \  'cache_file': '/tmp/vim2nix-cache',
+    \  'try_catch': 0,
+    \  'plugin_dictionaries': ["vim-addon-manager"]+map(readfile(vim_scripts), 'eval(v:val)')
+    \ })
+
+Then run
+
+    nix-shell -p vimUtils.vim_with_vim2nix --command "vim -c 'source generate.vim'"
+
+You should get a Vim buffer with the nix derivations (output1) and vam.pluginDictionaries (output2).
+You can add your vim to your system's configuration file like this and start it by "vim-my":
+
+    my-vim =
+     let plugins = let inherit (vimUtils) buildVimPluginFrom2Nix; in {
+          copy paste output1 here
+     }; in vim_configurable.customize {
+       name = "vim-my";
+
+       vimrcConfig.vam.knownPlugins = plugins; # optional
+       vimrcConfig.vam.pluginDictionaries = [
+          copy paste output2 here
+       ];
+
+       # Pathogen would be
+       # vimrcConfig.pathogen.knownPlugins = plugins; # plugins
+       # vimrcConfig.pathogen.pluginNames = ["tlib"];
+     };
+
+
+Sample output1:
+
+    "reload" = buildVimPluginFrom2Nix { # created by nix#NixDerivation
+      name = "reload";
+      src = fetchgit {
+        url = "git://github.com/xolox/vim-reload";
+        rev = "0a601a668727f5b675cb1ddc19f6861f3f7ab9e1";
+        sha256 = "0vb832l9yxj919f5hfg6qj6bn9ni57gnjd3bj7zpq7d4iv2s4wdh";
+      };
+      dependencies = ["nim-misc"];
+
+    };
+    [...]
+
+Sample output2:
+
+    [
+      ''vim-addon-manager''
+      ''tlib''
+      { "name" = ''vim-addon-sql''; }
+      { "filetype_regex" = ''\%(vim)$$''; "names" = [ ''reload'' ''vim-dev-plugin'' ]; }
+    ]
+
+
+## Important repositories
+
+- [vim-pi](https://bitbucket.org/vimcommunity/vim-pi) is a plugin repository
+  from VAM plugin manager meant to be used by others as well used by
+
+- [vim2nix](http://github.com/MarcWeber/vim-addon-vim2nix) which generates the
+  .nix code
+
diff --git a/pkgs/misc/vim-plugins/vim-utils.nix b/pkgs/misc/vim-plugins/vim-utils.nix
index f39d7093c73b..bc9a1fceb195 100644
--- a/pkgs/misc/vim-plugins/vim-utils.nix
+++ b/pkgs/misc/vim-plugins/vim-utils.nix
@@ -366,6 +366,8 @@ rec {
       '';
     }));
 
+  vim_with_vim2nix = vim_configurable.customize { name = "vim"; vimrcConfig.vam.pluginDictionaries = [ "vim-addon-vim2nix" ]; };
+
   buildVimPluginFrom2Nix = a: buildVimPlugin ({
     buildPhase = ":";
     configurePhase =":";