Leer la ayuda (la habilidad que no caduca)

La lección anterior te dio un idioma. Esta te da el diccionario, y el orden importa: sin él dependerás para siempre de que alguien haya escrito un tutorial sobre tu problema, con tu versión y en tu idioma. Neovim trae cerca de un millón de palabras de documentación en tu disco, escritas por quienes implementaron cada función, versionadas junto al código que describen y disponibles sin conexión. El problema nunca fue que faltara información: es que la ayuda tiene un sistema de nombres que nadie te explica, y sin él parece que no encuentra nada.

• Resolver el nombre exacto del tag de un comando, una opción, un modo o un patrón.
• Distinguir :h o_v de :h v_o y saber por qué son dos páginas distintas.
• Navegar la documentación con Ctrl-], Ctrl-o y gO.
• Buscar por texto con :helpgrep cuando no conoces el vocabulario.
• Identificar las páginas que resuelven el 90% de las dudas de una versión nueva.

Por qué esto va antes que cualquier plugin

Un tutorial de 2023 te enseña require('lspconfig').lua_ls.setup{}. Hoy eso ya no es la forma. Un vídeo de hace ocho meses te enseña nvim-treesitter.configs, un módulo que ya no existe. Casi todo lo escrito sobre Neovim describe una versión que ya no tienes, y no porque esté mal escrito: describe un editor que cambió debajo.

:help no tiene ese problema, y la razón es estructural: se instala con el binario. La ayuda que abres no es «la documentación de Neovim», es la documentación de tu Neovim. Si tienes 0.12.4, :h vim.pack existe; si tienes 0.11, no, y el editor te lo dirá en vez de enseñarte algo que no puedes usar. Ninguna página web puede darte esa garantía.

El reflejo que separa a los dos tipos de usuario

Hay quien, cuando algo no funciona, abre el navegador. Y hay quien pulsa :h y el nombre de lo que falla.

El primero depende de que alguien haya escrito sobre su problema, con su versión, en su idioma, y de saber distinguir un artículo de 2021 de uno de este mes. El segundo tiene la respuesta en dos segundos, siempre, y sin margen de que esté caducada. Esa diferencia no se nota el primer día; a los seis meses es abismal.

Cómo está construida la ayuda

Antes de buscar conviene saber qué estás buscando dentro de.

La documentación son ficheros de texto plano en $VIMRUNTIME/doc/. Cada uno define tags —marcadores— escribiéndolos entre asteriscos, así: *ciw*. Al arrancar, un fichero doc/tags indexa todos y los asocia a su fichero y su línea. Cuando escribes :h ciw, el editor busca ciw en ese índice y salta ahí. No hay servidor, no hay búsqueda difusa: hay una tabla de nombres exactos.

De ahí salen las dos consecuencias que gobiernan todo lo demás. La primera es que el nombre importa: :h no adivina, resuelve. La segunda es que el sistema es extensible: cualquier plugin que traiga un doc/ con sus propios tags entra en el mismo índice y se consulta con el mismo :h. La documentación de tus plugins vive en el mismo sitio que la del editor, y vim.pack regenera ese índice por ti cada vez que instala o actualiza algo.

Las palabras que ves entre barras verticales, como |fold-methods|, son referencias a esos tags. Son enlaces, y se siguen.

Los prefijos: la clave de todo

Aquí está lo que hace que la gente crea que la ayuda «no encuentra nada». La misma tecla significa cosas distintas en cada modo, así que el índice no puede tener una sola entrada o. Cada modo tiene su prefijo:

Fíjate en el par del medio, porque no es un ejemplo cualquiera. :h v_o es «en Visual, la tecla o»: salta al otro extremo de la selección. :h o_v es «en operador-pendiente, la tecla v»: fuerza que la operación sea por caracteres, justo lo que usaste en dvj en la lección anterior. Mismas dos letras, orden distinto, dos páginas que no se parecen en nada. Si alguna vez te ha dado la sensación de que la ayuda te lleva a un sitio random, casi siempre es esto.

Y hay tres familias más que no son modos pero funcionan igual:

Las comillas de las opciones no son decorativas

