Génération de fichiers d'aide pour vim

8

Actuellement, j'écris ma documentation directement sous forme de fichiers d'aide vim. Parfois, j'ai besoin de générer d'autres formats (par exemple PDF). Mon flux de travail consiste à copier le contenu des fichiers d'aide et à les transformer en quelque chose dont j'ai besoin. C'est un travail assez fastidieux, car je dois surtout ajouter du balisage supplémentaire.

J'aime l'approche de Markdown, qui peut (par exemple en utilisant Pandoc) être transformée en une variété de formats de sortie. Malheureusement pas les fichiers d'aide vim. Je recherche un convertisseur qui prend un format d'entrée standard (par exemple XML, Markdown, texte reStructed, texte brut,…) et génère un fichier d'aide vim. Ou existe-t-il d'autres moyens de générer automatiquement des fichiers d'aide vim sans écrire moi-même un tel convertisseur?

vim Marco
la source
Vous pourriez probablement créer une feuille de style XSLT en quelques heures.
Ignacio Vazquez-Abrams

Réponses:

11

Désolé d'avoir ressuscité un très vieux fil. Je suis l'auteur du mkd2vimdocscript derrière le premier lien suggéré précédemment par lornix . J'ai récemment réécrit à mkd2vimdocpartir de zéro en html2vimdoc . Il prend toujours en charge Markdown comme format d'entrée; il convertira Markdown en HTML, puis convertira ce HTML en fichier d'aide Vim. Pendant la réécriture, l'accent a été mis sur la prise en charge d'une plus large gamme de documents d'entrée.

Le nouveau script est utilisé par moi-même et plusieurs autres auteurs de plug-ins, il est donc certainement destiné à un usage général. Si vous souhaitez réessayer, j'aimerais savoir si cela fonctionne mieux pour les documents sur lesquels vous souhaitez l'utiliser. Si cela ne fonctionne toujours pas, n'hésitez pas à créer un problème sur GitHub.

xolox
la source
3
Bienvenue sur SuperUser! Répondre aux anciennes questions est apprécié ici, certaines personnes peuvent toujours chercher des réponses à celles-ci et il est bon d'améliorer les anciennes.
gronostaj
4

J'ai trouvé ce script, que l'auteur a créé pour convertir le markdown en documentation vim. Cela semble très proche de ce que vous recherchez.

Alors que ce script vim.org ( github repo ) convertit le démarque en ce qui ressemble à presque tout MAIS vimdoc. (soupir) Si près ... peut-être une légère modification?

lornix
la source
Le premier script est inutilisable pour une utilisation générale. Cela pourrait fonctionner pour le style de balisage des auteurs, mais il n'a pas converti correctement un seul de mes fichiers de balisage (valides). La deuxième option est pandoc, un convertisseur très performant que j'aime beaucoup. Malheureusement, il ne prend pas en charge vimhelp. J'ai demandé sur la liste de diffusion d'ajouter un support pour cela, mais la réponse a été que vimhelp n'est pas un format de sortie à usage général mais un format spécialisé destiné à la documentation de vim, contrairement aux autres formats pris en charge. Quoi qu'il en soit, merci beaucoup pour le conseil.
Marco
Je suis curieux de savoir ce que cela pourrait impliquer de créer un convertisseur de markdown en vimdoc, car la plupart des vimdoc sont du formatage et des caractères marqueurs spéciaux, tandis que la magie est effectuée par la commande helptags et le visualiseur d'aide vim lui-même. Bien sûr, je pourrais mettre mon pied dans ma bouche (encore!) ... cela dépend peut-être de la complexité de votre démarque initiale.
lornix
Une solution de contournement intelligente suggérée sur la liste de diffusion était de créer vimhelp qui est également une démarque valide. L'inconvénient est que la démarque est un peu encombrée de syntaxe vim et que les fichiers vimhelp n'obéissent pas aux conventions de formatage. Mais en dehors de cela, il est utilisable.
Marco