Leer la documentación: :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.

• Construir la etiqueta de ayuda correcta para opciones, funciones, comandos y teclas de cualquier modo.
• Moverte por el mapa de archivos: lua.txt, api.txt, options.txt, vimfn.txt, news, deprecated y vim_diff.
• Buscar con comodines y con :helpgrep cuando no conoces el nombre exacto.
• Diagnosticar comportamientos inesperados con :checkhealth, :messages y :verbose, en ese orden.

La documentación 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:

Los archivos usr_* enseñan y se leen en orden; los de referencia certifican y se consultan. Acudir al equivocado es la causa habitual de «no encontrar» lo que sí estaba escrito. Y los tres últimos de la tabla deberían ser rutina y casi nadie los abre: news después de cada actualización, deprecated cuando algo avise, y vim_diff cada vez que adaptes una respuesta de internet que fue escrita para el editor original.

La gramática 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 van entre comillas simples. Las funciones llevan sus paréntesis. Los comandos ex llevan los dos puntos delante. Las teclas de modos distintos del Normal llevan un prefijo de una letra y guion bajo: i_ para Insertar, v_ para Visual, c_ para la línea de comandos.

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

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 te ayuda: Tab completa las candidatas y CTRL-D las lista todas de golpe.

Dentro de la ayuda, la navegación es la de un hipertexto, con las mismas teclas que usas sobre código: CTRL-] salta a la etiqueta bajo el cursor, CTRL-T (o CTRL-O) te devuelve por donde viniste, y gO abre el índice del archivo. No es una coincidencia: es literalmente la pila de etiquetas de tags, el mismo mecanismo con el que saltas a definiciones.

Los ejemplos de la ayuda son ejecutables

Los bloques de Lua de la documentación se pueden evaluar sin salir de ella: coloca el cursor en la línea y ejecuta :.lua, que trata la línea actual como código Lua (:help :lua-heredoc cuenta el resto de variantes). Es la forma más rápida de comprobar si has entendido una firma antes de llevarla a tu configuración.

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 con comodines: :help *fold* seguido de Tab lista todas las etiquetas que contienen el fragmento, y muy a menudo el nombre aparece ahí a la primera.

El segundo es :helpgrep, la búsqueda global en toda la documentación: recorre cada archivo de ayuda y deposita las coincidencias en la quickfix. Es el instrumento adecuado cuando buscas un concepto y no un identificador, y encaja con todo el vocabulario que ya dominas de la lección 1.6.

El tercero es preguntar al editor en lugar de a la documentación, que es el tema de la lección 8.5 y aquí aparece solo como anticipo: vim.fn.getcompletion expone el motor de completado como función, de modo que obtener todas las opciones o todos los eventos que contienen una cadena es una llamada de una línea.

:help *fold*        " comodines en la etiqueta + Tab:helpgrep marca de columna:copen              " las coincidencias, en la quickfix

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 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, messages y verbose

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 —:checkhealth vim.lsp— para no leer el informe entero. Escribir el tuyo propio es trivial: un módulo health.lua dentro de tu espacio de nombres que use vim.health:

-- lua/mi/health.lualocal 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", { "instálalo con tu gestor de paquetes" })  endendreturn 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, nvim --startuptime registro.log 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 —lo explotarás a fondo en la lección 25.1.

Tercero, y es el instrumento más infravalorado de los tres, el prefijo :verbose. 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

La etiqueta es la dirección

Si sabes cómo se llama, sabes dónde está. La gramática de comillas, paréntesis, dos puntos y prefijos de modo convierte cualquier nombre en una consulta directa.

Referencia y manual no son lo mismo

Los archivos usr_* enseñan y se leen en orden; options.txt, api.txt y lua.txt certifican y se consultan. Acudir al equivocado es la causa habitual de no encontrar lo que sí estaba escrito.

La ayuda no es un manual, es el código fuente en prosa

Hay un cambio de actitud que separa a quien consulta la ayuda de quien la habita, y no tiene que ver con la velocidad de lectura sino con entender qué clase de texto es. Los archivos de la documentación de Neovim viven en el mismo repositorio que el código, se modifican en las mismas confirmaciones que cambian el comportamiento y se revisan con el mismo rigor. Cuando la entrada de una función dice que puede lanzar un error si el manejador no es válido, esa frase no la escribió un redactor técnico interpretando el código: la escribió quien implementó la comprobación, en el mismo momento en que la implementó. Por eso la ayuda contiene una categoría de información que ningún tutorial, ningún foro y ningún modelo de lenguaje pueden ofrecer con la misma autoridad: no solo lo que ocurre, sino lo que está garantizado que siga ocurriendo. Y de ahí se deduce la disciplina que conviene adoptar para el resto de tu vida con este editor. Cuando encuentres un fragmento de configuración en internet, no lo pegues: extrae de él los nombres, búscalos en la ayuda y lee sus dos o tres párrafos. Descubrirás con frecuencia que el fragmento hacía algo ligeramente distinto de lo que decía su título, que estaba escrito para el editor original y no para este, o que la función que usaba lleva dos versiones marcada como obsoleta con un reemplazo mejor documentado en la línea siguiente. Ese pequeño rodeo de treinta segundos es lo que convierte una configuración copiada en una configuración comprendida, y comprendida significa exactamente una cosa: que sabrás repararla tú cuando se rompa.

Debajo del nombre verás «global» o «local to window/buffer» y el defecto. Son las dos líneas que la lección 8.2 te enseñó a necesitar, y están siempre en el mismo sitio de cada entrada.

Los comodines listan etiquetas candidatas; :helpgrep busca en el texto completo y deja las coincidencias en la quickfix, donde ]q las recorre.

La última línea de la respuesta dice el archivo y la línea exactos. Si señala un plugin, ya sabes con quién negociar la tecla.

:.lua evalúa la línea actual como Lua. La ayuda pasa de texto que lees a laboratorio en el que pruebas.

Es el registro de novedades de tu versión exacta, escrito por quienes las implementaron. Su pareja es :help deprecated: lo que ya avisa de su retirada.

Convierte la ayuda en tu primer reflejo

1. Construye de memoria la etiqueta de ayuda de una opción, una función de Vimscript, una función de la API, un comando ex y una tecla de modo Insertar. Verifica las cinco con :help.
2. Elige tres líneas de tu configuración que copiaste sin entender. Localiza la entrada de ayuda de cada nombre implicado y resume en una frase qué garantiza.
3. Navega: entra en :help api, salta con CTRL-] a tres etiquetas encadenadas y vuelve al principio a golpe de CTRL-T. Abre el índice del archivo con gO.
4. Ejecuta :checkhealth completo y arregla todo lo que aparezca en rojo. Anota cuántos de esos problemas desconocías.
5. Usa :verbose set para averiguar qué archivo estableció tu valor actual de shiftwidth, y :verbose nmap sobre una tecla que use un plugin.
6. Escribe el módulo de salud de tu configuración con vim.health, comprueba que :checkhealth mi lo ejecuta, y añádele una comprobación real de una dependencia externa que uses.