:h number te lleva a la ayuda sobre números de línea en general. :h 'number' te lleva a la opción: qué hace, su valor por defecto, si es global o local, y a qué otras afecta.

Regla práctica: si es algo que se pone con vim.o o vim.opt, ponle comillas simples. Sin ellas casi nunca llegas.

No adivines el nombre: complétalo

En la línea de comandos, escribe :h y parte del término y pulsa Tab para completar, o Ctrl-d para ver todas las entradas que empiezan así.

:h fold + Ctrl-d lista fold-methods, 'foldlevel', 'foldexpr', fold-commands… Es la forma de descubrir qué existe sobre un tema del que aún no conoces el vocabulario. Y desde 0.12 los propios buffers de ayuda tienen omnicompletado, así que Ctrl-x``Ctrl-o dentro de la ayuda también te propone tags.

Cómo se lee una página

Encontrar la página es media batalla; la otra media es que la documentación tiene una notación propia, consistente en sus casi un millón de palabras, que nadie te explica y que hace que una entrada de tres líneas parezca críptica.

Mira una entrada real:

["x]["y]{count}d{motion}

Cada símbolo significa algo exacto:

Y hay una línea que aparece bajo muchas funciones y que resuelve la mitad de las dudas de compatibilidad:

Attributes: ~    Since: 0.11.0

Cuando la veas, tienes la respuesta a «¿esto existe en mi versión?» sin buscar en ningún sitio.

Los códigos de error son tags, y casi nadie lo sabe

Este es el truco de mayor rendimiento de toda la lección, y cabe en una línea.

Cuando Neovim te escupe algo como E128: Function name must start with a capital, ese E128 no es un identificador interno para los desarrolladores: es un tag de la documentación. Escribe :h E128 y llegas al párrafo exacto que explica qué significa, en qué situación se produce y qué hacer.

Piensa en lo que eso cambia. En cualquier otra herramienta, un código de error es el comienzo de una búsqueda: lo copias, lo pegas en el navegador, lees tres respuestas de foro de distinta antigüedad y decides a cuál hacerle caso. Aquí es el final: dos segundos, sin salir del editor, en la versión que tienes, escrito por quien puso el error ahí.

Y hay un segundo orden que merece la pena ver. Para que eso funcione, alguien tuvo que decidir que cada mensaje de error lleva un identificador estable y documentado, y sostener esa decisión durante décadas y miles de mensajes. Es trabajo puro de disciplina, invisible cuando está y desesperante cuando falta —piensa en la última vez que un programa te dijo «algo ha salido mal» y te dejó ahí—. Un identificador estable convierte un mensaje en una dirección: algo a lo que se puede enlazar, buscar y documentar. Sin él, el texto del error es solo una frase, y las frases cambian, se traducen y se reescriben.

Es el mismo motivo por el que los compiladores buenos numeran sus diagnósticos, por el que las especificaciones numeran sus secciones y por el que los códigos de estado de HTTP siguen valiendo cincuenta años después. Cuando construyas algo que pueda fallar, la pregunta no es solo qué mensaje mostrar: es si ese fallo tiene un nombre por el que alguien pueda preguntar.

Moverse dentro de la ayuda

Ctrl-] y Ctrl-o son el «ir a definición» y el «atrás» de un navegador, y no son exclusivos de la ayuda: son el mecanismo de tags de Vim, el mismo que usarás sobre tu código en cuanto tengas LSP. Practicarlos aquí es practicarlos para todo el editor, que es la razón de que esta lección esté en el Nivel 0 y no perdida en un apéndice.

gO merece un párrafo propio porque casi nadie lo conoce: abre un índice de secciones de la página que estás leyendo y te deja saltar a cualquiera. En ficheros de ayuda de tres mil líneas —options.txt, lsp.txt— es la diferencia entre leer y buscar a ciegas. Y es la misma tecla que en el Nivel 3 te dará el esquema de símbolos de un fichero de código vía LSP.

Cuando no sabes cómo se llama

:helpgrep busca dentro del texto de todas las páginas, no en los nombres de los tags:

