ฉันจะสร้างเอกสาร Vim ได้จาก Markdown notes หรือความคิดเห็นแบบอินไลน์หรือมีวิธีที่ดีกว่าในการเพิ่มเอกสาร?

นี้เป็นชนิดของคำถามที่สองในหนึ่ง เมื่อเร็ว ๆ นี้ฉันใช้เวลาเรียนรู้ vimscript ในเชิงลึกเรียนรู้การทำงานภายในของ vim และทำตามขั้นตอนแรกของฉันในการเขียนปลั๊กอิน vim ในระหว่างกระบวนการนี้ฉันได้เก็บบันทึกย่อไว้ในไฟล์มาร์กอัปแต่ละไฟล์และเพิ่มความคิดเห็น 'เอกสารประกอบ' แบบอินไลน์ลงในไฟล์ vimscript

ในที่สุดฉันรู้สึกว่าฉันได้รับรหัสที่คุ้มค่าในการแบ่งปันและต้องการเริ่มเพิ่มเอกสารจริง ฉันยังไม่ได้เขียนไฟล์ helpdoc ของฉันเองดังนั้นฉันยังคงหาวิธีการนั้น

ไม่มีประสบการณ์หรือความเข้าใจที่ดีเกี่ยวกับเวิร์กโฟลว์นี้มีสองงานที่ฉันพยายามคิดออก:

1. การสร้างไฟล์ helpdoc จากไฟล์ 'notes' ของ markdown ของฉันบน vim / vimscript ดังนั้นฉันสามารถอ่าน / อ้างอิงได้อย่างรวดเร็วและง่ายดายจาก vim เมื่อใดก็ได้
2. การแยกเอกสารอินไลน์จากไฟล์ vimscript ของฉัน (คล้ายกับวิธีshoccoทำงานสำหรับเชลล์สคริปต์) เพื่อสร้าง helpdoc ที่เกี่ยวข้องสำหรับ vimscripts

ข้อเสนอแนะหรือคำแนะนำใด ๆ เกี่ยวกับความคิด ( นี่เป็นความคิดที่ไม่ดีเพราะ ... ความคิดที่ดีกว่าคือ ... ) หรือวิธีการทำให้สำเร็จจะได้รับการชื่นชมอย่างมาก

เท่าที่ฉันรู้ในปัจจุบันยังไม่มีวิธีแก้ปัญหาที่ดีสำหรับปัญหาใด ๆ แต่ผู้คนจำนวนมากจะสนใจในการแก้ปัญหาเหล่านั้น

Markdown เป็นส่วนเสริมของ HTML ดังนั้นฉันจะบอกว่าวิธีการแปลงจากหน้าแรกเป็น markdown เป็น Vim ช่วยไม่น่าจะประสบความสำเร็จ หากคุณสามารถพูด Haskell คุณอาจจะพยายามที่จะเขียนแบ็กเอนด์ความช่วยเหลือที่เป็นกลุ่มpandoc นั่นจะเป็นทางออกที่ดีมากแม้ว่ามันจะไม่สมบูรณ์แบบก็ตาม

มีความพยายามในการทำเช่นนั้นแปลงหน้าวิธีใช้ Vim เป็นรูปแบบที่มีประโยชน์ มีสคริปต์บางตัวที่ลอยอยู่รอบ ๆ ซึ่งสร้างเวอร์ชัน HTML และ PDF ของความช่วยเหลืออย่างเป็นทางการโดยมีระดับความสำเร็จที่แตกต่างกัน แต่พวกเขาทั้งหมดขึ้นอยู่กับความช่วยเหลือที่มากหรือน้อยในลักษณะเดียวกัน แม้แต่ Vim help reader สำหรับpandocก็เป็นโครงการที่คุ้มค่า

ในฐานะที่เป็นสำหรับการแยกเอกสารจากโค้ดที่เป็นกลุ่มมีการแยกวิเคราะห์สำหรับ VimL ในหลาม, JavaScript และ VimL ตัวเองชื่อvimlparser มันค่อนข้างดีมันไม่ควรยากที่จะเขียนสิ่งที่แยกวิเคราะห์ VimL และทิ้งความคิดเห็นที่สร้างขึ้นเป็นพิเศษ ความสามารถในการแปลงความคิดเห็นเหล่านี้เป็นสิ่งที่ต้องการพูดPODจะมีประโยชน์อย่างมากเช่นกัน

html2vimdoc.py

เครื่องมือที่มีแนวโน้มมากที่สุดที่ฉันได้พบคือhtml2vimdoc.pyซึ่งสามารถพบได้ที่นี่ http://peterodding.com/code/vim/toolsและGitHub มันสามารถแปลง markdown และ html เป็นรูปแบบความช่วยเหลือของ vim คุณสมบัติที่โฆษณาคือ:

• มันสามารถจัดการกับ HTML ที่ซับซ้อนด้วย [BeautifulSoup] bs
• สร้างแท็กไฟล์วิธีใช้ Vim โดยอัตโนมัติสำหรับส่วนหัว
• สร้างสารบัญจากส่วนหัวและแท็ก
• รองรับโครงสร้างบล็อกที่ซ้อนกันเช่นรายการซ้อนกันบล็อกที่จัดรูปแบบล่วงหน้าภายในรายการ ฯลฯ
• กระชับ & ขยายรายการตามจำนวนบรรทัดโดยเฉลี่ยต่อรายการ

ทางเลือกที่เก่ากว่าคือhttps://github.com/mklabs/vim-markdown-helpfile

นอกจากนี้ยังมีการอภิปรายเกี่ยวกับ/superuser//q/415470/generating-help-files-for-vim