Pregunta:
Son dos preguntas en una. Últimamente he pasado mucho tiempo aprendiendo vimscript en profundidad, aprendiendo los aspectos internos de vim y dando mis primeros pasos escribiendo complementos de vim. Durante este proceso, he estado guardando notas extensas en archivos de rebajas individuales y agregué muchos comentarios de 'documentación' en línea a los archivos de vimscript.
Siento que finalmente tengo un código que vale la pena compartir y quiero comenzar a agregar documentación real . Todavía no he creado ninguno de mis propios archivos de helpdoc, así que todavía estoy averiguando ese proceso.
Sin ninguna experiencia todavía o una comprensión sólida de este flujo de trabajo, hay dos tareas que estoy tratando de resolver:
- Generando archivos de helpdoc a partir de mis archivos de 'notas' de rebajas en vim / vimscript, para que pueda leer / hacer referencia rápida y fácilmente desde vim en cualquier momento.
- Analizar la documentación en línea de mis archivos vimscript (similar a la forma en que shocco funciona para scripts de shell) para generar el documento de ayuda asociado para los vimscripts.
Cualquier sugerencia o consejo sobre las ideas ( esta es una mala idea porque …, una mejor idea es … ), o cómo llevarlas a cabo, será muy apreciado.
Respuesta:
Hasta donde yo sé, actualmente no existe una buena solución para ninguno de los problemas, pero mucha gente estaría interesada en resolverlos.
Markdown es un superconjunto de HTML, por lo que diría que es poco probable que un enfoque frontal para la conversión de Markdown a la ayuda de Vim tenga éxito. Si puede hablar Haskell, podría intentar escribir un backend de ayuda de Vim para pandoc . Esa sería una solución muy buena incluso si no es perfecta.
Ha habido algunos intentos de hacerlo al revés, convertir las páginas de ayuda de Vim a algún formato útil. Hay algunos scripts flotando que producen versiones HTML y PDF de la ayuda oficial, con diversos grados de éxito. Pero todos confían en que la ayuda sea de estilo más o menos homogéneo. Incluso un lector de ayuda de Vim para algo como pandoc sería un proyecto valioso.
En cuanto a la extracción de documentación del código de Vim, hay un analizador para VimL en Python, JavaScript y VimL mismo, llamado vimlparser . Es bastante bueno, no debería ser difícil escribir algo que analice las fuentes de VimL y arroje comentarios especiales elaborados. Ser capaz de convertir estos comentarios en algo como, por ejemplo, POD también sería muy útil.