当调试器或者其他集成开发环境的工具控制编辑器时，它需要通过给出某些特定的高亮以
给用户一些关于文件有用信息的反馈。一个例子是调试器在左边的列中给出图标来表示这
里有一个断点。另一个可能的例子是用一个箭头代表当前程序计数器 PC 的位置。标号特
性既包括在窗口的左边放置标号或者图标的支持，也包括该行使用的高亮的定义。显示图
像化的标号可能只适用于 gvim (虽然 Sun Microsystem 的 dtterm 也支持，它是我所知
的唯一支持的终端模拟器)。但文字化的标号和高亮应该可用于任何彩色终端模拟器。
标号和相应的高亮并不仅对调试器有用。Sun 的 Visual WorkShop 用标号和高亮来标识
错误和源程序浏览器的命中位置。它的调试器也支持 8 到 10 种不同的标号和高亮色。
Netbeans 也是如此。
应用标号的过程分两步进行:
1. 定义标号。这里指定图像，文字和高亮设定。例如，你可以定义 "break" 标号为路边
的停止符号和文字 "!!"。
2. 放置标号。这里指定标号显示的文件和行号。每个定义好的标号可以在不同的文件和
行号上多次放置。
sign-column
如果文件里定义了标号，Vim 自动增加两个字符的纵列来显示标号。撤销最后一个标号之
后，该列又会自动消失。'signcolumn' 选项可改变此行为。
该列的颜色由 SignColumn 高亮组定义 hl-SignColumn 。一个设定该颜色的示例:
:highlight SignColumn guibg=darkgrey
打开 'cursorline' 时，使用 CursorLineSign 高亮组 hl-CursorLineSign 。
sign-identifier
已放置的标号以一个数值识别，称为标号标识符。此标识符用于跳转到标号或删除标号。
标识符在用 :sign-place 命令或 sign_place() 函数放置标号时分配。每个标号标
识符应是唯一的数值。如果多个已放置的标号使用相同的标识符，标号的跳转或删除将不
可预测。为了避免标识符重复，可用标号组。 sign_place() 函数调用时可提供零标号
标识符来分配下个可用的标识符。
sign-group
每个已放置的标号可在全局组或某命名组中分配。放置标号时，如果不提供组名或组名为
空串时，标号放置在全局组。否则标号放置在命名组。标号标识符在每个组里是唯一的。
标号组允许 Vim 插件使用唯一的标号，而不会为其它使用标号的插件相互干扰。
要在弹出窗口中放置标号，组名必须以 "PopUp" 开始。其它标号不能在弹出窗口中显
示。组名 "PopUpMenu" 用于 'cursorline' 置位的弹出窗口。
sign-priority
每个已放置的标号会分配一个优先值。同一行上如有多个标号放置，使用最高优先级的标
号的属性，这与标号组无关。标号的缺省优先级是 10。优先级在标号放置时分配。
当出现相同优先级的两个标号且其中一个在标号列上显示图标或文本而另一个有行高亮
时，两个标号同时显示。
标号放置的行如被删除，移动标号到下一行 (如果没有下一行则为缓冲区的末行)。删除
如被撤销，标号并不移回。
如果同时有带行高亮的标号和 'cursorline' 高亮，对优先级为 100 或更高的标号，其
高亮优先，反之则 'cursorline' 高亮优先。
这里提供了一例，在当前文件的第 23 行显示 "piet" 标号，以文字 ">>" 标明。
:sign define piet text=>> texthl=Search
:exe ":sign place 2 line=23 name=piet file=" .. expand("%:p")
:sign unplace 2
注意 ":sign" 命令后面不能跟其它命令或者注释。如果需要，使用 :execute 命令。
定 义 标 号 :sign-define E255 E160 E612
见 sign_define() 给出等价的 Vim 脚本函数。
:sign define {name} {argument}...
定义新标号或为已存在的标号设置属性。{name} 可以是完全由数位组
成的数值，也可以是由非数位开头的名字。忽略开头的零，所以
"0012"、"012" 和 "12" 认为是相同的名字。
可以定义大约 120 个不同的标号。
允许的参数是:
icon={bitmap}
位图文件名。必须是完整的路径名。位图应该能够在两个字符的宽度内
显示。但是不会实际检查这一点，如果位图太大，刷新时会有问题。只
有 GTK 2 可以按比例缩放位图，使之刚好能占据可用的空间。
工具包 支持
GTK 1 pixmap (.xpm)
GTK 2 许多
Motif pixmap (.xpm)
Win32 .bmp, .ico, .cur
pixmap (.xpm) +xpm_w32
linehl={group}
用以显示整个标号行的高亮组。多用于定义背景色。
numhl={group}
放置标号的行的行号使用的高亮组。优先于 hl-LineNr 、
hl-LineNrAbove 、 hl-LineNrBelow 和 hl-CursorLineNr 。
text={text} E239
没有图标或者不用 GUI 时显示的文本。只允许可显示字符，而且必须
占据一到两个显示单元。
texthl={group}
显示文本项目的高亮组。
culhl={group}
打开 'cursorline' 时，光标在标号所在的行时文本项目使用的高亮
组。
示例:
:sign define MySign text=>> texthl=Search linehl=DiffText
删 除 标 号 :sign-undefine E155
见 sign_undefine() 给出等价的 Vim 脚本函数。
:sign undefine {name}
删除标号的定义。如果 {name} 标号已经放置，会有问题。
示例:
:sign undefine MySign
列 出 标 号 :sign-list E156
见 sign_getdefined() 给出等价的 Vim 脚本函数。
:sign list 列出所有的标号和它们的属性。
:sign list {name}
列出单个标号和他的属性。
放 置 标 号 :sign-place E158
见 sign_place() 给出等价的 Vim 脚本函数。
:sign place {id} line={lnum} name={name} file={fname}
把 {name} 指定的标号放在文件 {fname} 的第 {lnum} 行。
:sign-fname
文件 {fname} 必须已经在某个缓冲区调入，而且必须使用准确的文件
名。通配符，$ENV 和 ~ 不会被扩展，空白不会被转义。结尾的空白则
会忽略。
用 {id} 记住这个标号，将来可作进一步应用。{id} 必须是数值。用
户可以自行决定 {id} 在每个文件内是否唯一。(如果多次使用，撤销
放置就必须做多次，而且进行修改时未必尽如预期)。
以下可选的标号属性可在 "file=" 前指定:
group={group} 把标号放置在标号组 {group}
priority={prio} 给标号分配优先级 {prio}
缺省，标号放置在全局标号组。
缺省，标号分配的缺省优先级为 10。要分配不同的优先值，用
"priority={prio}" 来指定。优先级用于在同一行有多个标号放置时决
定显示的标号。
示例:
: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}]
同上，但指定缓冲区 {nr}。如果不给出缓冲区参数，标号放置在当前
缓冲区。
示例:
:sign place 10 line=99 name=sign3
:sign place 10 line=99 name=sign3 buffer=3
E885
:sign place {id} name={name} file={fname}
把文件 {fname} 里用 {id} 记住的标号换成 {name} 指定的新标号。
参看关于 {fname} 的说明 :sign-fname 。可用于不移动某个标号的
同时，更改它的显示方式 (例如，当调试器停在某个断点时)。
可选的 "group={group}" 属性可在 "file=" 前使用来选择特定组的标
号。可选的 "priority={prio}" 属性可用来发来已有标号的优先级。
示例:
:sign place 23 name=sign1 file=/path/to/edit.py
:sign place {id} name={name} [buffer={nr}]
同上，但指定缓冲区 {nr}。如果不给出缓冲区参数，使用当前缓冲
区。
示例:
:sign place 23 name=sign1
:sign place 23 name=sign1 buffer=7
撤 销 放 置 标 号 :sign-unplace E159
见 sign_unplace() 给出等价的 Vim 脚本函数。
:sign unplace {id} file={fname}
从文件 {fname} 里撤销已放置的标号 {id} 的放置。
参看关于 {fname} 的说明 :sign-fname 。
:sign unplace {id} group={group} file={fname}
同上，但撤销标号组 {group} 里的标号 {id}。
:sign unplace {id} group=* file={fname}
同上，但摊销所有标号组里的标号 {id}。
:sign unplace * file={fname}
从文件 {fname} 里撤销所有标号的放置。
:sign unplace * group={group} file={fname}
从文件 {fname} 里撤销组 {group} 里所有标号的放置。
:sign unplace * group=* file={fname}
从文件 {fname} 里撤销所有组里所有标号的放置。
:sign unplace {id} buffer={nr}
从缓冲区 {nr} 里撤销已放置的标号 {id} 的放置。
:sign unplace {id} group={group} buffer={nr}
从缓冲区 {nr} 里撤销组 {group} 里已放置的标号 {id} 的放置。
:sign unplace {id} group=* buffer={nr}
从缓冲区 {nr} 里撤销所有组里已放置的标号 {id} 的放置。
:sign unplace * buffer={nr}
从缓冲区 {nr} 里撤销所有标号的放置。
:sign unplace * group={group} buffer={nr}
从缓冲区 {nr} 里撤销组 {group} 里所有标号的放置。
:sign unplace * group=* buffer={nr}
从缓冲区 {nr} 里撤销所有组里所有标号的放置。
:sign unplace {id}
撤销所有文件里出现的 {id} 标号的放置。
:sign unplace {id} group={group}
撤销所有文件里出现的组 {group} 里 {id} 标号的放置。
:sign unplace {id} group=*
撤销所有文件里出现的所有组里 {id} 标号的放置。
:sign unplace *
从所有文件撤销全局组里所有标号的放置。
:sign unplace * group={group}
从所有文件撤销组 {group} 里所有标号的放置。
:sign unplace * group=*
从所有文件撤销所有组里所有标号的放置。
:sign unplace
撤销光标所在标号的放置。如果同一行有多个标号，只删除一个。
:sign unplace group={group}
撤销组 {group} 里光标所在标号的放置。
:sign unplace group=*
撤销所有组里光标所在标号的放置。
列 出 放 置 标 号 :sign-place-list
见 sign_getplaced() 给出等价的 Vim 脚本函数。
:sign place file={fname}
列出文件 {fname} 里所有放置的标号。
参看关于 {fname} 的说明 :sign-fname 。
:sign place group={group} file={fname}
列出文件 {fname} 里组 {group} 里所有放置的标号。
:sign place group=* file={fname}
列出文件 {fname} 里所有组里所有放置的标号。
:sign place buffer={nr}
列出缓冲区 {nr} 里所有放置的标号。
:sign place group={group} buffer={nr}
列出缓冲区 {nr} 里组 {group} 里所有放置的标号。
:sign place group=* buffer={nr}
列出缓冲区 {nr} 里所有组里所有放置的标号。
:sign place 列出所有文件里全局组里放置的标号。
:sign place group={group}
列出所有文件里组 {group} 里放置的标号。
:sign place group=*
列出所有文件里所有组里放置的标号。
跳 到 标 号 :sign-jump E157
见 sign_jump() 给出等价的 Vim 脚本函数。
:sign jump {id} file={fname}
打开文件 {fname} 或者跳转到包含 {fname} 的窗口并把光标设在标号
{id} 所在的位置。
参看关于 {fname} 的说明 :sign-fname 。
如果此文件不在窗口显示但当前文件又不能被放弃 abandon ，此动作
失败。
:sign jump {id} group={group} file={fname}
同上，但跳转到组 {group} 里的标号
:sign jump {id} [buffer={nr}] E934
同上，但指定缓冲区 {nr}。如果缓冲区 {nr} 没有名字，报错。如果
未给出缓冲区参数，使用当前缓冲区。
:sign jump {id} group={group} [buffer={nr}]
同上，但跳转到组 {group} 里的标号
sign_define({name} [, {dict}]) sign_define()
sign_define({list})
定义名为 {name} 的新标号或为已存在的标号设置属性。类似于
:sign-define 命令。
给 {name} 加上独有的前缀以避免名字冲突。不像放置标号那样有
{group} 的区隔。
{name} 可以是字符串或数值。可选的 {dict} 参数指定标号的属性。
支持以下的值:
icon 用于标号的位图文件完整路径。
linehl 用于标号放置所在的整行的高亮组。
numhl 放置标号的行的行号使用的高亮组。
text 没有图标或不使用 GUI 时显示的文本。
texthl 文本项目使用的高亮组
culhl 打开 'cursorline' 时，光标在标号所在的行时文本
项目使用的高亮组。
如果名为 {name} 的标号已存在，更新标号的属性。
单个参数 {list} 可用来定义一列标号。每个列表项是 {dict} 中上述
项目的字典，此外还有 "name" 项目指定标号名。
成功时返回 0，失败时返回 -1。如果使用单个参数 {list}，返回值的
列表，其中每个值对应一个定义的标号。
示例:
call sign_define("mySign", {
\ "text" : "=>",
\ "texthl" : "Error",
\ "linehl" : "Search"})
call sign_define([
\ {'name' : 'sign1',
\ 'text' : '=>'},
\ {'name' : 'sign2',
\ 'text' : '!!'}
\ ])
也可用作 method :
GetSignList()->sign_define()
{name}]) sign_getdefined()
获取已定义标号及其属性的列表。类似于 :sign-list 命令。
如果不给出 {name}，返回所有已定义标号的列表，否则返回指定标号
的属性。
返回值的每个列表项是包含以下项目的字典:
icon 标号的位图文件完整路径
linehl 标号放置所在的整行的高亮组；有设置此项目才存在
name 标号名
numhl 放置标号的行的行号使用的高亮组；有设置此项目才
存在
text 没有图标或不使用 GUI 时显示的文本。
texthl 文本项目使用的高亮组；有设置此项目才存在
culhl 打开 'cursorline' 时，光标在标号所在的行时文本
项目使用的高亮组；有设置此项目才存在
如果没有标号或 {name} 找不到，返回空列表。
示例:
" 获取所有定义的标号的列表
echo sign_getdefined()
" 获取名为 mySign 的标号的属性
echo sign_getdefined("mySign")
也可用作 method :
GetSignList()->sign_getdefined()
{buf} [, {dict}]]) sign_getplaced()
返回一个或所有缓冲区里放置的标号的列表。类似于
:sign-place-list 命令。
如果给出可选的缓冲区名 {buf}，只返回该缓冲区里放置的标号列表。
{buf} 的用法见 bufname() 。可选的 {dict} 可包含以下项目:
group 只选择此组内的标号
id 选择带此标识符的标号
lnum 选择放置在此行的标号。{lnum} 的用法见
line() 。
如果 {group} 为 '*'，返回包括全局组的所有组的标号。如果
{group} 未给出或为空串，只返回全局组里的标号。如果无参数，返回
所有缓冲区里放置的全局组里的所有标号。见 sign-group 。
返回值的每个列表项目是带有以下项目的字典:
bufnr 带有此标号的缓冲区号
signs 放置在 {bufnr} 的标号列表。每个列表项目是带有
下列项的字典
每个标号的字典包含以下项:
group 标号组。全局组设为 ''。
id 标号标识符
lnum 标号放置的行号
name 已定义的标号名
priority 标号优先级
缓冲区里返回的标号以行号和优先级排序。
失败或没有已放置的标号时返回空列表。
示例:
" 获取在 eval.c 里放置的全局组里的标号列表
echo sign_getplaced("eval.c")
" 获取在 eval.c 里放置的组 'g1' 里的标号列表
echo sign_getplaced("eval.c", {'group' : 'g1'})
" 获取在 eval.c 里放置在第 10 行的标号列表
echo sign_getplaced("eval.c", {'lnum' : 10})
" 获取在 a.py 里放置的标识符为 10 的标号
echo sign_getplaced("a.py", {'id' : 10})
" 获取在 a.py 里放置的组 'g1' 里带 id 20 的标号
echo sign_getplaced("a.py", {'group' : 'g1',
\ 'id' : 20})
" 获取所有放置的标号的列表
echo sign_getplaced()
也可用作 method :
GetBufname()->sign_getplaced()
sign_jump()
sign_jump({id}, {group}, {buf})
打开缓冲区 {buf} 或跳转到包含 {buf} 的窗口，并定位光标到组
{group} 里的标号 {id}。类似于 :sign-jump 命令。
{group} 为空串时使用全局组。
{buf} 的用法见 bufname() 。
返回标号的行号。如果参数非法返回 -1。
示例:
" 跳转到当前缓冲区的标号 10
call sign_jump(10, '', '')
也可用作 method :
GetSignid()->sign_jump()
sign_place()
sign_place({id}, {group}, {name}, {buf} [, {dict}])
把 {name} 指定的标号放在文件 {fname} 或缓冲区 {buf} 的第
{lnum} 行，并给标号指定 {id} 和 {group}。类似于 :sign-place
命令。
如果标号标识符 {id} 为零，分配新的标识符。否则使用指定的数值。
{group} 为标号组名。要指定全局标号组，使用空串。{group} 相当于
{id} 的命名空间，这样两个组就可有相同的 ID。详情参见
sign-identifier 和 sign-group 。
{name} 指定已定义的标号。
{buf} 指定缓冲区名或号。可接受的值见 bufname() 。
可选的 {dict} 参数支持以下项目:
lnum 放置标号的文件或缓冲区 {buf} 的行号。
可接受的值见 line() 。
priority 标号优先级。详见 sign-priority 。
如果不给出可选的 {dict}，那么修改已放置的在组 {group} 里的标号
{id} 使用已定义的标号 {name}。
成功时返回标号标识符，失败时返回 -1。
示例:
" 放置名为 sign1 的标号在缓冲区 json.c 第 20 行带 id
" 为 5
call sign_place(5, '', 'sign1', 'json.c',
\ {'lnum' : 20})
" 更新缓冲区 json.c 的标号 5 使用 sign2
call sign_place(5, '', 'sign2', 'json.c')
" 放置名为 sign3 的标号在缓冲区 json.c 第 30 行带新分
" 配的标识符
let id = sign_place(0, '', 'sign3', 'json.c',
\ {'lnum' : 30})
" 放置名为 sign4 的标号在缓冲区 json.c 第 40 行带 id
" 为 10 且优先级为 90
call sign_place(10, 'g3', 'sign4', 'json.c',
\ {'lnum' : 40, 'priority' : 90})
也可用作 method :
GetSignid()->sign_place(group, name, expr)
sign_placelist()
sign_placelist({list})
放置一或多个标号。类似于 sign_place() 函数。{list} 参数指定
要放置的一列标号。每个列表项目是带以下标号属性的字典:
buffer 缓冲区名或号。可接受的值见 bufname() 。
group 标号组名。{group} 相当于 {id} 的命名空间，这样
两个组就可有相同的 ID。不指定或设为空串时则指
定全局标号组，详见 sign-group 。
id 标号标识符。如果未指定或为零，分配新的唯一的标
识符。否则使用指定的数值。详见
sign-identifier 。
lnum 缓冲区里放置标号的行号。可接受值见 line() 。
name 放置的标号名。详见 sign_define() 。
priority 标号优先级。多个标号放置在同一行时，使用最高优
先级的标号。如果不指定，缺省优先级是 10。详见
sign-priority 。
如果 {id} 指定已存在的桔，则修改已有的标号以使用指定的 {name}
和/或 {priority}。
返回标号标识符列表。如果放置某标号失败，对应的列表项设为 -1。
示例:
" 放置标号 s1 在缓冲区 a.c 的第 20 行带 id 5，还有第
" 30 行带 id 10
let [n1, n2] = sign_placelist([
\ {'id' : 5,
\ 'name' : 's1',
\ 'buffer' : 'a.c',
\ 'lnum' : 20},
\ {'id' : 10,
\ 'name' : 's1',
\ 'buffer' : 'a.c',
\ 'lnum' : 30}
\ ])
" 放置标号 s1 在缓冲区 a.c 的第 40 和 50 行带自动生成
" 的标识符
let [n1, n2] = sign_placelist([
\ {'name' : 's1',
\ 'buffer' : 'a.c',
\ 'lnum' : 40},
\ {'name' : 's1',
\ 'buffer' : 'a.c',
\ 'lnum' : 50}
\ ])
也可用作 method :
GetSignlist()->sign_placelist()
{name}]) sign_undefine()
sign_undefine({list})
删除之前定义的标号 {name}。类似于 :sign-undefine 命令。如果
不给出 {name}，删除所有定义的标号。
单个参数 {list} 可用来删除一列标号的定义。每个列表项是标号名。
成功时返回 0，失败时返回 -1。如果使用单个参数 {list}，返回值的
列表，其中每个值对应一个删除定义的标号。
示例:
" 删除名为 mySign 的标号
call sign_undefine("mySign")
" 删除标号 'sign1' 和 'sign2'
call sign_undefine(["sign1", "sign2"])
" 删除所有标号
call sign_undefine()
也可用作 method :
GetSignlist()->sign_undefine()
{group} [, {dict}]) sign_unplace()
撤销在一或多个缓冲区里已放置的标号的放置。类似于
:sign-unplace 命令。
{group} 是标号组名。要使用全局标号组，使用空串。如果 {group}
设为 '*'，使用所有的组，包括全局组。
{group} 里标号的选择基于 {dict} 的项目。支持以下的 {dict} 可选
项目:
buffer 缓冲区名或号。见 bufname() 。
id 标号标识符
如果不给出 {dict}，删除 {group} 里的所有标号。
成功时返回 0，失败时返回 -1。
示例:
" 从缓冲区 a.vim 撤销标号 10
call sign_unplace('', {'buffer' : "a.vim", 'id' : 10})
" 从缓冲区 3 撤销 'g1' 组里的标号 20
call sign_unplace('g1', {'buffer' : 3, 'id' : 20})
" 从缓冲区 10 撤销 'g2' 组里的所有标号
call sign_unplace('g2', {'buffer' : 10})
" 从所有缓冲区撤销 'g3' 组里的标号 30
call sign_unplace('g3', {'id' : 30})
" 从缓冲区 5 撤销所有已放置的标号
call sign_unplace('*', {'buffer' : 5})
" 从所有缓冲区撤销 'g4' 组里的所有标号
call sign_unplace('g4')
" 从所有缓冲区撤销标号 40
call sign_unplace('*', {'id' : 40})
" 从所有缓冲区撤销所有已放置的标号
call sign_unplace('*')
GetSigngroup()->sign_unplace()
sign_unplacelist({list}) sign_unplacelist()
撤销在一或多个缓冲区里已放置的标号的放置。类似于
sign_unplace() 函数。
{list} 参数指定要撤销的标号的列表。每个列表项目是带有以下标号
属性的字典:
buffer 缓冲区名或号。可接受的值见 bufname() 。如无指
定，从所有缓冲区里撤销指定的标号。
group 标号组名。如无指定或设为空串，使用全局标号组，
如果设为 '*'，使用所有的组，包括全局组。
id 标号标识符。如无指定，撤销指定组的所有标号。
返回列表，如果标号被成功撤销，对应项设为 0，如果失败设为 -1。
示例:
" 从缓冲区 a.vim 撤销带 id 10 的标号，从缓冲区 b.vim
" 撤销带 id 20 的标号
call sign_unplacelist([
\ {'id' : 10, 'buffer' : "a.vim"},
\ {'id' : 20, 'buffer' : 'b.vim'},
\ ])
也可用作 method :
GetSignlist()->sign_unplacelist()
vim:tw=78:ts=8:noet:ft=help:norl: