Leer la documentacion: help como fuente de verdad

Hay una diferencia de método, no de talento, entre quien resuelve un problema de Neovim en dos minutos y quien pasa la tarde probando fragmentos copiados de foros. La persona rápida no ha memorizado más: sabe que la respuesta está en :help, sabe construir la etiqueta exacta que lleva hasta ella y sabe interpretar lo que lee como lo que es, una especificación normativa y no una guía amable. La documentación de Neovim vive en el mismo repositorio que el código, la escriben quienes implementan los cambios y se versiona con ellos. Es la única fuente que no envejece por su cuenta, y aprender a navegarla es probablemente la habilidad de mayor rendimiento de todo este nivel.

La documentacion como contrato

La ayuda no describe lo que el editor suele hacer: describe lo que se compromete a hacer. Esa distinción tiene consecuencias prácticas. Cuando la entrada de una función de la API dice que los índices empiezan en cero y que el final del rango es exclusivo, eso no es una observación sobre la implementación actual sino una garantía que sobrevivirá a las próximas versiones. Cuando dice que una opción es de buffer, ese ámbito es parte del contrato. Y cuando una función está marcada como obsoleta, la marca incluye desde qué versión lo está y qué la sustituye.

Experimentar en el editor te dice lo que ocurre hoy en tu máquina. La documentación te dice además lo que seguirá ocurriendo, y esa es la diferencia entre una configuración que aguanta tres actualizaciones y una que se rompe con la primera.

Hay un segundo motivo, menos obvio, para preferirla a la experimentación: la ayuda documenta también los casos que no puedes provocar fácilmente. Qué ocurre si el manejador de buffer ya no es válido, qué pasa cuando el rango excede el número de líneas, cómo se comporta la función si el archivo no existe. Reproducir cada uno de esos casos a mano cuesta más que leer el párrafo que los describe, y omitirlos es exactamente lo que convierte una configuración en frágil.

Conviene conocer el mapa antes de moverse por él. El archivo de la biblioteca de Lua contiene la guía de introducción y el catálogo de módulos. El de la API documenta cada función nvim_ con sus parámetros y sus errores. El de opciones tiene una entrada por opción, con su ámbito y su valor por defecto. El de funciones incorporadas cubre todo lo accesible desde vim.fn. Los archivos del manual de usuario, con nombres que empiezan por las siglas correspondientes, son pedagógicos y se leen en orden; los de referencia son normativos y se consultan. Y hay tres que casi nadie abre y deberían ser rutina: el de novedades de cada versión, el de elementos obsoletos y el de diferencias respecto de Vim, indispensable este último cuando adaptas una respuesta encontrada en internet que fue escrita para el editor original.

La gramatica de las etiquetas

Todo lo documentado tiene una etiqueta, y las etiquetas siguen una gramática que puedes aplicar sin buscar. Dominarla convierte el nombre de cualquier cosa en su dirección exacta.

Las opciones se escriben entre comillas simples. Las funciones llevan sus paréntesis vacíos. Los comandos ex llevan el carácter de dos puntos delante. Las funciones de la API se nombran con su identificador completo. Las teclas de modos distintos del normal llevan un prefijo de una letra y un guion bajo, y las de secuencia también se escriben con su prefijo.

:help 'scrolloff'          " opcion, entre comillas simples
:help getline()            " funcion de Vimscript
:help nvim_buf_set_lines() " funcion de la API
:help :bufdo               " comando ex
:help i_CTRL-W             " CTRL-W en modo Insercion
:help v_u                  " la tecla u en modo Visual
:help c_CTRL-R             " CTRL-R en la linea de comandos
:help g_CTRL-A             " secuencia que empieza por g
:help vim.opt              " modulo de la biblioteca de Lua

La consecuencia práctica es que casi nunca hace falta buscar: si sabes cómo se llama algo, sabes dónde está documentado. Y si dudas de la etiqueta exacta, la línea de comandos completa con la tecla de tabulación y lista todas las candidatas con la combinación de listado.

Dentro de la ayuda, la navegación es la de un hipertexto. La combinación de corchete de cierre con la tecla de control salta a la etiqueta bajo el cursor; la de la letra te devuelve por donde viniste; el mismo mecanismo de la pila de etiquetas que usas para saltar a definiciones en tu código funciona idéntico aquí, porque es literalmente el mismo mecanismo.

Buscar cuando no sabes el nombre

El caso difícil es el otro: sabes qué quieres conseguir pero no cómo se llama. Para eso hay tres instrumentos, en orden creciente de fuerza bruta.

El primero es el completado de la propia ayuda, que acepta comodines. Escribir un fragmento con un asterisco delante y detrás lista todas las etiquetas que lo contienen, y muy a menudo el nombre aparece ahí a la primera.

El segundo es la búsqueda global en toda la documentación, que recorre cada archivo y deposita las coincidencias en la lista de correcciones rápidas. Es el instrumento adecuado cuando buscas un concepto y no un identificador, y encaja con todo el flujo de trabajo de esa lista que ya conoces.

El tercero es preguntar al editor en lugar de a la documentación, que es el tema de la lección siguiente y que aquí aparece solo como anticipo: el motor de completado de la línea de comandos puede consultarse desde Lua, de modo que obtener la lista de todas las opciones o de todos los eventos que contienen una cadena es una llamada de una línea.

:help *fold*        " comodines en la etiqueta
:helpgrep marca de columna
:copen              " las coincidencias, en la lista de correcciones

Merece la pena añadir un hábito que casi nadie adopta y que multiplica el rendimiento de la ayuda: leer la entrada entera, no la primera línea. Las entradas de opciones incluyen su ámbito, su valor por defecto, sus interacciones con otras opciones y, con frecuencia, una advertencia sobre el caso límite que estás a punto de encontrarte. Las entradas de funciones de la API terminan casi siempre con una sección de parámetros y otra de valores devueltos que resuelven de golpe la duda que te llevó allí. Buscar la línea exacta y salir corriendo desperdicia el ochenta por ciento del texto útil.

Diagnosticar: checkhealth, verbose y messages

Cuando algo no funciona, la secuencia eficiente tiene un orden y saltárselo cuesta tiempo.

Primero, :checkhealth. El sistema de salud recolecta comprobaciones declaradas por el propio Neovim y por cada plugin instalado, y las ejecuta produciendo un informe con tres niveles de severidad y, lo más valioso, con instrucciones concretas de remedio. Se puede acotar a un componente para no leer el informe entero. Escribir el tuyo propio es trivial: un módulo con nombre de salud dentro de tu plugin que use las funciones de inicio, éxito, aviso y error del módulo correspondiente.

-- lua/mi/health.lua
local M = {}

function M.check()
  vim.health.start("mi configuracion")
  if vim.fn.executable("rg") == 1 then
    vim.health.ok("ripgrep encontrado")
  else
    vim.health.error("falta ripgrep", { "instalalo con tu gestor de paquetes" })
  end
end

return M

Segundo, :messages. Un error que se imprimió durante el arranque y desapareció bajo la pantalla de inicio sigue estando ahí. Es sorprendente la cantidad de problemas que se diagnostican en el primer minuto simplemente leyendo lo que el editor ya había dicho. Cuando el fallo solo aparece al arrancar, el argumento de línea de órdenes que registra la traza de carga produce un archivo con todo lo que se ejecutó y en qué orden, que es la única forma fiable de saber quién llegó antes en una carrera entre plugins.

Tercero, y es el instrumento más infravalorado de los tres, el prefijo de verbosidad. Anteponerlo a una consulta de opción o de mapeo hace que Neovim indique el archivo y la línea exactos donde se estableció ese valor. Ante la pregunta de quién ha cambiado esta opción, o qué plugin ha secuestrado esta tecla, es la respuesta directa en lugar de una búsqueda a ciegas por el directorio de configuración.

:verbose set shiftwidth?
:verbose nmap <leader>f
:verbose autocmd BufWritePre

flowchart TB
X[Algo no funciona] --> H[checkhealth del componente]
H --> M[messages para errores ya impresos]
M --> V[verbose set o verbose map]
V --> D[help de la etiqueta exacta]
D --> N[news y deprecated de tu version]
N --> F[Correccion con contrato conocido]
style H fill:#f9e2af,color:#11111b
style F fill:#a6e3a1,color:#11111b