Bagaimana cara menghasilkan dokumentasi Vim dari catatan Markdown atau komentar sebaris, atau adakah cara yang lebih baik untuk menambahkan dokumentasi?

Ini adalah jenis dua pertanyaan dalam satu. Akhir-akhir ini saya telah menghabiskan banyak waktu untuk mempelajari vimscript secara mendalam, mempelajari internal vim & mengambil langkah pertama saya menulis plugin vim. Selama proses ini, saya telah menyimpan catatan luas dalam file penurunan harga individu & menambahkan banyak komentar 'dokumentasi' sebaris ke file vimscript.

Saya merasa akhirnya saya punya beberapa kode yang layak dibagikan, dan ingin mulai menambahkan beberapa dokumentasi yang sebenarnya . Saya belum menulis file helpdoc saya sendiri, jadi saya masih mencari tahu proses itu.

Tanpa pengalaman atau pemahaman yang solid tentang alur kerja ini, ada dua tugas yang saya coba cari tahu:

1. Menghasilkan file helpdoc dari file 'catatan' penurunan harga saya di vim / vimscript, sehingga saya dapat membaca / referensi dengan cepat & mudah dari vim kapan saja.
2. Parsing dokumentasi inline dari file vimscript saya (mirip dengan cara shocco bekerja untuk skrip shell) untuk menghasilkan helpdoc terkait untuk vimscript.

Setiap saran atau saran tentang ide-ide ( ini adalah ide yang buruk karena ..., ide yang lebih baik adalah ... ), atau cara mencapainya akan sangat dihargai.

Sejauh yang saya tahu saat ini tidak ada solusi yang baik untuk masalah tersebut, tetapi banyak orang akan tertarik untuk menyelesaikannya.

Penurunan harga adalah superset dari HTML, jadi saya akan mengatakan pendekatan frontal untuk konversi dari penurunan harga ke bantuan Vim tidak mungkin berhasil. Jika Anda dapat berbicara bahasa Haskell, Anda bisa mencoba menulis backend bantuan Vim untuk pandoc . Itu akan menjadi solusi yang sangat bagus bahkan jika itu tidak sempurna.

Ada beberapa upaya untuk melakukan hal sebaliknya, mengonversi halaman bantuan Vim ke beberapa format yang bermanfaat. Ada beberapa skrip yang beredar yang menghasilkan versi HTML dan PDF dari bantuan resmi, dengan berbagai tingkat keberhasilan. Tetapi mereka semua bergantung pada bantuan yang kurang lebih homogen dalam gaya. Bahkan Vim membantu pembaca untuk sesuatu seperti pandoc akan menjadi proyek yang bermanfaat.

Adapun mengekstraksi dokumentasi dari kode Vim, ada parser untuk VimL di Python, JavaScript, dan VimL itu sendiri, bernama vimlparser . Ini cukup bagus, seharusnya tidak sulit untuk menulis sesuatu yang mem-parsing sumber VimL dan mencampakkan komentar khusus yang dibuat. Mampu mengubah komentar ini menjadi sesuatu seperti, katakanlah, POD akan sangat berguna juga.

html2vimdoc.py

Alat paling menjanjikan yang saya temukan adalah html2vimdoc.pyyang dapat ditemukan di sini http://peterodding.com/code/vim/tools dan di github . Itu dapat mengonversi markdown dan html ke format bantuan vim. Fitur yang diiklankan adalah:

• Itu dapat menangani HTML yang kompleks berkat [BeautifulSoup] bs
• Secara otomatis menghasilkan tag file bantuan Vim untuk pos
• Menghasilkan daftar isi dari pos & tag
• Mendukung struktur blok bersarang seperti daftar bertingkat, blok yang telah diformat di dalam daftar, dll.
• Memadatkan & memperluas item daftar berdasarkan rata-rata jumlah baris per item daftar

Alternatif yang lebih lama adalah https://github.com/mklabs/vim-markdown-helpfile

Ada juga diskusi tentang /superuser//q/415470/generating-help-files-for-vim