Mercurial > vim
diff runtime/doc/sign.txt @ 15209:3a99b2e6d136 v8.1.0614
patch 8.1.0614: placing signs can be complicated
commit https://github.com/vim/vim/commit/162b71479bd4dcdb3a2ef9198a1444f6f99e6843
Author: Bram Moolenaar <Bram@vim.org>
Date: Fri Dec 21 15:17:36 2018 +0100
patch 8.1.0614: placing signs can be complicated
Problem: Placing signs can be complicated.
Solution: Add functions for defining and placing signs. Introduce a group
name to avoid different plugins using the same signs. (Yegappan
Lakshmanan, closes #3652)
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Fri, 21 Dec 2018 15:30:07 +0100 |
parents | 2f7e67dd088c |
children | 97b40b4c6911 |
line wrap: on
line diff
--- a/runtime/doc/sign.txt +++ b/runtime/doc/sign.txt @@ -1,4 +1,4 @@ -*sign.txt* For Vim version 8.1. Last change: 2016 Aug 17 +*sign.txt* For Vim version 8.1. Last change: 2018 Dec 21 VIM REFERENCE MANUAL by Gordon Prieur @@ -51,6 +51,20 @@ The color of the column is set with the Example to set the color: > :highlight SignColumn guibg=darkgrey +< + *sign-group* +Each sign can be assigned to either the global group or a named group. When +placing a sign, if a group name is not supplied, or an empty string is used, +then the sign is placed in the global group. Otherwise the sign is placed in +the named group. The sign identifier is unique within a group. The sign group +allows Vim plugins to use unique signs without interfering with other plugins +using signs. + + *sign-priority* +Each placed sign is assigned a priority value. When multiple signs are placed +on the same line, the attributes of the sign with the highest priority is used +independent of the sign group. The default priority for a sign is 10. The +priority is assigned at the time of placing a sign. ============================================================================== 2. Commands *sign-commands* *:sig* *:sign* @@ -69,6 +83,8 @@ comment. If you do need that, use the | DEFINING A SIGN. *:sign-define* *E255* *E160* *E612* +See |sign_define()| for the equivalent Vim script function. + :sign define {name} {argument}... Define a new sign or set attributes for an existing sign. The {name} can either be a number (all digits) or a name @@ -106,13 +122,18 @@ DEFINING A SIGN. *:sign-define* *E255* DELETING A SIGN *:sign-undefine* *E155* +See |sign_undefine()| for the equivalent Vim script function. + :sign undefine {name} Deletes a previously defined sign. If signs with this {name} are still placed this will cause trouble. + LISTING SIGNS *:sign-list* *E156* +See |sign_getdefined()| for the equivalent Vim script function. + :sign list Lists all defined signs and their attributes. :sign list {name} @@ -121,6 +142,8 @@ LISTING SIGNS *:sign-list* *E156* PLACING SIGNS *:sign-place* *E158* +See |sign_place()| for the equivalent Vim script function. + :sign place {id} line={lnum} name={name} file={fname} Place sign defined as {name} at line {lnum} in file {fname}. *:sign-fname* @@ -136,6 +159,25 @@ PLACING SIGNS *:sign-place* *E158* to be done several times and making changes may not work as expected). + The following optional sign attributes can be specified before + "file=": + group={group} Place sign in sign group {group} + priority={prio} Assign priority {prio} to sign + + By default, the sign is placed in the global sign group. + + By default, the sign is assigned a default priority of 10. To + assign a different priority value, use "priority={prio}" to + specify a value. The priority is used to determine the + highlight group used when multiple signs are placed on the + same line. + + Examples: > + :sign place 5 line=3 name=sign1 file=a.py + :sign place 6 group=g2 line=2 name=sign2 file=x.py + :sign place 9 group=g2 priority=50 line=5 + \ name=sign1 file=a.py +< :sign place {id} line={lnum} name={name} buffer={nr} Same, but use buffer {nr}. @@ -146,31 +188,73 @@ PLACING SIGNS *:sign-place* *E158* This can be used to change the displayed sign without moving it (e.g., when the debugger has stopped at a breakpoint). + The optional "group={group}" attribute can be used before + "file=" to select a sign in a particular group. + :sign place {id} name={name} buffer={nr} Same, but use buffer {nr}. REMOVING SIGNS *:sign-unplace* *E159* +See |sign_unplace()| for the equivalent Vim script function. + :sign unplace {id} file={fname} Remove the previously placed sign {id} from file {fname}. See remark above about {fname} |:sign-fname|. +:sign unplace {id} group={group} file={fname} + Same but remove the sign {id} in sign group {group}. + +:sign unplace {id} group=* file={fname} + Same but remove the sign {id} from all the sign groups. + :sign unplace * file={fname} Remove all placed signs in file {fname}. +:sign unplace * group={group} file={fname} + Remove all placed signs in group {group} from file {fname}. + +:sign unplace * group=* file={fname} + Remove all placed signs in all the groups from file {fname}. + :sign unplace {id} buffer={nr} Remove the previously placed sign {id} from buffer {nr}. +:sign unplace {id} group={group} buffer={nr} + Remove the previously placed sign {id} in group {group} from + buffer {nr}. + +:sign unplace {id} group=* buffer={nr} + Remove the previously placed sign {id} in all the groups from + buffer {nr}. + :sign unplace * buffer={nr} Remove all placed signs in buffer {nr}. +:sign unplace * group={group} buffer={nr} + Remove all placed signs in group {group} from buffer {nr}. + +:sign unplace * group=* buffer={nr} + Remove all placed signs in all the groups from buffer {nr}. + :sign unplace {id} Remove the previously placed sign {id} from all files it appears in. +:sign unplace {id} group={group} + Remove the previously placed sign {id} in group {group} from + all files it appears in. + +:sign unplace {id} group=* + Remove the previously placed sign {id} in all the groups from + all the files it appears in. + :sign unplace * - Remove all placed signs. + Remove all placed signs in the global group. + +:sign unplace * group=* + Remove all placed signs in all the groups. :sign unplace Remove the placed sign at the cursor position. @@ -178,15 +262,26 @@ REMOVING SIGNS *:sign-unplace* *E15 LISTING PLACED SIGNS *:sign-place-list* +See |sign_getplaced()| for the equivalent Vim script function. + :sign place file={fname} List signs placed in file {fname}. See remark above about {fname} |:sign-fname|. +:sign place group={group} file={fname} + List signs in group {group} placed in file {fname}. + :sign place buffer={nr} List signs placed in buffer {nr}. +:sign place group={group} buffer={nr} + List signs in group {group} placed in buffer {nr}. + :sign place List placed signs in all files. +:sign place group={group} + List placed signs in all sign groups in all the files. + JUMPING TO A SIGN *:sign-jump* *E157*