Add README file

README.md

@@ -0,0 +1,186 @@
+# Vim Configuration
+
+## Plugins
+
+### [YouCompleteMe][ycm]
+
+The plugin is cloned to `~/.vim/pack/minpac/opt/YouCompleteMe` recursively using
+[minpac][minpac]. Making the plugin optional can be useful when completion is
+not desired and for fast Vim loading times, when completion is desired it can be
+loaded with Vim command:
+
+```console
+$ :packadd YouCompleteMe
+```
+
+Post clone the compiled C++ components must be built before completion can be
+used, run the following command from the root of the [YouCompleteMe][ycm]
+repository:
+
+```console
+$ ./install --clang-completer
+```
+
+This uses the older `libclang.so` based completer despite [YouCompleteMe][ycm]
+recommending the use of `clangd` due to working on projects which predate the
+newer completer and the migration overhead of switching to it. To completely
+disable the `clangd` completer this must also be present in `~/.vim/vimrc`:
+
+```vim
+let g:ycm_use_clangd = 0
+```
+
+The following two options are for customising bindings for cycling through the
+completion menu when multiple completions are available.
+
+* [g:ycm_key_list_select_completion](https://github.com/ycm-core/YouCompleteMe#the-gycm_key_list_select_completion-option)
+* [g:ycm_key_list_previous_completion](https://github.com/ycm-core/YouCompleteMe#the-gycm_key_list_previous_completion-option)
+
+```vim
+let g:ycm_key_list_select_completion = ['<C-n>', '<Down>']
+let g:ycm_key_list_previous_completion = ['<C-p>', '<Up>']
+```
+
+The next options enable populating the list of potential completions beyond
+those suggested by the semantic language completer.
+
+* [g:ycm_collect_identifiers_from_comments_and_strings](https://github.com/ycm-core/YouCompleteMe#the-gycm_collect_identifiers_from_comments_and_strings-option)
+* [g:ycm_seed_identifiers_with_syntax](https://github.com/ycm-core/YouCompleteMe#the-gycm_seed_identifiers_with_syntax-option)
+
+```vim
+let g:ycm_collect_identifiers_from_comments_and_strings = 1
+let g:ycm_seed_identifiers_with_syntax = 1
+```
+
+These options enable completions inside comments and strings.
+
+* [g:ycm_complete_in_comments](https://github.com/ycm-core/YouCompleteMe#the-gycm_complete_in_comments-option)
+* [g:ycm_complete_in_strings](https://github.com/ycm-core/YouCompleteMe#the-gycm_complete_in_strings-option)
+
+```vim
+let g:ycm_complete_in_comments = 1
+let g:ycm_complete_in_strings = 1
+```
+
+Trigger the completion menu after entering a single character.
+
+* [g:ycm_min_num_of_chars_for_completion](https://github.com/ycm-core/YouCompleteMe#the-gycm_min_num_of_chars_for_completion-option)
+
+```vim
+let g:ycm_min_num_of_chars_for_completion = 1
+```
+
+Populating the location list with warnings and errors in the current buffer is
+very useful for jumping to those source locations, especially when using
+[mappings][location-list-mappings].
+
+* [g:ycm_always_populate_location_list](https://github.com/ycm-core/YouCompleteMe#the-gycm_always_populate_location_list-option)
+
+```vim
+let g:ycm_always_populate_location_list = 1
+```
+
+When a completion is selected the signature, and help comments if there is any
+available, are displayed in a separate buffer. This option enables
+automatically closing that buffer.
+
+* [g:ycm_autoclose_preview_window_after_insertion](https://github.com/ycm-core/YouCompleteMe#the-gycm_autoclose_preview_window_after_insertion-option)
+
+```vim
+let g:ycm_autoclose_preview_window_after_insertion = 1
+```
+
+Control how a split is created when using the `:YcmCompleter Goto` command.
+
+* [g:ycm_goto_buffer_command](https://github.com/ycm-core/YouCompleteMe#the-gycm_goto_buffer_command-option)
+
+```vim
+let g:ycm_goto_buffer_command = 'horizontal-split'
+```
+
+Warnings and errors are displayed in the Vim gutter, to the left of line
+numbers, these override the default characters used to display them.
+
+* [g:ycm_error_symbol](https://github.com/ycm-core/YouCompleteMe#the-gycm_error_symbol-option)
+* [g:ycm_warning_symbol](https://github.com/ycm-core/YouCompleteMe#the-gycm_warning_symbol-option)
+
+```vim
+let g:ycm_error_symbol = '▸'
+let g:ycm_warning_symbol = '▸'
+```
+
+## Mappings
+
+### [YouCompleteMe][ycm] Mappings
+
+Apply the compilers suggestion to fix a warning or error.
+
+```vim
+nnoremap <leader>fi :YcmCompleter FixIt<CR>
+```
+
+Go to the declaration of the symbol under the cursor.
+
+```vim
+nnoremap <leader>gd :YcmCompleter GoTo<CR>
+```
+
+Get the type of the symbol under the cursor.
+
+```vim
+nnoremap <leader>gt :YcmCompleter GetType<CR>
+```
+
+Display the full compiler diagnostic output for the warning or error on the
+line under the cursor.
+
+```vim
+nnoremap <leader>sd :YcmShowDetailedDiagnostic<CR>
+```
+
+### Location List Mappings
+
+Open the location list buffer.
+
+```vim
+nnoremap <leader>lo :lopen<CR>
+```
+
+Close the location list buffer.
+
+```vim
+nnoremap <leader>lc :lclose<CR>
+```
+
+Jump to the current location in the location list.
+
+```vim
+nnoremap <leader>ll :ll<CR>
+```
+
+Jump to the next location in the location list.
+
+```vim
+nnoremap <leader>ln :lnext<CR>
+```
+
+Jump to the previous location in the location list.
+
+```vim
+nnoremap <leader>lp :lprevious<CR>
+```
+
+Jump to the first location in the location list.
+
+```vim
+nnoremap <leader>lf :lfirst<CR>
+```
+
+Jump to the last location in the location list.
+
+```vim
+nnoremap <leader>la :llast<CR>
+```
+
+[ycm]: https://github.com/ycm-core/YouCompleteMe
+[minpac]: https://github.com/k-takata/minpac