reading-vimrc
reading-vimrc copied to clipboard
vim-jp
vimrc style guide
itchyny せっかくvimrc読書会とかいう世界でも類を見ないものをやっているのに、それで鍛えられたvimrcを見る目を外国にフィードバックしないのはもったいない。 特に外国の人のvimrcを読んだりすると、本人のいないところで悪口言いあってる感じがする。それよりも何がよくて何が悪いかというのをちゃんと発表するほうがいい。 あと、vim-jpというコミュニティーとして発表することも大事なんじゃないかなぁと思った。
http://lingr.com/room/vim/archives/2014/11/16#message-20620208
フォーマットの案(?)
yaml あたりで書いて Jekyll からも楽に参照して表示できる + Vim とか他のインターフェースからも参照できるようにするとかよさそう? 言語も en と ja で分けて管理とかするのに, markdown 直書きとかはつらい可能性(?)
議題
vimrc style guideを作りましょう。 まずは、賛否を取ります。 十分な賛成意見が得られなければ、取り下げます。
vimrc style guideの目的
世界のVimのユーザーに対して、vim-jpの見解として、vimrcの正しい作法を発信することを目的とする。 vimrcに書いてはいけないことと、書くべきことを、文章としてまとめて公開する。
動機付け
vimrc読書会を行っていても、読んでいるvimrcを使っている当人には声が届かないことが多いと思います。 特に海外の方のvimrcを読んでいる時に、Lingrで「あれはダメだ、これができていない」と言いあっていても、当人のvimrcが改善されないのであれば、よろしくありません。 vimrcでやってはいけないこと、やって良いことを判断できるのであれば、それを世界に発信して広めていかないともったいないと思います。
ターゲット
主に、Vimを使う外国人とします。 Vim scriptを理解しない、プラグインを書いたことがない人を含みます。 自分のvimrcを少し見直してみようという人を主に想定します。
クレジット
vim-jpという団体の公式見解として発表したいと考えています。
個人でスタイルガイドを作ってもなかなか周知できないであろうからです。 vim-jpの影響力で世界のvimrcを浄化していきましょう。 style guideの中でvim-jpとはどういう団体なのか説明する必要があるでしょう。
内容
vimrcのスタイルガイドです。vimrcでよく書かれる間違いや、vimrcに必ず書くべき内容などについてドキュメントにします。 例えば、nmap/nnoremapの使い分け方、augroupの使い方、set nocompatibleの作用、<c-u>の意味と使い方などです。 各々の項目について、なぜやってはいけないか、なぜ書くべきかを正確に記述します。 helpを読めは尤もな意見ですが、helpに書いてあるにも関わらず誤った書き方のvimrcが多いのであれば、style guideとして記述する価値はあると考えます。
デフォルトのVimに付属しないプラグインやプラグインマネージャーについては扱いません。 各々の作者がやることであり、また時代と共に変わっていくからです。
ドキュメントをどこに置くか
私(itchyny)としては、次の条件は満たして欲しいと思います。
- 海外の人が見て安心できるドメイン
- コードハイライトがある
- vim-jpのみんながコミット、レビューしやすい
- curl一発でドキュメントを落とせる。読みやすい、検索しやすいフォーマットで(ex: markdown)。
私の最初のイメージは、githubのREADME.mdかgh-pagesでしたが、vim-jp.orgがいいかもしれないです。 ただ、vim-jp.orgは日本語なので、海外の人にはトップページを見ても読めないのが問題です。 GitHubのvim-jpから簡単に辿れるのが理想です。
ドキュメント/ソースのフォーマット
私(itchyny)としての意見です。
ドキュメントは
- 目次がある
- ソースコードはハイライトされている
- 重要事項から。 (should→may)
ソースは
- 読みやすい
- 編集しやすい
が理想です。 項目ごとにファイルを分けるのも一つのアイディアですが、それはそれでmakeが必要になってきて辛くなってきます。 正直README.mdでいいかなという思いもあります。要相談です。
Vim script plugin style guide
プラグインの読書会も行っており、プラグインの書き方についてスタイルガイドを作ることも一つのアイディアです。 今回提案するvimrc style guideでは、プラグインについては扱うべきではありません。 理由は以下の通りです。
- プラグインについて記述すれば、Vimプラグインを作らないユーザーは読まなくなる。
- vimrcのstyle guideだけでも十分な長さのドキュメントを書けることが予想できる (読むのに苦労しない長さじゃないとみんな読まない)
日本語版
日本語版を作るとダブルメンテナンスになるのでつらいでしょう。 個人的にはいらないと思っています。 ただ、「vim-jpとして日本人向けに啓蒙しないのもどうよ」というのは意見としてあるかもしれません。
お前のコメントは長い。三行で書けや。
- vim-jpの公式見解としてvimrc style guideを作るかどうか、意見を伺いたい。
- vimrc読書会でvimrcのお作法が共有されてきているので、それを世界に発信しよう。
- vimrcでやってはいけないことと、書くべきことを、vim-jpのみんなで協力してまとめよう。
結論
まずは、vim-jpとしてvimrc style guideを作るという提案に対して、みなさんの意見をお聞かせください。 フォーマット等の相談は、作るという決定がでた後になります。 vim-jpとしてそのようなことをするのは嫌だ、やめてくれ、個人的にやってくれという意見があれば、自分が個人的に作りたいなぁと思います。
:+1:
ターゲットですが, 日本人でもあまり活発にVim活してない人は全然vimrcの書き方はわからないし, 現状日本語でまとまっているものも無いと思うので日本語版も僕はあるといいかなーと思いました. どちらかができたら余裕がアレばそれを翻訳すればよいかとは思います
:+1:
日本語版を作るとダブルメンテナンスになるのでつらいでしょう。
同意です。個人的に日本語版は各個人のブログに書いて、URLだけ掲載するという形がよいと思います。
:+1:
vim-jpという団体の公式見解として発表したいと考えています。
僕もこの意見に賛成です。が、これどこまで合意が取れれば団体としての扱いになるんだろう
海外向けという意味を込めると @itchyny さんが言うように reading-vimrcページでも vim-jp.org でも基本日本語なのがネックなので新しくvim-jpでリポジトリ作ってもらって, そこで gh-pages 使うのが一番いいかなーと思いました.
ハイライトとかはJekyllで対応できるけど, 目次生成するプラグインとかを入れるためにはGitHub pagesデフォルトのJekyllでは使えないのがつらい... yaml or json あたりのデータとして書いてページに表示する形なら目次もデータから表示できるのでプラグイン or 手動目次作成はいらないかなー
個人的に日本語版は各個人のブログに書いて、URLだけ掲載するという形がよいと思います。
これをやるくらいなら普通に vim-jp で公開すればいいと思います
全体的に同意。ただ、日本語版も必要だと思います。 読者に関してもそうですが、vim-jp というだけあってコントリビュータはほぼ全員日本人です。英語が不得手な人もいます(私も含む)。英語のみにすると、そういった人が貢献しづらくなります。 まずは日本語でいいのでネタをかき集めて、英語できる人が適時翻訳、が速いんじゃないかなぁと思ってます。何より内容がないと始まらないですし。
:+1:
日本語版作って、適当なタイミングで英訳するのが現実的？ thincaさんの意見に同意。
最終的にはvimlintやvintに反映できれば便利そう。
超雑なプロトタイプつくってみました
ページ: http://haya14busa.github.io/reading-vimrc/styleguide.html yamlで書いてる様子: https://github.com/haya14busa/reading-vimrc/blob/gh-pages/_data/vimrc_style_guide.yml
コードブロック用のCSSまだインクルードしてなかったり, CSSがvimrc読書会に最適化されていてみずらいですが yamlで書くとこんな感じかな〜と. (別に書きやすくはなかったけどデータとしてあとから使いやすい...可能性...も?)
デザインに関してはちゃんとCSS当てればよくなるはず
yamlだと面倒さはやっぱりあるのでmarkdownのほうがいい感はとてもあるか... あとvimlintとかvint, etc..からデータとして使用したい場合もスタイルガイトのデータってどう提供すればよいかわからないし最初からデータ化するメリット無い気がしてきた
:+1: あくまで英語版が正で日本語版はそれに付随する形、但し日本語でしかコミットできない人もすくい上げていきたい為その救済措置が必要になってくると思っていいでしょうか。
まずは日本語で
というの、ベースを作るためには有効な手段なんですが、これをどこまで続けるかというのを明確にしておかないと日本語版のみ先行することになりかねないと思っています。
:+1: :+1: :+1: :+1: :+1: 感極まってきました。
正式版に対して、あくまで参照用として日本語翻訳版も提供する、というのは良いと思いますが、翻訳版も常に最新の情報を示しているという保証をしないのであれば、ダブルメンテの負荷を落とすことができて健全そうです。
一方、(本issueそのものを含め) 議論を日本語で行うのはokということでどうでしょうか。件名が英語ならばとりあえずは内容の推測ができるはずなので。
一点強く主張したいのは、各項目にパーマリンク (# のページ内リンクでok) がついていて、それが簡単に参照可能であることです。
スタイルガイドは、通読されるだけではなく、コードレビューなどのときに引用するというユースケースが最も高頻度な気がするためです。
https://github.com/vim-jp/reading-vimrc/issues/15#issuecomment-63247285
https://github.com/vim-jp/reading-vimrc/issues/15#issuecomment-63247322
:+1:
日本語版の運用は意見が割れる重要な議題であることが分かりましたので、またしっかり話し合いましょう。
まだ半日しか経っていないので、もうしばらく他の方のコメントを待ちたいと思います。 vim-jpとして作っていくには意思決定が遅くなるかもしれませんが、少数意見を無下にせず、焦らずに行きましょう。
実際に作ることになれば、このリポジトリーではなくて新しいリポジトリーを作るのが良いと思います。そこで日本語版について新しくissueを立てて議論しましょう。
ふとneovimのスタイルガイドを見ていたんですが xml で書いてた http://neovim.org/develop/style-guide.xml
XMLとVim scriptかどうかって関係あるんデス? とまぁ一応リンクしたものの, まずはgithubのREADME(というかmarkdown)でやればいいかなーと個人的には思いました。一番手軽かつ, 項目リンクとかコードブロックのハイライトも対応してるe.g. https://github.com/johnpapa/angularjs-styleguide
