*DynamicSigns.txt* - Using Signs for different things

Author:  Christian Brabandt <cb@256bit.org>
Version: 0.2 Mon, 07 Jan 2019
                                                        *SignsCopyright*
Copyright: (c) 2009-2019 by Christian Brabandt
           The VIM LICENSE applies to DynamicSigns (see |copyright|)
           except use DynamicSigns instead of "Vim".
           NO WARRANTY, EXPRESS OR IMPLIED.  USE AT-YOUR-OWN-RISK.

===========================================================================
1. Contents                                                 *Signs-content*

        1.  Contents...................................: |Signs-content|
        2.  Manual.....................................: |Signs-manual|
        2.1   Display Indent Level.....................: |Signs-Indentation|
        2.2   Display Whitespace Warnings..............: |Signs-Whitespace|
        2.3   Display Marks............................: |Signs-Marks|
        2.4   SignExpressions..........................: |Signs-Hook|
        2.5   Display Signs for Quickfix items.........: |Signs-QF|
        2.6   Display Signs to display changes.........: |Signs-Diff|
        2.7   Alternating colors.......................: |Signs-Alternate|
        2.8   ASCII Scrollbar..........................: |Signs-Scrollbar|
        2.9   SignHighlighting.........................: |Signs-Highlight|
        3.  Autocommands...............................: |Signs-Autocommands|
        4.  Commands...................................: |Signs-Commands|
        5.  Icons......................................: |Signs-Icons|
        6.  Feedback...................................: |Signs-feedback|
        7.  History....................................: |Signs-history|

==========================================================================
2. Using the Signs Plugin                                    *Signs-manual*

Functionality

This plugin enables you to use signs |sign-support| for different things.
For example you can use signs to display Indentation-Levels, display line
whitespace errors, display marks |mark-motion|, display the differences
between the current editing file and the file on disk or whenever an
expression evalutates true (similar to how fold-expressions work
|fold-expr|)

All you need to do, is configure the plugin by setting some configuration
variables and run |:Signs|


2.1 Display Indentation Level                           *Signs-Indentation*
-----------------------------

If you want the plugin to display the numeric indentation level, simply set
the g:Signs_IndentationLevel variable like this in your |.vimrc|, e.g. like
this: >

    let g:Signs_IndentationLevel = 1
<

