patch 8.1.0614: placing signs can be complicatedv8.1.0614

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)

1 files changed, 97 insertions, 2 deletions

diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt
index bd63ea9ade..115e1faa45 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 @@ The color of the column is set with the SignColumn group |hl-SignColumn|.
 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 |:execute| command.
 
 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* *E160* *E612*
 
 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* *E159*
 
 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*