gutter refactoring

docs/editor.md

@@ -83,6 +83,7 @@ api.editor:clear_tab_icon(1)             -- снова "file"
 | `api.editor:clear_gutter_kind(kind)` | Убрать иконки типа во всех строках активной вкладки; возвращает число удалённых |
 | `api.editor:clear_gutter()` | Убрать все иконки активной вкладки |
 | `api.editor:on_gutter_click(kind, callback)` | Назначить обработчик клика по иконке типа `kind`; `callback(line, icon, kind)`. `nil` вместо функции снимает обработчик |
+| `api.editor:on_gutter_shift(kind, callback)` | Назначить обработчик переноса иконки типа `kind`; `callback(kind, old_line, new_line)`. Вызывается для каждой иконки, чья строка съехала после правки текста. `nil` снимает обработчик |
 
 ```lua
 api.editor:set_gutter_icon(4, "circle", "diagnostics", { color = "#e5484d" })
@@ -96,15 +97,24 @@ api.editor:on_gutter_click("breakpoint", function(line, icon, kind)
     print("клик", line, icon, kind)
 end)
 
+api.editor:on_gutter_shift("breakpoint", function(kind, old_line, new_line)
+    print("иконка уехала", kind, old_line, new_line)
+end)
+
 api.editor:clear_gutter_icon(4, "diagnostics") -- только один тип строки
 api.editor:clear_gutter_kind("diagnostics")  -- перерисовать только диагностику
 api.editor:clear_gutter_line(4)              -- все иконки строки
 api.editor:clear_gutter()                    -- все иконки вкладки
 ```
 
-Иконки привязаны к номерам строк и автоматически не сдвигаются при правке
-текста: сценарий сам решает, когда их переставить. При прокрутке колонка
-двигается вместе с редактором.
+Иконки привязаны к началу своей строки и едут вместе с ней: если правка
+вставила или удалила строки выше иконки, она сдвигается на столько же строк.
+Правка внутри строки без изменения их числа номера не меняет. Вставка ровно
+в начало строки относится к её содержимому — иконка едет вместе с текстом.
+Чтобы узнать о переносе, сценарий назначает `on_gutter_shift`. При прокрутке
+колонка двигается вместе с редактором. Внешняя замена всего текста через
+`api.editor:set_active_text` сбрасывает иконки активной вкладки: их номера
+строк относятся к старому тексту.
 
 ## Текст