By default, this displays the indentation level (e.g. the indentation
divided by the 'tabstop' setting) as numeric values (actually it only
displays levels 1-9 or '>9' for a larger indent.

Run |:Signs| to display the signs for those lines.

2.2 Display Whitespace Warnings                         *Signs-Whitespace*
-------------------------------

If you want the plugin to display the warnings for lines with whitespace
errors, simply set the variable g:Signs_MixedIndentation like this in your
|.vimrc|, e.g. >

    :let g:Signs_MixedIndentation = 1
<

By default, this display warning signs for each line where either the
indentation consists of mixed whitespace (e.g. tabspace and blanks) or the
line ends with trailing whitespace.

Run |:Signs| to display the signs for those lines.

2.3 Display Marks                                             *Signs-Marks*
-----------------
If you want the plugin to display your marks, set the variable
g:Signs_Bookmarks to 1 in your |.vimrc|, e.g. >

    :let g:Signs_Bookmarks = 1
<
This will display the marks a-z and A-Z, if they are in your current buffer.

If this is enabled, |m| will be mapped to a function, that places the
bookmarks in your buffer and sets the mark. (|:k| does not update the signs,
Use |:Signs| or |:UpdateSigns| to manually update the view in case this is
needed).

                                                          *:SignExpression*
2.4 SignExpressions                                        *Signs-Hook*
-------------------

You can let Vim have an expression evaluated for each line in your current
buffer. On each line, where this expression is true, Vim will place a sign
for your. This enables you, to put e.g. a Sign on each line, that contains
'TODO'.

To do this, run the command |:SignExpression| and give an expression as
its argument, which will be evaluated for each line. Use the variable
|v:lnum| in your expression for the current line.

Say, you want to place a sign on each line, that contains 'TODO'. You simply
enter >

    :SignExpression getline(v:lnum)=~'TODO'?'Warning':0

This will place a sign on each line, that contains the word TODO
This expression is window-local.

As a special return value for the expression, you can return the type of sign
that should be placed. Currently the following sign types are understood: >

    Warning
    OK
    Error
    Info
    Add
    Arrow
    Flag
    Delete
    Stop
    Line1
    Line2
    Line3
    Line4
    Line5
    Gutter1
    Gutter2
    Gutter3
    Gutter4
    Gutter5
    1-99
    0
<
All except for "Line" only draw a flag in the sign column while the sign types
"Line1"-"Line5" highlights the complete line without displaying anything in
the Sign Column. "Gutter1"-"Gutter5" highlights only the gutter column, but
does not draw anything inside it. It uses the SignLine1-SignLine5 highlighting
groups for highlighting (|Signs-Highlight|)

The special return value 0 is meant to not place a sign, all other numbers
simply stand for themselves, e.g. will draw the corresponding number.

For example you want to highlight all Lines that contain the word 'TODO' with
the todo sign. Therefore you call the command: >

    :SignExpression getline(v:lnum)=~'TODO'?'Todo':0

Note, the Expression will be re-evaluated for that buffer on Changes to the
buffer.

                                                       *relativenumber_signs*

Here is an example, on how to draw relative numbers but only every fifth line.
First define a custom function like the following. You can usually just do
that in your |.vimrc| >

  fu! CustomSignExpression(lnum, div)
      if a:lnum < line('w0') || a:lnum > line ('w$')
          return 0
      endif
      if !exists("#CustomSignExpression#CursorMoved")
          augroup CustomSignExpression
              au!
              au CursorMoved * :Signs
              au VimResized  * :UpdateSigns
          augroup end
      endif
      let part=abs(a:lnum - line('.'))
      if part % a:div == 0
          return part > 99 ? 99 : part
      else
          return 0
      endif
  endfu

Then you simply call: >
  :SignExpression CustomSignExpression(v:lnum, 5)

This makes sure, the relative numbers will only be drawn on every fifth line.
Adjust the second number if you want it at other intervals. The autocommand
is there to make sure, it will be re-evaluated on cursor changes. By default,
custom sign expressions are only evaluated once the text changes, but this is
needed here, or else the relative line numbering will get out of sync soon.
Note it is recommended to use the CustomSignExpression |augroup|, as this will
be automatically cleaned up on the |:DisableSigns| command, if one exists,
otherwise the autocommand will still trigger although it probably should not.

2.5 Display signs for quickfix items                            *Signs-QF*
------------------------------------
If you want the plugin to display signs next to each match when using the
|quickfix| feature of vim, set the variable g:Signs_QFList, e.g. >

    :let g:Signs_QFList = 1
<
This will hook up an autocommand, that fires whenever the quickfix command
(|:helpgrep|, |:make|, |:vimgrep|, etc has been executed and places a small
sign next to each match.

2.6 Display Signs for viewing changes to the buffer             *Signs-Diff*
---------------------------------------------------
You can also set up the plugin to display small signs, that indicate,
whether the current line has been modified/deleted/added compared to the
version stored on disk. To enable this feature, set the g:Signs_Diff
variable in your |.vimrc| like this: >

    :let g:Signs_Diff = 1
<
This will run a diff of your buffer and the version stored on disk and place
a sign on each line that was modified.

Run |:UpdateSigns| or |:Signs| to update displaying the signs in your
buffer.

2.7 Alternating colors                                     *Signs-Alternate*
----------------------

You can also set up the plugin to color the lines in your buffer in
alternating colors. To do so, set the g:Signs_Alternate variable in your
|.vimrc| like this: >

    :let g:Signs_Alternate = 1
<
This will display each evenly numbered line in one color and each oddly
numbered line in a different color.

Run |:UpdateSigns| or |:Signs| to update displaying the signs in your
buffer.

2.8 ASCII Scrollbar                                        *Signs-Scrollbar*
-------------------
The DynamicSigns plugin can also emulate an ascii scrollbar. This is useful
in terminal Vim, to visually indicate, where in the buffer on is.

If you want to enable this, simply set the g:Signs_Scrollbar variable in
your |.vimrc| like this: >

    :let g:Signs_Scrollbar = 1

This will enable the Scrollbar and disable all other Sign features.

Unfortunately, this does not work well with |folds| and therefore the
scrollbar can't be displayed on a folded line. Also Linewrapping 'wrap' can
disturb the display of the scrollbar.

2.9 Sign Highlighting                                        *Signs-Highlight*
---------------------

By default the plugin defines the following highlighting groups: >

    SignLine1   - gray
    SignLine2   - orange
    SignLine3   - blue
    SignLine4   - red
    SignLine5   - yellow

You can however override those highlighting groups, by predefining them in
your |.vimrc| to whatever you want.

3.0 Autocommands                                      *:Signs-Autocommands*
----------------
This plugin installs some autocommands to update the signs dynamically.
Basically it uses |BufWritePost| and |InsertLeave| autocommands to update
displaying the signs.

Theoretically, it could also use |CursorHold| and |CursorHoldI|
autocommands, but that seems to slow down Vim a lot, when working with long
buffers and also seems to interrupt the workflow too much. You can however
force Vim to update the signs on those autocommands, by setting the variable
g:Signs_CursorHold to 1, e.g. put >
    let g:Signs_CursorHold = 1
<
in your .vimrc

When switching to the |:gui|, Vim will also updates the signs, so the gui
version can use some nice lookings |Signs-Icons|.

Last, when the using the quickfix feature together with the Signs
(|Signs-QF|), this plugin also installs an |QuickFixCmdPost| autocommand, to
be able to put signs on each line, where a warning/error is.

===========================================================================

4.0 Commands                                              *:Signs-Commands*
------------

The plugin introduces the following commands:

>
    :Signs          

Update the signs in the current buffer. According to your configuration runs
through every line in your buffer and checks, if a sign has to be displayed.
For performance reasons, it caches the values.

>
    :UpdateSigns

Discard the cache and update the signs for each line.

>
    :DisableSigns

Disable the Sign plugin.

>
    :SignQF

Display a quickfix list that contains all your signs in the current buffer.
|Sign-QF|

>
    :SignExpression expr

Display a sign on each line, where expr evaluates to true |Signs-Hook|

>
    :SignDiff

Run a diff of the buffer and the file on disk and display signs for the
changes |Signs-Diff|

============================================================================
5. Icons                                                       *Signs-Icons*
--------

The GTK version of Vim (and possibly also the Windows version) can also
display graphical Signs. For this reason, this plugin includes some nice
looking icons, that have been provided by
http://www.designkode.com/blog/free-developer-icons

"DesignKode is releasing this set of 40 free high quality icons for your web
site and application GUI designs. All icons in this set are 32 x 32 pixel
PNG image files. You may freely use these icons in your commercial or
personal projects without attribution."

(Source not available anymore, currently still available at the Internet
Archive:
https://web.archive.org/web/20111224161343/http://www.designkode.com/?download=Free%20Icons%20for%20Developers)

The Bookmark icons are "Red Orb Alphabet Icons" and have been take from
http://www.iconarchive.com/show/red-orb-alphabet-icons-by-iconarchive.html

Those are licensed under a Creative Commons Attribution 3.0 License.

The icons have been taken as is and only converted to a .bmp fileformat and a
size of 16x16, so that the gtk and Windows built of gVim can display them.

The autoload/DynamicSigns/ folder contains the original archive files with all
icons.

===========================================================================
6. Feedback                                                *Signs-Feedback*
-----------
Feedback is always welcome. If you like the plugin, please rate it at the
vim-page:
http://www.vim.org/scripts/script.php?script_id=3965

You can also follow the development of the plugin at github:
http://github.com/chrisbra/DynamicSigns

Please don't hesitate to report any bugs to the maintainer, mentioned in the
third line of this document.

==========================================================================
4. History                                              *Signs-history*

0.3: (unreleased) {{{1
- Performance improvements to make updating the signs faster
  (could slow down saving considerably for large files)
- Implement a Scrollbar |Signs-Scrollbar|
- Function was called too early issue #2
  (#2, reported by
  Charles, thanks!)
- Update SignExpressions on Changes to buffer or when switching to the gui
- Do not clean the signs, when starting up
- Make the |:SignExpression| command window-local

0.2: Mar 15, 2012 {{{1
- Initial upload
- development versions are available at the github repository
- put plugin on a public repository (http://github.com/chrisbra/Signs)
  }}}
===========================================================================
Modeline:
vim:tw=78:ts=8:ft=help:et:fdm=marker:fdl=0:norl