update documentation and add install/update scripts

Author: Gaspar Chilingarov

CHEATSHEET.md

@@ -0,0 +1,107 @@
+
+
+# Vim-Elixir-IDE
+
+List of defined shortcuts and (some) commands and some useful native Vim
+shortcuts/commands:
+
+#### Navigation
+ **Between Files**
+ * `<Ctrl-P>` to start navigation in current project
+    * `<Ctrl-P>` to recall last fuzzy search text
+    * enter text to fuzzy filter file names
+    * `<Ctrl-z>` allows to select multiple files
+    * `<Ctrl-k>`/`<Ctrl-j>` or arrows move up/down in the list
+    * `<Ctrl-v>` opens selected files in vertical split
+    * `<Ctrl-s>` opens selected files in horizontal split
+
+ **In file**
+ * `<F1>` shows Elixir docs for function under cursor.
+ * `<Ctrl-@>` opens functions list for fuzzy search
+ * `<Leader>l` opens all lines in the file for fuzzy search
+ * `<Ctrl-]>` jump to definition of function/module under cursor
+ * `<Ctrl-T>` return from previous jump
+ * `<Leader>;;` search word under cursor, show match list and propmt to jump
+ * `<Ctrl-Enter>` same as above, but only in GVim
+ * `%` jumps to matching do/end tag, brackets, braces, etc. Also can be used
+   after `<Ctrl-V>` or `v` to select function/text block.
+
+ Use Vim marks `:help marks` to navigate quickly between several positions in
+ file or between files.
+
+ * `ma` .. `mz` set mark which is available only in current file
+ * `mA` .. `mZ` set global mark which is available across files.
+ * ```a`` .. ```z`` jumps between marks in current file (so many files may have `ma` mark)
+ * ```A`` .. ```Z`` jumps between global marks and switches buffers if necessary.
+ * ```.`` jumps to last edited position
+ * ```````` jumps to position before last jump (basically jumps between 2 positions)
+
+ **In file using Tagbar**
+
+ * `<F4>` opens/closes Tagbar window.
+ * `<Enter>` or click on function name takes you to function definition.
+ * `<p>` on function name takes you to function definition, but focus stays in tagbar.
+ * `<P>` on function name opens function in preview window.
+
+ More on [tagbar page](https://majutsushi.github.io/tagbar/).
+
+#### Editing
+ * `<F2>` to save current file to disk.
+ * `ZZ` to save current file and close it. In GVim it keeps editor open.
+ * `:bdd` closes current buffer, but keeps window split.
+ * `<F3>` to toggle current fold open/close.
+ * `zR` to open all folds.
+ * `zM` to close all folds.
+ * `<Ctrl-K><Ctrl-L>` highlight word under cursor in whole file.
+ 
+ * `<Ctrl-K><Ctrl-P>` toggles comment on current line/selection
+ * `<Ctrl-K><Ctrl-[>` adds comment on current line/selection
+ * `<Ctrl-K><Ctrl-]>` removes comment from current line/selection
+ *It is impossible at all to map `<Ctrl-/>` in Vim :(. So please get used to these shortcuts.*
+
+ * `<Leader>=` to align vertically `=>` map keys.
+ * `<Leader>-` to align vertically `->` function/case clauses.
+ * `<Leader>:` to align vertically `:` map or Keyword list keys.
+ * `<Leader>eq` to align vertically `=` assignment signs.
+
+ * `<Leader>$` or `<Leader>trailing` to remove trailing spaces from all lines.
+
+#### Compilation
+ * `:make` to compile changed files and show only errors
+ * `<Leader>xc` to compile changed files and show errors+warnings
+ * `<Leader>x!` to compile whole project and show errors+warnings
+ * `:cw` to open quickfix window
+ * `]e` go to next error/warning
+ * `[e` go to previous error/warning
+
+#### ExUnit
+
+ * `<Leader>xa` runs ExUnit tests on whole project
+ * `<Leader>xf` runs ExUnit tests on current file
+ * `<Leader>xl` runs ExUnit tests on current line of current file
+ * `<Leader>xx` repeats last executed command
+
+ * `<Leader>wa` runs in background ExUnit tests on whole project
+ * `<Leader>wf` runs in background ExUnit tests on current file
+ * `<Leader>wl` runs in background ExUnit tests on current file:line
+ * `<Leader>ww` runs again in background last executed command
+ * `<Leader>ws` or `<Leader>wc` stop automatic test execution on save.
+
+ * `:cw` to open quickfix window
+ * `]e` go to next error
+ * `[e` go to previous error
+
+#### Git integration
+ * `:Gstatus` - show modified files and staged status
+    * `-` (in normal mode) on file name moves between staged/unstaged mode
+    * `p` (in normal mode) on file name allows to stage/unstage only parts of the file.
+    * `d` (in normal mode) on file name opens diff between working copy and repository
+    * `:Gcommit` starts commit of staged files (use save/exit to commit, clear
+        message to abort)
+ * `:Gdiff` - shows diff between current file and repository
+
+ More on [vim-figutive page](https://github.com/tpope/vim-fugitive).
+
+#### Other
+
+ * `<Ctrl-X>` opens XTerm in current directory

README.md

@@ -8,16 +8,21 @@ avoid laborious task of finding and tuning of plugins/themes.
 ## Features
  * Navigation
   * Jump to module/function definitions
-  * Module/function/callback window for navigating in single file
+  * Module/function/callback list window for navigating in single file
   * Fuzzy search by function/module name in file
   * Fuzzy filename search in project
   * Navigation to Elixir/Erlang source code
  * Editing
-  * Line comment/uncomment
+  * Automatic folding of functions and tests
+  * Line comment/uncomment shortcuts
   * Autocompletion of module/function names
   * Autodetection of spacing format in your project (tab/spaces)
   * Removal of trailing spaces
   * Reformatting code (hashes, assignments, etc)
+ * Compile and testing
+  * Compile project from and jump to errors/warnings
+  * Run ExUnit tests and jump to errors
+  * Run ExUnit tests on source save and just to errors
  * Other
   * Colorschemes for Elixir programming
   * Git integration directly from Vim.
@@ -26,7 +31,22 @@ avoid laborious task of finding and tuning of plugins/themes.
   * Clutter free vim-airline settings
 
 
-See sections below for usage instructions and shortcuts.
+See [cheat sheet](CHEATSHEET.md) for quick overview of functionality and shortcuts offered.
+Read below for detailed usage instructions.
+
+## Motivation
+
+Finding, installing and tuning Vim plugins can be quite frustating and time
+consuming task.  Especially making sure they do not conflict with each other
+and that they use consistent shortcuts.
+
+Also it is easy to miss some useful ones in a wast variety of Vim plugins.
+Vim-Ide-Elixir offers curated set of plugins, which are tuned to seamlessly
+work together. Also some new pluging/settings provided for more comfortable
+work.
+
+Plugin updates also come in (tested) bundles, which assures that changes in one
+plugin will not break others.
 
 ## Installation
 
@@ -38,15 +58,24 @@ Following command with download plugin and all extras it uses.
 cd ~/.vim/bundle
 git clone https://github.com/gasparch/vim-ide-elixir.git vim-ide-elixir
 cd ~/.vim/bundle/vim-ide-elixir
-git submodule update --init --recursive
+./install.sh
 ```
 
+Follow instructions of install script.
+
+**Manually install**
+
 Update your `~/.vimrc` to contain following line instead of just `pathogen#infect`.
 
 ```vim
 execute pathogen#infect("bundle/{}", "bundle/vim-ide-elixir/bundle/{}")
 ```
 
+Also in the very end of the file add
+```vim
+call vimide#init()
+```
+
 ### Installing required utilities
 
 In order to properly work this plugin requires number of additional programs installed.
@@ -73,20 +102,126 @@ Run provided script to automatically check out matching Erlang/OTP and Elixir ve
 ## Updating plugin & submodules
 ```sh
 cd ~/.vim/bundle/vim-ide-elixir
-git pull
-git submodule update --remote --merge
+./update.sh
 ```
 
+## Editing
+
+Vim-Elixir-IDE tries to smart guess your tabulation settings and set it for the
+file using [vim-sleuth](https://github.com/tpope/vim-sleuth).
+
 ## Source browsing
 
-Tagbar most of the time shows correct arity on functions and does not report multiple function clauses.
-GenServer callbacks moved to separate group.
+Tagbar most of the time shows correct arity on functions and does not report
+multiple function clauses.  GenServer callbacks moved to separate group.
+
+## Compiler and ExUnit integration
+
+Compiler and ExUnit integration provided with vim-elixir-exunit module, which
+is designed to work with vim-elixir-ide.  All commands can be executed in any
+subdirectory of project, it will find closest `mix.exs` in file hierarchy.
+
+Following commands and shortcuts are available:
+
+#### Compiling project
+
+ * `:make` will invoke `mix compile` and show only errors in quickfix list.
+    Normal `:cl` `:copen` `:cnext` `:cprev` commands are available, but use of
+    `[e` and `]e` is recommended.
+ * `:cw` is redefined to show quickfix window always at bottom, even if split exists.
+ * `:MixCompile` will compile files (`mix compile`) and show errors and warnings. 
+     All messages are loaded in quickfix.
+ * `:MixCompile!` will recompile all project (`mix compile --force`) and show
+    errors and warnings.  All messages are loaded in quickfix.
+ * `<Leader>xc` and `<Leader>x!` invoke `:MixCompile` and `:MixCompile!` respectively
+ * `[e` and `]e` provide smart navigation between errors/warnings in quickfix,
+    also trying to jump to correct column name (e.g. identificator if warning is
+    'variable foo is not used').
+
+
+#### Running ExUnit
+
+ All ExUnit commands suppress warning messages in quickfix window. If you want
+ to check warnings in project - use compile commands above. ExUnit output is
+ cluttered by itself, so no need to add more information with warnings.
+
+ I recommend Vim8.x + XTerm as you can have much more with it - see below.
+
+ **Functionality for Vim version 7.x:**
+
+ * `ExUnitQfRunAll` or `<Leader>xa` runs ExUnit tests on whole project 
+    (`mix test`) and shows output in quickfix window
+ * `ExUnitQfRunFile` or `<Leader>xf` runs ExUnit tests on current file
+    (`mix test path/to/file`) and shows output in quickfix window
+ * `ExUnitQfRunLine` or `<Leader>xl` runs ExUnit tests on current line of
+    current file, effectively running just one test.
+    (`mix test path/to/file.exs:123`) and shows output in quickfix window
+ * `ExUnitQfRunRerun` or `<Leader>xx` repeats last executed command (ExUnitQfRunAll/File/Line)
+
+ You can navigate with `[e` and `]e` between errors. Both test name and exact
+ failed assert lines are available in quickfix list. Latter is more useful most of the time.
+
+ Use `:copen` or `:cw` to check quickfix window, because most relevant ExUnit
+ output is available there as well, g.e. assert failure messages, crash messages
+ and etc.
+
+ Some less relevant ExUnit output (like GenServer crash logs and etc) are
+ stripped to preserve space in quickfix window.
+
+
+ **Functionality for Vim version 8.x:**
+
+ Vim 8 brings asynchronous jobs and allows to build much more real IDE-like experience.
+
+ This mode allows you to start XTerm (or any other terminal emulator) next to
+ your Vim/GVim instance and have all output of ExUnit shown there, while also
+ having possiblity to jump over errors using quickfix. This also allows you to
+ close/reopen Vim/GVim without closing XTerm and still have output in it.
+ Basically you position it once on your screen and then you are free to run
+ open and close Vim as much times as you want.
+
+ Also this mode automatically re-runs your tests on any Elixir files saved in
+ the project, removing hassle of switching and running them by hand. 
+
+ Test run status is shown in status line, so you don't need to check it manually.
+
+ To check which test is executing now, especially if you just re-run it, see
+ XTerm window title - it shows text like 'ExUnit test/foo\_test.esx'.
+
+ If you combine that with [ex\_unit\_notifier](https://github.com/navinpeiris/ex_unit_notifier) it
+ becomes very easy to see if your tests fail or pass.
+
+ Available commands: 
+
+ * `ExUnitWatchAll` or `<Leader>wa` runs ExUnit tests on whole project 
+    (`mix test`) and shows output in xterm + quickfix window
+ * `ExUnitWatchFile` or `<Leader>wf` runs ExUnit tests on current file 
+    (`mix test path/to/file`) and shows output xterm + in quickfix window
+ * `ExUnitWatchLine` or `<Leader>wl` runs ExUnit tests on current line of
+    current file, effectively running just one test.
+    (`mix test path/to/file.exs:123`) and shows output in xterm + quickfix window
+ * `ExUnitWatchRerun` or `<Leader>ww` runs again last executed command
+   (ExUnitWatchAll/File/Line). Most probably you do not need to run it manually,
+   as it is executed on each save of Elixir file in current project.
+ * `ExUnitWatchStop` or `<Leader>ws` or `<Leader>wc` (both stop/cancel mnemonics) stops
+   automatic execution of tests on save.
+
+ Use `[e` and `]e` to navigate test errors.
+
+
+ **Note**
+
+ All `mix test` commands executed with `--seed 0` parameter which forces
+ execution from top to down of test file. If you want randomized execution
+ sequence to check hidden errors in tests - you will need to run tests
+ manually.
+
+
+ 
+
+
 
-## Shortcuts
 
-`F4` for opening Tagbar.
-`Ctrl-@` to use Ctrl-P search on function names and quick jump on them
-`<Leader>l` to fuzzy search text in file
 
 
 

ROADMAP.md

@@ -0,0 +1,75 @@
+
+This is a roadmap of features planned for Vim-Elixir-IDE.
+
+Items marked with x are done.
+
+## Installation/upgrade
+ x scripts to fetch Elixir/Erlang sources
+ x scripts to download/install powerline fonts
+ x scripts to download/install Hack font
+ * scripts to pull updates (and switch submodules automatically)
+ * make sure it is totally usable standalone, so I can attract testers
+
+## Functionality
+ * make it load w/reasonable defaults in empty vim (top)
+ * add indentLine plugin to bundle (top)
+ * add sensibleDefaults plugin
+ * setup Hack font for GUI + size changes
+
+## Editing
+
+ x compile time errors and jump to them
+ x quickfix support for ExUnit test outputs + xterm integration (crashes/test fails)
+ x test runner (test/test.watch) on project, file or current function
+ * add switching between test/source file (`test file name == source + "_test.exs")
+
+ * templates for GenServer/GenStage/etc modules (may be also snipMate)
+
+ * highlight current identificator under cursor in function
+
+ * syntax highlight for fprof dump file
+ * syntax highlight for eprof dump file
+
+ * snippets for ExUnit tests (integrate snipMate)
+ * snippets for GenServer callbacks
+ * snippets for def/depf/defmodule
+
+ * snippets for tracing fprof/eprof with some meaningful defaults
+
+ * syntax highlights for style problems (missing spaces, too much space,
+     trailing space, etc) (low)
+
+ * fold big alias/import blocks
+ * fold @moduledoc tags
+ * fold big @doc tags (while keeping @spec open!)
+ * better syntax highlight for console (desert-style) (low) 
+ * signs on left edge - syntax highlight for ExUnit test outputs (crashes/test fails) (low)
+
+ * nested level syntax highlight (like in https://github.com/bigfish/vim-js-context-coloring)
+
+## Navigation
+
+ * faster in-file navigation (ctags?) (top)
+ * clone tagbar and create cross reference browsing plugin (based on mix output)
+ * make tagbar use alchemist.vim for getting tag information from file
+
+## Syntax autofixes
+
+ * fix unused variables warnings automatically
+ * integrate with dogma
+ * integrate with credo + autocorrection of problems (spacing/indents/arguments definitions and etc)
+
+## Refactoring
+
+ * variable renaming in single function clause
+ * renaming of GenServer call atoms
+ * renaming all function clauses + callers (using xref)
+ * plugin to find large pieces of commented out code, which is not documentation
+ * build code prefix trees to find (structurally same) duplicate code blocks
+
+## Documentation
+ * based on credo - add @moduledoc tags
+ * automatic guessing of signatures from debug traces and generation of @spec
+
+## Erlang support!!!
+ * support erlang syntax highlighting/source navigation/etc