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

あなたは誰

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

ヘルプ、引いていますか？

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

:help helphelp

プラグインのドキュメントは2箇所ありうる

• doc/foo.txt
  • Vim scriptで書かれているプラグインだとこっちが多い？
• README.md
  • 最近のLuaだとこっちが多い気がする

Vimmer的には

• doc/foo.txtだと:help foo.txtで引けて便利

  • Vimでヘルプが見れる、すばらしい

• プラグインを作る側としては2箇所に同じドキュメントを書くのは面倒

  • README側をsee :h foo.txt more...としておくのも1つの手ではあるが...

最近こんなものが出てきたよ

tani/podium

• Plain Old Document(POD)で書いた.podファイルを変換
  • HTML
  • Markdown
  • LaTeX
  • Vimdoc

例えば(pod => markdown)

---
name: pod-sample
description: sample pod text
--

=pod

=head1 sample X<sample-index>

sample

=head2 Contents

    Hello gorilla vim!!

=over 0

=item * L<gooogle|https://google.com>

=back

=cut

# sample

sample

## Contents

```
    Hello gorilla vim!!
```

- [gooogle](https://google.com)

例えば(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:

個人的に気になったところ

• ハイライトつきコードブロックが出力できない

```vim
:echo 42
```

:echo 42

• ↑のmarkdownに相当するpodの構文がない

=pod

    ここがコードブロックになる

=cut

```
:echo 42
```

ラッパーを作った

Omochice/podeno

• highlight.jsとshiki.jsのハイライト言語に対応

• 現状、pod => Markdownとpod => Vimdocに対応

begin vim

:echo 42

end vim

```vim
:echo 42
```

>
    :echo 42
<

使い方

$ deno install --allow-net --allow-read --allow-write \
    https://pax.deno.dev/Omochice/podeno/cli.ts

$ podeno markdown --in sample.pod

CIでつかう

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

まとめ

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

以下、補足資料

補足: Alternative

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