podiumを使ってdocとreadmeを生成する

podiumを使ってdocとreadmeを生成する 2023-08-26 @ゴリラ.vim #28 1 / 18

あなたは誰 Name: Omochice Twitter: @omochicemgr GitHub: Omochice Hobby: Vim Deno $ vim-startuptime -vimpath ~/.local/nvim/bin/nvim Extra options: [] Measured: 10 times Total Average: 23.684300 msec Total Max: 26.716000 msec Total Min: 21.802000 msec 2 / 18

ヘルプ、引いていますか？ https://vim-jp.org/vimdoc-ja/helphelp.html :help helphelp 3 / 18

• https://vim-jp.org/vimdoc-ja/helphelp.html

プラグインのドキュメントは2箇所ありうる doc/foo.txt Vim scriptで書かれているプラグインだとこっちが多い？ README.md 最近のLuaだとこっちが多い気がする 4 / 18

5 / 18

Vimmer的には doc/foo.txt だと :help foo.txt で引けて便利 Vimでヘルプが見れる、すばらしい プラグインを作る側としては2箇所に同じドキュメントを書くのは面倒 README側を see :h foo.txt more... としておくのも1つの手ではあるが... 6 / 18

最近こんなものが出てきたよ tani/podium Plain Old Document(POD)で書いた .pod ファイルを変換 HTML Markdown LaTeX Vimdoc 7 / 18

• https://github.com/tani/podium

例えば(pod => markdown) --name: pod-sample description: sample pod text -- # sample =pod ## Contents =head1 sample X<sample-index> ``` sample =head2 Contents Hello gorilla vim!! sample ``` Hello gorilla vim!! - [gooogle](https://google.com) =over 0 =item * L<gooogle|https://google.com> =back =cut 8 / 18

例えば(pod => vimdoc) *pod-sample.txt* sample pod text ============================================================================= sample ~ *sample-index* sample Contents~ > < Hello gorilla vim!! - gooogle |https://google.com| vim:tw=78:ts=8:noet:ft=help:norl: 9 / 18

個人的に気になったところ ハイライトつきコードブロックが出力できない ```vim :echo 42 ``` :echo 42 ↑のmarkdownに相当するpodの構文がない =pod ここがコードブロックになる ``` :echo 42 ``` =cut 10 / 18

ラッパーを作った Omochice/podeno highlight.jsとshiki.jsのハイライト言語に対応 現状、pod => Markdownとpod => Vimdocに対応 begin vim :echo 42 end vim ```vim :echo 42 ``` > < :echo 42 11 / 18

• https://github.com/Omochice/podeno

使い方 $ deno install --allow-net --allow-read --allow-write \ https://pax.deno.dev/Omochice/podeno/cli.ts $ podeno markdown --in sample.pod 12 / 18

CIでつかう https://github.com/Omochice/tataku-processordeepl/blob/main/.github/workflows/doc.yml 13 / 18

• https://github.com/Omochice/tataku-processor-deepl/blob/main/.github/workflows/doc.yml

要改善点(知見求) インデックス: X<foo> とリンク: L<foo> の扱い Vimdoc: 同一ファイルの *foo* へのリンク *foo* (ヘルプタグ)と |foo| (ヘルプタグへのリンク) :help help-writing が詳しい Markdown: カレントファイルから foo の位置にあるものへのリンク 存在しない場所へのリンクになってしまう 例: https://github.com/Omochice/tataku-processor-deepl#contents 14 / 18

• https://vim-jp.org/vimdoc-ja/helphelp.html#help-writing
• https://github.com/Omochice/tataku-processor-deepl#contents

まとめ :help は便利 Vimプラグインのドキュメントはちゃんとやろうとすると2箇所に必要 podiumを使うと .pod ファイル1つから2つのヘルプを生成できる podiumはコードハイライトできない コードブロックにハイライトが付かないのが気になったのでラッパ ( podeno )を書いた podenoはまだ課題があるので詳しい人、教えてください 15 / 18

16 / 18

以下、補足資料 17 / 18

補足: Alternative kdheepak/panvimdoc pandocを使ってmd => vimdocに変換 FooSoft/md2vim goで書かれたmd => vimdocの変換 archived 4513ECHO/vim-readme-viewer readmeをvimで読めるようにするプラグイン 18 / 18

• https://github.com/kdheepak/panvimdoc
• https://github.com/FooSoft/md2vim
• https://github.com/4513ECHO/vim-readme-viewer