git.r.bdr.sh - rbdr/dotfiles/blob - vim/doc/showmarks.txt

   1 *showmarks.txt* Visually show the location of marks
   2
   3                By Anthony Kruize <trandor@labyrinth.net.au>
   4                   Michael Geddes <michaelrgeddes@optushome.com.au>
   5
   6
   7 ShowMarks provides a visual representation of |marks| local to a buffer.
   8 Marks are useful for jumping back and forth between interesting points in a
   9 buffer, but can be hard to keep track of without any way to see where you have
  10 placed them.
  11
  12 ShowMarks hopefully makes life easier by placing a |sign| in the
  13 leftmost column of the buffer.  The sign indicates the label of the mark and
  14 its location.
  15
  16 ShowMarks is activated by the |CursorHold| |autocommand| which is triggered
  17 every |updatetime| milliseconds.  This is set to 4000(4 seconds) by default.
  18 If this is too slow, setting it to a lower value will make it more responsive.
  19
  20 Note: This plugin requires Vim 6.x compiled with the |+signs| feature.
  21
  22 ===============================================================================
  23 1. Contents                                    *showmarks* *showmarks-contents*
  24
  25     1. Contents              |showmarks-contents|
  26     2. Configuration         |showmarks-configuration|
  27     3. Highlighting          |showmarks-highlighting|
  28     4. Key mappings          |showmarks-mappings|
  29     5. Commands              |showmarks-commands|
  30     6. ChangeLog             |showmarks-changelog|
  31
  32     Appendix
  33     A. Using marks           |marks|
  34     B. Using signs           |sign|
  35     C. Defining updatetime   |updatetime|
  36     D. Defining a mapleader  |mapleader|
  37     E. Defining highlighting |highlight|
  38
  39 ===============================================================================
  40 2. Configuration                                      *showmarks-configuration*
  41
  42 ShowMarks can be configured to suit your needs.
  43 The following options can be added to your |vimrc| to change how ShowMarks
  44 behaves:
  45
  46                                                            *'showmarks_enable'*
  47 'showmarks_enable'      boolean (default: 1)
  48                         global
  49    This option enables or disables ShowMarks on startup. Normally ShowMarks
  50    will be enabled when Vim starts, setting this to 0 will disable ShowMarks
  51    by default.
  52    ShowMarks can be turned back on using the |ShowMarksToggle| command.
  53
  54                                                           *'showmarks_include'*
  55 'showmarks_include'     string  (default:
  56 "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.'`^<>[]{}()\"")
  57                         global or local to buffer
  58    This option specifies which marks will be shown and in which order if
  59    placed on the same line. Marks earlier in the list take precedence over
  60    marks later in the list.
  61    This option can also be specified as a buffer option which will override
  62    the global version.
  63
  64    NOTE: When including the " mark, it must be escaped with a \.
  65
  66    For example to only include marks 'abcdefzxABHJio', in that order:
  67 >
  68      let g:showmarks_include="abcdefzxABJio"
  69 <
  70    To override this for a particular buffer with 'ABCDhj.'^':
  71 >
  72      let b:showmarks_include="abcdefzxABJio"
  73 <
  74                                                       *'showmarks_ignore_type'*
  75 'showmarks_ignore_type' string  (default: "hq")
  76                         global
  77    This option defines which types of buffers should be ignored.
  78    Each type is represented by a letter. This option is not case-sensitive.
  79    Valid buffer types are:
  80    - h : Help
  81    - m : Non-modifiable
  82    - p : Preview
  83    - q : Quickfix
  84    - r : Readonly
  85
  86    For example to ignore help, preview and readonly files:
  87 >
  88      let g:showmarks_ignore_type="hpr"
  89 <
  90                                                       *'showmarks_ignore_name'*
  91 'showmarks_textlower'   string  (default: ">" )
  92                         global
  93    This option defines how the marks a-z will be displayed.
  94    A maximum of two characters can be defined.
  95    To include the mark in the text use a tab(\t) character. A single
  96    character will display as the mark with the character suffixed (same as
  97    "\t<character>"). Specifying two characters will simply display those two
  98    characters.
  99
 100    Some examples:
 101      To display the mark with a > suffixed: >
 102        let g:showmarks_textlower="\t>"
 103 <         or >
 104        let g:showmarks_textlower=">"
 105 <
 106      To display the mark with a ( prefixed: >
 107        let g:showmarks_textlower="(\t"
 108 <
 109      To display two > characters: >
 110        let g:showmarks_textlower=">>"
 111 <
 112                                                         *'showmarks_textupper'*
 113 'showmarks_textupper'   string  (default: ">")
 114                         global
 115    This option defines how the marks A-Z will be displayed. It behaves the same
 116    as the |'showmarks_textlower'| option.
 117
 118                                                         *'showmarks_textother'*
 119 'showmarks_textother'   string  (default: ">")
 120                         global
 121    This option defines how all other marks will be displayed. It behaves the
 122    same as the |'showmarks_textlower'| option.
 123
 124 'showmarks_hlline_lower' boolean (default: 0)        *'showmarks_hlline_lower'*
 125                         global
 126    This option defines whether the entire line a lowercase mark is on will
 127    be highlighted.
 128
 129 'showmarks_hlline_upper' boolean (default: 0)        *'showmarks_hlline_upper'*
 130                         global
 131    This option defines whether the entire line an uppercase mark is on will
 132    be highlighted.
 133
 134 'showmarks_hlline_other' boolean (default: 0)        *'showmarks_hlline_other'*
 135                         global
 136    This option defines whether the entire line other marks are on will be
 137    highlighted.
 138
 139 ===============================================================================
 140 3. Highlighting                                        *showmarks-highlighting*
 141
 142 Four highlighting groups are used by ShowMarks to define the colours used to
 143 highlight each of the marks.
 144
 145   - ShowMarksHLl : This group is used to highlight all the lowercase marks.
 146   - ShowMarksHLu : This group is used to highlight all the uppercase marks.
 147   - ShowMarksHLo : This group is used to highlight all other marks.
 148   - ShowMarksHLm : This group is used when multiple marks are on the same line.
 149
 150 You can define your own highlighting by overriding these groups in your |vimrc|.
 151 For example: >
 152
 153   highlight ShowMarksHLl guifg=red guibg=green
 154 <
 155 Will set all lowercase marks to be red on green when running in GVim.
 156 See |highlight| for more information.
 157
 158 ===============================================================================
 159 4. Mappings                                                *showmarks-mappings*
 160
 161 The following mappings are setup by default:
 162
 163   <Leader>mt   - Toggles ShowMarks on and off.
 164   <Leader>mo   - Forces ShowMarks on.
 165   <Leader>mh   - Clears the mark at the current line.
 166   <Leader>ma   - Clears all marks in the current buffer.
 167   <Leader>mm   - Places the next available mark on the current line.
 168
 169 (see |mapleader| for how to setup the mapleader variable.)
 170
 171 ===============================================================================
 172 5. Commands                                                *showmarks-commands*
 173
 174                                                               *ShowMarksToggle*
 175 :ShowMarksToggle
 176    This command will toggle the display of marks on or off.
 177
 178
 179 :ShowMarksOn                                                      *ShowMarksOn*
 180    This command will force the display of marks on.
 181
 182                                                            *ShowMarksClearMark*
 183 :ShowMarksClearMark
 184    This command will clear the mark on the current line.
 185    It doesn't actually remove the mark, it simply moves it to line 1 and
 186    removes the sign.
 187
 188                                                             *ShowMarksClearAll*
 189 :ShowMarksClearAll
 190    This command will clear all marks in the current buffer.
 191    It doesn't actually remove the marks, it simply moves them to line 1 and
 192    removes the signs.
 193
 194                                                            *ShowMarksPlaceMark*
 195 :ShowMarksPlaceMark
 196    This command will place the next available mark on the current line. This
 197    effectively automates mark placement so you don't have to remember which
 198    marks are placed or not. Hidden marks are considered to be available.
 199    NOTE: Only marks a-z are supported by this function.
 200
 201 ===============================================================================
 202 6. ChangeLog                                              *showmarks-changelog*
 203
 204 2.2 - 2004-08-17
 205    Fixed highlighting of the A-Z marks when ignorecase is on. (Mike Kelly)
 206    Fixed the delay with ShowMarks triggering when entering a buffer for the
 207      first time. (Mikolaj Machowski)
 208    Added support for highlighting the entire line where a mark is placed.
 209    Now uses HelpExtractor by Charles E. Campbell to install the help file.
 210
 211 2.1 - 2004-03-04
 212    Added ShowMarksOn. It forces ShowMarks to be enabled whether it's on or not.
 213      (Gary Holloway)
 214    Marks now have a definable order of precedence for when mulitple alpha marks
 215      have been placed on the same line. A new highlight group, ShowMarksHLm is
 216      used to identify this situation. (Gary Holloway)
 217        - showmarks_include has changed accordingly.
 218        - ShowMarksHL is now ShowMarksHLl.
 219    ShowMarksPlaceMark now places marks in the order specified by
 220      showmarks_include. (Gary Holloway)
 221    showmarks_include can now be specified per buffer. (Gary Holloway)
 222
 223 2.0 - 2003-08-11
 224    Added ability to ignore buffers by type.
 225    Fixed toggling ShowMarks off when switching buffers.
 226    ShowMarksHideMark and ShowMarksHideAll have been renamed to
 227      ShowMarksClearMark and ShowMarksClearAll.
 228    Marks a-z, A-Z and others now have different highlighting from each other.
 229    Added support for all other marks. (Gary Holloway)
 230    Enhanced customization of how marks are displayed by allowing a prefix to
 231      be specified.(Gary Holloway & Anthony Kruize)
 232    Fixed CursorHold autocmd triggering even when ShowMarks is disabled.
 233      (Charles E. Campbell)
 234
 235 1.5 - 2002-07-16
 236    Added ability to customize how the marks are displayed.
 237
 238 1.4 - 2002-05-29
 239    Added support for placing the next available mark.
 240      (Thanks to Shishir Ramam for the idea)
 241    Added support for hiding all marks.
 242    Marks on line 1 are no longer shown. This stops hidden marks from
 243      reappearing when the file is opened again.
 244    Added a help file.
 245
 246 1.3 - 2002-05-20
 247    Fixed toggling ShowMarks not responding immediately.
 248    Added user commands for toggling/hiding marks.
 249    Added ability to disable ShowMarks by default.
 250
 251 1.2 - 2002-03-06
 252    Added a check that Vim was compiled with +signs support.
 253    Added the ability to define which marks are shown.
 254    Removed debugging code that was accidently left in.
 255
 256 1.1 - 2002-02-05
 257    Added support for the A-Z marks.
 258    Fixed sign staying placed if the line it was on is deleted.
 259    Clear autocommands before making new ones.
 260
 261 1.0 - 2001-11-20
 262    First release.
 263
 264 vim:tw=78:ts=8:ft=help