*bookmarks.txt*                    A Vim plugin for using line-based bookmarks.


                                Vim Bookmarks


Author:            Mattes Groeger <http://blog.mattes-groeger.de/>
Plugin Homepage:   <https://github.com/MattesGroeger/vim-bookmarks>

===============================================================================
CONTENTS                                                    *BookmarksContents*

  1.  Introduction ................. |BookmarksIntroduction|
  2.  Installation ................. |BookmarksInstallation|
  3.  Usage ........................ |BookmarksUsage|
  4.  Commands ..................... |BookmarksCommands|
  5.  Customisation ................ |BookmarksCustomisation|
  6.  Extending .................... |BookmarksExtening|
  7.  FAQ .......................... |BookmarksFAQ|

===============================================================================
1. INTRODUCTION                                         *BookmarksIntroduction*
                                                                    *Bookmarks*

This vim plugin allows toggling bookmarks per line. A quickfix window gives
access to all bookmarks. Annotations can be added as well. These are special
bookmarks with a comment attached. They are useful for preparing code reviews.
All bookmarks will be restored on the next startup.

===============================================================================
2. INSTALLATION                                         *BookmarksInstallation*

Use your favorite plugin manager:

Pathogen:
>
  git clone https://github.com/MattesGroeger/vim-bookmarks.git \
            ~/.vim/bundle/vim-bookmarks
<

Vundle:
  1. Add Plugin 'MattesGroeger/vim-bookmarks' to .vimrc
  2. Run :PluginInstall

NeoBundle:
  1. Add NeoBundle 'MattesGroeger/vim-bookmarks' to .vimrc
  2. Run :NeoBundleInstall

vim-plug:
  1. Add Plug 'MattesGroeger/vim-bookmarks' to .vimrc
  2. Run :PlugInstall

===============================================================================
3. USAGE                                                       *BookmarksUsage*

You don't have to do anything: it just works.

===============================================================================
4. COMMANDS                                                 *BookmarksCommands*

Commands for using Bookmarks

  :BookmarkToggle                                             *:BookmarkToggle*
      Add or remove bookmark at current line

  :BookmarkAnnotate <TEXT>                                  *:BookmarkAnnotate*
      Add/edit/remove annotation at current line

  :BookmarkNext                                                 *:BookmarkNext*
      Jump to the next bookmark downwards

  :BookmarkPrev                                                 *:BookmarkPrev*
      Jump to the next bookmark upwards

  :BookmarkShowAll                                           *:BookmarkShowAll*
      Show bookmarks across all buffers in new window (toggle)

  :BookmarkClear                                               *:BookmarkClear*
      Removes bookmarks for current buffer

  :BookmarkClearAll                                         *:BookmarkClearAll*
      Removes bookmarks for all buffer

  :BookmarkSave <FILE_PATH>                                     *:BookmarkSave*
      Saves all bookmarks to a file so you can load them back in later

  :BookmarkLoad <FILE_PATH>                                     *:BookmarkLoad*
      Loads bookmarks from a file (see :BookmarkSave)

===============================================================================
5. CUSTOMISATION                                       *BookmarksCustomisation*

You can customise:

- The sign column's colours
- The signs' colours and symbols
- Line highlights
- Key mappings
- Whether or not line highlighting is on (defaults to off)
- Whether to close bookmarks split when jumping to a bookmark or not.

Please note that vim-bookmarks won't override any colours or highlights you've
set in your colorscheme.

SIGN COLUMN

The background colour of the sign column is controlled by the |hlSignColumn|
highlight group.  This will be either set in your colorscheme or Vim's default.

To find out where it's set, and to what it's set, use:
>
  :verbose highlight SignColumn
<

To change your sign column's appearance, update your colorscheme or |vimrc|
like this:

  Desired appearance                  Command ~
  Same as line number column          highlight clear SignColumn
  User-defined (terminal Vim)         highlight SignColumn ctermbg={whatever}
  User-defined (graphical Vim)        highlight SignColumn guibg={whatever}

SIGNS' COLOURS AND SYMBOLS

To customise the colours, set up the following highlight groups in your
colorscheme or |vimrc|:
>
  BookmarkSign            " the sign
  BookmarkAnnotationSign  " the annotation sign
<

You can either set these with `highlight BookmarkSign {key}={arg}...` or link
them to existing highlight groups with, say:
>
  highlight link BookmarkSign Todo
<

To customise the symbols, add the following to your |vimrc|:
>
  let g:bookmark_sign = '>>'
  let g:bookmark_annotation_sign = '##'
<

LINE HIGHLIGHTS

Similarly to the signs' colours, set up the following highlight group in your
colorscheme or |vimrc|:
>
  BookmarkLine            " the highlighted line
  BookmarkAnnotationLine  " the highlighted annotation line
<

KEY MAPPINGS

To change the default keys:
>
  nmap <Leader><Leader> <Plug>BookmarkToggle
  nmap <Leader>i <Plug>BookmarkAnnotate
  nmap <Leader>a <Plug>BookmarkShowAll
  nmap <Leader>j <Plug>BookmarkNext
  nmap <Leader>k <Plug>BookmarkPrev
  nmap <Leader>c <Plug>BookmarkClear
  nmap <Leader>x <Plug>BookmarkClearAll
<

MORE OPTIONS

Change the following options in your |vimrc| to customize the plugin behaviour.

Disable auto saving (default 1):

>
  let g:bookmark_auto_save = 0
<

Change file for auto saving (default $HOME .'/.vim-bookmarks'):

>
  let g:bookmark_auto_save_file = '/tmp/my_bookmarks'
<

Turn on line highlighting (default 0):

>
  let g:bookmark_highlight_lines = 1
<

Turn off the warning when clearing all bookmarks (default 1):

>
  let g:bookmark_show_warning = 0
<

Turn on vertical line centering when jumping to bookmark (default 0):

>
  let g:bookmark_center = 1
<

Automatically close bookmarks split when jumping to a bookmark (default 0):

>
  let g:bookmark_auto_close = 1
<
===============================================================================
6. EXTENDING                                               *BookmarksExtending*

You can implement automatic switching of bookmarks file on your desired event.
To do so, use functions BookmarkSave, BookmarkLoad and BookmarkClearAll with
the last argument set to 1. This will suppress any messages and prompts these
functions normally issue. The BookmarkLoad function will return 1 to indicate
that file loading was successful, and 0 for failure. An example script using
this feature is located in the 'examples/bm-autoload-example.vim' file.

===============================================================================
7. FAQ                                                           *BookmarksFAQ*

a. Why are the colours in the sign column weird?

  Your colorscheme is configuring the |hl-SignColumn| highlight group weirdly.
  Please see |BookmarksCustomisation| on customising the sign column.

b. What happens if I also use another plugin which uses signs (e.g. Syntastic)?

  Vim only allows one sign per line. Therefore bookmarks will override any
  existing sign. When removing the bookmark the original sign will show up
  again. In other words vim-bookmarks won't remove another plugin's signs.

c. Why aren't any signs showing at all?

  Make sure your vim supports signs. This should return "1":
>
  :echo has('signs')
<
