*signature.txt*  A plugin to toggle, display and navigate marks

     _________.__                            __                              ~
    /   _____/|__|   ____    ____  _____   _/  |_  __ __ _______   ____      ~
    \_____  \ |  |  / ___\  /    \ \__  \  \   __\|  |  \\_  __ \_/ __ \     ~
    /        \|  | / /_/  >|   |  \ / __ \_ |  |  |  |  / |  | \/\  ___/     ~
   /_______  /|__| \___  / |___|  /(____  / |__|  |____/  |__|    \___  >    ~
           \/     /_____/       \/      \/                            \/     ~


==============================================================================
Contents                                                           *Signature*

  1. Mappings         |SignatureMappings|
  2. Commands         |SignatureCommands|
  3. Customization    |SignatureCustomization|
  4. Contributing     |SignatureContributing|
  5. Credits          |SignatureCredits|
  6. License          |SignatureLicense|


==============================================================================
1. Mappings                                                *SignatureMappings*

Out of the box, the followings mappings are defined by default

  mx           Toggle mark 'x' and display it in the leftmost column
  dmx          Remove mark 'x' where x is a-zA-Z

  m,           Place the next available mark
  m.           If no mark on line, place the next available mark. Otherwise,
               remove (first) existing mark.
  m-           Delete all marks from the current line
  m<Space>     Delete all marks from the current buffer
  ]`           Jump to next mark
  [`           Jump to prev mark
  ]'           Jump to start of next line containing a mark
  ['           Jump to start of prev line containing a mark
  `]           Jump by alphabetical order to next mark
  `[           Jump by alphabetical order to prev mark
  ']           Jump by alphabetical order to start of next line having a mark
  '[           Jump by alphabetical order to start of prev line having a mark
  m/           Open location list and display marks from current buffer

  m[0-9]       Toggle the corresponding marker !@#$%^&*()
  m<S-[0-9]>   Remove all markers of the same type
  ]-           Jump to next line having a marker of the same type
  [-           Jump to prev line having a marker of the same type
  ]=           Jump to next line having a marker of any type
  [=           Jump to prev line having a marker of any type
  m?           Open location list and display markers from current buffer
  m<BS>        Remove all markers

This will allow the use of default behavior of m to set marks and, if
the line already contains the mark, it'll be unset. The default behavior
of ]', [', ]` and [` is supported and enhanced by wrapping around when
beginning or end of file is reached. ]-, [-, ]= and [= also accept a count.

To directly jump to a given marker, the following maps can be used
>
  nnoremap [1 :call signature#marker#Goto('prev', 1, v:count)
  nnoremap ]1 :call signature#marker#Goto('next', 1, v:count)
  nnoremap [2 :call signature#marker#Goto('prev', 2, v:count)
  nnoremap ]2 :call signature#marker#Goto('next', 2, v:count)
<
etc. These are not defined by default


==============================================================================
2. Commands                                                *SignatureCommands*

*:SignatureToggleSigns*
  Toggle the display of signs. This won't affect the marks or the mappings.

*:SignatureRefresh*
  Force the display of signs in the buffer to refresh. Use this to correct
  the signs if things go awry

*:SignatureListBufferMarks* [n]
  List all the marks used in the current buffer in the location list
  Accepts an optional argument to provide 'n' lines of context

*:SignatureListGlobalMarks* [n]
  List only the global marks used in all buffers in the location list
  Accepts an optional argument to provide 'n' lines of context

*:SignatureListMarkers* [marker] [n]
  List all instances of the specified marker(s) used in the current buffer
  in the location list. If no argument is given, it lists all markers
  Accepts an optional argument to provide 'n' lines of context
>
  :SignatureListMarkers         : List all markers
  :SignatureListMarkers 1       : List only the '!' marker
  :SignatureListMarkers @       : List only the '@' marker
  :SignatureListMarkers 0, 2    : List only ) marker with 2 lines of context
  :SignatureListMarkers '', 2   : List all markers with 2 lines of context
  :SignatureListMarkers '!@', 2 : List only the '!' and '@' markers and show
                                  2 lines of context around them
<

==============================================================================
3. Customization                                      *SignatureCustomization*

  *g:SignatureMap*
  Type: Dictionary, Default:
  To set up your own mappings copy the following dictionary and edit it
