Làm cách nào để tạo tài liệu Vim từ ghi chú Markdown hoặc nhận xét nội tuyến hoặc có cách nào tốt hơn để thêm tài liệu?

Đây là loại hai câu hỏi trong một. Gần đây tôi đã dành rất nhiều thời gian để học chuyên sâu về vimscript, học nội bộ của vim và thực hiện những bước đầu tiên của tôi để viết các plugin vim. Trong quá trình này, tôi đã giữ các ghi chú mở rộng trong các tệp đánh dấu riêng lẻ và thêm nhiều nhận xét 'tài liệu' nội tuyến vào các tệp vimscript.

Tôi cảm thấy như cuối cùng tôi đã nhận được một số mã đáng để chia sẻ và muốn bắt đầu thêm một số tài liệu thực tế . Tôi chưa tạo ra bất kỳ tệp trợ giúp nào của riêng mình, vì vậy tôi vẫn đang tìm ra quy trình đó.

Chưa có kinh nghiệm hoặc hiểu biết sâu sắc về quy trình công việc này, có hai nhiệm vụ tôi đang cố gắng tìm ra:

1. Tạo các tệp helpdoc từ các tệp 'ghi chú' đánh dấu của tôi trên vim / vimscript, vì vậy tôi có thể đọc / tham khảo nhanh chóng & dễ dàng từ vim bất cứ lúc nào.
2. Phân tích tài liệu nội tuyến từ các tệp vimscript của tôi (tương tự như cách shocco hoạt động cho các tập lệnh shell) để tạo trợ giúp liên quan cho các vimscripts.

Bất kỳ đề xuất hoặc lời khuyên nào về các ý tưởng ( đây là một ý tưởng tồi bởi vì ..., một ý tưởng tốt hơn là ... ) hoặc cách thực hiện chúng sẽ được đánh giá cao.

Theo tôi biết hiện tại không có giải pháp tốt cho một trong hai vấn đề, nhưng rất nhiều người sẽ quan tâm đến việc giải quyết chúng.

Markdown là một siêu mã của HTML, vì vậy tôi muốn nói rằng cách tiếp cận trực tiếp để chuyển đổi từ đánh dấu sang trợ giúp Vim khó có thể thành công. Nếu bạn có thể nói Haskell, bạn có thể thử viết phần trợ giúp Vim cho pandoc . Đó sẽ là một giải pháp rất hay ngay cả khi nó không hoàn hảo.

Đã có một vài nỗ lực để thực hiện theo cách khác, chuyển đổi các trang trợ giúp Vim sang một số định dạng hữu ích. Có một vài tập lệnh nổi xung quanh sản xuất các phiên bản HTML và PDF của trợ giúp chính thức, với mức độ thành công khác nhau. Nhưng tất cả họ đều dựa vào sự giúp đỡ ít nhiều đồng nhất trong phong cách. Ngay cả một người đọc giúp Vim cho một cái gì đó như pandoc sẽ là một dự án đáng giá.

Đối với việc trích xuất tài liệu từ mã Vim, có một trình phân tích cú pháp cho VimL bằng Python, JavaScript và VimL, ​​được đặt tên là vimlparser . Điều đó khá tốt, không khó để viết một cái gì đó phân tích các nguồn VimL và bỏ các bình luận được chế tạo đặc biệt. Có thể chuyển đổi những bình luận này thành một cái gì đó như, giả sử, POD cũng sẽ rất hữu ích.

html2vimdoc.py

Công cụ hứa hẹn nhất mà tôi tìm thấy là html2vimdoc.pycó thể tìm thấy ở đây http://peterodding.com/code/vim/tools và trên github . Nó có thể chuyển đổi markdown và html sang định dạng trợ giúp của vim. Các tính năng được quảng cáo là:

• Nó có thể xử lý HTML phức tạp nhờ bs [BeautifulSoup]
• Tự động tạo thẻ tập tin trợ giúp Vim cho các tiêu đề
• Tạo mục lục từ các tiêu đề và thẻ
• Hỗ trợ các cấu trúc khối lồng nhau như danh sách lồng nhau, khối được định dạng sẵn trong danh sách, v.v.
• Hợp tác & mở rộng danh sách các mục dựa trên số dòng trung bình trên mỗi mục danh sách

Một thay thế cũ hơn là https://github.com/mklabs/vim-markdown-helpfile

Cũng đã có một cuộc thảo luận về /superuser//q/415470/generating-help-files-for-vim