Adding upstream version 2:8.1.0875.upstream/2%8.1.0875upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 346 insertions, 0 deletions

diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt
new file mode 100644
index 0000000..4886f74
--- /dev/null
+++ b/runtime/doc/sign.txt
@@ -0,0 +1,346 @@
+*sign.txt*      For Vim version 8.1.  Last change: 2019 Jan 17
+
+
+		  VIM REFERENCE MANUAL    by Gordon Prieur
+					  and Bram Moolenaar
+
+
+Sign Support Features				*sign-support*
+
+1. Introduction				|sign-intro|
+2. Commands				|sign-commands|
+
+{Vi does not have any of these features}
+{only available when compiled with the |+signs| feature}
+
+==============================================================================
+1. Introduction					*sign-intro* *signs*
+
+When a debugger or other IDE tool is driving an editor it needs to be able
+to give specific highlights which quickly tell the user useful information
+about the file.  One example of this would be a debugger which had an icon
+in the left-hand column denoting a breakpoint.  Another example might be an
+arrow representing the Program Counter (PC).  The sign features allow both
+placement of a sign, or icon, in the left-hand side of the window and
+definition of a highlight which will be applied to that line.  Displaying the
+sign as an image is most likely only feasible in gvim (although Sun
+Microsystem's dtterm does support this it's the only terminal emulator I know
+of which does).  A text sign and the highlight should be feasible in any color
+terminal emulator.
+
+Signs and highlights are not useful just for debuggers.  Sun's Visual
+WorkShop uses signs and highlights to mark build errors and SourceBrowser
+hits.  Additionally, the debugger supports 8 to 10 different signs and
+highlight colors, see |NetBeans|.
+
+There are two steps in using signs:
+
+1. Define the sign.  This specifies the image, text and highlighting.  For
+   example, you can define a "break" sign with an image of a stop roadsign and
+   text "!!".
+
+2. Place the sign.  This specifies the file and line number where the sign is
+   displayed.  A defined sign can be placed several times in different lines
+   and files.
+
+							*sign-column*
+When signs are defined for a file, Vim will automatically add a column of two
+characters to display them in.  When the last sign is unplaced the column
+disappears again.  This behavior can be changed with the 'signcolumn' option.
+
+The color of the column is set with the SignColumn group |hl-SignColumn|.
+Example to set the color: >
+
+	:highlight SignColumn guibg=darkgrey
+<
+							*sign-identifier*
+Each placed sign is identified by a number called the sign identifier. This
+identifier is used to jump to the sign or to remove the sign. The identifier
+is assigned when placing the sign using the |:sign-place| command or the
+|sign_place()| function. Each sign identifier should be a unique number. If
+multiple placed signs use the same identifier, then jumping to or removing a
+sign becomes unpredictable. To avoid overlapping identifiers, sign groups can
+be used. The |sign_place()| function can be called with a zero sign identifier
+to allocate the next available identifier.
+
+							*sign-group*
+Each placed 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.
+
+When the line on which the sign is placed is deleted, the sign is moved to the
+next line (or the last line of the buffer, if there is no next line).  When
+the delete is undone the sign does not move back.
+
+==============================================================================
+2. Commands					*sign-commands* *:sig* *:sign*
+
+Here is an example that places a sign "piet", displayed with the text ">>", in
+line 23 of the current file: >
+	:sign define piet text=>> texthl=Search
+	:exe ":sign place 2 line=23 name=piet file=" . expand("%:p")
+
+And here is the command to delete it again: >
+	:sign unplace 2
+
+Note that the ":sign" command cannot be followed by another command or a
+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
+		starting with a non-digit.  Leading zeros are ignored, thus
+		"0012", "012" and "12" are considered the same name.
+		About 120 different signs can be defined.
+
+		Accepted arguments:
+
+	icon={bitmap}
+		Define the file name where the bitmap can be found.  Should be
+		a full path.  The bitmap should fit in the place of two
+		characters.  This is not checked.  If the bitmap is too big it
+		will cause redraw problems.  Only GTK 2 can scale the bitmap
+		to fit the space available.
+			toolkit		supports ~
+			GTK 1		pixmap (.xpm)
+			GTK 2		many
+			Motif		pixmap (.xpm)
+			Win32		.bmp, .ico, .cur
+					pixmap (.xpm) |+xpm_w32|
+
+	linehl={group}
+		Highlighting group used for the whole line the sign is placed
+		in.  Most useful is defining a background color.
+
+	text={text}						*E239*
+		Define the text that is displayed when there is no icon or the
+		GUI is not being used.  Only printable characters are allowed
+		and they must occupy one or two display cells.
+
+	texthl={group}
+		Highlighting group used for the text item.
+
+
+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}
+		Lists one defined sign and its attributes.
+
+
+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*
+		The file {fname} must already be loaded in a buffer.  The
+		exact file name must be used, wildcards, $ENV and ~ are not
+		expanded, white space must not be escaped.  Trailing white
+		space is ignored.
+
+		The sign is remembered under {id}, this can be used for
+		further manipulation.  {id} must be a number.
+		It's up to the user to make sure the {id} is used only once in
+		each file (if it's used several times unplacing will also have
+		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}.  If the buffer argument is not
+		given, place the sign in the current buffer.
+
+							*E885*
+:sign place {id} name={name} file={fname}
+		Change the placed sign {id} in file {fname} to use the defined
+		sign {name}.  See remark above about {fname} |:sign-fname|.
+		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}.  If the buffer argument is not
+		given, use the current buffer.
+
+
+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 in the global group from all the files.
+
+:sign unplace * group={group}
+		Remove all placed signs in group {group} from all the files.
+
+:sign unplace * group=*
+		Remove all placed signs in all the groups from all the files.
+
+:sign unplace
+		Remove a placed sign at the cursor position. If multiple signs
+		are placed in the line, then only one is removed.
+
+:sign unplace group={group}
+		Remove a placed sign in group {group} at the cursor
+		position.
+
+:sign unplace group=*
+		Remove a placed sign in any group at the cursor position.
+
+
+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 group=* file={fname}
+		List signs in all the groups 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 group=* buffer={nr}
+		List signs in all the groups placed in buffer {nr}.
+
+:sign place	List placed signs in the global group in all files.
+
+:sign place group={group}
+		List placed signs with sign group {group} in all files.
+
+:sign place group=*
+		List placed signs in all sign groups in all files.
+
+
+JUMPING TO A SIGN					*:sign-jump* *E157*
+
+See |sign_jump()| for the equivalent Vim script function.
+
+:sign jump {id} file={fname}
+		Open the file {fname} or jump to the window that contains
+		{fname} and position the cursor at sign {id}.
+		See remark above about {fname} |:sign-fname|.
+		If the file isn't displayed in window and the current file can
+		not be |abandon|ed this fails.
+
+:sign jump {id} group={group} file={fname}
+		Same but jump to the sign in group {group}
+
+:sign jump {id} [buffer={nr}]					*E934*
+		Same, but use buffer {nr}.  This fails if buffer {nr} does not
+		have a name. If the buffer argument is not given, use the
+		current buffer.
+
+:sign jump {id} group={group} [buffer={nr}]
+		Same but jump to the sign in group {group}
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: