Wie erstelle ich Vim-Dokumentation aus Markdown-Notizen oder Inline-Kommentaren oder gibt es bessere Möglichkeiten, Dokumentation hinzuzufügen?

Dies ist Art von zwei Fragen in einem. In letzter Zeit habe ich viel Zeit damit verbracht, Vimscript gründlich zu lernen, die internen Aspekte von Vim zu lernen und meine ersten Schritte beim Schreiben von Vim-Plugins zu unternehmen. Während dieses Prozesses habe ich ausführliche Notizen in einzelnen Markdown-Dateien erstellt und den Vimscript-Dateien zahlreiche Inline-Kommentare zur Dokumentation hinzugefügt.

Ich habe das Gefühl, dass ich endlich einen Code habe, der es wert ist, geteilt zu werden, und ich möchte damit beginnen, einige aktuelle Dokumentationen hinzuzufügen . Ich habe noch keine eigenen Hilfedokumente verfasst, daher finde ich diesen Prozess immer noch heraus.

Ohne Erfahrung oder solides Verständnis für diesen Workflow gibt es zwei Aufgaben, die ich herausfinden möchte:

1. Generieren von Helpdoc-Dateien aus meinen Markdown-Notizen-Dateien in vim / vimscript, sodass ich jederzeit schnell und einfach von vim aus lesen / referenzieren kann.
2. Analysieren Sie die Inline-Dokumentation aus meinen Vimscript-Dateien (ähnlich wie shocco für Shell-Skripte funktioniert), um das zugehörige Hilfedokument für die Vimscript- Dateien zu generieren.

Vorschläge oder Ratschläge zu den Ideen ( dies ist eine schlechte Idee, weil ..., eine bessere Idee ist ... ) oder wie man sie umsetzt, wären sehr dankbar.

Soweit ich weiß, gibt es derzeit keine gute Lösung für beide Probleme, aber viele Leute wären daran interessiert, sie zu lösen.

Markdown ist eine Obermenge von HTML, daher würde ich sagen, dass ein frontaler Ansatz für die Konvertierung von Markdown zu Vim-Hilfe wahrscheinlich nicht erfolgreich ist. Wenn Sie Haskell sprechen können, können Sie versuchen, ein Vim-Hilfe-Backend für Pandoc zu schreiben . Das wäre eine sehr schöne Lösung, auch wenn es nicht perfekt ist.

Es wurden einige Versuche unternommen, die Hilfeseiten von Vim in ein nützliches Format umzuwandeln. Es gibt ein paar Skripte, die HTML- und PDF-Versionen der offiziellen Hilfe mit unterschiedlichem Erfolg erzeugen. Sie alle sind jedoch darauf angewiesen, dass die Hilfe einen mehr oder weniger homogenen Stil aufweist. Selbst ein Vim- Hilfeleser für so etwas wie Pandoc wäre ein lohnendes Projekt.

Zum Extrahieren von Dokumentation aus Vim-Code gibt es einen Parser für VimL in Python, JavaScript und VimL selbst, der den Namen vimlparser trägt . Es ist ziemlich gut, es sollte nicht schwer sein, etwas zu schreiben, das VimL-Quellen analysiert und speziell gestaltete Kommentare ausgibt. In der Lage zu sein, diese Kommentare in so etwas wie POD umzuwandeln, wäre ebenfalls sehr nützlich.

html2vimdoc.py

Das vielversprechendste Tool, das ich gefunden habe, befindet html2vimdoc.pysich hier http://peterodding.com/code/vim/tools und auf github . Es kann Markdown und HTML in das Hilfeformat von vim konvertieren. Beworbene Funktionen sind:

• Es kann dank [BeautifulSoup] bs mit komplexem HTML umgehen
• Generiert automatisch Vim-Hilfedateitags für Überschriften
• Erzeugt ein Inhaltsverzeichnis aus Überschriften und Tags
• Unterstützt verschachtelte Blockstrukturen wie verschachtelte Listen, vorformatierte Blöcke in Listen usw.
• Komprimiert und erweitert Listenelemente basierend auf der durchschnittlichen Anzahl der Zeilen pro Listenelement

Eine ältere Alternative ist https://github.com/mklabs/vim-markdown-helpfile

Es gab auch eine Diskussion unter /superuser//q/415470/generating-help-files-for-vim