>
      let g:SignatureMap = {
        \ 'Leader'             :  "m",
        \ 'PlaceNextMark'      :  "m,",
        \ 'ToggleMarkAtLine'   :  "m.",
        \ 'PurgeMarksAtLine'   :  "m-",
        \ 'DeleteMark'         :  "dm",
        \ 'PurgeMarks'         :  "m<Space>",
        \ 'PurgeMarkers'       :  "m<BS>",
        \ 'GotoNextLineAlpha'  :  "']",
        \ 'GotoPrevLineAlpha'  :  "'[",
        \ 'GotoNextSpotAlpha'  :  "`]",
        \ 'GotoPrevSpotAlpha'  :  "`[",
        \ 'GotoNextLineByPos'  :  "]'",
        \ 'GotoPrevLineByPos'  :  "['",
        \ 'GotoNextSpotByPos'  :  "]`",
        \ 'GotoPrevSpotByPos'  :  "[`",
        \ 'GotoNextMarker'     :  "]-",
        \ 'GotoPrevMarker'     :  "[-",
        \ 'GotoNextMarkerAny'  :  "]=",
        \ 'GotoPrevMarkerAny'  :  "[=",
        \ 'ListBufferMarks'    :  "m/",
        \ 'ListBufferMarkers'  :  "m?"
        \ }