:helpgrep carga perezosa:copen                      " abre la lista de resultados

Los resultados van a la quickfix, así que se recorren con :cnext y :cprev, o con ]q y [q, que vienen mapeados de serie desde 0.11. Es la misma lista que recibirá los errores del compilador y las referencias del LSP: en Neovim casi todo lo que produce «una lista de sitios a los que ir» acaba ahí, y aprender a manejarla una vez sirve para todas. Si prefieres no pisar la quickfix global, :lhelpgrep hace lo mismo sobre la lista local de la ventana.

La línea de comandos también se edita

Cuando lleves un rato, escribirás comandos largos: un :helpgrep con varias palabras, un :substitute complicado. Pulsa q: en modo Normal y se abre la ventana de línea de comandos: un buffer normal con tu historial de comandos, donde te mueves y editas con toda la gramática que ya sabes. Enter ejecuta la línea del cursor.

q/ hace lo mismo con el historial de búsquedas, y desde la propia línea de comandos se llega con Ctrl-f. Es de lo más útil que tiene el editor y de lo menos conocido; en el Nivel 1 lo usarás en serio con :substitute. Se cierra con :q, como cualquier ventana.

Las siete páginas que conviene abrir una vez

:h help-summary

Cómo está organizada la propia ayuda y cómo buscar en ella. Es esta lección, escrita por el proyecto.

:h index

Todas las teclas de todos los modos, con lo que hacen. La respuesta a «¿está libre esta tecla?».

:h quickref

La chuleta oficial: los comandos y opciones más usados, en una sola página.

:h news

Qué cambió en tu versión, qué se rompió y qué se deprecó. La primera página tras cada actualización.

:h deprecated

Qué ya no debes usar y por qué alternativa cambiarlo. Explica la mitad de los avisos que verás.

:h vim_diff

En qué se aparta Neovim de Vim, incluidos los defaults que ya trae puestos.

:h lua-guide

Lua dentro de Neovim, de principio a fin. El punto de entrada a vim.api, vim.fn y vim.opt.

Dos de esas siete cambian cómo trabajas, y no son las que parecen.

:h index merece una visita consciente. Cuando en el Nivel 2 empieces a repartir atajos, saber que s, S, Y, x y gc ya tienen dueño te evita el fallo más común de las configuraciones ajenas: pisar un comando nativo y no enterarte hasta meses después, cuando lo necesites y no esté.

:h news es la página que convierte una actualización de versión en veinte minutos de lectura en vez de en tres semanas de sorpresas. Ahí está, por ejemplo, que i_CTRL-R ahora inserta los registros literalmente, o que la clave buffer de los autocomandos pasó a llamarse buf. Ninguna de las dos cosas te dará un error: te darán un comportamiento distinto sin avisar.

El manual de usuario es un curso entero

Además de la referencia, Neovim trae un manual narrativo: :h user-manual, cuarenta y cinco capítulos numerados de usr_01 a usr_45, pensados para leerse en orden. :h usr_10 es «hacer cambios grandes», :h usr_12 son «trucos inteligentes», :h usr_29 es «moverse por los programas». Es el temario canónico del que descienden todos los cursos, incluido este.

No hace falta leerlo entero. Pero si alguna lección de esta guía te sabe a poco, ahí está el capítulo que la desarrolla.

Ayuda para Lua y para la API

Las funciones de Lua se buscan con sus paréntesis:

:h vim.keymap.set():h nvim_buf_set_lines():h vim.lsp.config():h vim.system()

Y dentro de un fichero Lua, con el cursor sobre una función de la API, K abre su documentación directamente. Es el mismo K que con LSP te enseñará la firma de cualquier símbolo de tu código: el editor reusa la tecla porque la pregunta es la misma —«¿qué es esto que tengo debajo?»— y solo cambia quién la contesta.

:checkhealth se lee como la ayuda, pero no es documentación

:checkhealth genera un informe de qué le falta a tu instalación: binarios ausentes, versiones incompatibles, opciones mal puestas. Se abre en un buffer con la misma navegación —gO para el índice, Ctrl-] para los enlaces— y admite argumento: :checkhealth vim.lsp mira solo esa parte.

