お題

今回の話題は「vimのヘルプの公開」です。

序

vim-jpはvim界隈でも活動実績が評価されてるユーザーグループです。(なんとなくはしっこに参加させてもらってます)

ここの成果はいろいろありますが...

vim本体の不具合の確認やパッチ作成の場(日本語)
vital.vimという有用ライブラリプラグイン(他のプラグインに取り込んで使う)
vimのヘルプの日本語訳

などがあります。

ここで今回のに関係するものとして「vimのヘルプの日本語訳」があります。

本体の日本語化などはKaoriya(香り屋)版vimで有名な @koron さんや @mattn さんらが始めて、ヘルプについても多数の方が継続的に翻訳更新しつづけているものです。現在は @h_east さんらが積極的に活動されてますね。

これはプラグインとしてvimへ導入できるので、その用途での利用が多いかと思います。
ただ、あわせてHTML変換したヘルプを公開しており、

help - Vim日本語ドキュメント

として閲覧可能です。

プラグインのヘルプ

話はかわりまして、各Vimプラグインですが、(英語の)help docが充実しているというのがあります。

これは

統合的なパッケージ管理サイトが作られたとはいえなかった(なくはないが更新がおいつかない)、これによって独立独歩な気風がある
Emacsでもややそうだが、疎結合すぎるor勝手に動くと迷惑になりすぎることもあり、プラグインとして説明が必須なこと
併せて、設定のためのUIなどはなく、ヘルプから設定オプションを知る必要がある/知らせる必要があること
インタフェースが自由(すぎる)ので、ヘルプで利用方法を説明し、そうしているIFは安定IF、逆に説明がないならどんどん変更しても文句はいわせない、という線引きになる(あるプラグイン製作者曰く)

という理由などになります。

課題

さて、各プラグインのヘルプなのですが、ただでさえ英語多数なのに加え、プレーンテキストベースの文章です。
読める環境を制限しないかわりに、ミニマークアップ程度なので、読みやすいかというと微妙です。

ですが、そういう状況でも各プラグインのドキュメントはHTML化などはあまりされていません。
(自動生成ドキュメント系はHTMLにしての公開が多いですよね、Python系とか)

これはvimで見るうえ、そのvimではハイパーリンクやシンタックスハイライト+自分の好きなカラースキームで見れるというのがあるためです。

ただ、vim-jpの vim help で分りますが、HTML化+公開すると、

Webから簡単に見れる/Vimがなくても見れる
Vimなどにくらべるとフォントとカラーリッチ(やろうと思えば)

などもあり、無駄ということもなさそうです。

解決

今回、これを解決するために、簡単にHTMLで公開できるように仕組みを作ってみました。

GitHub Actionsを有効にし、上記actionを使って次のワークフローを定義することで、自動でgh-pagesへデプロイできます。

vimhelpdeploy.yml

name: "deploy vim help to gh-pages"
on:
  push:
    branches:
      - master
jobs:
  ghpages:
    name: Convert and deploy vim help
    runs-on: ubuntu-latest
    steps:
      - name: checkout
        uses: actions/checkout@master
      - name: generate html
        uses: tsuyoshicho/action-vimhelp-html-generate@master
        env:
          FOLDER: build
      - name: deploy gh-pages
        uses: JamesIves/github-pages-deploy-action@master
        env:
          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
          # alternative GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BASE_BRANCH: master
          BRANCH: gh-pages
          FOLDER: build

例
- 自作vimプラグイン vim-pass のHTML化 doc

これを各プラグイン製作者が自分のプラグインに組込むことで、自動的(GitHubのリポジトリオプションでgh-pagesを公開する設定は必要)に公開できます。

不具合

なお、変換にかかわるコードを vimdoc-jp からもってきて移植したのですが、まだまだ荒削りで以下の不具合があります。

ターゲットはvim help固定、docフォルダ固定(これはまあ仕様に近いから拡充するモチベーションはないですが)
ライト固定でbackgroundのダーク化や、カラーテーマの選択はできない(さぼってる)
なにより自動生成しているindexが tree コマンドそのまま

結

各vimプラグインの内容をもっと低い敷居で取得、理解できるようになり、vimとプラグインが発展していくと嬉しいですね。

(というか、持ち上げておいてなんですが、ヘルプのないプラグインもそれなりにあるし、日本人作でもグローバル対応としてヘルプが英語だけ/手間から日本語だけ、みたいなことも多いので、HTML公開でのアピール向上がしやすくなることで、それがもうちょっとでも充実させるモチベーションになって、充実してほしいというのもあります)

vim-jpの活動とプラグインとヘルプファイル

お題

序

プラグインのヘルプ

課題

解決

不具合

結