<
  By default, it defines the mappings as shown in |signature-mappings|
  To disable a map entirely, specify it as an empty string.
  If a key is not specified, the default value will be picked up.
  These same characters will be used to invoke the shortcuts.


  *g:SignatureIncludeMarks*
  String, Default : 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'

  Specify the marks that can be controlled by this plugin.
  Only supports Alphabetical marks at the moment.
  'b:SignatureIncludeMarks' can be set separately for buffer-specific marks.


  *g:SignatureIncludeMarkers*
  String, Default : ')!@#$%^&*('

  Specify the symbols that can be used by the plugin to be placed by 0-9.
  Note that there's a 1:1 correspondence between the symbols and 0-9.
  This string must be at most 10 chars long. Extra char will be ignored.
  Also, this string must not include any alphabetical characters `[a-zA-Z]`
  However, it can contain spaces to indicate blanks. Eg.
    `m0` will place `)` by default
    `m1` will place `!` by default
    `m2` will place `@` by default etc.

  If set to `')!'`, `m0` and `m1` will behave as described above but `m[2-9]` will
  not be handled by this plugin.

  If set to `' !'` (note the space before !), only `m1` will have any affect
  while `m[0,2-9]` will not have any affect

  An example of a use case is for keyboards with alternate layouts wherein
  the symbols associated with 0-9 could be different than the default.
  'b:SignatureIncludeMarkers' can be specified separately for each buffer


  *g:SignatureMap['Leader']*
  String, Default: 'm'

  Set the key used to toggle marks and markers.
  For eg. If this key is set to `<leader>m`,
    `<leader>ma`       will toggle the mark 'a' on the current line
    `<leader>m,`       will place the next available mark
    `<leader>m.`       will place the next available mark if there are no
                     marks already on the line; otherwise, will remove
                     first mark from line
    `<leader>m<Space>` will delete all marks
    `<leader>m1`       will toggle the marker '!'
    `<leader>m!`       will remove all the '!' markers
    `<leader>m<BS>`    will remove all markers

  NOTE: Currently, either marks or markers can be displayed in front of a
  line. Both can't be displayed simultaenously.

  To set this to mapleader or maplocalleader

    `let g:SignatureMap['Leader'] = '<Leader>'`
    `let g:SignatureMap['Leader'] = '<LocalLeader>'`


  *g:SignatureWrapJumps*
  Boolean, Default : 1

  Specify if jumping to marks should wrap-around.
  b:SignatureWrapJumps can be set to specify buffer-specific settings.


  *g:SignatureMarkOrder*
  String, Default : "\p\m"

  Signature allows you to display upto marks in front of a line. This controls
  the order in which marks are displayed.
    '\m' indicates the current or latest mark placed on the line
    '\p' indicates the previous mark placed on the line

  For eg,
    `g:SignatureMarkOrder="\m."`  : Display last mark with '.' suffixed
    `g:SignatureMarkOrder="_\m"`  : Display last mark with '_' prefixed
    `g:SignatureMarkOrder=">"`    : Display only a ">" for a line with a mark.
                                  The mark is not displayed
    `g:SignatureMarkOrder="\m\p"` : Display last two marks placed

  NOTE: The signs feature allows only 2 characters to be displayed. This limit
  is imposed by vim itself and not by the plugin


  *g:SignatureMarkTextHL*
  String, Default : 'SignatureMarkText'

  The highlight group used for mark signs. This can be set either to a string
  or to a |Funcref|.

  If it holds a string, it must be an expression suitable for passing to
  |eval()|. In the simple case, it can be the name of a highlight group. It can
  also hold more complicated expressions, in which case the expression `a:lnum`
  may be helpful. It holds the number of the line where the current mark is to
  be highlighted.

  If it holds a |Funcref|, then the function will be called with one argument,
  the line number of the mark to be highlighted. The function should return
  the name of a highlight group.

  Example using a string:
    `let g:SignatureMarkTextHL = "Exception"`

  Example of |Funcref|:
    `function Example(lineno)`
      `return "Exception"`
    `endfunction`
    `let g:SignatureMarkTextHL = function("Example")`

  By default, this is set to SignatureMarkText which is a highlight group
  that is linked to Exception

  *g:SignatureMarkTextHLDynamic*
  Boolean, Default: 0

  Highlight signs of marks dynamically based upon state indicated by
  vim-gitgutter. Setting this to `1` prior to plugin initialization overwrites
  |g:SignatureMarkTextHL|.

  vim-signify is not supported at the moment. For details, refer
  https://github.com/kshenoy/vim-signature/issues/93#issuecomment-195672354

  *g:SignatureMarkLineHL*
  String, Default : 'SignatureMarkLine'

  The highlight group used for hightlighting lines having marks. This can be a
  string or |Funcref|. SignatureMarkLine links to Normal by default.
  See |g:SignatureMarkTextHL| for details.


  *g:SignatureMarkerTextHL*
  String, Default : 'SignatureMarkerText'

  The highlight group used for marker signs. This can be a string or |Funcref|.
  SignatureMarkText links to WarningMsg by default.
  See |g:SignatureMarkTextHL| for details.


  *g:SignatureMarkerTextHLDynamic*
  Boolean, Default: 0

  Highlight signs of markers dynamically based upon state indicated by
  vim-gitgutter or vim-signify. Setting this to `1` prior to plugin
  initialization overwrites |g:SignatureMarkerTextHL|.


  *g:SignatureMarkerLineHL*
  String, Default : ''

  The highlight group used for hightlighting lines having markers. This can be
  a string or a |Funcref|. SignatureMarkerLine links to Normal by default.
  See |g:SignatureMarkTextHL| for details.


  *g:SignatureDeleteConfirmation*
  Boolean, Default: 0

  An option for the more clumsy-fingered of us. Asks for confirmation before
  moving/replacing/overwriting any marks


  *g:SignaturePurgeConfirmation*
  Boolean, Default: 0

  Similar to g:SignatureDeleteConfirmation. Asks for confirmation before
  deleting all marks/markers


  *g:SignaturePeriodicRefresh*
  Boolean, Default: 1

  Enable the display to refresh periodically. Generally a good thing to have.
  This makes use of the CursorHold autocmd event to execute periodically.
  The frequency of this event can be controlled by changing the value of the
  updatetime variable in milliseconds
    `set updatetime = 100`


  *g:SignaturePrioritizeMarks*
  Boolean, Default: 1

  When a line has both marks and markers, display the sign for marks. If set
  to 0, it will display the sign for markers instead


  *g:SignatureEnabledAtStartup*
  Boolean, Default: 1

  Control if the signs should be shown by default. If set to 0, the signs
  won't be visible until `:SignatureToggleSigns` has been called


  *g:SignatureDeferPlacement*
  Boolean, Default: 1

  NOTE: Not supported currently. Code was highly inefficient.
  Check if any other plugin has already placed a sign and if set to 1,
  Signature will hold off from placing a sign. If set to 0, Signature will
  overwrite any signs that are already present.


  *g:SignatureUnconditionallyRecycleMarks*
  Boolean, Default: 0

  Controls behavior when trying to place next available mark and all marks
  have been used. If set to 0, then either an error or warning message will be
  emitted, depending on the setting of |g:SignatureErrorIfNoAvailableMarks|.
  If set to 1, then the first local mark (e.g., 'a') will be removed from its
  existing location and applied to the current line.


  *g:SignatureErrorIfNoAvailableMarks*
  Boolean, Default: 1

  Controls behavior when unable to place a new mark. If set to 1, then an
  error is raised. If set to 0, then just a warning message.


  *g:SignatureForceRemoveGlobal*
  Boolean, Default: 0

  Vim's handling of global marks is a bit iffy. This option forces the removal
  of global marks by deleting it from the viminfo (or neovim's shada) file.

  Note that this is a very heavy hammer since it affects other things too.
  Refer 'viminfo' or 'shada' for more information on features that could be
  affected.


  *g:SignatureForceMarkPlacement*
  Boolean, Default: 0

  When set to 1, will always place marks instead of toggling them


  *g:SignatureForceMarkerPlacement*
  Boolean, Default: 0

  When set to 1, will always place markers instead of toggling them


==============================================================================
4. Contributing                                        *SignatureContributing*

  Please post any issues and all your suggestions on Github
    https://github.com/kshenoy/vim-signature

  Show some love by spreading the word and rating on
    http://www.vim.org/scripts/script.php?script_id=4118


==============================================================================
5. Credits                                                  *SignatureCredits*

A great thanks to these guys for providing the idea and inspiration to develop
Signature

* Sergey Khorev for mark-tools
  http://www.vim.org/scripts/script.php?script_id=2929

* Zak Johnson for vim-showmarks
  https://github.com/zakj/vim-showmarks

I'd also like to thank Steve J. Losh for learningvimscriptthehardway.com
without whose detailed guide this plugin would not have seen the light of day.


==============================================================================
6. License                                                  *SignatureLicense*

Signature is MIT/X11 licensed


vim:tw=78:ts=2:et:sts=2:sw=2:ft=help
