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)
diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt
index bd63ea9..115e1fa 100644
--- 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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*