Entre :h y :checkhealth se resuelve la inmensa mayoría de los problemas antes de que llegues a abrir el navegador. El primero dice cómo debería funcionar; el segundo, qué falta en tu máquina para que funcione.

Sin el prefijo v_ acabarías en la o de modo Normal, que abre una línea nueva. El prefijo es lo único que las distingue.

Ctrl-d lista las entradas que empiezan por lo escrito. Sirve para explorar un tema del que no sabes el vocabulario.

Con comillas simples. Sin ellas no llegas a la opción, sino a una página sobre desplazamiento.

gO abre el índice de secciones de la página actual. Es la misma tecla que da el esquema de un fichero con LSP.

La ventana de línea de comandos es un buffer normal con tu historial. Te mueves con j y k, editas con ciw, y Enter ejecuta.

Los códigos de error son tags de la documentación. Es el final de la búsqueda, no el principio.

:helpgrep busca dentro del texto, no en los títulos, y deja los resultados en la quickfix.

Documentación que se instala, no que se consulta

Merece la pena aislar por qué esto funciona tan bien, porque la respuesta no es «la gente de Vim escribe bien» —que también—, sino una decisión de diseño que casi ninguna herramienta moderna toma.

La documentación de Neovim se versiona con el código y se distribuye con el binario. No es un sitio web al que apuntas: es un artefacto que viaja dentro del programa. Eso tiene tres consecuencias que ningún portal de documentación puede replicar. No puede desincronizarse, porque el mismo commit que cambia la función cambia su página. No puede caerse, ni tapiarse tras un login, ni desaparecer cuando la empresa pivote. Y no puede mentirte sobre tu versión, porque solo conoce la tuya. La web te ofrece la documentación de la versión más popular; el disco te ofrece la de la que estás ejecutando, que es la única que te sirve.

El patrón tiene nombre viejo y sigue siendo minoritario. Las páginas man y info lo hacen. Los docstrings de Python, los /// de Rust que alimentan a cargo doc, el go doc. Los RFC. En todos, la fuente de verdad está pegada a lo que describe, y las copias en internet son eso, copias. Frente a eso está el modelo dominante hoy: la documentación como sitio web, mantenida por un equipo distinto al que escribe el código, con su propio ciclo de despliegue, y complementada por un sedimento de blogs, respuestas de foro y vídeos que nadie actualiza y que los buscadores siguen sirviendo cinco años después con el mismo aspecto de recién hecho.

Ese sedimento es el problema real. No es que haya poca información sobre Neovim: es que hay demasiada y sin fecha visible. Cuando aprendes a resolver un tag en dos segundos, no estás ganando velocidad —estás cambiando de fuente—, y esa es una decisión que se paga sola. La habilidad que acabas de adquirir no caduca porque no es sobre Neovim: es sobre preferir la fuente que se instala a la fuente que se busca, y esa preferencia te servirá igual el día que tengas que entender una librería que nadie ha blogueado nunca.

Que la ayuda sea el primer sitio, no el último

1. Abre :h help-summary y léela entera. Son cinco minutos y te ahorra meses.
2. Busca :h o_v y comprueba que es exactamente lo que hiciste con dvj en la lección anterior. Luego busca :h v_o y comprueba que no tienen nada que ver.
3. Abre :h index, busca la sección de modo Normal y localiza s, S e Y. Las tres están ocupadas. Recuérdalo cuando empieces a mapear teclas.
4. Ejecuta :h news y busca la sección de cambios que rompen. Localiza qué le pasó a i_CTRL-R en 0.12: es un cambio de comportamiento que no da ningún error.
5. Verifica lo que dice la lección sobre la extensibilidad: ejecuta :h vim.pack y luego :h local-additions. La segunda lista la documentación que han aportado tus plugins al mismo índice.
6. Con :h 'undofile' averigua qué hace esa opción antes de que la config del Nivel 2 te la ponga.
7. Sigue un enlace con Ctrl-] y vuelve con Ctrl-o. Repítelo hasta que sea automático: son las mismas teclas que usarás para navegar tu código.